Download PDF
ESP-IDF Programming Guide - ESP32-S3 - — ESP-IDF Programming Guide latest documentation
Not Your Device? Search For Manuals or Datasheets below:
File Info : application/pdf, 2251 Pages, 21.36MB
Document DEVICE REPORTesp-idf-en-v5.0-dev-2349-g4350e6fef8-esp32s3ESP32-S3 ESP-IDF Programming Guide Release v5.0-dev-2349-g4350e6fef8 Espressif Systems Apr 01, 2022 Table of contents Table of contents i 1 Get Started 3 1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 What You Need . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2.1 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2.2 Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.3.1 IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.3.2 Manual Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.4 Build Your First Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 2 API Reference 47 2.1 API Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 2.1.1 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 2.1.2 Configuration structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 2.1.3 Private APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.1.4 Components in example projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.1.5 API Stability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 2.2 Application Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 2.2.1 ASIO port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 2.2.2 ESP-Modbus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 2.2.3 ESP-MQTT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 2.2.4 ESP-TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 2.2.5 ESP HTTP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 2.2.6 ESP Local Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 2.2.7 ESP Serial Slave Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 2.2.8 ESP x509 Certificate Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 2.2.9 HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 2.2.10 HTTPS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 2.2.11 ICMP Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 2.2.12 mDNS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 2.2.13 Mbed TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 2.2.14 IP Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 2.3 Bluetooth API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 2.3.1 BT COMMON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 2.3.2 BT LE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 2.3.3 Controller && VHCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 2.3.4 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 2.3.5 NimBLE-based host APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 2.4 Error Codes Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 2.5 Networking APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 2.5.1 Wi-Fi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 2.5.2 Ethernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 2.5.3 Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 2.5.4 ESP-NETIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 2.5.5 IP Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638 i 2.5.6 Application Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 2.6 Peripherals API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 2.6.1 Analog to Digital Converter (ADC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 2.6.2 GPIO & RTC GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 2.6.3 General Purpose Timer (GPTimer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677 2.6.4 Dedicated GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686 2.6.5 Hash-based Message Authentication Code (HMAC) . . . . . . . . . . . . . . . . . . . . 690 2.6.6 Digital Signature (DS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693 2.6.7 Inter-Integrated Circuit (I2C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 2.6.8 Inter-IC Sound (I2S) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713 2.6.9 LCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728 2.6.10 LED Control (LEDC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 2.6.11 Motor Control Pulse Width Modulator (MCPWM) . . . . . . . . . . . . . . . . . . . . . 755 2.6.12 Pulse Counter (PCNT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779 2.6.13 Remote Control (RMT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789 2.6.14 SD Pull-up Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809 2.6.15 SDMMC Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810 2.6.16 SD SPI Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816 2.6.17 Sigma-delta Modulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821 2.6.18 SPI Master Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824 2.6.19 SPI Slave Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842 2.6.20 Temperature Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848 2.6.21 Touch Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851 2.6.22 Two-Wire Automotive Interface (TWAI) . . . . . . . . . . . . . . . . . . . . . . . . . . 872 2.6.23 Universal Asynchronous Receiver/Transmitter (UART) . . . . . . . . . . . . . . . . . . 888 2.6.24 USB Device Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910 2.6.25 USB Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917 2.7 Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 2.7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 2.7.2 Project Configuration Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 2.7.3 Using sdkconfig.defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946 2.7.4 Kconfig Formatting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946 2.7.5 Backward Compatibility of Kconfig Options . . . . . . . . . . . . . . . . . . . . . . . . 946 2.7.6 Configuration Options Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947 2.8 Provisioning API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204 2.8.1 Protocol Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204 2.8.2 Unified Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214 2.8.3 Wi-Fi Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217 2.9 Storage API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234 2.9.1 FAT Filesystem Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234 2.9.2 Manufacturing Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1240 2.9.3 Non-volatile storage library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1244 2.9.4 NVS Partition Generator Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263 2.9.5 SD/SDIO/MMC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270 2.9.6 SPI Flash API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1281 2.9.7 SPIFFS Filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314 2.9.8 Virtual filesystem component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1318 2.9.9 Wear Levelling API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331 2.10 System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334 2.10.1 App Image Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334 2.10.2 Application Level Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339 2.10.3 Call function with external stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344 2.10.4 Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345 2.10.5 eFuse Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353 2.10.6 Error Codes and Helper Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375 2.10.7 ESP HTTPS OTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378 2.10.8 Event Loop Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382 2.10.9 FreeRTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393 ii 2.10.10 FreeRTOS Supplemental Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497 2.10.11 Heap Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1514 2.10.12 Heap Memory Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526 2.10.13 High Resolution Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1536 2.10.14 Internal and Unstable APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1542 2.10.15 Inter-Processor Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1543 2.10.16 Interrupt allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1548 2.10.17 Logging library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1554 2.10.18 Miscellaneous System APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559 2.10.19 SoC Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1568 2.10.20 Over The Air Updates (OTA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575 2.10.21 Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1585 2.10.22 Power Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1589 2.10.23 POSIX Threads Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595 2.10.24 Random Number Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599 2.10.25 Sleep Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1601 2.10.26 System Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1610 2.10.27 The Async memcpy API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1614 2.10.28 ULP Coprocessor programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617 2.10.29 ULP RISC-V Coprocessor programming . . . . . . . . . . . . . . . . . . . . . . . . . . 1652 2.10.30 Watchdogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1656 3 ESP32-S3 Hardware Reference 1661 3.1 Chip Series Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661 3.1.1 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663 4 API Guides 1665 4.1 Application Level Tracing library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665 4.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665 4.1.2 Modes of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665 4.1.3 Configuration Options and Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . 1666 4.1.4 How to use this library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1667 4.2 Application Startup Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675 4.2.1 First stage bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1676 4.2.2 Second stage bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1676 4.2.3 Application startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1677 4.3 BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 4.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 4.3.2 The BluFi Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 4.3.3 The Flow Chart of BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679 4.3.4 The Frame Formats Defined in BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679 4.3.5 The Security Implementation of ESP32-S3 . . . . . . . . . . . . . . . . . . . . . . . . . 1685 4.3.6 GATT Related Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686 4.4 Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686 4.4.1 Bootloader compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687 4.4.2 Log Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687 4.4.3 Factory reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687 4.4.4 Boot from Test Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688 4.4.5 Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688 4.4.6 Watchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688 4.4.7 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689 4.4.8 Fast boot from Deep Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689 4.4.9 Custom bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689 4.5 Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689 4.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689 4.5.2 Using the Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1690 4.5.3 Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694 4.5.4 Project CMakeLists File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1695 iii 4.5.5 Component CMakeLists Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696 4.5.6 Component Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1698 4.5.7 Preprocessor Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1698 4.5.8 Component Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699 4.5.9 Overriding Parts of the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1702 4.5.10 Configuration-Only Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703 4.5.11 Debugging CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703 4.5.12 Example Component CMakeLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1704 4.5.13 Custom sdkconfig defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708 4.5.14 Flash arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708 4.5.15 Building the Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708 4.5.16 Selecting the Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709 4.5.17 Writing Pure CMake Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709 4.5.18 Using Third-Party CMake Projects with Components . . . . . . . . . . . . . . . . . . . 1710 4.5.19 Using Prebuilt Libraries with Components . . . . . . . . . . . . . . . . . . . . . . . . . 1710 4.5.20 Using ESP-IDF in Custom CMake Projects . . . . . . . . . . . . . . . . . . . . . . . . . 1711 4.5.21 ESP-IDF CMake Build System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1711 4.5.22 File Globbing & Incremental Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715 4.5.23 Build System Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1716 4.5.24 Build System Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1716 4.5.25 Migrating from ESP-IDF GNU Make System . . . . . . . . . . . . . . . . . . . . . . . 1718 4.6 Core Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1719 4.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1719 4.6.2 Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720 4.6.3 Save core dump to flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720 4.6.4 Print core dump to UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721 4.6.5 ROM Functions in Backtraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721 4.6.6 Dumping variables on demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721 4.6.7 Running espcoredump.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722 4.7 Deep Sleep Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724 4.7.1 Rules for Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724 4.7.2 Implementing A Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725 4.7.3 Loading Code Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725 4.7.4 Loading Data Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725 4.7.5 CRC Check For Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1726 4.8 Device Firmware Upgrade through USB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1726 4.8.1 Building the DFU Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727 4.8.2 Flashing the Chip with the DFU Image . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727 4.9 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1728 4.9.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1728 4.9.2 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1729 4.9.3 Converting error codes to error messages . . . . . . . . . . . . . . . . . . . . . . . . . . 1729 4.9.4 ESP_ERROR_CHECK macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1729 4.9.5 ESP_ERROR_CHECK_WITHOUT_ABORT macro . . . . . . . . . . . . . . . . . . . . . 1730 4.9.6 ESP_RETURN_ON_ERROR macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730 4.9.7 ESP_GOTO_ON_ERROR macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730 4.9.8 ESP_RETURN_ON_FALSE macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730 4.9.9 ESP_GOTO_ON_FALSE macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730 4.9.10 CHECK MACROS Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730 4.9.11 Error handling patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1731 4.9.12 C++ Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732 4.10 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732 4.10.1 Getting Started with ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732 4.10.2 ESP-BLE-MESH Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738 4.10.3 ESP-BLE-MESH Demo Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740 4.10.4 ESP-BLE-MESH FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740 4.10.5 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740 4.11 ESP-IDF FreeRTOS (SMP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769 iv 4.11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769 4.11.2 Symmetric Multiprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770 4.11.3 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770 4.11.4 SMP Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772 4.11.5 Critical Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1775 4.11.6 Misc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776 4.12 ESP-WIFI-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1777 4.12.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1777 4.12.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778 4.12.3 ESP-WIFI-MESH Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1779 4.12.4 Building a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784 4.12.5 Managing a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1789 4.12.6 Data Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1792 4.12.7 Channel Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794 4.12.8 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797 4.12.9 Further Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798 4.13 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798 4.13.1 Wi-Fi, Ethernet, and IP Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798 4.13.2 Mesh Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799 4.13.3 Bluetooth Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800 4.14 Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800 4.14.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800 4.14.2 Panic Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800 4.14.3 Register Dump and Backtrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1801 4.14.4 GDB Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1803 4.14.5 Guru Meditation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1804 4.14.6 Other Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806 4.15 Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808 4.15.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808 4.15.2 Relevant eFuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809 4.15.3 Flash Encryption Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809 4.15.4 Flash Encryption Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1810 4.15.5 Possible Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816 4.15.6 ESP32-S3 Flash Encryption Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817 4.15.7 Reading and Writing Data in Encrypted Flash . . . . . . . . . . . . . . . . . . . . . . . 1818 4.15.8 Updating Encrypted Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819 4.15.9 Disabling Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819 4.15.10 Key Points About Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819 4.15.11 Limitations of Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1820 4.15.12 Flash Encryption and Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1820 4.15.13 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1820 4.15.14 External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822 4.15.15 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822 4.16 SPI Flash and External SPI RAM Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822 4.16.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822 4.16.2 How to configure Flash and PSRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1823 4.16.3 All Supported Modes and Speeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1823 4.16.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824 4.17 Hardware Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1825 4.17.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1825 4.17.2 LL (Low Level) Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1826 4.17.3 HAL (Hardware Abstraction Layer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1827 4.18 High-Level Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828 4.18.1 Interrupt Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828 4.18.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828 4.19 JTAG Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829 4.19.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829 4.19.2 How it Works? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1830 v 4.19.3 Selecting JTAG Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1830 4.19.4 Setup of OpenOCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1831 4.19.5 Configuring ESP32-S3 Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1831 4.19.6 Launching Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834 4.19.7 Debugging Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834 4.19.8 Building OpenOCD from Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834 4.19.9 Tips and Quirks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1839 4.19.10 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1843 4.20 Linker Script Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868 4.20.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868 4.20.2 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868 4.20.3 Linker Script Generation Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871 4.21 lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877 4.21.1 Supported APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877 4.21.2 BSD Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878 4.21.3 Netconn API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1882 4.21.4 lwIP FreeRTOS Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1882 4.21.5 IPv6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1882 4.21.6 esp-lwip custom modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1883 4.21.7 Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884 4.22 Memory Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1885 4.22.1 DRAM (Data RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1885 4.22.2 IRAM (Instruction RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886 4.22.3 IROM (code executed from flash) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887 4.22.4 RTC FAST memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887 4.22.5 DROM (data stored in flash) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887 4.22.6 RTC Slow memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887 4.22.7 DMA Capable Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1888 4.22.8 DMA Buffer in the stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1888 4.23 OpenThread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1889 4.23.1 Mode of the OpenThread stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1889 4.23.2 How To Write an OpenThread Application . . . . . . . . . . . . . . . . . . . . . . . . . 1889 4.23.3 The OpenThread border router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1890 4.24 Partition Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1890 4.24.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1891 4.24.2 Built-in Partition Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1891 4.24.3 Creating Custom Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1891 4.24.4 Generating Binary Partition Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894 4.24.5 Partition Size Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894 4.24.6 Flashing the partition table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894 4.24.7 Partition Tool (parttool.py) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895 4.25 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896 4.25.1 How to Optimize Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896 4.25.2 Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896 4.26 RF calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912 4.26.1 Partial calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912 4.26.2 Full calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912 4.26.3 No calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913 4.26.4 PHY initialization data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913 4.26.5 API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913 4.27 Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915 4.27.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916 4.27.2 Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916 4.27.3 Secure Boot V2 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916 4.27.4 Signature Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1917 4.27.5 Verifying a Signature Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1917 4.27.6 Verifying an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1917 4.27.7 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918 vi 4.27.8 eFuse usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918 4.27.9 How To Enable Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918 4.27.10 Restrictions after Secure Boot is enabled . . . . . . . . . . . . . . . . . . . . . . . . . . 1919 4.27.11 Generating Secure Boot Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1919 4.27.12 Remote Signing of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920 4.27.13 Secure Boot Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920 4.27.14 Key Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920 4.27.15 Multiple Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920 4.27.16 Key Revocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1921 4.27.17 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1921 4.27.18 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922 4.27.19 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 1922 4.27.20 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922 4.28 Support for External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923 4.28.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923 4.28.2 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923 4.28.3 Configuring External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923 4.28.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1924 4.28.5 Failure to initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925 4.28.6 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925 4.29 Thread Local Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925 4.29.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925 4.29.2 FreeRTOS Native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925 4.29.3 Pthread API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925 4.29.4 C11 Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926 4.30 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926 4.30.1 Downloadable Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926 4.30.2 IDF Docker Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935 4.30.3 IDF Windows Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936 4.30.4 IDF Component Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1937 4.30.5 IDF Clang Tidy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938 4.31 Unit Testing in ESP32-S3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939 4.31.1 Normal Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1940 4.31.2 Multi-device Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1940 4.31.3 Multi-stage Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941 4.31.4 Tests For Different Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942 4.31.5 Building Unit Test App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942 4.31.6 Running Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1943 4.31.7 Timing Code with Cache Compensated Timer . . . . . . . . . . . . . . . . . . . . . . . 1944 4.31.8 Mocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945 4.32 Unit Testing on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946 4.32.1 Embedded Software Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1947 4.32.2 IDF Unit Tests on Linux Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1947 4.33 USB OTG Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1948 4.33.1 Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1948 4.33.2 Software Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1948 4.33.3 Uploading the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1949 4.33.4 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1949 4.34 USB Serial/JTAG Controller Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1950 4.34.1 Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1950 4.34.2 Software Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1950 4.34.3 Uploading the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951 4.34.4 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951 4.35 Wi-Fi Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951 4.35.1 ESP32-S3 Wi-Fi Feature List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951 4.35.2 How To Write a Wi-Fi Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1952 4.35.3 ESP32-S3 Wi-Fi API Error Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1952 4.35.4 ESP32-S3 Wi-Fi API Parameter Initialization . . . . . . . . . . . . . . . . . . . . . . . 1953 vii 4.35.5 ESP32-S3 Wi-Fi Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953 4.35.6 ESP32-S3 Wi-Fi Event Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953 4.35.7 ESP32-S3 Wi-Fi Station General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . 1956 4.35.8 ESP32-S3 Wi-Fi AP General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 1959 4.35.9 ESP32-S3 Wi-Fi Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1959 4.35.10 ESP32-S3 Wi-Fi Station Connecting Scenario . . . . . . . . . . . . . . . . . . . . . . . 1966 4.35.11 ESP32-S3 Wi-Fi Station Connecting When Multiple APs Are Found . . . . . . . . . . . 1970 4.35.12 Wi-Fi Reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 4.35.13 Wi-Fi Beacon Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 4.35.14 ESP32-S3 Wi-Fi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1970 4.35.15 Wi-Fi Easy ConnectTM (DPP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975 4.35.16 Wireless Network Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976 4.35.17 Radio Resource Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976 4.35.18 ESP32-S3 Wi-Fi Power-saving Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976 4.35.19 ESP32-S3 Wi-Fi Throughput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977 4.35.20 Wi-Fi 80211 Packet Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977 4.35.21 Wi-Fi Sniffer Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1979 4.35.22 Wi-Fi Multiple Antennas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1980 4.35.23 Wi-Fi Channel State Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1981 4.35.24 Wi-Fi Channel State Information Configure . . . . . . . . . . . . . . . . . . . . . . . . . 1982 4.35.25 Wi-Fi HT20/40 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983 4.35.26 Wi-Fi QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983 4.35.27 Wi-Fi AMSDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1984 4.35.28 Wi-Fi Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1984 4.35.29 WPS Enrollee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1984 4.35.30 Wi-Fi Buffer Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1984 4.35.31 How to improve Wi-Fi performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985 4.35.32 Wi-Fi Menuconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1989 4.35.33 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1992 4.36 Wi-Fi Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1996 4.36.1 ESP32-S3 Wi-Fi Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998 4.36.2 Protected Management Frames (PMF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998 4.36.3 WPA3-Personal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999 4.37 RF Coexistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999 4.37.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999 4.37.2 Supported Coexistence Scenario for ESP32-S3 . . . . . . . . . . . . . . . . . . . . . . . 2000 4.37.3 Coexistence Mechanism and Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000 4.37.4 How to Use the Coexistence Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001 5 ESP-IDF 5.0 Migration Guides 2003 5.1 Migrate Build System to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003 5.1.1 Migrating from make to cmake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003 5.1.2 Update fragment file grammar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003 5.1.3 Component dependencies that shall be explicit . . . . . . . . . . . . . . . . . . . . . . . 2003 5.2 Migrate Windows Environment to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003 5.3 Migrate Ethernet Drivers to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003 5.3.1 esp_eth_ioctl() API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003 5.3.2 KSZ8041/81 and LAN8720 Driver Update . . . . . . . . . . . . . . . . . . . . . . . . . 2004 5.3.3 ESP NETIF Glue Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004 5.4 Migrate FreeRTOS to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004 5.4.1 Legacy API and Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004 5.4.2 Tasks Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004 5.4.3 FreeRTOS Asserts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005 5.5 Migrate Peripherals to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005 5.5.1 Peripheral Clock Gating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005 5.5.2 SPI Flash Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005 5.5.3 ADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005 5.5.4 GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005 viii 5.5.5 Timer Group Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005 5.5.6 UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006 5.5.7 I2C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006 5.5.8 Pulse Counter Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006 5.5.9 Temperature Sensor Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2007 5.5.10 RMT Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2008 5.6 Migration of Protocol Components to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . 2008 5.6.1 Mbed TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2008 5.6.2 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2009 5.6.3 ESP HTTPS SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2009 5.6.4 ESP HTTPS OTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2009 5.7 Removed or deprecated components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010 5.8 Migrate Storage to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010 5.8.1 Breaking changes: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010 5.9 Migrate System to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011 5.9.1 Inter-Processor Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011 5.9.2 ESP Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011 5.9.3 Cache Error Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011 5.9.4 Brownout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011 5.9.5 Trax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011 5.9.6 ROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011 5.9.7 ESP HW Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011 5.9.8 ESP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012 5.9.9 SOC dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012 5.9.10 APP Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012 5.9.11 ESP Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012 5.10 Migrate Tools to ESP-IDF 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012 5.10.1 IDF Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012 5.10.2 Deprecated commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012 5.11 TCP/IP Adapter Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2013 5.11.1 Updating network connection code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2013 6 Libraries and Frameworks 2015 6.1 Cloud Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015 6.1.1 ESP RainMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015 6.1.2 AWS IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015 6.1.3 Azure IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015 6.1.4 Google IoT Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015 6.1.5 Aliyun IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015 6.1.6 Joylink IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015 6.1.7 Tencent IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016 6.1.8 Tencentyun IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016 6.1.9 Baidu IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016 6.2 Espressifns Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016 6.2.1 Espressif Audio Development Framework . . . . . . . . . . . . . . . . . . . . . . . . . 2016 6.2.2 ESP-CSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016 6.2.3 Espressif DSP Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016 6.2.4 ESP-WIFI-MESH Development Framework . . . . . . . . . . . . . . . . . . . . . . . . 2017 6.2.5 ESP-WHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017 6.2.6 ESP RainMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017 6.2.7 ESP-IoT-Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017 6.2.8 ESP-Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017 7 Contributions Guide 2019 7.1 How to Contribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2019 7.2 Before Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2019 7.3 Pull Request Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2019 7.4 Legal Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2020 ix 7.5 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2020 7.5.1 Espressif IoT Development Framework Style Guide . . . . . . . . . . . . . . . . . . . . 2020 7.5.2 Install pre-commit Hook for ESP-IDF Project . . . . . . . . . . . . . . . . . . . . . . . 2027 7.5.3 Documenting Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2028 7.5.4 Creating Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2033 7.5.5 API Documentation Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2034 7.5.6 Contributor Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036 7.5.7 Copyright Header Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2038 7.5.8 ESP-IDF Tests with Pytest Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2039 8 ESP-IDF Versions 2047 8.1 Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2047 8.2 Which Version Should I Start With? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2047 8.3 Versioning Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2047 8.4 Support Periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2048 8.5 Checking the Current Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049 8.6 Git Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2050 8.7 Updating ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2050 8.7.1 Updating to Stable Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2051 8.7.2 Updating to a Pre-Release Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2051 8.7.3 Updating to Master Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2051 8.7.4 Updating to a Release Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2052 9 Resources 2053 9.1 PlatformIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2053 9.1.1 What is PlatformIO? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2053 9.1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2053 9.1.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054 9.1.4 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054 9.1.5 Project Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054 9.1.6 Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054 9.2 Useful Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054 10 Copyrights and Licenses 2055 10.1 Software Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055 10.1.1 Firmware Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055 10.1.2 Build Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056 10.1.3 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056 10.2 ROM Source Code Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056 10.3 Xtensa libhal MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056 10.4 TinyBasic Plus MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057 10.5 TJpgDec License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057 11 About 2059 12 Switch Between Languages 2061 Index 2063 Index 2063 x Table of contents This is the documentation for Espressif IoT Development Framework (esp-idf). ESP-IDF is the official development framework for the ESP32, ESP32-S and ESP32-C Series SoCs. This document describes using ESP-IDF with the ESP32-S3 SoC. Get Started API Reference H/W Reference API Guides Contribute Resources Espressif Systems 1 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Table of contents Espressif Systems 2 Release v5.0-dev-2349-g4350e6fef8 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 1.2.1 Hardware · An ESP32-S3 board. · USB cable - USB A / micro USB B. · Computer running Windows, Linux, or macOS. Note: Currently, some of the development boards are using USB Type C connectors. Be sure you have the correct cable to connect your board! 3 Chapter 1. Get Started If you have one of ESP32-S3 official development boards listed below, you can click on the link to learn more about the hardware. 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 ESP32-S3-WROOM-1, ESP32-S3WROOM-1U, or ESP32-S3-WROOM-2, a general-purpose Wi-Fi + Bluetooth® LE MCU module that integrates complete Wi-Fi 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. Fig. 1: ESP32-S3-DevKitC-1 with ESP32-S3-WROOM-1 Module 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. · 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. 2: ESP32-S3-DevKitC-1 - front Description of Components The key components of the board are described in a counter-clockwise direction. Espressif Systems 4 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Key Component ESP32-S3-WROOM-1/1U/2 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, ESP32-S3-WROOM-1U, and ESP32-S3-WROOM2 are 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 and ESP32S3-WROOM-2 comes with a PCB antenna. ESP32-S3-WROOM-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. Note: For boards with ESP32-S3-WROOM-2 modules, the pins GPIO35, GPIO36 and GPIO37 are used for the internal communication between ESP32-S3 and SPI flash/PSRAM memory, thus not availablt for external use. 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 will quickly help you set up the development environment and then flash an application example onto your board. Contents and Packaging Espressif Systems 5 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Ordering Information The development board has a variety of variants to choose from, as shown in the table below. Ordering Code Module Integrated Flash ESP32-S3-DevKitC-1-N8 ESP32-S3-DevKitC-1N8R2 ESP32-S3-DevKitC-1N8R8 ESP32-S3-DevKitC-1N16R8V ESP32-S3-DevKitC-1N32R8V ESP32-S3-DevKitC-1UN8 ESP32-S3-DevKitC-1UN8R2 ESP32-S3-DevKitC-1UN8R8 ESP32-S3-WROOM-1-N8 ESP32-S3-WROOM-1N8R2 ESP32-S3-WROOM-1N8R8 ESP32-S3-WROOM-2N16R8V ESP32-S3-WROOM-2N32R8V ESP32-S3-WROOM-1UN8 ESP32-S3-WROOM-1UN8R2 ESP32-S3-WROOM-1UN8R8 8 MB QD 8 MB QD 8 MB QD 16 MB OT 32 MB OT 8 MB QD 8 MB QD 8 MB QD PSRAM i 2 MB QD 8 MB OT 8 MB OT 8 MB OT i 2 MB QD 8 MB OT SPI Voltage 3.3 V 3.3 V 3.3 V 1.8 V 1.8 V 3.3 V 3.3 V 3.3 V Note: In the table above, QD stands for Quad SPI and OT stands for Octal SPI. 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. Hardware Reference Block Diagram The block diagram below shows the components of ESP32-S3-DevKitC-1 and their interconnections. 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 6 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 3: ESP32-S3-DevKitC-1 (click to enlarge) 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 P: Power supply; I: Input; O: Output; T: High impedance. Espressif Systems 7 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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). Pin Layout Espressif Systems Fig. 4: ESP32-S3-DevKitC-1 Pin Layout (click to enlarge) 8 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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-WROOM-2 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]. 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. 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. 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 9 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 5: ESP32-S3-DevKitM-1 with ESP32-S3-MINI-1 Module Espressif Systems 10 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 6: ESP32-S3-DevKitM-1 - front 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 Espressif Systems 11 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started · 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 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. Hardware Reference Block Diagram The block diagram below shows the components of ESP32-S3-DevKitM-1 and their interconnections. Espressif Systems Fig. 7: ESP32-S3-DevKitM-1 (click to enlarge) 12 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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). 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 P: Power supply; I: Input; O: Output; T: High impedance. Espressif Systems 13 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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). Pin Layout Espressif Systems Fig. 8: ESP32-S3-DevKitM-1 Pin Layout (click to enlarge) 14 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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.2.2 Software To start using ESP-IDF on ESP32-S3 younll need the following software installed: · Toolchain to compile code for ESP32-S3 · 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 1.3 Installation To install all the required software, we offer some different ways to facilitate this task. Choose from one of the available options. Espressif Systems 15 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 1.3.1 IDE Note: We highly recommend installing the ESP-IDF through your favorite IDE. 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. Getting Started with VS Code IDE We have official support for Visual Studio Code and we aim to provide complete end-to-end support for all actions related to ESP-IDF: namely build, flash, monitor, debug, tracing, core-dump, System Trace Viewer, etc. Quick Install Guide The recommended way to install the ESP-IDF Visual Studio Code Extension is by downloading it from VS Code Marketplace or following Quick Installation Guide. Review the tutorials for the ESP-IDF Visual Studio Code Extension to learn how to use all of the features. Supported Features · Setup, will help you to quickly install ESP-IDF and its relevant toolchain with just a 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 a built-in terminal, you can trigger IDF Monitor Commands from within VS Code as you are used to in traditional terminals. · Debugging, with out-of-the-box hardware debugging. · GUI Menu Config, provides a simplified UI for configuring your chip. · App & Heap Tracing, provides support for collecting traces from your application, and a simplified UI for analyzing them. · System View Tracing Viewer, aims to read and display the .svdat files into the trace UI (we also support multiple core tracing views). · IDF Size Analysis Overview presents a UI for binary size analysis. · Rainmaker Cloud, inbuilt Rainmaker Cloud support where you can edit/read the state of your connected IoT devices easily. For more information see the ESP Rainmaker page. · Code Coverage, inbuilt code coverage support with color highlights showing which lines have been covered. The HTML report renders 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 you ask your question in the forum, or open a GitHub Issue for our dev teams to review. We also welcome new feature requests. Most of the features we have today are a result of people asking for them to be implemented. To improve certain aspects of the extension, raise your feature request on GitHub. 1.3.2 Manual Installation For the manual procedure, please select according to your operating system. Espressif Systems 16 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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. Windows Installer Download What is the usecase for Online and Offline Installer Online Installer is very small and allows the installation of all available releases of ESP-IDF. The installer will download only necessary dependencies including Git For Windows during the installation process. The installer stores downloaded files in the cache directory %userprofile%\. espressif Offline Installer does not require any network connection. The installer contains all required dependencies including Git For Windows . Components of the installation The installer deploys the following components: · Embedded Python · Cross-compilers · OpenOCD · CMake and Ninja build tools · ESP-IDF The installer also allows reusing the existing directory with ESP-IDF. The recommended directory is %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: Espressif Systems 17 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 9: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF PowerShell Environment Espressif Systems Fig. 10: ESP-IDF PowerShell 18 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Run ESP-IDF Command Prompt (cmd.exe): Fig. 11: Completing the ESP-IDF Tools Setup Wizard with 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. 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. First Steps on ESP-IDF Now you have all requirements met, the next topic will guide you on how to start your first project. This guide will help you on the first steps using ESP-IDF. Follow this guide to start a new project on the ESP32-S3 and build, flash, and monitor the device output. Note: If you havennt yet installed the ESP-IDF, please go to Installation and follow the instruction in oder to get Espressif Systems 19 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 12: ESP-IDF Command Prompt Espressif Systems 20 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started all the software needed to use this guide. Start a Project Now you are ready to prepare your application for ESP32-S3. You can start with getstarted/hello_world project from examples directory in IDF. Important: The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects. Copy the project get-started/hello_world to ~/esp directory: Windows cd %userprofile%\esp xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world Linux/macOS cd ~/esp cp -r $IDF_PATH/examples/get-started/hello_world . Note: 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. 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. Configure your Project Navigate to your hello_world directory, set ESP32-S3 chip as the target and run the project configuration utility menuconfig. Windows cd %userprofile%\esp\hello_world idf.py set-target esp32s3 idf.py menuconfig Linux/macOS cd ~/esp/hello_world idf.py set-target esp32s3 idf.py menuconfig Espressif Systems 21 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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 configurations, they will be cleared and initialized. The target may be saved in the 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. 13: 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. 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 -- Component names: ... -- Component paths: ... ... (more lines of build system output) [527/527] Generating hello_world.bin esptool.py v2.3.1 Project build complete. To flash, run this command: (continues on next page) Espressif Systems 22 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started (continued from previous page) ../../../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. 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. 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. Encountered Issues While Flashing? If you run the given command and see errors such asoFailed 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). · 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. 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 (continues on next page) Espressif Systems 23 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started (continued from previous page) 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. Monitor the Output To check if ohello_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 <PORT> 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 <PORT> 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 ... Espressif Systems 24 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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 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. 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.7 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. 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: Espressif Systems 25 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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. 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 Espressif Systems 26 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 14: USB to UART bridge of ESP32-DevKitC in Windows Device Manager Espressif Systems 27 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 15: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager Espressif Systems 28 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started ls /dev/cu.* 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 29 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 16: Setting Serial Communication in PuTTY on Windows Espressif Systems 30 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Fig. 17: Setting Serial Communication in PuTTY on Linux Espressif Systems 31 Release v5.0-dev-2349-g4350e6fef8 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 5. First Steps on ESP-IDF when installing s/w for ESP32-S3 development, then you can continue with Step 5. First Steps on ESP-IDF. 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 32 Release v5.0-dev-2349-g4350e6fef8 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) · Ctrl+X (or X) Ctrl+C 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 Exit the program 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: Espressif Systems 33 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled. Register dump: PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00 A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000 A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0 A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0 A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000 Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90 IDF Monitor adds more details to the dump: Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled. Register dump: PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00 0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/ hello_world/main/./hello_world_main.c:57 (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_ world/main/./hello_world_main.c:52 A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000 A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0 A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0 A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000 Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90 0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/ hello_world/main/./hello_world_main.c:57 (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_ world/main/./hello_world_main.c:52 0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_ world/main/./hello_world_main.c:47 0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/ main/./hello_world_main.c:42 0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/ ./hello_world_main.c:33 0x400d071d: main_task at /home/gus/esp/32/idf/components/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 Espressif Systems 34 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started option: idf_monitor.py --disable-address-decoding to disable address decoding. Launching GDB with GDBStub By default, if esp-idf crashes, the panic handler prints relevant registers and the stack dump (similar to the ones above) over the serial port. Then it resets the board. Furthermore, the application can be configured to run GDBStub in the background and handle the Ctrl+C event from the monitor. Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware. To enable GDBStub on panic, open the project configuration menu (idf.py menuconfig) and set 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. Espressif Systems 35 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started · Rule "tag1:I tag2:W" only prints tag1 at the Info verbosity level or lower and tag2 at the Warning verbosity level or lower. · Rule "tag1:I tag2:W tag3:N" is essentially equivalent to the previous one because tag3:N specifies that tag3 should not be printed. · tag3:N in the rule "tag1:I tag2:W tag3:N *:V" is more meaningful because without tag3:N the tag3 messages could have been printed; the errors for tag1 and tag2 will be printed at the specified (or lower) verbosity level and everything else will be printed by default. A More Complex Filtering Example The following log snippet was acquired without any filtering options: load:0x40078000,len:13564 entry 0x40078d4c E (31) esp_image: image at 0x30000 has invalid magic byte W (31) esp_image: image at 0x30000 has invalid SPI mode 255 E (39) boot: Factory app partition is not bootable I (568) cpu_start: Pro cpu up. I (569) heap_init: Initializing. RAM available for dynamic allocation: I (603) cpu_start: Pro cpu start user code D (309) light_driver: [light_init, 74]:status: 1, mode: 2 D (318) vfs: esp_vfs_register_fd_range is successful for range <54; 64) and VFS ID 1 I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0 The captured output for the filtering options PRINT_FILTER="wifi esp_image:E light_driver:I" is given below: E (31) esp_image: image at 0x30000 has invalid magic byte I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0 The options ``PRINT_FILTER="light_driver:D esp_image:N boot:N cpu_start:N vfs:N wifi:N *:V" show the following output: load:0x40078000,len:13564 entry 0x40078d4c I (569) heap_init: Initializing. RAM available for dynamic allocation: D (309) light_driver: [light_init, 74]:status: 1, mode: 2 Known Issues with IDF Monitor Issues Observed on Windows · Arrow keys, as well as some other keys, do not work in GDB due to Windows Console limitations. · Occasionally, when 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. Standard Toolchain Setup for Linux and macOS Installation Step by Step This is a detailed roadmap to walk you through the installation process. Setting up Development Environment These are the steps for setting up the ESP-IDF for your ESP32-S3. · Step 1. Install Prerequisites · Step 2. Get ESP-IDF · Step 3. Set up the tools · Step 4. Set up the environment variables · Step 5. First Steps on ESP-IDF Espressif Systems 36 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Step 1. Install Prerequisites In order to use ESP-IDF with the ESP32-S3, you need to install some software packages based on your Operating System. This setup guide will help you on getting everything installed on Linux and macOS based systems. For Linux Users To compile using ESP-IDF you will 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. For macOS Users ESP-IDF will use the version of Python installed by default on macOS. · Install pip: sudo easy_install pip · Install CMake & Ninja build: If you have HomeBrew, you can run: brew install cmake ninja dfu-util If you have MacPorts, you can run: sudo port install cmake ninja dfu-util Otherwise, consult the CMake and Ninja home pages for macOS installation downloads. · It is strongly recommended to also install ccache for faster builds. If you have HomeBrew, this can be done via brew install ccache or sudo port install ccache on MacPorts. Note: If an error like this is shown during any step: xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun Then you will need to install the XCode command line tools to continue. You can install these by running xcodeselect --install. Espressif Systems 37 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Installing Python 3 Based 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 the above command returns an error, it means Python 3 is not installed. Below is an overview of the 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 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. 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. 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, for projects supporting ESP32-S3. cd ~/esp/esp-idf ./install.sh esp32s3 or with Fish shell cd ~/esp/esp-idf ./install.fish esp32s3 The above commands install tools for ESP32-S3 only. If you intend to develop projects for more chip targets then you should list all of them and run for example: cd ~/esp/esp-idf ./install.sh esp32,esp32s2 or with Fish shell cd ~/esp/esp-idf ./install.fish esp32,esp32s2 In order to install tools for all supported targets please run the following command: Espressif Systems 38 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started cd ~/esp/esp-idf ./install.sh all or with Fish shell cd ~/esp/esp-idf ./install.fish all 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. 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 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. 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. 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. 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 39 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Step 5. First Steps on ESP-IDF Now you have all requirements met, the next topic will guide you on how to start your first project. This guide will help you on the first steps using ESP-IDF. Follow this guide to start a new project on the ESP32-S3 and build, flash, and monitor the device output. Note: If you havennt yet installed the ESP-IDF, please go to Installation and follow the instruction in oder to get all the software needed to use this guide. Start a Project Now you are ready to prepare your application for ESP32-S3. You can start with getstarted/hello_world project from examples directory in IDF. Important: The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects. Copy the project get-started/hello_world to ~/esp directory: Windows cd %userprofile%\esp xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world Linux/macOS cd ~/esp cp -r $IDF_PATH/examples/get-started/hello_world . Note: 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. 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. Configure your Project Navigate to your hello_world directory, set ESP32-S3 chip as the target and run the project configuration utility menuconfig. Windows cd %userprofile%\esp\hello_world idf.py set-target esp32s3 idf.py menuconfig Espressif Systems 40 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Linux/macOS cd ~/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 configurations, they will be cleared and initialized. The target may be saved in the 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. 18: 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. 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 -- Component names: ... -- Component paths: ... ... (more lines of build system output) (continues on next page) Espressif Systems 41 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started (continued from previous page) [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. 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. 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. Encountered Issues While Flashing? If you run the given command and see errors such asoFailed 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). · 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. Normal Operation When flashing, you will see the output log similar to the following: Espressif Systems 42 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started ... 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. Monitor the Output To check if ohello_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 <PORT> 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 <PORT> 115200 --- (continues on next page) Espressif Systems 43 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started (continued from previous page) --- 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 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. 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.7 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. Tip: Updating ESP-IDF It is recommended to update ESP-IDF from time to time, as newer versions fix bugs and/or provide new features. Please note that each ESP-IDF major and minor release version has an associated support period, and when one release branch is approaching end of life (EOL), all users are encouraged to upgrade their projects to more recent ESP-IDF releases, to find out more about support periods, see ESP-IDF Versions. Espressif Systems 44 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started 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. Related Documents 1.4 Build Your First Project If you already have the ESP-IDF installed and not using IDE, you can build your first project from the command line following Step 5. First Steps on ESP-IDF. Espressif Systems 45 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 1. Get Started Espressif Systems 46 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2 API Reference 2.1 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.1.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.1.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" (continues on next page) 47 Chapter 2. API Reference }; esp_timer_handle_t my_timer; esp_err_t err = esp_timer_create(&my_timer_args, &my_timer); (continued from previous page) Initialization functions never store the pointer to the configuration structure, so it is safe to allocate the structure on the stack. The application must initialize all fields of the structure. The following is incorrect: esp_timer_create_args_t my_timer_args; my_timer_args.callback = &my_timer_callback; /* Incorrect! Fields .arg and .name are not initialized */ esp_timer_create(&my_timer_args, &my_timer); Most ESP-IDF examples use C99 designated initializers for structure initialization, since they provide a concise way of setting a subset of fields, and zero-initializing the remaining fields: const esp_timer_create_args_t my_timer_args = { .callback = &my_timer_callback, /* Correct, fields .arg and .name are zero-initialized */ }; C++ language 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.1.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.1.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. Espressif Systems 48 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference It is not recommended to reference these components directly in custom projects (via EXTRA_COMPONENT_DIRS build system variable), as they may change significantly between ESP-IDF versions. When starting a new project based on an ESP-IDF example, copy both the project and the common components it depends on out of ESP-IDF, and treat the common components as part of the project. Note that the common components are written with examples in mind, and might not include all the error handling required for production applications. Take time to read the code and understand if it applicable to your use case. 2.1.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. Espressif Systems 49 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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.2 Application Protocols 2.2.1 ASIO port Overview Asio is a cross-platform C++ library, see https://think-async.com. It provides a consistent asynchronous model using a modern C++ approach. ASIO documentation Please refer to the original asio documentation at https://think-async.com/Asio/ Documentation. Asio also comes with a number of examples which could be find under Documentation/Examples on that web site. Supported features ESP platform port currently supports only network asynchronous socket operations; does not support serial port. SSL/TLS support is disabled by default and could be enabled in component configuration menu by choosing TLS library from · mbedTLS with OpenSSL translation layer (default option) · wolfSSL SSL support is very basic at this stage and it does include following features: · Verification callbacks · DH property files · Certificates/private keys file APIs Internal asio settings for ESP include · EXCEPTIONS are enabled in ASIO if enabled in menuconfig · TYPEID is enabled in ASIO if enabled in menuconfig Application Example ESP examples are based on standard asio protocols/asio: · protocols/asio/udp_echo_server · protocols/asio/tcp_echo_server · protocols/asio/asio_chat · protocols/asio/ssl_client_server Please refer to the specific example README.md for details 2.2.2 ESP-Modbus Overview The Modbus serial communication protocol is de facto standard protocol widely used to connect industrial electronic devices. Modbus allows communication among many devices connected to the same network, for example, a system that measures temperature and humidity and communicates the results to a computer. The Modbus protocol uses several types of data: Holding Registers, Input Registers, Coils (single bit output), Discrete Inputs. Versions of the Modbus protocol exist for serial port and for Ethernet and other protocols that support the Internet protocol suite. There are many variants of Modbus protocols, some of them are: Espressif Systems 50 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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); (continues on next page) Espressif Systems 51 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 1: Modbus segment diagram Espressif Systems Fig. 2: Modbus data mapping 52 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference if (master_handler == NULL || err != ESP_OK) { ESP_LOGE(TAG, "mb controller initialization fail."); } (continued from previous page) 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 53 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Table 1: 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 2: 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 54 Release v5.0-dev-2349-g4350e6fef8 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 55 Release v5.0-dev-2349-g4350e6fef8 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 56 Release v5.0-dev-2349-g4350e6fef8 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, ¶m_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 57 Release v5.0-dev-2349-g4350e6fef8 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 3: 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 58 Release v5.0-dev-2349-g4350e6fef8 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(¶m_lock); holding_reg_area[2] += 10; portEXIT_CRITICAL(¶m_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 59 Release v5.0-dev-2349-g4350e6fef8 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 4: 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_PERIOD_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(®_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 60 Release v5.0-dev-2349-g4350e6fef8 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 61 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Table 5: 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 62 Release v5.0-dev-2349-g4350e6fef8 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 63 Release v5.0-dev-2349-g4350e6fef8 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 64 Release v5.0-dev-2349-g4350e6fef8 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 65 Release v5.0-dev-2349-g4350e6fef8 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 66 Release v5.0-dev-2349-g4350e6fef8 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 67 Release v5.0-dev-2349-g4350e6fef8 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 68 Release v5.0-dev-2349-g4350e6fef8 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 69 Release v5.0-dev-2349-g4350e6fef8 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 70 Release v5.0-dev-2349-g4350e6fef8 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 71 Release v5.0-dev-2349-g4350e6fef8 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.2.3 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: Espressif Systems 72 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference mqtt://username:[email protected]:1884 MQTT over TCP, port 1884, with username and password · MQTT over SSL samples: mqtts://mqtt.eclipseprojects.io: MQTT over SSL, port 8883 mqtts://mqtt.eclipseprojects.io:8884: MQTT over SSL, port 8884 · MQTT over Websocket samples: ws://mqtt.eclipseprojects.io:80/mqtt · MQTT over Websocket Secure samples: wss://mqtt.eclipseprojects.io:443/mqtt · Minimal configurations: const esp_mqtt_client_config_t mqtt_cfg = { .uri = "mqtt://mqtt.eclipseprojects.io", // .user_context = (void *)your_context }; esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg); esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client); esp_mqtt_client_start(client); · Note: By default mqtt client uses event loop library to post related mqtt events (connected, subscribed, 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/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 Espressif Systems 73 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · lwt_retain: specifies the retain flag of the LWT message Other Configuration Parameters · disable_clean_session: determines the clean session flag for the connect message, defaults to a clean session · keepalive: determines how many seconds the client will wait for a ping response before disconnecting, default is 120 seconds. · disable_auto_reconnect: enable to stop the client from reconnecting to server after errors or 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. Espressif Systems 74 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · MQTT_EVENT_ERROR: The client has encountered an error. esp_mqtt_error_type_t from error_handle in the event data can be used to further determine the type of the error. The type of error will determine which parts of the error_handle struct is filled. API Reference Header File · components/mqtt/esp-mqtt/include/mqtt_client.h Functions esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config) Creates mqtt client handle based on the configuration. Return mqtt_client_handle if successfully created, NULL on error Parameters · config: mqtt configuration structure esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, const char *uri) Sets mqtt connection URI. This API is usually used to overrides the URI configured in esp_mqtt_client_init. Return ESP_FAIL if URI parse error, ESP_OK on success Parameters · client: mqtt client handle · uri: esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client) Starts mqtt client with already created client handle. Return ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on other error Parameters · 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 Espressif Systems 75 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 76 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client) Destroys the client handle. Notes: · Cannot be called from the mqtt event handler Return ESP_OK ESP_ERR_INVALID_ARG on wrong initialization Parameters · 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 Espressif Systems 77 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int esp_tls_stack_err tls specific error code reported from underlying tls stack int esp_tls_cert_verify_flags tls flags reported from underlying tls stack during certificate verification esp_mqtt_error_type_t error_type error type referring to the source of the error esp_mqtt_connect_return_code_t connect_return_code connection refused error code reported from MQTT broker on connection int esp_transport_sock_errno errno from the underlying socket struct esp_mqtt_event_t MQTT event configuration structure Public Members esp_mqtt_event_id_t event_id MQTT event type esp_mqtt_client_handle_t client MQTT client handle for this event void *user_context User context passed from MQTT client config char *data Data associated with this event int data_len Length of the data for this event int total_data_len Total length of the data (longer data are supplied with multiple events) int current_data_offset Actual offset for the data associated with this event char *topic Topic associated with this event int topic_len Length of the topic for this event associated with this event int msg_id MQTT messaged id of message int session_present MQTT session_present flag for connection event esp_mqtt_error_codes_t *error_handle esp-mqtt error handle including esp-tls errors as well as internal mqtt errors bool retain Retained flag of the message associated with this event 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 Espressif Systems 78 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members mqtt_event_callback_t event_handle handle for MQTT events as a callback in legacy mode esp_event_loop_handle_t event_loop_handle handle for MQTT event loop library const char *host MQTT server domain (ipv4 as string) const char *uri Complete MQTT broker URI uint32_t port MQTT server port 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) Espressif Systems 79 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_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 Espressif Systems 80 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference void *ds_data carrier of handle for digital signature parameters int network_timeout_ms Abort network operation if it is not completed after this value, in milliseconds (defaults to 10s) bool disable_keepalive Set disable_keepalive=true to turn off keep-alive mechanism, false by default (keepalive is active by default). Note: setting the config value keepalive to 0 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 Espressif Systems 81 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference MQTT_EVENT_DISCONNECTED disconnected event MQTT_EVENT_SUBSCRIBED subscribed event, additional context: · 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 Espressif Systems 82 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Values: MQTT_ERROR_TYPE_NONE = 0 MQTT_ERROR_TYPE_TCP_TRANSPORT MQTT_ERROR_TYPE_CONNECTION_REFUSED enum esp_mqtt_transport_t Values: MQTT_TRANSPORT_UNKNOWN = 0x0 MQTT_TRANSPORT_OVER_TCP MQTT over TCP, using scheme: mqtt MQTT_TRANSPORT_OVER_SSL MQTT over SSL, using scheme: mqtts MQTT_TRANSPORT_OVER_WS MQTT over Websocket, using scheme:: ws MQTT_TRANSPORT_OVER_WSS MQTT over Websocket Secure, using scheme: wss enum esp_mqtt_protocol_ver_t MQTT protocol version used for connection Values: MQTT_PROTOCOL_UNDEFINED = 0 MQTT_PROTOCOL_V_3_1 MQTT_PROTOCOL_V_3_1_1 2.2.4 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 (continues on next page) Espressif Systems 83 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_tls_mbedtls.h esp_tls_wolfssl.h (continued from previous page) 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.: Espressif Systems 84 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (First change directory (cd) to your project directory) mkdir components cd components git clone https://github.com/espressif/esp-wolfssl.git 2) Add wolfssl as an extra component in your project. · Download wolfssl with: git clone https://github.com/espressif/esp-wolfssl.git · Include esp-wolfssl in ESP-IDF with setting EXTRA_COMPONENT_DIRS in CMakeLists.txt of your project as done in wolfssl/examples. For reference see Optional Project variables in build-system. After above steps, you will have option to choose wolfssl as underlying SSL/TLS library in configuration menu of your project as follows: idf.py menuconfig -> ESP-TLS -> choose SSL/TLS Library -> mbedtls/wolfssl Comparison between mbedtls and wolfssl The following table shows a typical comparison between wolfssl and mbedtls when protocols/https_request 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 */ (continues on next page) Espressif Systems 85 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference .ds_data = (void *)ds_ctx, }; (continued from previous page) 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. Espressif Systems 86 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 87 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return · >0 if read operation was successful, the return value is the number of bytes actually read from the TLS/SSL connection. · 0 if read operation was not successful. The underlying connection was closed. · <0 if read operation was not successful, because either an error occured or an action must be taken by the calling process. Parameters · [in] 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 Espressif Systems 88 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · 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 Espressif Systems 89 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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. · [out] error_handle: ESP-TLS error handle holding potential errors occurred during con- nection · [out] sockfd: Socket descriptor if successfully connected on TCP layer Structures struct psk_key_hint ESP-TLS preshared key and hint structure. Public Members const uint8_t *key key in PSK authentication mode in binary format const size_t key_size length of the key const char *hint hint in PSK authentication mode in string format struct tls_keep_alive_cfg esp-tls client session ticket ctx Keep alive parameters structure Public Members bool keep_alive_enable Enable keep-alive timeout int keep_alive_idle Keep-alive idle time (second) int keep_alive_interval Keep-alive interval time (second) int keep_alive_count Keep-alive packet retry send count struct esp_tls_cfg ESP-TLS configuration parameters. Note Note about format of certificates: · This structure includes certificates of a Certificate Authority, of client or server as well as private keys, which may be of PEM or DER format. In case of PEM format, the buffer must be NULL terminated (with NULL character included in certificate size). · Certificate 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 Espressif Systems 90 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 91 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference bool skip_common_name Skip any validation of server certificate CN field tls_keep_alive_cfg_t *keep_alive_cfg Enable TCP keep-alive timeout for SSL connection const psk_hint_key_t *psk_hint_key Pointer to PSK hint and key. if not NULL (and certificates are NULL) then PSK authentication is enabled with configured setup. Important note: the pointer must be valid for connection 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. Espressif Systems 92 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_tls_conn_state_t conn_state ESP-TLS Connection state fd_set rset read file descriptors fd_set wset write file descriptors bool is_tls indicates connection type (TLS or NON-TLS) esp_tls_role_t role esp-tls role · ESP_TLS_CLIENT · ESP_TLS_SERVER esp_tls_error_handle_t error_handle handle to error descriptor Type Definitions typedef enum esp_tls_conn_state esp_tls_conn_state_t ESP-TLS Connection State. typedef enum esp_tls_role esp_tls_role_t typedef struct psk_key_hint psk_hint_key_t ESP-TLS preshared key and hint structure. typedef struct tls_keep_alive_cfg tls_keep_alive_cfg_t esp-tls client session ticket ctx Keep alive parameters structure typedef struct esp_tls_cfg esp_tls_cfg_t ESP-TLS configuration parameters. Note Note about format of certificates: · This structure includes certificates of a Certificate Authority, of client or server as well as private keys, which may be of PEM or DER format. In case of PEM format, the buffer must be NULL terminated (with NULL character included in certificate size). · Certificate 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 Espressif Systems 93 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference enum esp_tls_role Values: ESP_TLS_CLIENT = 0 ESP_TLS_SERVER Header File · components/esp-tls/esp_tls_errors.h Structures struct esp_tls_last_error Error structure containing relevant errors in case tls error occurred. Public Members esp_err_t last_error error code (based on ESP_ERR_ESP_TLS_BASE) of the last occurred error int esp_tls_error_code esp_tls error code from last esp_tls failed api int esp_tls_flags last certification verification flags Macros ESP_ERR_ESP_TLS_BASE Starting number of ESP-TLS error codes ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAME Error if hostname couldnnt be resolved upon tls connection ESP_ERR_ESP_TLS_CANNOT_CREATE_SOCKET Failed to create socket ESP_ERR_ESP_TLS_UNSUPPORTED_PROTOCOL_FAMILY Unsupported protocol family ESP_ERR_ESP_TLS_FAILED_CONNECT_TO_HOST Failed to connect to host ESP_ERR_ESP_TLS_SOCKET_SETOPT_FAILED failed to set/get socket option ESP_ERR_ESP_TLS_CONNECTION_TIMEOUT new connection in esp_tls_low_level_conn connection timeouted ESP_ERR_ESP_TLS_SE_FAILED ESP_ERR_ESP_TLS_TCP_CLOSED_FIN ESP_ERR_MBEDTLS_CERT_PARTLY_OK mbedtls parse certificates was partly successful ESP_ERR_MBEDTLS_CTR_DRBG_SEED_FAILED mbedtls api returned error ESP_ERR_MBEDTLS_SSL_SET_HOSTNAME_FAILED mbedtls api returned error ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED mbedtls api returned error Espressif Systems 94 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_ERR_MBEDTLS_SSL_CONF_ALPN_PROTOCOLS_FAILED mbedtls api returned error ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED mbedtls api returned error ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILED mbedtls api returned error ESP_ERR_MBEDTLS_SSL_SETUP_FAILED mbedtls api returned error ESP_ERR_MBEDTLS_SSL_WRITE_FAILED mbedtls api returned error ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_CONF_PSK_FAILED mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_TICKET_SETUP_FAILED mbedtls api returned failed ESP_ERR_WOLFSSL_SSL_SET_HOSTNAME_FAILED wolfSSL api returned error ESP_ERR_WOLFSSL_SSL_CONF_ALPN_PROTOCOLS_FAILED wolfSSL api returned error ESP_ERR_WOLFSSL_CERT_VERIFY_SETUP_FAILED wolfSSL api returned error ESP_ERR_WOLFSSL_KEY_VERIFY_SETUP_FAILED wolfSSL api returned error ESP_ERR_WOLFSSL_SSL_HANDSHAKE_FAILED wolfSSL api returned failed ESP_ERR_WOLFSSL_CTX_SETUP_FAILED wolfSSL api returned failed ESP_ERR_WOLFSSL_SSL_SETUP_FAILED wolfSSL api returned failed ESP_ERR_WOLFSSL_SSL_WRITE_FAILED wolfSSL api returned failed ESP_TLS_ERR_SSL_WANT_READ Definition of errors reported from IO API (potentially non-blocking) in case of error: · esp_tls_conn_read() · esp_tls_conn_write() ESP_TLS_ERR_SSL_WANT_WRITE ESP_TLS_ERR_SSL_TIMEOUT Type Definitions typedef struct esp_tls_last_error *esp_tls_error_handle_t typedef struct esp_tls_last_error esp_tls_last_error_t Error structure containing relevant errors in case tls error occurred. Espressif Systems 95 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Enumerations enum esp_tls_error_type_t Definition of different types/sources of error codes reported from different components Values: ESP_TLS_ERR_TYPE_UNKNOWN = 0 ESP_TLS_ERR_TYPE_SYSTEM System error errno ESP_TLS_ERR_TYPE_MBEDTLS Error code from mbedTLS library ESP_TLS_ERR_TYPE_MBEDTLS_CERT_FLAGS Certificate flags defined in mbedTLS ESP_TLS_ERR_TYPE_ESP ESP-IDF error type esp_err_t ESP_TLS_ERR_TYPE_WOLFSSL Error code from wolfSSL library ESP_TLS_ERR_TYPE_WOLFSSL_CERT_FLAGS Certificate flags defined in wolfSSL ESP_TLS_ERR_TYPE_MAX Last err type invalid entry 2.2.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: · 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. Espressif Systems 96 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) · 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. Espressif Systems 97 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 98 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 99 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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. 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 Espressif Systems 100 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · (-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 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) Espressif Systems 101 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · (-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. 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) Espressif Systems 102 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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 Espressif Systems 103 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 104 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 105 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 106 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 107 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference HTTP_METHOD_NOTIFY HTTP NOTIFY Method HTTP_METHOD_SUBSCRIBE HTTP SUBSCRIBE Method HTTP_METHOD_UNSUBSCRIBE HTTP UNSUBSCRIBE Method HTTP_METHOD_OPTIONS HTTP OPTIONS Method HTTP_METHOD_COPY HTTP COPY Method HTTP_METHOD_MOVE HTTP MOVE Method HTTP_METHOD_LOCK HTTP LOCK Method HTTP_METHOD_UNLOCK HTTP UNLOCK Method HTTP_METHOD_PROPFIND HTTP PROPFIND Method HTTP_METHOD_PROPPATCH HTTP PROPPATCH Method HTTP_METHOD_MKCOL HTTP MKCOL Method HTTP_METHOD_MAX enum esp_http_client_auth_type_t HTTP Authentication type. Values: HTTP_AUTH_TYPE_NONE = 0 No authention HTTP_AUTH_TYPE_BASIC HTTP Basic authentication HTTP_AUTH_TYPE_DIGEST HTTP Disgest authentication enum HttpStatus_Code Enum for the HTTP status codes. Values: HttpStatus_Ok = 200 HttpStatus_MultipleChoices = 300 HttpStatus_MovedPermanently = 301 HttpStatus_Found = 302 HttpStatus_SeeOther = 303 HttpStatus_TemporaryRedirect = 307 HttpStatus_PermanentRedirect = 308 HttpStatus_BadRequest = 400 HttpStatus_Unauthorized = 401 Espressif Systems 108 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference HttpStatus_Forbidden = 403 HttpStatus_NotFound = 404 HttpStatus_InternalError = 500 2.2.6 ESP Local Control Overview ESP Local Control (esp_local_ctrl) component in ESP-IDF provides capability to control an ESP device over Wi-Fi + HTTPS or BLE. It provides access to application defined properties that are available for reading / writing via a set of configurable handlers. Initialization of the esp_local_ctrl service over BLE transport is performed as follows: esp_local_ctrl_config_t config = { .transport = ESP_LOCAL_CTRL_TRANSPORT_BLE, .transport_config = { .ble = & (protocomm_ble_config_t) { .device_name = SERVICE_NAME, .service_uuid = { /* LSB <--------------------------------------- * ---------------------------------------> MSB */ 0x21, 0xd5, 0x3b, 0x8d, 0xbd, 0x75, 0x68, 0x8a, 0xb4, 0x42, 0xeb, 0x31, 0x4a, 0x1e, 0x98, 0x3d } } }, .proto_sec = { .version = PROTOCOM_SEC0, .custom_handle = NULL, .pop = NULL, }, .handlers = { /* User defined handler functions */ .get_prop_values = get_property_values, .set_prop_values = set_property_values, .usr_ctx = NULL, .usr_ctx_free_fn = NULL }, /* Maximum number of properties that may be set */ .max_properties = 10 }; /* Start esp_local_ctrl service */ ESP_ERROR_CHECK(esp_local_ctrl_start(&config)); Similarly for HTTPS transport: /* Set the configuration */ httpd_ssl_config_t https_conf = HTTPD_SSL_CONFIG_DEFAULT(); /* Load server certificate */ extern const unsigned char servercert_start[] asm("_binary_servercert_pem_ start"); extern const unsigned char servercert_end[] asm("_binary_servercert_pem_ end"); https_conf.servercert = servercert_start; https_conf.servercert_len = servercert_end - servercert_start; /* Load server private key */ (continues on next page) Espressif Systems 109 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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 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, (continues on next page) Espressif Systems 110 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference .ctx_free_fn = NULL }; /* Now register the property */ esp_local_ctrl_add_property(×tamp); (continued from previous page) Also notice that there is a ctx field, which is set to point to some custom func_get_time(). This can be used inside the property get / set handlers to retrieve timestamp. Here is an example of get_prop_values() handler, which is used for retrieving the timestamp. static esp_err_t get_property_values(size_t props_count, const esp_local_ctrl_prop_t *props, esp_local_ctrl_prop_val_t *prop_ values, void *usr_ctx) { for (uint32_t i = 0; i < props_count; i++) { ESP_LOGI(TAG, "Reading %s", props[i].name); if (props[i].type == TYPE_TIMESTAMP) { /* Obtain the timer function from ctx */ int32_t (*func_get_time)(void) = props[i].ctx; /* Use static variable for saving the value. * This is essential because the value has to be * valid even after this function returns. * Alternative is to use dynamic allocation * and set the free_fn field */ static int32_t ts = func_get_time(); prop_values[i].data = &ts; } } return ESP_OK; } Here is an example of set_prop_values() handler. Notice how we restrict from writing to read-only properties. static esp_err_t set_property_values(size_t props_count, const esp_local_ctrl_prop_t *props, const esp_local_ctrl_prop_val_t *prop_values, void *usr_ctx) { for (uint32_t i = 0; i < props_count; i++) { if (props[i].flags & READONLY) { ESP_LOGE(TAG, "Cannot write to read-only property %s", props[i].name); return ESP_ERR_INVALID_ARG; } else { ESP_LOGI(TAG, "Setting %s", props[i].name); /* For keeping it simple, lets only log the incoming data */ ESP_LOG_BUFFER_HEX_LEVEL(TAG, prop_values[i].data, prop_values[i].size, ESP_LOG_INFO); } } return ESP_OK; } For complete example see protocols/esp_local_ctrl Espressif Systems 111 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 6: 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 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. Espressif Systems 112 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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. Espressif Systems 113 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_local_ctrl_transport_config_httpd_t *httpd This is same as httpd_ssl_config_t. See esp_https_server.h for available configuration parameters. Structures struct esp_local_ctrl_prop Property description data structure, which is to be populated and passed to the esp_local_ctrl_add_property() function. Once a property is added, its structure is available for read-only access inside get_prop_values() and set_prop_values() handlers. Public Members char *name Unique name of property uint32_t type Type of property. This may be set to application defined enums size_t size Size of the property value, which: · if zero, the property can have values of variable size · if non-zero, the property can have values of fixed size only, therefore, checks are performed internally by esp_local_ctrl when setting the value of such a property uint32_t flags Flags set for this property. This could be a bit field. A flag may indicate property behavior, e.g. read-only / constant void *ctx Pointer to some context data relevant for this property. This will be available for use inside the get_prop_values and set_prop_values handlers as a part of this property structure. When set, this is valid throughout the lifetime of a property, till either the property is removed or the esp_local_ctrl service is stopped. void (*ctx_free_fn)(void *ctx) Function used by esp_local_ctrl to internally free the property context when esp_local_ctrl_remove_property() or esp_local_ctrl_stop() is called. struct esp_local_ctrl_prop_val Property value data structure. This gets passed to the get_prop_values() and set_prop_values() handlers for the purpose of retrieving or setting the present value of a property. Public Members void *data Pointer to memory holding property value size_t size Size of property value void (*free_fn)(void *data) This may be set by the application in get_prop_values() handler to tell esp_local_ctrl to call this function on the data pointer above, for freeing its resources after sending the get_prop_values response. struct esp_local_ctrl_handlers Handlers for receiving and responding to local control commands for getting and setting properties. Espressif Systems 114 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 115 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 116 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.2.7 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 Espressif Systems 117 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 118 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · · · · · · · 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 Espressif Systems 119 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 3. The master do the last RDDMA transaction of 512 bytes (equal, longer, or shorter than the total length loaded by the slave are all allowed). The first 508 bytes are valid data from the slave, while the last 4 bytes are meaningless bytes. 4. The master sends CMD8 to the slave 5. The slave loads another 4092 bytes of data onto the RDDMA 6. The master can start new reading transactions after it sends the CMD8 Terminology · ESSL: Abbreviation for ESP Serial Slave Link, the component described by this document. · Master: The device running the esp_serial_slave_link component. · ESSL device: a virtual device on the master associated with an ESP slave device. The device context has the knowledge of the slave protocol above the bus, relying on some bus drivers to communicate with the slave. · ESSL device handle: a handle to ESSL device context containing the configuration, status and data required by the ESSL component. The context stores the driver configurations, communication state, data shared by master and slave, etc. The context should be initialized before it is used, and get deinitialized if not used any more. The master application operates on the ESSL device through this handle. · ESP slave: the slave device connected to the bus, which ESSL component is designed to communicate with. · Bus: The bus over which the master and the slave communicate with each other. · Slave protocol: The special communication protocol specified by Espressif HW/SW over the bus. · TX buffer num: a counter, which is on the slave and can be read by the master, indicates the accumulated buffer numbers that the slave has loaded to the hardware to receive data from the master. · RX data size: a counter, which is on the slave and can be read by the master, indicates the accumulated data size that the slave has loaded to the hardware to send to the master. Services provided by ESP slave There are some common services provided by the Espressif slaves: 1. Tohost Interrupts: The slave can inform the master about certain events by the interrupt line. (optional) 2. Frhost Interrupts: The master can inform the slave about certain events. 3. Tx FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can also indicate it has new data to send to master by the interrupt line. The slave updates the TX buffer num to inform the master how much data it can receive, and the master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining. 4. Rx FIFO (slave to master): the slave can receive data from the master in units of receiving buffers. The slave updates the RX data size to inform the master how much data it has prepared to send, and then the master read the data size, and take off the data length it has already received to know how many data is remaining. 5. Shared registers: the master can read some part of the registers on the slave, and also write these registers to let the slave read. The services provided by the slave depends on the 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. Espressif Systems 120 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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_packet() 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. Espressif Systems 121 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 122 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · [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. Espressif Systems 123 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 124 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 125 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Header File · components/esp_serial_slave_link/include/esp_serial_slave_link/essl_spi.h Functions esp_err_t essl_spi_init_dev(essl_handle_t *out_handle, const essl_spi_config_t *init_config) Initialize the ESSL SPI device function list and get its handle. Return · ESP_OK: On success · ESP_ERR_NO_MEM: Memory exhausted · ESP_ERR_INVALID_STATE: SPI driver is not initialized · ESP_ERR_INVALID_ARG: Wrong register ID Parameters · [out] out_handle: Output of the handle · init_config: Configuration for the ESSL SPI device esp_err_t essl_spi_deinit_dev(essl_handle_t handle) Deinitialize the ESSL SPI device and free the memory used by the device. Return · ESP_OK: On success · ESP_ERR_INVALID_STATE: ESSL SPI is not in use Parameters · handle: Handle of the ESSL SPI device esp_err_t essl_spi_read_reg(void *arg, uint8_t addr, uint8_t *out_value, uint32_t wait_ms) Read from the shared registers. Note The registers for Master/Slave synchronization are reserved. Do not use them. (see rx_sync_reg in essl_spi_config_t) Return · ESP_OK: success · ESP_ERR_INVALID_STATE: ESSL SPI has not been initialized. · ESP_ERR_INVALID_ARG: The address argument is not valid. See note 1. · or other return value from :cpp:func:spi_device_transmit. Parameters · arg: Context of the component. (Member arg from essl_handle_t) · addr: Address of the shared registers. (Valid: 0 ~ SOC_SPI_MAXIMUM_BUFFER_SIZE, 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. Espressif Systems 126 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 127 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 128 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 allowed 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 Espressif Systems 129 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 2.2.8 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 Fri Mar 18 12:29:51 2022 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. Espressif Systems 130 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 ESP-IDF, then the certificate list can be downloaded from Mozilla as described in Generating the List of Root Certificates. 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. Espressif Systems 131 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. esp_err_t esp_crt_bundle_set(const uint8_t *x509_bundle, size_t bundle_size) Set the default certificate bundle used for verification. Overrides the default certificate bundle only in case of successful initialization. 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. 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] x509_bundle: A pointer to the certificate bundle. · [in] bundle_size: Size of the certificate bundle in bytes. 2.2.9 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. Espressif Systems 132 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · httpd_register_uri_handler(): A URI handler is registered by passing object of type httpd_uri_t structure which has members including uri name, method type (eg. HTTPD_GET/ HTTPD_POST/HTTPD_PUT etc.), function pointer of type esp_err_t *handler (httpd_req_t *req) and user_ctx pointer to user context data. Application Example /* Our URI handler function to be called during GET /uri request */ esp_err_t get_handler(httpd_req_t *req) { /* Send a simple response */ const char resp[] = "URI GET Response"; httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN); return ESP_OK; } /* Our URI handler function to be called during POST /uri request */ esp_err_t post_handler(httpd_req_t *req) { /* Destination buffer for content of HTTP POST request. * httpd_req_recv() accepts char* only, but content could * as well be any binary data (needs type casting). * In case of string data, null termination will be absent, and * content length would give length of string */ char content[100]; /* Truncate if content length larger than the buffer */ size_t recv_size = MIN(req->content_len, sizeof(content)); int ret = httpd_req_recv(req, content, recv_size); if (ret <= 0) { /* 0 return value indicates connection closed */ /* Check if timeout occurred */ if (ret == HTTPD_SOCK_ERR_TIMEOUT) { /* In case of timeout one can choose to retry calling * httpd_req_recv(), but to keep it simple, here we * respond with an HTTP 408 (Request Timeout) error */ httpd_resp_send_408(req); } /* In case of error, returning ESP_FAIL will * ensure that the underlying socket is closed */ return ESP_FAIL; } /* Send a simple response */ const char resp[] = "URI POST Response"; httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN); return ESP_OK; } /* URI handler structure for GET /uri */ httpd_uri_t uri_get = { .uri = "/uri", .method = HTTP_GET, .handler = get_handler, .user_ctx = NULL }; /* URI handler structure for POST /uri */ httpd_uri_t uri_post = { .uri = "/uri", .method = HTTP_POST, (continues on next page) Espressif Systems 133 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference .handler = post_handler, .user_ctx = NULL }; (continued from previous page) /* Function for starting the webserver */ httpd_handle_t start_webserver(void) { /* Generate default configuration */ httpd_config_t config = HTTPD_DEFAULT_CONFIG(); /* Empty handle to esp_http_server */ httpd_handle_t server = NULL; /* Start the httpd server */ if (httpd_start(&server, &config) == ESP_OK) { /* Register URI handlers */ httpd_register_uri_handler(server, &uri_get); httpd_register_uri_handler(server, &uri_post); } /* If server failed to start, handle will be NULL */ return server; } /* Function for stopping the webserver */ void stop_webserver(httpd_handle_t server) { if (server) { /* Stop the httpd server */ httpd_stop(server); } } Simple HTTP server example Check HTTP server example under protocols/http_server/simple where handling of arbitrary content lengths, reading request headers and URL query parameters, and setting response headers is demonstrated. Persistent Connections HTTP server features persistent connections, allowing for the re-use of the same connection (session) for several transfers, all the while maintaining context specific data for the session. Context data may be allocated dynamically by the handler in which case a custom function may need to be specified for freeing this data when the connection/session is closed. Persistent Connections Example /* Custom function to free context */ void free_ctx_func(void *ctx) { /* Could be something other than free */ free(ctx); } esp_err_t adder_post_handler(httpd_req_t *req) { /* Create session's context if not already available */ if (! req->sess_ctx) { req->sess_ctx = malloc(sizeof(ANY_DATA_TYPE)); /*!< Pointer to context data */ (continues on next page) Espressif Systems 134 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference req->free_ctx = free_ctx_func; context data */ } (continued from previous page) /*!< Function to free /* Access context data */ ANY_DATA_TYPE *ctx_data = (ANY_DATA_TYPE *)req->sess_ctx; /* Respond */ ............... ............... ............... return ESP_OK; } Check the example under protocols/http_server/persistent_sockets. Websocket server HTTP server provides a simple websocket support if the feature is enabled in menuconfig, please see 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 }; (continues on next page) Espressif Systems 135 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // Register handler if (httpd_register_uri_handler(server_handle, &my_uri) != ESP_OK) { // If failed to register handler .... } Note URI handlers can be registered in real time as long as the server handle is valid. Return · ESP_OK : On successfully registering the handler · ESP_ERR_INVALID_ARG : Null arguments · ESP_ERR_HTTPD_HANDLERS_FULL : If no slots left for new handler · ESP_ERR_HTTPD_HANDLER_EXISTS : If handler with same URI and method is already reg- istered Parameters · [in] handle: handle to HTTPD server instance · [in] uri_handler: pointer to handler that needs to be registered esp_err_t httpd_unregister_uri_handler(httpd_handle_t handle, const char *uri, Unregister a URI handler. httpd_method_t method) 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) Espressif Systems 136 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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, 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 Espressif Systems 137 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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. Espressif Systems 138 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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¶m2=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 Espressif Systems 139 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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 Espressif Systems 140 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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. Espressif Systems 141 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. · 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 Espressif Systems 142 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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 Espressif Systems 143 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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 · 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 Espressif Systems 144 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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 · [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: Espressif Systems 145 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // Function for stopping the webserver void stop_webserver(httpd_handle_t server) { // Ensure handle is non NULL if (server != NULL) { // Stop the httpd server httpd_stop(server); } } Return · ESP_OK : Server stopped successfully · ESP_ERR_INVALID_ARG : Handle argument is Null Parameters · [in] handle: Handle to server returned by httpd_start esp_err_t httpd_queue_work(httpd_handle_t handle, httpd_work_fn_t work, void *arg) Queue execution of a function in 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 Espressif Systems 146 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 147 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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 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. Espressif Systems 148 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference This field can be used to store arbitrary user data within the server context. The value can be retrieved using the server handle, available e.g. in the httpd_req_t struct. When shutting down, the server frees up the user context by calling free() on the global_user_ctx field. If you wish to use a custom function for freeing the global user context, please specify that here. httpd_free_ctx_fn_t global_user_ctx_free_fn Free function for global user context void *global_transport_ctx Global transport context. Similar to global_user_ctx, but used for session encoding or encryption (e.g. to hold the SSL context). It will be freed using free(), unless global_transport_ctx_free_fn is specified. httpd_free_ctx_fn_t global_transport_ctx_free_fn Free function for global transport context httpd_open_func_t open_fn Custom session opening callback. Called on a new session socket just after accept(), but before reading any data. This is an opportunity to set up e.g. SSL encryption using global_transport_ctx and the send/recv/pending session overrides. If a context needs to be maintained between these functions, store it in the session using httpd_sess_set_transport_ctx() and retrieve it later with httpd_sess_get_transport_ctx() Returning a value other than ESP_OK will immediately close the new socket. httpd_close_func_t close_fn Custom session closing callback. Called when a session is deleted, before freeing user and transport contexts and before closing the socket. This is a place for custom de-init code common to all sockets. 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 Espressif Systems 149 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference const char uri[HTTPD_MAX_URI_LEN + 1] The URI of this request (1 byte extra for null termination) size_t content_len Length of the request body void *aux Internally used members void *user_ctx User context pointer passed during URI registration. void *sess_ctx Session Context Pointer A session context. Contexts are maintained across 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 Espressif Systems 150 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference HTTPD_SOCK_ERR_TIMEOUT HTTPD_200 HTTP Response 200 HTTPD_204 HTTP Response 204 HTTPD_207 HTTP Response 207 HTTPD_400 HTTP Response 400 HTTPD_404 HTTP Response 404 HTTPD_408 HTTP Response 408 HTTPD_500 HTTP Response 500 HTTPD_TYPE_JSON HTTP Content type JSON HTTPD_TYPE_TEXT HTTP Content type text/HTML HTTPD_TYPE_OCTET HTTP Content type octext-stream HTTPD_DEFAULT_CONFIG() ESP_ERR_HTTPD_BASE Starting number of HTTPD error codes ESP_ERR_HTTPD_HANDLERS_FULL All slots for registering URI handlers have been consumed ESP_ERR_HTTPD_HANDLER_EXISTS URI handler with same method and target URI already registered ESP_ERR_HTTPD_INVALID_REQ Invalid request pointer ESP_ERR_HTTPD_RESULT_TRUNC Result string truncated ESP_ERR_HTTPD_RESP_HDR Response header field larger than supported ESP_ERR_HTTPD_RESP_SEND Error occured while sending response packet ESP_ERR_HTTPD_ALLOC_MEM Failed to dynamically allocate memory for resource ESP_ERR_HTTPD_TASK Failed to launch server task/thread HTTPD_RESP_USE_STRLEN Type Definitions typedef struct httpd_req httpd_req_t HTTP Request Data Structure. typedef struct httpd_uri httpd_uri_t Structure for URI handler. Espressif Systems 151 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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() 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, Espressif Systems 152 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference httpd_resp_send_err() must be invoked inside this function if user wishes to generate HTTP error responses. · When invoked, the validity of uri, method, content_len and user_ctx fields of the httpd_req_t parameter is not guaranteed as the HTTP request may be partially received/parsed. · The function must return ESP_OK if underlying socket needs to be kept open. Any other value will ensure that the socket is closed. The return value is ignored when error is of type HTTPD_500_INTERNAL_SERVER_ERROR and the socket closed anyway. Return · ESP_OK : error handled successful · ESP_FAIL : failure indicates that the underlying socket needs to be closed Parameters · [in] req: HTTP request for which the error needs to be handled · [in] error: Error type typedef void *httpd_handle_t HTTP Server Instance Handle. Every instance of the server will have a unique handle. typedef enum http_method httpd_method_t HTTP Method Type wrapper over 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. Espressif Systems 153 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note Use HTTPD_DEFAULT_CONFIG() to initialize the configuration to a default value and then modify only those fields that are specifically determined by the use case. typedef void (*httpd_work_fn_t)(void *arg) Prototype of the HTTPD work function Please refer to httpd_queue_work() for more details. Parameters · [in] arg: The arguments for this work function Enumerations enum httpd_err_code_t Error codes sent as HTTP response in case of errors encountered during processing of an HTTP request. Values: HTTPD_500_INTERNAL_SERVER_ERROR = 0 HTTPD_501_METHOD_NOT_IMPLEMENTED HTTPD_505_VERSION_NOT_SUPPORTED HTTPD_400_BAD_REQUEST HTTPD_401_UNAUTHORIZED HTTPD_403_FORBIDDEN HTTPD_404_NOT_FOUND HTTPD_405_METHOD_NOT_ALLOWED HTTPD_408_REQ_TIMEOUT HTTPD_411_LENGTH_REQUIRED HTTPD_414_URI_TOO_LONG HTTPD_431_REQ_HDR_FIELDS_TOO_LARGE HTTPD_ERR_CODE_MAX 2.2.10 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::global_transport_ctx httpd_config::global_transport_ctx_free_fn Espressif Systems 154 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference httpd_config::open_fn - used to set up secure sockets Everything else can be used without limitations. Usage Please see the example protocols/https_server to learn how to set up a secure server. Basically all you need is to generate a certificate, embed it in the firmware, and provide its pointers and lengths to the start function via the init struct. The server can be started with or without SSL by changing a flag in the init struct httpd_ssl_config::transport_mode. This could be used e.g. for testing or in trusted environments where you prefer speed over security. Performance The initial session setup can take about two seconds, or more with slower clock speeds or more verbose logging. Subsequent requests through the open secure socket are much faster (down to under 100 ms). API Reference Header File · components/esp_https_server/include/esp_https_server.h Functions esp_err_t httpd_ssl_start(httpd_handle_t *handle, httpd_ssl_config_t *config) Create a SSL capable HTTP server (secure mode may be disabled in config) Return success Parameters · [inout] config: - server config, must not be const. Does not have to stay valid after calling this function. · [out] handle: - storage for the server handle, must be a valid pointer void httpd_ssl_stop(httpd_handle_t handle) Stop the server. Blocks until the server is shut down. Parameters · [in] handle: Structures struct esp_https_server_user_cb_arg Callback data struct, contains the ESP-TLS connection handle and the connection state at which the callback is executed. 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. Espressif Systems 155 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference const uint8_t *servercert Server certificate size_t servercert_len Server certificate byte length const uint8_t *cacert_pem CA certificate ((CA used to sign clients, or client cert itself) size_t cacert_len CA certificate byte length 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 bool use_secure_element Enable secure element for server session 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 and the connection state at which the callback is executed. 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 Espressif Systems 156 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Enumerations enum httpd_ssl_transport_mode_t Values: HTTPD_SSL_TRANSPORT_SECURE HTTPD_SSL_TRANSPORT_INSECURE enum httpd_ssl_user_cb_state_t Indicates the state at which the user callback is executed, i.e at session creation or session close. Values: HTTPD_SSL_USER_CB_SESS_CREATE HTTPD_SSL_USER_CB_SESS_CLOSE 2.2.11 ICMP Echo Overview ICMP (Internet Control Message Protocol) is used for diagnostic or control purposes or generated in response to errors in IP operations. The common network util ping is implemented based on the ICMP packets with the type field value of 0, also called Echo Reply. During a ping session, the source host firstly sends out an ICMP echo request packet and wait for an ICMP echo reply with specific times. In this way, it also measures the round-trip time for the messages. After receiving a valid ICMP echo reply, the source host will generate statistics about the IP link layer (e.g. packet loss, elapsed time, etc). It is common that IoT device needs to check whether a remote server is alive or not. The device should show the warnings to users when it got offline. It can be achieved by creating a ping session and sending/parsing ICMP echo packets periodically. To make this internal procedure much easier for users, ESP-IDF provides some out-of-box APIs. Create a new ping session To create a ping session, you need to fill in the esp_ping_config_t configuration structure firstly, specifying target IP address, interval times, and etc. Optionally, you can also register some callback functions with the esp_ping_callbacks_t` structure. Example method to create a new ping session and register callbacks: static void test_on_ping_success(esp_ping_handle_t hdl, void *args) { // optionally, get callback arguments // const char* str = (const char*) args; // printf("%s\r\n", str); // "foo" uint8_t ttl; uint16_t seqno; uint32_t elapsed_time, recv_len; ip_addr_t target_addr; esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno)); esp_ping_get_profile(hdl, ESP_PING_PROF_TTL, &ttl, sizeof(ttl)); esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_ addr)); esp_ping_get_profile(hdl, ESP_PING_PROF_SIZE, &recv_len, sizeof(recv_len)); esp_ping_get_profile(hdl, ESP_PING_PROF_TIMEGAP, &elapsed_time, sizeof(elapsed_ time)); printf("%d bytes from %s icmp_seq=%d ttl=%d time=%d ms\n", recv_len, inet_ntoa(target_addr.u_addr.ip4), seqno, ttl, elapsed_time); } static void test_on_ping_timeout(esp_ping_handle_t hdl, void *args) { (continues on next page) Espressif Systems 157 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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)); 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. Espressif Systems 158 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 159 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 160 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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.2.12 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: Espressif Systems 161 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference void start_mdns_service() { //initialize mDNS service esp_err_t err = mdns_init(); if (err) { printf("MDNS Init failed: %d\n", err); return; } //set hostname mdns_hostname_set("my-esp32s3"); //set default instance mdns_instance_name_set("Jhon's ESP32-S3 Thing"); } mDNS Services mDNS can advertise information about network services that your device offers. Each service is defined by a few properties. · instance_name: friendly name for your service, like Jhon's EESP32-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); (continues on next page) Espressif Systems 162 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) struct ip4_addr addr; addr.addr = 0; esp_err_t err = mdns_query_a(host_name, 2000, if(err){ if(err == ESP_ERR_NOT_FOUND){ printf("Host was not found!"); return; } printf("Query Failed"); return; } &addr); printf(IPSTR, IP2STR(&addr)); } Example method to resolve local services: static const char * if_str[] = {"STA", "AP", "ETH", "MAX"}; static const char * ip_protocol_str[] = {"V4", "V6", "MAX"}; void mdns_print_results(mdns_result_t * results){ mdns_result_t * r = results; mdns_ip_addr_t * a = NULL; int i = 1, t; while(r){ printf("%d: Interface: %s, Type: %s\n", i++, if_str[r->tcpip_if], ip_ protocol_str[r->ip_protocol]); if(r->instance_name){ printf(" PTR : %s\n", r->instance_name); } if(r->hostname){ printf(" SRV : %s.local:%u\n", r->hostname, r->port); } if(r->txt_count){ printf(" TXT : [%u] ", r->txt_count); for(t=0; t<r->txt_count; t++){ printf("%s=%s; ", r->txt[t].key, r->txt[t].value); } printf("\n"); } a = r->addr; while(a){ if(a->addr.type == IPADDR_TYPE_V6){ printf(" AAAA: " IPV6STR "\n", IPV62STR(a->addr.u_addr.ip6)); } else { printf(" A : " IPSTR "\n", IP2STR(&(a->addr.u_addr.ip4))); } a = a->next; } r = r->next; } } void find_mdns_service(const char * service_name, const char * proto) { ESP_LOGI(TAG, "Query PTR: %s.%s.local", service_name, proto); mdns_result_t * results = NULL; (continues on next page) Espressif Systems 163 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) esp_err_t err = mdns_query_ptr(service_name, proto, 3000, 20, if(err){ ESP_LOGE(TAG, "Query Failed"); return; } if(!results){ ESP_LOGW(TAG, "No results found!"); return; } &results); 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"); } 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 Espressif Systems 164 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_ERR_INVALID_ARG Parameter error · ESP_ERR_NO_MEM memory error Parameters · hostname: Hostname to set esp_err_t mdns_delegate_hostname_add(const char *hostname, const mdns_ip_addr_t *address_list) Adds a hostname and address to be delegated A/AAAA queries will be replied for the hostname and services can be added to this host. Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · 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. Espressif Systems 165 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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) Espressif Systems 166 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 167 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 168 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 169 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 170 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 *hostname, const char *subtype) Add subtype for service. 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. · 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) Espressif Systems 171 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 172 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 173 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_register_netif(esp_netif_t *esp_netif) Register custom esp_netif with mDNS functionality mDNS service runs by default on preconfigured interfaces (STA, AP, ETH). This API enables running the service on any customized interface, either using standard WiFi or Ethernet driver or any kind of user defined driver. Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running or this netif is already registered · ESP_ERR_NO_MEM not enough memory for this in interface in the netif list (see CONFIG_MDNS_MAX_INTERFACES) Parameters · esp_netif: Pointer to esp-netif interface esp_err_t mdns_unregister_netif(esp_netif_t *esp_netif) Unregister esp-netif already registered in mDNS service. Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running · ESP_ERR_NOT_FOUND this esp-netif was not registered in mDNS service Parameters · esp_netif: Pointer to esp-netif interface esp_err_t mdns_netif_action(esp_netif_t *esp_netif, mdns_event_actions_t event_action) Set esp_netif to a desired state, or perform a desired action, such as enable/disable this interface or send announcement packets to this netif. · This function is used to enable (probe, resolve conflicts and announce), announce, or disable (send bye) mDNS services on the specified network interface. · This function must be called if users registers a specific interface using mdns_register_netif() to enable mDNS services on that interface. · This function could be used in IP/connection event handlers to automatically enable/announce mDNS services when network properties change and/or disable them on disconnection. Return · ESP_OK success · ESP_ERR_INVALID_STATE mDNS is not running or this netif is not registered · ESP_ERR_NO_MEM memory error Parameters · esp_netif: Pointer to esp-netif interface · event_action: Disable/Enable/Announce on this interface over IPv4/IPv6 protocol. Actions enumerated in mdns_event_actions_t type. Structures struct mdns_txt_item_t mDNS basic text item structure Used in mdns_service_add() Public Members const char *key item key name const char *value item value string struct mdns_ip_addr_s mDNS query linked list IP item Espressif Systems 174 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 esp_netif_t *esp_netif ptr to corresponding esp-netif uint32_t ttl time to live mdns_ip_protocol_t ip_protocol ip_protocol type of the interface (v4/v6) char *instance_name instance name char *service_type service type char *proto srevice protocol char *hostname hostname uint16_t port service port mdns_txt_item_t *txt txt record uint8_t *txt_value_len array of txt value len of each record size_t txt_count number of txt items mdns_ip_addr_t *addr linked list of IP addresses found Macros MDNS_TYPE_A MDNS_TYPE_PTR MDNS_TYPE_TXT MDNS_TYPE_AAAA MDNS_TYPE_SRV MDNS_TYPE_OPT MDNS_TYPE_NSEC MDNS_TYPE_ANY Espressif Systems 175 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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_event_actions_t Values: MDNS_EVENT_ENABLE_IP4 = 1 << 1 MDNS_EVENT_ENABLE_IP6 = 1 << 2 MDNS_EVENT_ANNOUNCE_IP4 = 1 << 3 MDNS_EVENT_ANNOUNCE_IP6 = 1 << 4 MDNS_EVENT_DISABLE_IP4 = 1 << 5 MDNS_EVENT_DISABLE_IP6 = 1 << 6 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_query_transmission_type_t mDNS query type to be explicitly set to either Unicast or Multicast Values: MDNS_QUERY_UNICAST MDNS_QUERY_MULTICAST 2.2.13 Mbed TLS Mbed TLS is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems. Note: ESP-IDF uses a fork of Mbed TLS which includes a few patches (related to hardware routines of certain modules like bignum (MPI) and ECC) over vanilla Mbed TLS. Mbed TLS supports SSL 3.0 up to TLS 1.3 and DTLS 1.0 to 1.2 communication by providing the following: · TCP/IP communication functions: listen, connect, accept, read/write. · SSL/TLS communication functions: init, handshake, read/write. · X.509 functions: CRT, CRL and key handling · Random number generation · Hashing · Encryption/decryption Espressif Systems 176 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note: Mbed TLS is in the process of migrating all the documentation to a single place. In the meantime, users can find the documentation at the old Mbed TLS site . Mbed TLS Support in ESP-IDF Please find the information about the Mbed TLS versions present in different branches of ESP-IDF here. Note: Please refer the ESP-IDF Migration Guide to migrate from Mbed TLS version 2.x to version 3.0 or greater. Application Examples Examples in ESP-IDF use ESP-TLS which provides a simplified API interface for accessing the commonly used TLS functionality. Refer to the examples protocols/https_server/simple (Simple HTTPS server) and protocols/https_request (Make HTTPS requests) for more information. If the Mbed TLS API is to be used directly, refer to the example protocols/https_mbedtls. Alternatives ESP-TLS acts as an abstraction layer over the underlying SSL/TLS library and thus has an option to use Mbed TLS or wolfSSL as the underlying library. By default, only Mbed TLS is available and used in ESP-IDF whereas wolfSSL is available publicly at https://github.com/espressif/esp-wolfSSL with the upstream submodule pointer. Please refer to ESP-TLS: Underlying SSL/TLS Library Options docs for more information on this and comparison of Mbed TLS and wolfSSL. Important Config Options Following is a brief list of important config options accessible at Component Config -> mbedTLS. The full list of config options can be found here. · CONFIG_MBEDTLS_SSL_PROTO_TLS1_2: Support for TLS 1.2 · CONFIG_MBEDTLS_SSL_PROTO_TLS1_3: Support for TLS 1.3 · CONFIG_MBEDTLS_CERTIFICATE_BUNDLE: Support for trusted root certificate bundle (more about this: ESP x509 Certificate Bundle) · CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS: Support for TLS Session Resumption: Client session tickets · CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS: Support for TLS Session Resumption: Server session tickets · CONFIG_MBEDTLS_HARDWARE_SHA: Support for hardware SHA acceleration · CONFIG_MBEDTLS_HARDWARE_AES: Support for hardware AES acceleration · CONFIG_MBEDTLS_HARDWARE_MPI: Support for hardware MPI (bignum) acceleration Note: Mbed TLS v3.0.0 and later support only TLS 1.2 and TLS 1.3 (SSL 3.0, TLS 1.0, TLS 1.1 and DTLS 1.0 are not supported). The support for TLS 1.3 is experimental and only supports the client-side. More information about this can be found out here. Espressif Systems 177 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Performance and Memory Tweaks Reducing Heap Usage The following table shows typical memory usage with different configs when the protocols/https_request example (with Server Validation enabled) was run with Mbed TLS as the SSL/TLS library. Mbed Test TLS Related Configs Default Enable SSL Variable Length Disable Keep Peer Certificate Enable Dynamic TX/RX Buffer NA CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE CONFIG_MBEDTLS_DYNAMIC_BUFFER FIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA FIG_MBEDTLS_DYNAMIC_FREE_CA_CERT Heap Usage (approx.) 42196 B 42120 B 38533 B CON- 22013 B CON- Note: These values are subject to change with change in configuration options and versions of Mbed TLS. Reducing Binary Size Under Component Config -> mbedTLS, there are multiple Mbed TLS features which are enabled by default but can be disabled if not needed to save code size. More information can be about this can be found in Minimizing Binary Size docs. Code examples for this API section are provided in the protocols directory of ESP-IDF examples. 2.2.14 IP Network Layer Documentation for IP Network Layer protocols (below the Application Protocol layer) are provided in Networking APIs. 2.3 Bluetooth API 2.3.1 BT COMMON BT GENERIC DEFINES Overview Instructions Application Example Instructions API Reference Header File · components/bt/host/bluedroid/api/include/api/esp_bt_defs.h Structures struct esp_bt_uuid_t UUID type. Espressif Systems 178 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t len UUID length, 16bit, 32bit or 128bit uint16_t uuid16 16bit UUID uint32_t uuid32 32bit UUID uint8_t uuid128[ESP_UUID_LEN_128] 128bit UUID union esp_bt_uuid_t::[anonymous] uuid UUID Macros ESP_BLUEDROID_STATUS_CHECK(status) ESP_BT_OCTET16_LEN ESP_BT_OCTET8_LEN ESP_DEFAULT_GATT_IF Default GATT interface id. ESP_BLE_CONN_INT_MIN relate to BTM_BLE_CONN_INT_MIN in stack/btm_ble_api.h ESP_BLE_CONN_INT_MAX relate to BTM_BLE_CONN_INT_MAX in stack/btm_ble_api.h ESP_BLE_CONN_LATENCY_MAX relate to ESP_BLE_CONN_LATENCY_MAX in stack/btm_ble_api.h ESP_BLE_CONN_SUP_TOUT_MIN relate to BTM_BLE_CONN_SUP_TOUT_MIN in stack/btm_ble_api.h ESP_BLE_CONN_SUP_TOUT_MAX relate to ESP_BLE_CONN_SUP_TOUT_MAX in stack/btm_ble_api.h ESP_BLE_CONN_PARAM_UNDEF ESP_BLE_SCAN_PARAM_UNDEF ESP_BLE_IS_VALID_PARAM(x, min, max) Check the param is valid or not. ESP_UUID_LEN_16 ESP_UUID_LEN_32 ESP_UUID_LEN_128 ESP_BD_ADDR_LEN Bluetooth address length. ESP_BLE_ENC_KEY_MASK Used to exchange the encryption key in the init key & response key. ESP_BLE_ID_KEY_MASK Used to exchange the IRK key in the init key & response key. ESP_BLE_CSR_KEY_MASK Used to exchange the CSRK key in the init key & response key. Espressif Systems 179 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_LINK_KEY_MASK Used to exchange the link key(this key just used in the BLE & BR/EDR coexist mode) in the init key & response key. ESP_APP_ID_MIN Minimum of the application id. ESP_APP_ID_MAX Maximum of the application id. ESP_BD_ADDR_STR ESP_BD_ADDR_HEX(addr) Type Definitions typedef uint8_t esp_bt_octet16_t[ESP_BT_OCTET16_LEN] typedef uint8_t esp_bt_octet8_t[ESP_BT_OCTET8_LEN] typedef uint8_t esp_link_key[ESP_BT_OCTET16_LEN] typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN] Bluetooth device address. typedef uint8_t esp_ble_key_mask_t Enumerations enum esp_bt_status_t Status Return Value. Values: ESP_BT_STATUS_SUCCESS = 0 ESP_BT_STATUS_FAIL ESP_BT_STATUS_NOT_READY ESP_BT_STATUS_NOMEM ESP_BT_STATUS_BUSY ESP_BT_STATUS_DONE = 5 ESP_BT_STATUS_UNSUPPORTED ESP_BT_STATUS_PARM_INVALID ESP_BT_STATUS_UNHANDLED ESP_BT_STATUS_AUTH_FAILURE ESP_BT_STATUS_RMT_DEV_DOWN = 10 ESP_BT_STATUS_AUTH_REJECTED ESP_BT_STATUS_INVALID_STATIC_RAND_ADDR ESP_BT_STATUS_PENDING ESP_BT_STATUS_UNACCEPT_CONN_INTERVAL ESP_BT_STATUS_PARAM_OUT_OF_RANGE ESP_BT_STATUS_TIMEOUT ESP_BT_STATUS_PEER_LE_DATA_LEN_UNSUPPORTED ESP_BT_STATUS_CONTROL_LE_DATA_LEN_UNSUPPORTED ESP_BT_STATUS_ERR_ILLEGAL_PARAMETER_FMT Espressif Systems 180 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 181 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 182 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_ERR_INVALID_STATE : if bluetooth stack is not yet enabled · ESP_FAIL : others Parameters · [in] name: : device name to be set 2.3.2 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 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 Espressif Systems 183 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 184 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 185 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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 · [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. Espressif Systems 186 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_ble_gap_add_duplicate_scan_exceptional_device(esp_ble_duplicate_exceptional_info_type_t type, esp_duplicate_info_t device_info) This function is called to add a device info into the duplicate scan exceptional list. Return · ESP_OK : success · other : failed Parameters · [in] type: device info type, it is defined in esp_ble_duplicate_exceptional_info_type_t when type is MESH_BEACON_TYPE, MESH_PROV_SRV_ADV or MESH_PROXY_SRV_ADV , device_info is invalid. · [in] device_info: the device information. esp_err_t esp_ble_gap_remove_duplicate_scan_exceptional_device(esp_ble_duplicate_exceptional_info_type_t type, esp_duplicate_info_t device_info) This function is called to remove a device info from the duplicate scan exceptional list. Return · ESP_OK : success · other : failed Parameters · [in] type: device info type, it is defined in esp_ble_duplicate_exceptional_info_type_t when type is MESH_BEACON_TYPE, MESH_PROV_SRV_ADV or MESH_PROXY_SRV_ADV , device_info is invalid. · [in] device_info: the device information. esp_err_t esp_ble_gap_clean_duplicate_scan_exceptional_list(esp_duplicate_scan_exceptional_list_type_t list_type) This function is called to clean the duplicate scan exceptional list. This API will delete all device information in the duplicate scan exceptional list. Return · ESP_OK : success · other : failed Parameters · [in] list_type: duplicate scan exceptional list type, the value can be one or more of esp_duplicate_scan_exceptional_list_type_t. esp_err_t esp_ble_gap_set_security_param(esp_ble_sm_param_t param_type, void *value, uint8_t len) Set a GAP security parameter value. Overrides the default value. Secure connection is highly recommended to avoid some major vulnerabilities like 'Impersonation in the Pin Pairing Protocol' (CVE-2020-26555) and 'Authentication of the LE Legacy Pairing Protocol'. To accept only `secure connection mode`, it is necessary do as following: 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 Espressif Systems 187 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · other : failed Parameters · [in] param_type: : the type of the param which to be set · [in] value: : the param value · [in] len: : the length of the param value esp_err_t esp_ble_gap_security_rsp(esp_bd_addr_t bd_addr, bool accept) Grant security request access. Return - ESP_OK : success · other : failed Parameters · [in] bd_addr: : BD address of the peer · [in] accept: : accept the security request or not esp_err_t esp_ble_set_encryption(esp_bd_addr_t bd_addr, esp_ble_sec_act_t sec_act) Set a gap parameter value. Use this function to change the default GAP parameter values. Return - ESP_OK : success · other : failed Parameters · [in] bd_addr: : the address of the peer device need to encryption · [in] sec_act: : This is the security action to indicate what kind of BLE security level is required for the BLE link if the BLE is supported esp_err_t esp_ble_passkey_reply(esp_bd_addr_t bd_addr, bool accept, uint32_t passkey) Reply the key value to the peer device in the legacy connection stage. Return - ESP_OK : success · other : failed Parameters · [in] bd_addr: : BD address of the peer · [in] accept: : passkey entry successful or declined. · [in] passkey: : passkey value, must be a 6 digit number, can be lead by 0. esp_err_t esp_ble_confirm_reply(esp_bd_addr_t bd_addr, bool accept) Reply the confirm value to the peer device in the secure connection stage. Return - ESP_OK : success · other : failed Parameters · [in] bd_addr: : BD address of the peer device · [in] accept: : numbers to compare are the same or different. esp_err_t esp_ble_remove_bond_device(esp_bd_addr_t bd_addr) Removes a device from the security database list of peer device. It manages unpairing event while connected. Return - ESP_OK : success · other : failed Parameters · [in] bd_addr: : BD address of the peer device int esp_ble_get_bond_device_num(void) Get the device number from the security database list of peer device. It will return the device bonded number immediately. Return - >= 0 : bonded devices number. · ESP_FAIL : failed 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 Espressif Systems 188 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 189 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · other : failed Parameters · [in] bd_addr: : BD address of the peer device esp_err_t esp_ble_gap_set_prefered_default_phy(esp_ble_gap_phy_mask_t tx_phy_mask, esp_ble_gap_phy_mask_t rx_phy_mask) This function is used to allows the Host to specify its preferred values for the transmitter PHY and receiver PHY to be used for all subsequent connections over the LE transport. Return - ESP_OK : success · other : failed Parameters · [in] tx_phy_mask: : indicates the transmitter PHYs that the Host prefers the Controller to use · [in] rx_phy_mask: : indicates the receiver PHYs that the Host prefers the Controller to use esp_err_t esp_ble_gap_set_prefered_phy(esp_bd_addr_t bd_addr, esp_ble_gap_all_phys_t all_phys_mask, esp_ble_gap_phy_mask_t tx_phy_mask, esp_ble_gap_phy_mask_t rx_phy_mask, esp_ble_gap_prefer_phy_options_t phy_options) This function is used to set the PHY preferences for the connection identified by the remote address. The Controller might not be able to make the change (e.g. because the peer does not support the requested PHY) or may decide that the current PHY is preferable. Return - ESP_OK : success · other : failed Parameters · [in] bd_addr: : remote address · [in] all_phys_mask: : a bit field that allows the Host to specify · [in] tx_phy_mask: : a bit field that indicates the transmitter PHYs that the Host prefers the Controller to use · [in] rx_phy_mask: : a bit field that indicates the receiver PHYs that the Host prefers the Controller to use · [in] phy_options: : a bit field that allows the Host to specify options for PHYs esp_err_t esp_ble_gap_ext_adv_set_rand_addr(uint8_t instance, esp_bd_addr_t rand_addr) This function is used by the Host to set the random device address specified by the Random_Address parameter. Return - ESP_OK : success · other : failed Parameters · [in] instance: : Used to identify an advertising set · [in] rand_addr: : Random Device Address esp_err_t esp_ble_gap_ext_adv_set_params(uint8_t instance, const esp_ble_gap_ext_adv_params_t *params) This function is used by the Host to set the advertising parameters. Return - ESP_OK : success · other : failed Parameters · [in] instance: : identifies the advertising set whose parameters are being configured. · [in] params: : advertising parameters esp_err_t esp_ble_gap_config_ext_adv_data_raw(uint8_t instance, uint16_t length, const uint8_t *data) This function is used to set the data used in advertising PDUs that have a data field. Return - ESP_OK : success · other : failed Parameters · [in] instance: : identifies the advertising set whose data are being configured · [in] length: : data length · [in] data: : data information Espressif Systems 190 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_ble_gap_config_ext_scan_rsp_data_raw(uint8_t instance, uint16_t length, const uint8_t *scan_rsp_data) This function is used to provide scan response data used in scanning response PDUs. Return - ESP_OK : success · other : failed Parameters · [in] instance: : identifies the advertising set whose response data are being configured. · [in] length: : responsedata length · [in] scan_rsp_data: : response data information esp_err_t esp_ble_gap_ext_adv_start(uint8_t num_adv, const esp_ble_gap_ext_adv_t *ext_adv) This function is used to request the Controller to enable one or more advertising sets using the advertising sets identified by the instance parameter. Return - ESP_OK : success · other : failed Parameters · [in] num_adv: : Number of advertising sets to enable or disable · [in] ext_adv: : adv parameters esp_err_t esp_ble_gap_ext_adv_stop(uint8_t num_adv, const uint8_t *ext_adv_inst) This function is used to request the Controller to disable one or more advertising sets using the advertising sets identified by the instance parameter. Return - ESP_OK : success · other : failed Parameters · [in] num_adv: : Number of advertising sets to enable or disable · [in] ext_adv_inst: : ext adv instance esp_err_t esp_ble_gap_ext_adv_set_remove(uint8_t instance) This function is used to remove an advertising set from the Controller. Return - ESP_OK : success · other : failed Parameters · [in] instance: : Used to identify an advertising set esp_err_t esp_ble_gap_ext_adv_set_clear(void) This function is used to remove all existing advertising sets from the Controller. Return - ESP_OK : success · other : failed esp_err_t esp_ble_gap_periodic_adv_set_params(uint8_t instance, const esp_ble_gap_periodic_adv_params_t *params) This function is used by the Host to set the parameters for periodic advertising. Return - ESP_OK : success · other : failed Parameters · [in] instance: : identifies the advertising set whose periodic advertising parameters are being configured. · [in] params: : periodic adv parameters 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 Espressif Systems 191 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [in] instance: : identifies the advertising set whose periodic advertising parameters are being configured. · [in] length: : the length of periodic data · [in] data: : periodic data information esp_err_t esp_ble_gap_periodic_adv_start(uint8_t instance) This function is used to request the Controller to enable the periodic advertising for the advertising set specified. Return - ESP_OK : success · other : failed Parameters · [in] instance: : Used to identify an advertising set esp_err_t esp_ble_gap_periodic_adv_stop(uint8_t instance) This function is used to request the Controller to disable the periodic advertising for the advertising set specified. Return - ESP_OK : success · other : failed Parameters · [in] instance: : Used to identify an advertising set esp_err_t esp_ble_gap_set_ext_scan_params(const esp_ble_ext_scan_params_t *params) This function is used to set the extended scan parameters to be used on the advertising channels. Return - ESP_OK : success · other : failed Parameters · [in] params: : scan parameters esp_err_t esp_ble_gap_start_ext_scan(uint32_t duration, uint16_t period) This function is used to enable scanning. Return - ESP_OK : success · other : failed Parameters · [in] duration: : Scan duration · [in] period: : Time interval from when the Controller started its last Scan Duration until it begins the subsequent Scan Duration. esp_err_t esp_ble_gap_stop_ext_scan(void) This function is used to disable scanning. Return - ESP_OK : success · other : failed esp_err_t esp_ble_gap_periodic_adv_create_sync(const esp_ble_gap_periodic_adv_sync_params_t *params) This function is used to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets. Return - ESP_OK : success · other : failed Parameters · [in] params: : sync parameters esp_err_t esp_ble_gap_periodic_adv_sync_cancel(void) This function is used to cancel the LE_Periodic_Advertising_Create_Sync command while it is pending. Return - ESP_OK : success · 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 Espressif Systems 192 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · [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 Espressif Systems 193 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_penc_keys_t penc_key received peer encryption key esp_ble_pcsrk_keys_t pcsrk_key received peer device SRK esp_ble_pid_keys_t pid_key peer device ID key esp_ble_lenc_keys_t lenc_key local encryption reproduction keys LTK = = d1(ER,DIV,0) esp_ble_lcsrk_keys lcsrk_key local device CSRK = d1(ER,DIV,1) union esp_ble_sec_t #include <esp_gap_ble_api.h> union associated with ble security Public Members esp_ble_sec_key_notif_t key_notif passkey notification esp_ble_sec_req_t ble_req BLE SMP related request esp_ble_key_t ble_key BLE SMP keys used when pairing esp_ble_local_id_keys_t ble_id_keys BLE IR event esp_ble_auth_cmpl_t auth_cmpl Authentication complete indication. union esp_ble_gap_cb_param_t #include <esp_gap_ble_api.h> Gap callback parameters union. Public Members struct esp_ble_gap_cb_param_t::ble_adv_data_cmpl_evt_param adv_data_cmpl Event parameter of ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_scan_rsp_data_cmpl_evt_param scan_rsp_data_cmpl Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_scan_param_cmpl_evt_param scan_param_cmpl Event parameter of ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_scan_result_evt_param scan_rst Event parameter of ESP_GAP_BLE_SCAN_RESULT_EVT struct esp_ble_gap_cb_param_t::ble_adv_data_raw_cmpl_evt_param adv_data_raw_cmpl Event parameter of ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_scan_rsp_data_raw_cmpl_evt_param scan_rsp_data_raw_cmpl Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_adv_start_cmpl_evt_param adv_start_cmpl Event parameter of ESP_GAP_BLE_ADV_START_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_scan_start_cmpl_evt_param scan_start_cmpl Event parameter of ESP_GAP_BLE_SCAN_START_COMPLETE_EVT Espressif Systems 194 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_sec_t ble_security ble gap security union type struct esp_ble_gap_cb_param_t::ble_scan_stop_cmpl_evt_param scan_stop_cmpl Event parameter of ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_adv_stop_cmpl_evt_param adv_stop_cmpl Event parameter of ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_set_rand_cmpl_evt_param set_rand_addr_cmpl Event parameter of ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT struct esp_ble_gap_cb_param_t::ble_update_conn_params_evt_param update_conn_params Event parameter of ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT struct esp_ble_gap_cb_param_t::ble_pkt_data_length_cmpl_evt_param pkt_data_lenth_cmpl Event parameter of ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_local_privacy_cmpl_evt_param local_privacy_cmpl Event parameter of ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_remove_bond_dev_cmpl_evt_param remove_bond_dev_cmpl Event parameter of ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_clear_bond_dev_cmpl_evt_param clear_bond_dev_cmpl Event parameter of ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_get_bond_dev_cmpl_evt_param get_bond_dev_cmpl Event parameter of ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_read_rssi_cmpl_evt_param read_rssi_cmpl Event parameter of ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_update_whitelist_cmpl_evt_param update_whitelist_cmpl Event parameter of ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_update_duplicate_exceptional_list_cmpl_evt_param update_duplicate_excepti Event parameter of ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_set_channels_evt_param ble_set_channels Event parameter of ESP_GAP_BLE_SET_CHANNELS_EVT struct esp_ble_gap_cb_param_t::ble_read_phy_cmpl_evt_param read_phy Event parameter of ESP_GAP_BLE_READ_PHY_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_set_perf_def_phy_cmpl_evt_param set_perf_def_phy Event parameter of ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_set_perf_phy_cmpl_evt_param set_perf_phy Event parameter of ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_adv_set_rand_addr_cmpl_evt_param ext_adv_set_rand_addr Event parameter of ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_adv_set_params_cmpl_evt_param ext_adv_set_params Event parameter of ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_adv_data_set_cmpl_evt_param ext_adv_data_set Event parameter of ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_adv_scan_rsp_set_cmpl_evt_param scan_rsp_set Event parameter of ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_adv_start_cmpl_evt_param ext_adv_start Event parameter of ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_adv_stop_cmpl_evt_param ext_adv_stop Event parameter of ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT Espressif Systems 195 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_gap_cb_param_t::ble_ext_adv_set_remove_cmpl_evt_param ext_adv_remove Event parameter of ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_adv_set_clear_cmpl_evt_param ext_adv_clear Event parameter of ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_periodic_adv_set_params_cmpl_param peroid_adv_set_params Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_periodic_adv_data_set_cmpl_param period_adv_data_set Event parameter of ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_periodic_adv_start_cmpl_param period_adv_start Event parameter of ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_periodic_adv_stop_cmpl_param period_adv_stop Event parameter of ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_period_adv_create_sync_cmpl_param period_adv_create_sync Event parameter of ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_period_adv_sync_cancel_cmpl_param period_adv_sync_cancel Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_period_adv_sync_terminate_cmpl_param period_adv_sync_term Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_period_adv_add_dev_cmpl_param period_adv_add_dev Event parameter of ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_period_adv_remove_dev_cmpl_param period_adv_remove_dev Event parameter of ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_period_adv_clear_dev_cmpl_param period_adv_clear_dev Event parameter of ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_set_ext_scan_params_cmpl_param set_ext_scan_params Event parameter of ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_scan_start_cmpl_param ext_scan_start Event parameter of ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_scan_stop_cmpl_param ext_scan_stop Event parameter of ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_conn_params_set_cmpl_param ext_conn_params_set Event parameter of ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_adv_terminate_param adv_terminate Event parameter of ESP_GAP_BLE_ADV_TERMINATED_EVT struct esp_ble_gap_cb_param_t::ble_scan_req_received_param scan_req_received Event parameter of ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT struct esp_ble_gap_cb_param_t::ble_channel_sel_alg_param channel_sel_alg Event parameter of ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT struct esp_ble_gap_cb_param_t::ble_periodic_adv_sync_lost_param periodic_adv_sync_lost Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT struct esp_ble_gap_cb_param_t::ble_periodic_adv_sync_estab_param periodic_adv_sync_estab Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT struct esp_ble_gap_cb_param_t::ble_phy_update_cmpl_param phy_update Event parameter of ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT struct esp_ble_gap_cb_param_t::ble_ext_adv_report_param ext_adv_report Event parameter of ESP_GAP_BLE_EXT_ADV_REPORT_EVT Espressif Systems 196 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_gap_cb_param_t::ble_periodic_adv_report_param period_adv_report Event parameter of ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT struct ble_adv_data_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the set advertising data operation success status struct ble_adv_data_raw_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the set raw advertising data operation success status struct ble_adv_start_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_START_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate advertising start operation success status struct ble_adv_stop_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate adv stop operation success status struct ble_adv_terminate_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_ADV_TERMINATED_EVT. Public Members uint8_t status Indicate adv terminate status uint8_t adv_instance extend advertising handle uint16_t conn_idx connection index uint8_t completed_event the number of completed extend advertising events struct ble_channel_sel_alg_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT. Espressif Systems 197 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t conn_handle connection handle uint8_t channel_sel_alg channel selection algorithm struct ble_clear_bond_dev_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the clear bond device operation success status struct ble_ext_adv_data_set_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate extend advertising data set status struct ble_ext_adv_report_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_REPORT_EVT. Public Members esp_ble_gap_ext_adv_reprot_t params extend advertising report parameters struct ble_ext_adv_scan_rsp_set_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate extend advertising sacn response data set status struct ble_ext_adv_set_clear_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate advertising stop operation success status struct ble_ext_adv_set_params_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT. Espressif Systems 198 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_bt_status_t status Indicate extend advertising parameters set status struct ble_ext_adv_set_rand_addr_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate extend advertising random address set status struct ble_ext_adv_set_remove_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate advertising stop operation success status struct ble_ext_adv_start_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate advertising start operation success status struct ble_ext_adv_stop_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate advertising stop operation success status struct ble_ext_conn_params_set_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate extend connection parameters set status struct ble_ext_scan_start_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate extend advertising start status struct ble_ext_scan_stop_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT. Espressif Systems 199 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_bt_status_t status Indicate extend advertising stop status struct ble_get_bond_dev_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the get bond device operation success status uint8_t dev_num Indicate the get number device in the bond list esp_ble_bond_dev_t *bond_dev the pointer to the bond device Structure struct ble_local_privacy_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the set local privacy operation success status struct ble_period_adv_add_dev_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate periodic advertising device list add status struct ble_period_adv_clear_dev_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate periodic advertising device list clean status struct ble_period_adv_create_sync_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate periodic advertising create sync status struct ble_period_adv_remove_dev_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT. Espressif Systems 200 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_bt_status_t status Indicate periodic advertising device list remove status struct ble_period_adv_sync_cancel_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate periodic advertising sync cancle status struct ble_period_adv_sync_terminate_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate periodic advertising sync terminate status struct ble_periodic_adv_data_set_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate periodic advertising data set status struct ble_periodic_adv_report_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT. Public Members esp_ble_gap_periodic_adv_report_t params periodic advertising report parameters struct ble_periodic_adv_set_params_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate periodic advertisingparameters set status struct ble_periodic_adv_start_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate periodic advertising start status struct ble_periodic_adv_stop_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT. Espressif Systems 201 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_bt_status_t status Indicate periodic advertising stop status struct ble_periodic_adv_sync_estab_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT. Public Members uint8_t status periodic advertising sync status uint16_t sync_handle periodic advertising sync handle uint8_t sid periodic advertising sid esp_ble_addr_type_t adv_addr_type periodic advertising address type esp_bd_addr_t adv_addr periodic advertising address esp_ble_gap_phy_t adv_phy periodic advertising phy type uint16_t period_adv_interval periodic advertising interval uint8_t adv_clk_accuracy periodic advertising clock accuracy struct ble_periodic_adv_sync_lost_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT. Public Members uint16_t sync_handle sync handle struct ble_phy_update_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT. Public Members esp_bt_status_t status phy update status esp_bd_addr_t bda address esp_ble_gap_phy_t tx_phy tx phy type esp_ble_gap_phy_t rx_phy rx phy type struct ble_pkt_data_length_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT. Espressif Systems 202 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_bt_status_t status Indicate the set pkt data length operation success status esp_ble_pkt_data_length_params_t params pkt data length value struct ble_read_phy_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_READ_PHY_COMPLETE_EVT. Public Members esp_bt_status_t status read phy complete status esp_bd_addr_t bda read phy address esp_ble_gap_phy_t tx_phy tx phy type esp_ble_gap_phy_t rx_phy rx phy type struct ble_read_rssi_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the read adv tx power operation success status int8_t rssi The ble remote device rssi value, the range is from -127 to 20, the unit is dbm, if the RSSI cannot be read, the RSSI metric shall be set to 127. esp_bd_addr_t remote_addr The remote device address struct ble_remove_bond_dev_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the remove bond device operation success status esp_bd_addr_t bd_addr The device address which has been remove from the bond list struct ble_scan_param_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the set scan param operation success status Espressif Systems 203 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct ble_scan_req_received_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT. Public Members uint8_t adv_instance extend advertising handle esp_ble_addr_type_t scan_addr_type scanner address type esp_bd_addr_t scan_addr scanner address struct ble_scan_result_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_RESULT_EVT. Public Members esp_gap_search_evt_t search_evt Search event type esp_bd_addr_t bda Bluetooth device address which has been searched esp_bt_dev_type_t dev_type Device type esp_ble_addr_type_t ble_addr_type Ble device address type esp_ble_evt_type_t ble_evt_type Ble scan result event type int rssi Searched 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 struct ble_scan_rsp_data_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the set scan response data operation success status Espressif Systems 204 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct ble_scan_rsp_data_raw_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate the set raw advertising data operation success status struct ble_scan_start_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_START_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate scan start operation success status struct ble_scan_stop_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate scan stop operation success status struct ble_set_channels_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_CHANNELS_EVT. Public Members esp_bt_status_t stat BLE set channel status struct ble_set_ext_scan_params_cmpl_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate extend advertising parameters set status struct ble_set_perf_def_phy_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate perf default phy set status struct ble_set_perf_phy_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT. Espressif Systems 205 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_bt_status_t status Indicate perf phy set status struct ble_set_rand_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT. Public Members esp_bt_status_t status Indicate set static rand address operation success status struct ble_update_conn_params_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT. Public Members esp_bt_status_t status Indicate update connection parameters success status esp_bd_addr_t bda Bluetooth device address uint16_t min_int Min connection interval uint16_t max_int Max connection interval uint16_t latency Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3 uint16_t conn_int Current connection interval uint16_t timeout Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec struct ble_update_duplicate_exceptional_list_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT. Public Members esp_bt_status_t status Indicate update duplicate scan exceptional list operation success status uint8_t subcode Define in esp_bt_duplicate_exceptional_subcode_type_t uint16_t length The length of device_info esp_duplicate_info_t device_info device information, when subcode is ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN, the value is invalid struct ble_update_whitelist_cmpl_evt_param #include <esp_gap_ble_api.h> ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT. Espressif Systems 206 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_bt_status_t status Indicate the add or remove whitelist operation success status esp_ble_wl_opration_t wl_opration The value is ESP_BLE_WHITELIST_ADD if add address to whitelist operation success, ESP_BLE_WHITELIST_REMOVE if remove address from the whitelist operation success Structures struct esp_ble_adv_params_t Advertising parameters. Public Members uint16_t adv_int_min Minimum advertising interval for undirected and low duty cycle directed advertising. Range: 0x0020 to 0x4000 Default: N = 0x0800 (1.28 second) Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec uint16_t adv_int_max Maximum advertising interval for undirected and low duty cycle directed advertising. Range: 0x0020 to 0x4000 Default: N = 0x0800 (1.28 second) Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec Advertising max interval esp_ble_adv_type_t adv_type Advertising type esp_ble_addr_type_t own_addr_type Owner bluetooth device address type esp_bd_addr_t peer_addr Peer device bluetooth device address esp_ble_addr_type_t peer_addr_type Peer device bluetooth device address type, only support public address type and random address type esp_ble_adv_channel_t channel_map Advertising channel map esp_ble_adv_filter_t adv_filter_policy Advertising filter policy struct esp_ble_adv_data_t Advertising data content, according to oSupplement to the Bluetooth Core Specificationp. Public Members bool set_scan_rsp Set this advertising data as scan response or not bool include_name Advertising data include device name or not bool include_txpower Advertising data include TX power int min_interval Advertising data show slave preferred connection min interval. The connection interval in the following manner: connIntervalmin = Conn_Interval_Min * 1.25 ms Conn_Interval_Min range: 0x0006 to 0x0C80 Value of 0xFFFF indicates no specific minimum. Values not defined above are reserved for future use. Espressif Systems 207 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 208 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t interval connection interval uint16_t latency Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3 uint16_t timeout Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec Time Range: 100 msec to 32 seconds struct esp_ble_conn_update_params_t Connection update parameters. Public Members esp_bd_addr_t bda Bluetooth device address uint16_t min_int Min connection interval uint16_t max_int Max connection interval uint16_t latency Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3 uint16_t timeout Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec Time Range: 100 msec to 32 seconds struct esp_ble_pkt_data_length_params_t BLE pkt date length keys. Public Members uint16_t rx_len pkt rx data length value uint16_t tx_len pkt tx data length value struct esp_ble_penc_keys_t BLE encryption keys. Public Members esp_bt_octet16_t ltk The long term key esp_bt_octet8_t rand The random number uint16_t ediv The ediv value uint8_t sec_level The security level of the security link uint8_t key_size The key size(7~16) of the security link Espressif Systems 209 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_pcsrk_keys_t BLE CSRK keys. Public Members uint32_t counter The counter esp_bt_octet16_t csrk The csrk key uint8_t sec_level The security level struct esp_ble_pid_keys_t BLE pid keys. Public Members esp_bt_octet16_t irk The irk value esp_ble_addr_type_t addr_type The address type esp_bd_addr_t static_addr The static address struct esp_ble_lenc_keys_t BLE Encryption reproduction keys. Public Members esp_bt_octet16_t ltk The long term key uint16_t div The div value uint8_t key_size The key size of the security link uint8_t sec_level The security level of the security link struct esp_ble_lcsrk_keys BLE SRK keys. Public Members uint32_t counter The counter value uint16_t div The div value uint8_t sec_level The security level of the security link esp_bt_octet16_t csrk The csrk key value Espressif Systems 210 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_sec_key_notif_t Structure associated with ESP_KEY_NOTIF_EVT. Public Members esp_bd_addr_t bd_addr peer address uint32_t passkey the numeric value for comparison. If just_works, do not show this number to UI struct esp_ble_sec_req_t Structure of the security request. Public Members esp_bd_addr_t bd_addr peer address struct esp_ble_bond_key_info_t struct type of the bond key information value Public Members esp_ble_key_mask_t key_mask the key mask to indicate witch key is present esp_ble_penc_keys_t penc_key received peer encryption key esp_ble_pcsrk_keys_t pcsrk_key received peer device SRK esp_ble_pid_keys_t pid_key peer device ID key struct esp_ble_bond_dev_t struct type of the bond device value Public Members esp_bd_addr_t bd_addr peer address esp_ble_bond_key_info_t bond_key the bond key information struct esp_ble_key_t union type of the security key value Public Members esp_bd_addr_t bd_addr peer address esp_ble_key_type_t key_type key type of the security link esp_ble_key_value_t p_key_value the pointer to the key value Espressif Systems 211 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_local_id_keys_t structure type of the ble local id keys value Public Members esp_bt_octet16_t ir the 16 bits of the ir value esp_bt_octet16_t irk the 16 bits of the ir key value esp_bt_octet16_t dhk the 16 bits of the dh key value struct esp_ble_auth_cmpl_t Structure associated with ESP_AUTH_CMPL_EVT. Public Members esp_bd_addr_t bd_addr BD address peer device. bool key_present Valid link key value in key element esp_link_key key Link key associated with peer device. uint8_t key_type The type of Link Key bool success TRUE of authentication succeeded, FALSE if failed. uint8_t fail_reason The HCI reason/error code for when success=FALSE esp_ble_addr_type_t addr_type Peer device address type esp_bt_dev_type_t dev_type Device type esp_ble_auth_req_t auth_mode authentication mode struct esp_ble_gap_ext_adv_params_t ext adv parameters Public Members esp_ble_ext_adv_type_mask_t type ext adv type uint32_t interval_min ext adv minimum interval uint32_t interval_max ext adv maximum interval esp_ble_adv_channel_t channel_map ext adv channel map Espressif Systems 212 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_addr_type_t own_addr_type ext adv own addresss type esp_ble_addr_type_t peer_addr_type ext adv peer address type esp_bd_addr_t peer_addr ext adv peer address esp_ble_adv_filter_t filter_policy ext adv filter policy int8_t tx_power ext adv tx power esp_ble_gap_pri_phy_t primary_phy ext adv primary phy uint8_t max_skip ext adv maximum skip esp_ble_gap_phy_t secondary_phy ext adv secondary phy uint8_t sid ext adv sid bool scan_req_notif ext adv sacn request event notify struct esp_ble_ext_scan_cfg_t ext scan config Public Members esp_ble_scan_type_t scan_type ext scan type uint16_t scan_interval ext scan interval uint16_t scan_window ext scan window struct esp_ble_ext_scan_params_t ext scan parameters Public Members esp_ble_addr_type_t own_addr_type ext scan own addresss type esp_ble_scan_filter_t filter_policy ext scan filter policy esp_ble_scan_duplicate_t scan_duplicate ext scan duplicate scan esp_ble_ext_scan_cfg_mask_t cfg_mask ext scan config mask esp_ble_ext_scan_cfg_t uncoded_cfg ext scan uncoded config parameters esp_ble_ext_scan_cfg_t coded_cfg ext scan coded config parameters Espressif Systems 213 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_gap_conn_params_t create extend connection parameters Public Members uint16_t scan_interval init scan interval uint16_t scan_window init scan window uint16_t interval_min minimum interval uint16_t interval_max maximum interval uint16_t latency ext scan type uint16_t supervision_timeout connection supervision timeout uint16_t min_ce_len minimum ce length uint16_t max_ce_len maximum ce length struct esp_ble_gap_ext_adv_t extend adv enable parameters Public Members uint8_t instance advertising handle int duration advertising duration int max_events maximum number of extended advertising events struct esp_ble_gap_periodic_adv_params_t periodic adv parameters Public Members uint16_t interval_min periodic advertising minimum interval uint16_t interval_max periodic advertising maximum interval uint8_t properties periodic advertising properties struct esp_ble_gap_periodic_adv_sync_params_t periodic adv sync parameters Espressif Systems 214 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_gap_sync_t filter_policy periodic advertising sync filter policy uint8_t sid periodic advertising sid esp_ble_addr_type_t addr_type periodic advertising address type esp_bd_addr_t addr periodic advertising address uint16_t skip the maximum number of periodic advertising events that can be skipped uint16_t sync_timeout synchronization timeout struct esp_ble_gap_ext_adv_reprot_t extend adv report parameters Public Members esp_ble_gap_adv_type_t event_type extend advertising type uint8_t addr_type extend advertising address type esp_bd_addr_t addr extend advertising address esp_ble_gap_pri_phy_t primary_phy extend advertising primary phy esp_ble_gap_phy_t secondly_phy extend advertising secondary phy uint8_t sid extend advertising sid uint8_t tx_power extend advertising tx power int8_t rssi extend advertising rssi uint16_t per_adv_interval periodic advertising interval uint8_t dir_addr_type direct address type esp_bd_addr_t dir_addr direct address esp_ble_gap_ext_adv_data_status_t data_status data type uint8_t adv_data_len extend advertising data length uint8_t adv_data[251] extend advertising data Espressif Systems 215 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_gap_periodic_adv_report_t periodic adv report parameters Public Members uint16_t sync_handle periodic advertising train handle uint8_t tx_power periodic advertising tx power int8_t rssi periodic advertising rssi esp_ble_gap_ext_adv_data_status_t data_status periodic advertising data type uint8_t data_length periodic advertising data length uint8_t data[251] periodic advertising data struct esp_ble_gap_periodic_adv_sync_estab_t perodic adv sync establish parameters Public Members uint8_t status periodic advertising sync status uint16_t sync_handle periodic advertising train handle uint8_t sid periodic advertising sid esp_ble_addr_type_t addr_type periodic advertising address type esp_bd_addr_t adv_addr periodic advertising address esp_ble_gap_phy_t adv_phy periodic advertising adv phy type uint16_t period_adv_interval periodic advertising interval uint8_t adv_clk_accuracy periodic advertising clock accuracy Macros ESP_BLE_ADV_FLAG_LIMIT_DISC BLE_ADV_DATA_FLAG data flag bit definition used for advertising data flag ESP_BLE_ADV_FLAG_GEN_DISC ESP_BLE_ADV_FLAG_BREDR_NOT_SPT ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT ESP_BLE_ADV_FLAG_DMT_HOST_SPT ESP_BLE_ADV_FLAG_NON_LIMIT_DISC Espressif Systems 216 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_LE_KEY_NONE ESP_LE_KEY_PENC ESP_LE_KEY_PID ESP_LE_KEY_PCSRK ESP_LE_KEY_PLK ESP_LE_KEY_LLK ESP_LE_KEY_LENC ESP_LE_KEY_LID ESP_LE_KEY_LCSRK ESP_LE_AUTH_NO_BOND ESP_LE_AUTH_BOND ESP_LE_AUTH_REQ_MITM ESP_LE_AUTH_REQ_BOND_MITM 0101 ESP_LE_AUTH_REQ_SC_ONLY ESP_LE_AUTH_REQ_SC_BOND ESP_LE_AUTH_REQ_SC_MITM ESP_LE_AUTH_REQ_SC_MITM_BOND ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_DISABLE ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE ESP_BLE_OOB_DISABLE ESP_BLE_OOB_ENABLE ESP_IO_CAP_OUT ESP_IO_CAP_IO ESP_IO_CAP_IN ESP_IO_CAP_NONE ESP_IO_CAP_KBDISP ESP_BLE_APPEARANCE_UNKNOWN ESP_BLE_APPEARANCE_GENERIC_PHONE ESP_BLE_APPEARANCE_GENERIC_COMPUTER ESP_BLE_APPEARANCE_GENERIC_WATCH ESP_BLE_APPEARANCE_SPORTS_WATCH ESP_BLE_APPEARANCE_GENERIC_CLOCK ESP_BLE_APPEARANCE_GENERIC_DISPLAY ESP_BLE_APPEARANCE_GENERIC_REMOTE ESP_BLE_APPEARANCE_GENERIC_EYEGLASSES ESP_BLE_APPEARANCE_GENERIC_TAG ESP_BLE_APPEARANCE_GENERIC_KEYRING ESP_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER Espressif Systems 217 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER ESP_BLE_APPEARANCE_GENERIC_THERMOMETER ESP_BLE_APPEARANCE_THERMOMETER_EAR ESP_BLE_APPEARANCE_GENERIC_HEART_RATE ESP_BLE_APPEARANCE_HEART_RATE_BELT ESP_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE ESP_BLE_APPEARANCE_BLOOD_PRESSURE_ARM ESP_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST ESP_BLE_APPEARANCE_GENERIC_HID ESP_BLE_APPEARANCE_HID_KEYBOARD ESP_BLE_APPEARANCE_HID_MOUSE ESP_BLE_APPEARANCE_HID_JOYSTICK ESP_BLE_APPEARANCE_HID_GAMEPAD ESP_BLE_APPEARANCE_HID_DIGITIZER_TABLET ESP_BLE_APPEARANCE_HID_CARD_READER ESP_BLE_APPEARANCE_HID_DIGITAL_PEN ESP_BLE_APPEARANCE_HID_BARCODE_SCANNER ESP_BLE_APPEARANCE_GENERIC_GLUCOSE ESP_BLE_APPEARANCE_GENERIC_WALKING ESP_BLE_APPEARANCE_WALKING_IN_SHOE ESP_BLE_APPEARANCE_WALKING_ON_SHOE ESP_BLE_APPEARANCE_WALKING_ON_HIP ESP_BLE_APPEARANCE_GENERIC_CYCLING ESP_BLE_APPEARANCE_CYCLING_COMPUTER ESP_BLE_APPEARANCE_CYCLING_SPEED ESP_BLE_APPEARANCE_CYCLING_CADENCE ESP_BLE_APPEARANCE_CYCLING_POWER ESP_BLE_APPEARANCE_CYCLING_SPEED_CADENCE ESP_BLE_APPEARANCE_GENERIC_PULSE_OXIMETER ESP_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP ESP_BLE_APPEARANCE_PULSE_OXIMETER_WRIST ESP_BLE_APPEARANCE_GENERIC_WEIGHT ESP_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVICE ESP_BLE_APPEARANCE_POWERED_WHEELCHAIR ESP_BLE_APPEARANCE_MOBILITY_SCOOTER ESP_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MONITOR ESP_BLE_APPEARANCE_GENERIC_INSULIN_PUMP ESP_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP ESP_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP Espressif Systems 218 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_APPEARANCE_INSULIN_PEN ESP_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY ESP_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NAV ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AND_NAV ESP_GAP_BLE_CHANNELS_LEN ESP_GAP_BLE_ADD_WHITELIST_COMPLETE_EVT This is the old name, just for backwards compatibility. ESP_BLE_ADV_DATA_LEN_MAX Advertising data maximum length. ESP_BLE_SCAN_RSP_DATA_LEN_MAX Scan response data maximum length. BLE_BIT(n) ESP_BLE_GAP_SET_EXT_ADV_PROP_NONCONN_NONSCANNABLE_UNDIRECTED ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE ESP_BLE_GAP_SET_EXT_ADV_PROP_DIRECTED ESP_BLE_GAP_SET_EXT_ADV_PROP_HD_DIRECTED ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY ESP_BLE_GAP_SET_EXT_ADV_PROP_ANON_ADV ESP_BLE_GAP_SET_EXT_ADV_PROP_INCLUDE_TX_PWR ESP_BLE_GAP_SET_EXT_ADV_PROP_MASK ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_IND ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_LD_DIR ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_HD_DIR ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_SCAN ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_NONCONN ESP_BLE_GAP_PHY_1M ESP_BLE_GAP_PHY_2M ESP_BLE_GAP_PHY_CODED ESP_BLE_GAP_NO_PREFER_TRANSMIT_PHY ESP_BLE_GAP_NO_PREFER_RECEIVE_PHY ESP_BLE_GAP_PRI_PHY_1M ESP_BLE_GAP_PRI_PHY_CODED ESP_BLE_GAP_PHY_1M_PREF_MASK ESP_BLE_GAP_PHY_2M_PREF_MASK ESP_BLE_GAP_PHY_CODED_PREF_MASK ESP_BLE_GAP_PHY_OPTIONS_NO_PREF Espressif Systems 219 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_GAP_PHY_OPTIONS_PREF_S2_CODING ESP_BLE_GAP_PHY_OPTIONS_PREF_S8_CODING ESP_BLE_GAP_EXT_SCAN_CFG_UNCODE_MASK ESP_BLE_GAP_EXT_SCAN_CFG_CODE_MASK ESP_BLE_GAP_EXT_ADV_DATA_COMPLETE ESP_BLE_GAP_EXT_ADV_DATA_INCOMPLETE ESP_BLE_GAP_EXT_ADV_DATA_TRUNCATED ESP_BLE_GAP_SYNC_POLICY_BY_ADV_INFO ESP_BLE_GAP_SYNC_POLICY_BY_PERIODIC_LIST ESP_BLE_ADV_REPORT_EXT_ADV_IND ESP_BLE_ADV_REPORT_EXT_SCAN_IND ESP_BLE_ADV_REPORT_EXT_DIRECT_ADV ESP_BLE_ADV_REPORT_EXT_SCAN_RSP ESP_BLE_LEGACY_ADV_TYPE_IND ESP_BLE_LEGACY_ADV_TYPE_DIRECT_IND ESP_BLE_LEGACY_ADV_TYPE_SCAN_IND ESP_BLE_LEGACY_ADV_TYPE_NONCON_IND ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_IND ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_SCAN_IND Type Definitions typedef uint8_t esp_ble_key_type_t typedef uint8_t esp_ble_auth_req_t combination of the above bit pattern typedef uint8_t esp_ble_io_cap_t combination of the io capability typedef uint8_t esp_gap_ble_channels[ESP_GAP_BLE_CHANNELS_LEN] typedef uint8_t esp_duplicate_info_t[ESP_BD_ADDR_LEN] typedef uint16_t esp_ble_ext_adv_type_mask_t typedef uint8_t esp_ble_gap_phy_t typedef uint8_t esp_ble_gap_all_phys_t typedef uint8_t esp_ble_gap_pri_phy_t typedef uint8_t esp_ble_gap_phy_mask_t typedef uint16_t esp_ble_gap_prefer_phy_options_t typedef uint8_t esp_ble_ext_scan_cfg_mask_t typedef uint8_t esp_ble_gap_ext_adv_data_status_t typedef uint8_t esp_ble_gap_sync_t typedef uint8_t esp_ble_gap_adv_type_t typedef void (*esp_gap_ble_cb_t)(esp_gap_ble_cb_event_t event, GAP callback function type. *param) esp_ble_gap_cb_param_t Espressif Systems 220 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Parameters · event: : Event type · param: : Point to callback parameter, currently is union type Enumerations enum esp_gap_ble_cb_event_t GAP BLE callback event type. Values: ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT = 0 When advertising data set complete, the event comes ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT When scan response data set complete, the event comes ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT When scan parameters set complete, the event comes ESP_GAP_BLE_SCAN_RESULT_EVT When one scan result ready, the event comes each time ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT When raw advertising data set complete, the event comes ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT When raw advertising data set complete, the event comes ESP_GAP_BLE_ADV_START_COMPLETE_EVT When start advertising complete, the event comes ESP_GAP_BLE_SCAN_START_COMPLETE_EVT When start scan complete, the event comes ESP_GAP_BLE_AUTH_CMPL_EVT = 8 ESP_GAP_BLE_KEY_EVT ESP_GAP_BLE_SEC_REQ_EVT ESP_GAP_BLE_PASSKEY_NOTIF_EVT ESP_GAP_BLE_PASSKEY_REQ_EVT ESP_GAP_BLE_OOB_REQ_EVT ESP_GAP_BLE_LOCAL_IR_EVT ESP_GAP_BLE_LOCAL_ER_EVT ESP_GAP_BLE_NC_REQ_EVT ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT When stop adv complete, the event comes ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT When stop scan complete, the event comes ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT = 19 When set the static rand address complete, the event comes ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT When update connection parameters complete, the event comes ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT When set pkt length complete, the event comes ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT When Enable/disable privacy on the local device complete, the event comes Espressif Systems 221 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT When remove the bond device complete, the event comes ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT When clear the bond device clear complete, the event comes ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT When get the bond device list complete, the event comes ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT When read the rssi complete, the event comes ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT When add or remove whitelist complete, the event comes ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT When update duplicate exceptional list complete, the event comes ESP_GAP_BLE_SET_CHANNELS_EVT = 29 When setting BLE channels complete, the event comes ESP_GAP_BLE_READ_PHY_COMPLETE_EVT ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_EVT ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT ESP_GAP_BLE_EXT_ADV_REPORT_EVT Espressif Systems 222 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GAP_BLE_SCAN_TIMEOUT_EVT ESP_GAP_BLE_ADV_TERMINATED_EVT ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVT ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT ESP_GAP_BLE_EVT_MAX enum esp_ble_adv_data_type The type of advertising data(not adv_type) Values: ESP_BLE_AD_TYPE_FLAG = 0x01 ESP_BLE_AD_TYPE_16SRV_PART = 0x02 ESP_BLE_AD_TYPE_16SRV_CMPL = 0x03 ESP_BLE_AD_TYPE_32SRV_PART = 0x04 ESP_BLE_AD_TYPE_32SRV_CMPL = 0x05 ESP_BLE_AD_TYPE_128SRV_PART = 0x06 ESP_BLE_AD_TYPE_128SRV_CMPL = 0x07 ESP_BLE_AD_TYPE_NAME_SHORT = 0x08 ESP_BLE_AD_TYPE_NAME_CMPL = 0x09 ESP_BLE_AD_TYPE_TX_PWR = 0x0A ESP_BLE_AD_TYPE_DEV_CLASS = 0x0D ESP_BLE_AD_TYPE_SM_TK = 0x10 ESP_BLE_AD_TYPE_SM_OOB_FLAG = 0x11 ESP_BLE_AD_TYPE_INT_RANGE = 0x12 ESP_BLE_AD_TYPE_SOL_SRV_UUID = 0x14 ESP_BLE_AD_TYPE_128SOL_SRV_UUID = 0x15 ESP_BLE_AD_TYPE_SERVICE_DATA = 0x16 ESP_BLE_AD_TYPE_PUBLIC_TARGET = 0x17 ESP_BLE_AD_TYPE_RANDOM_TARGET = 0x18 ESP_BLE_AD_TYPE_APPEARANCE = 0x19 ESP_BLE_AD_TYPE_ADV_INT = 0x1A ESP_BLE_AD_TYPE_LE_DEV_ADDR = 0x1b ESP_BLE_AD_TYPE_LE_ROLE = 0x1c ESP_BLE_AD_TYPE_SPAIR_C256 = 0x1d ESP_BLE_AD_TYPE_SPAIR_R256 = 0x1e ESP_BLE_AD_TYPE_32SOL_SRV_UUID = 0x1f ESP_BLE_AD_TYPE_32SERVICE_DATA = 0x20 ESP_BLE_AD_TYPE_128SERVICE_DATA = 0x21 ESP_BLE_AD_TYPE_LE_SECURE_CONFIRM = 0x22 Espressif Systems 223 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_AD_TYPE_LE_SECURE_RANDOM = 0x23 ESP_BLE_AD_TYPE_URI = 0x24 ESP_BLE_AD_TYPE_INDOOR_POSITION = 0x25 ESP_BLE_AD_TYPE_TRANS_DISC_DATA = 0x26 ESP_BLE_AD_TYPE_LE_SUPPORT_FEATURE = 0x27 ESP_BLE_AD_TYPE_CHAN_MAP_UPDATE = 0x28 ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE = 0xFF enum esp_ble_adv_type_t Advertising mode. Values: ADV_TYPE_IND = 0x00 ADV_TYPE_DIRECT_IND_HIGH = 0x01 ADV_TYPE_SCAN_IND = 0x02 ADV_TYPE_NONCONN_IND = 0x03 ADV_TYPE_DIRECT_IND_LOW = 0x04 enum esp_ble_adv_channel_t Advertising channel mask. Values: ADV_CHNL_37 = 0x01 ADV_CHNL_38 = 0x02 ADV_CHNL_39 = 0x04 ADV_CHNL_ALL = 0x07 enum esp_ble_adv_filter_t Values: ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00 Allow both scan and connection requests from anyone. ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY Allow both scan req from White List devices only and connection req from anyone. ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST Allow both scan req from anyone and connection req from White List devices only. ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST Allow scan and connection requests from White List devices only. enum esp_ble_sec_act_t Values: ESP_BLE_SEC_ENCRYPT = 1 ESP_BLE_SEC_ENCRYPT_NO_MITM ESP_BLE_SEC_ENCRYPT_MITM enum esp_ble_sm_param_t Values: ESP_BLE_SM_PASSKEY = 0 ESP_BLE_SM_AUTHEN_REQ_MODE ESP_BLE_SM_IOCAP_MODE Espressif Systems 224 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_SM_SET_INIT_KEY ESP_BLE_SM_SET_RSP_KEY ESP_BLE_SM_MAX_KEY_SIZE ESP_BLE_SM_MIN_KEY_SIZE ESP_BLE_SM_SET_STATIC_PASSKEY ESP_BLE_SM_CLEAR_STATIC_PASSKEY ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH ESP_BLE_SM_OOB_SUPPORT ESP_BLE_APP_ENC_KEY_SIZE ESP_BLE_SM_MAX_PARAM enum esp_ble_scan_type_t Ble scan type. Values: BLE_SCAN_TYPE_PASSIVE = 0x0 Passive scan BLE_SCAN_TYPE_ACTIVE = 0x1 Active scan enum esp_ble_scan_filter_t Ble scan filter type. Values: BLE_SCAN_FILTER_ALLOW_ALL = 0x0 Accept all : 1. advertisement packets except directed advertising packets not addressed to this device (default). BLE_SCAN_FILTER_ALLOW_ONLY_WLST = 0x1 Accept only : 1. advertisement packets from devices where the 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. enum esp_ble_scan_duplicate_t Ble scan duplicate type. Values: BLE_SCAN_DUPLICATE_DISABLE = 0x0 the Link Layer should generate advertising reports to the host for each packet received BLE_SCAN_DUPLICATE_ENABLE = 0x1 the Link Layer should filter out duplicate advertising reports to the Host Espressif Systems 225 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference BLE_SCAN_DUPLICATE_MAX = 0x2 0x02 0xFF, Reserved for future use enum esp_gap_search_evt_t Sub Event of ESP_GAP_BLE_SCAN_RESULT_EVT. Values: ESP_GAP_SEARCH_INQ_RES_EVT = 0 Inquiry result for a peer device. ESP_GAP_SEARCH_INQ_CMPL_EVT = 1 Inquiry complete. ESP_GAP_SEARCH_DISC_RES_EVT = 2 Discovery result for a peer device. ESP_GAP_SEARCH_DISC_BLE_RES_EVT = 3 Discovery result for BLE GATT based service on a peer device. ESP_GAP_SEARCH_DISC_CMPL_EVT = 4 Discovery complete. ESP_GAP_SEARCH_DI_DISC_CMPL_EVT = 5 Discovery complete. ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT = 6 Search cancelled ESP_GAP_SEARCH_INQ_DISCARD_NUM_EVT = 7 The number of pkt discarded by flow control enum esp_ble_evt_type_t Ble scan result event type, to indicate the result is scan response or advertising data or other. Values: ESP_BLE_EVT_CONN_ADV = 0x00 Connectable undirected advertising (ADV_IND) ESP_BLE_EVT_CONN_DIR_ADV = 0x01 Connectable directed advertising (ADV_DIRECT_IND) ESP_BLE_EVT_DISC_ADV = 0x02 Scannable undirected advertising (ADV_SCAN_IND) ESP_BLE_EVT_NON_CONN_ADV = 0x03 Non connectable undirected advertising (ADV_NONCONN_IND) ESP_BLE_EVT_SCAN_RSP = 0x04 Scan Response (SCAN_RSP) enum esp_ble_wl_opration_t Values: ESP_BLE_WHITELIST_REMOVE = 0X00 remove mac from whitelist ESP_BLE_WHITELIST_ADD = 0X01 add address to whitelist enum esp_bt_duplicate_exceptional_subcode_type_t Values: ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_ADD = 0 Add device info into duplicate scan exceptional list ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_REMOVE Remove device info from duplicate scan exceptional list Espressif Systems 226 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN Clean duplicate scan exceptional list enum esp_ble_duplicate_exceptional_info_type_t Values: ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_ADV_ADDR = 0 BLE advertising address , device info will be added into ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_LINK_ID BLE mesh link ID, it is for BLE mesh, device info will be added into ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_LIST ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_BEACON_TYPE BLE mesh beacon AD type, the format is | Len | 0x2B | Beacon Type | Beacon Data | ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROV_SRV_ADV BLE mesh provisioning service uuid, the format is | 0x02 | 0x01 | flags | 0x03 | 0x03 | 0x1827 | 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 Header File · components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h Unions union esp_gatt_rsp_t #include <esp_gatt_defs.h> GATT remote read request response type. Espressif Systems 227 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_gatt_value_t attr_value Gatt attribute structure uint16_t handle Gatt attribute handle Structures struct esp_gatt_id_t Gatt id, include uuid and instance id. Public Members esp_bt_uuid_t uuid UUID uint8_t inst_id Instance id struct esp_gatt_srvc_id_t Gatt service id, include id (uuid and instance id) and primary flag. Public Members esp_gatt_id_t id Gatt id, include uuid and instance bool is_primary This service is primary or not struct esp_attr_desc_t Attribute description (used to create database) Public Members uint16_t uuid_length UUID length uint8_t *uuid_p UUID value uint16_t perm Attribute permission uint16_t max_length Maximum length of the element uint16_t length Current length of the element uint8_t *value Element value array struct esp_attr_control_t attribute auto response flag Espressif Systems 228 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t auto_rsp if auto_rsp set to ESP_GATT_RSP_BY_APP, means the response of Write/Read operation will by replied by application. if auto_rsp set to ESP_GATT_AUTO_RSP, means the response of Write/Read operation will be replied by GATT stack automatically. struct esp_gatts_attr_db_t attribute type added to the gatt server database Public Members esp_attr_control_t attr_control The attribute control type esp_attr_desc_t att_desc The attribute type struct esp_attr_value_t set the attribute value type Public Members uint16_t attr_max_len attribute max value length uint16_t attr_len attribute current value length uint8_t *attr_value the pointer to attribute value struct esp_gatts_incl_svc_desc_t Gatt include service entry element. Public Members uint16_t start_hdl Gatt start handle value of included service uint16_t end_hdl Gatt end handle value of included service uint16_t uuid Gatt attribute value UUID of included service struct esp_gatts_incl128_svc_desc_t Gatt include 128 bit service entry element. Public Members uint16_t start_hdl Gatt start handle value of included 128 bit service uint16_t end_hdl Gatt end handle value of included 128 bit service struct esp_gatt_value_t Gatt attribute value. Espressif Systems 229 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t value[ESP_GATT_MAX_ATTR_LEN] Gatt attribute value uint16_t handle Gatt attribute handle uint16_t offset Gatt attribute value offset uint16_t len Gatt attribute value length uint8_t auth_req Gatt authentication request struct esp_gatt_conn_params_t Connection parameters information. Public Members uint16_t interval connection interval uint16_t latency Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3 uint16_t timeout Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec Time Range: 100 msec to 32 seconds struct esp_gattc_multi_t read multiple attribute Public Members uint8_t num_attr The number of the attribute uint16_t handles[ESP_GATT_MAX_READ_MULTI_HANDLES] The handles list struct esp_gattc_db_elem_t data base attribute element Public Members esp_gatt_db_attr_type_t type The attribute type uint16_t attribute_handle The attribute handle, 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 Espressif Systems 230 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 struct esp_gattc_incl_svc_elem_t include service element Public Members uint16_t handle The include service current attribute handle uint16_t incl_srvc_s_handle The start handle of the service which has been included uint16_t incl_srvc_e_handle The end handle of the service which has been included Espressif Systems 231 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 ESP_GATT_UUID_PRI_SERVICE ESP_GATT_UUID_SEC_SERVICE ESP_GATT_UUID_INCLUDE_SERVICE ESP_GATT_UUID_CHAR_DECLARE ESP_GATT_UUID_CHAR_EXT_PROP ESP_GATT_UUID_CHAR_DESCRIPTION ESP_GATT_UUID_CHAR_CLIENT_CONFIG ESP_GATT_UUID_CHAR_SRVR_CONFIG Espressif Systems 232 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GATT_UUID_CHAR_PRESENT_FORMAT ESP_GATT_UUID_CHAR_AGG_FORMAT ESP_GATT_UUID_CHAR_VALID_RANGE ESP_GATT_UUID_EXT_RPT_REF_DESCR ESP_GATT_UUID_RPT_REF_DESCR ESP_GATT_UUID_NUM_DIGITALS_DESCR ESP_GATT_UUID_VALUE_TRIGGER_DESCR ESP_GATT_UUID_ENV_SENSING_CONFIG_DESCR ESP_GATT_UUID_ENV_SENSING_MEASUREMENT_DESCR ESP_GATT_UUID_ENV_SENSING_TRIGGER_DESCR ESP_GATT_UUID_TIME_TRIGGER_DESCR ESP_GATT_UUID_GAP_DEVICE_NAME ESP_GATT_UUID_GAP_ICON ESP_GATT_UUID_GAP_PREF_CONN_PARAM ESP_GATT_UUID_GAP_CENTRAL_ADDR_RESOL ESP_GATT_UUID_GATT_SRV_CHGD ESP_GATT_UUID_ALERT_LEVEL ESP_GATT_UUID_TX_POWER_LEVEL ESP_GATT_UUID_CURRENT_TIME ESP_GATT_UUID_LOCAL_TIME_INFO ESP_GATT_UUID_REF_TIME_INFO ESP_GATT_UUID_NW_STATUS ESP_GATT_UUID_NW_TRIGGER ESP_GATT_UUID_ALERT_STATUS ESP_GATT_UUID_RINGER_CP ESP_GATT_UUID_RINGER_SETTING ESP_GATT_UUID_GM_MEASUREMENT ESP_GATT_UUID_GM_CONTEXT ESP_GATT_UUID_GM_CONTROL_POINT ESP_GATT_UUID_GM_FEATURE ESP_GATT_UUID_SYSTEM_ID ESP_GATT_UUID_MODEL_NUMBER_STR ESP_GATT_UUID_SERIAL_NUMBER_STR ESP_GATT_UUID_FW_VERSION_STR ESP_GATT_UUID_HW_VERSION_STR ESP_GATT_UUID_SW_VERSION_STR ESP_GATT_UUID_MANU_NAME ESP_GATT_UUID_IEEE_DATA ESP_GATT_UUID_PNP_ID Espressif Systems 233 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GATT_UUID_HID_INFORMATION ESP_GATT_UUID_HID_REPORT_MAP ESP_GATT_UUID_HID_CONTROL_POINT ESP_GATT_UUID_HID_REPORT ESP_GATT_UUID_HID_PROTO_MODE ESP_GATT_UUID_HID_BT_KB_INPUT ESP_GATT_UUID_HID_BT_KB_OUTPUT ESP_GATT_UUID_HID_BT_MOUSE_INPUT ESP_GATT_HEART_RATE_MEAS Heart Rate Measurement. ESP_GATT_BODY_SENSOR_LOCATION Body Sensor Location. ESP_GATT_HEART_RATE_CNTL_POINT Heart Rate Control Point. ESP_GATT_UUID_BATTERY_LEVEL ESP_GATT_UUID_SC_CONTROL_POINT ESP_GATT_UUID_SENSOR_LOCATION ESP_GATT_UUID_RSC_MEASUREMENT ESP_GATT_UUID_RSC_FEATURE ESP_GATT_UUID_CSC_MEASUREMENT ESP_GATT_UUID_CSC_FEATURE ESP_GATT_UUID_SCAN_INT_WINDOW ESP_GATT_UUID_SCAN_REFRESH ESP_GATT_ILLEGAL_UUID GATT INVALID UUID. ESP_GATT_ILLEGAL_HANDLE GATT INVALID HANDLE. ESP_GATT_ATTR_HANDLE_MAX GATT attribute max handle. ESP_GATT_MAX_READ_MULTI_HANDLES ESP_GATT_PERM_READ Attribute permissions. ESP_GATT_PERM_READ_ENCRYPTED ESP_GATT_PERM_READ_ENC_MITM ESP_GATT_PERM_WRITE ESP_GATT_PERM_WRITE_ENCRYPTED ESP_GATT_PERM_WRITE_ENC_MITM ESP_GATT_PERM_WRITE_SIGNED ESP_GATT_PERM_WRITE_SIGNED_MITM ESP_GATT_PERM_READ_AUTHORIZATION ESP_GATT_PERM_WRITE_AUTHORIZATION Espressif Systems 234 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GATT_CHAR_PROP_BIT_BROADCAST ESP_GATT_CHAR_PROP_BIT_READ ESP_GATT_CHAR_PROP_BIT_WRITE_NR ESP_GATT_CHAR_PROP_BIT_WRITE ESP_GATT_CHAR_PROP_BIT_NOTIFY ESP_GATT_CHAR_PROP_BIT_INDICATE ESP_GATT_CHAR_PROP_BIT_AUTH ESP_GATT_CHAR_PROP_BIT_EXT_PROP ESP_GATT_MAX_ATTR_LEN GATT maximum attribute length. ESP_GATT_RSP_BY_APP ESP_GATT_AUTO_RSP ESP_GATT_IF_NONE If callback report gattc_if/gatts_if as this macro, means this event is not correspond to any app Type Definitions typedef uint16_t esp_gatt_perm_t typedef uint8_t esp_gatt_char_prop_t typedef uint8_t esp_gatt_if_t Gatt interface type, different application on GATT client use different gatt_if Enumerations enum esp_gatt_prep_write_type Attribute write data type from the client. Values: ESP_GATT_PREP_WRITE_CANCEL = 0x00 Prepare write cancel ESP_GATT_PREP_WRITE_EXEC = 0x01 Prepare write execute enum esp_gatt_status_t GATT success code and error codes. Values: ESP_GATT_OK = 0x0 ESP_GATT_INVALID_HANDLE = 0x01 ESP_GATT_READ_NOT_PERMIT = 0x02 ESP_GATT_WRITE_NOT_PERMIT = 0x03 ESP_GATT_INVALID_PDU = 0x04 ESP_GATT_INSUF_AUTHENTICATION = 0x05 ESP_GATT_REQ_NOT_SUPPORTED = 0x06 ESP_GATT_INVALID_OFFSET = 0x07 ESP_GATT_INSUF_AUTHORIZATION = 0x08 ESP_GATT_PREPARE_Q_FULL = 0x09 ESP_GATT_NOT_FOUND = 0x0a Espressif Systems 235 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GATT_NOT_LONG = 0x0b ESP_GATT_INSUF_KEY_SIZE = 0x0c ESP_GATT_INVALID_ATTR_LEN = 0x0d ESP_GATT_ERR_UNLIKELY = 0x0e ESP_GATT_INSUF_ENCRYPTION = 0x0f ESP_GATT_UNSUPPORT_GRP_TYPE = 0x10 ESP_GATT_INSUF_RESOURCE = 0x11 ESP_GATT_NO_RESOURCES = 0x80 ESP_GATT_INTERNAL_ERROR = 0x81 ESP_GATT_WRONG_STATE = 0x82 ESP_GATT_DB_FULL = 0x83 ESP_GATT_BUSY = 0x84 ESP_GATT_ERROR = 0x85 ESP_GATT_CMD_STARTED = 0x86 ESP_GATT_ILLEGAL_PARAMETER = 0x87 ESP_GATT_PENDING = 0x88 ESP_GATT_AUTH_FAIL = 0x89 ESP_GATT_MORE = 0x8a ESP_GATT_INVALID_CFG = 0x8b ESP_GATT_SERVICE_STARTED = 0x8c ESP_GATT_ENCRYPED_MITM = ESP_GATT_OK ESP_GATT_ENCRYPED_NO_MITM = 0x8d ESP_GATT_NOT_ENCRYPTED = 0x8e ESP_GATT_CONGESTED = 0x8f ESP_GATT_DUP_REG = 0x90 ESP_GATT_ALREADY_OPEN = 0x91 ESP_GATT_CANCEL = 0x92 ESP_GATT_STACK_RSP = 0xe0 ESP_GATT_APP_RSP = 0xe1 ESP_GATT_UNKNOWN_ERROR = 0xef ESP_GATT_CCC_CFG_ERR = 0xfd ESP_GATT_PRC_IN_PROGRESS = 0xfe ESP_GATT_OUT_OF_RANGE = 0xff enum esp_gatt_conn_reason_t Gatt Connection reason enum. Values: ESP_GATT_CONN_UNKNOWN = 0 Gatt connection unknown ESP_GATT_CONN_L2C_FAILURE = 1 General L2cap failure Espressif Systems 236 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GATT_CONN_TIMEOUT = 0x08 Connection timeout ESP_GATT_CONN_TERMINATE_PEER_USER = 0x13 Connection terminate by peer user ESP_GATT_CONN_TERMINATE_LOCAL_HOST = 0x16 Connection terminated by local host ESP_GATT_CONN_FAIL_ESTABLISH = 0x3e Connection fail to establish ESP_GATT_CONN_LMP_TIMEOUT = 0x22 Connection fail for LMP response tout ESP_GATT_CONN_CONN_CANCEL = 0x0100 L2CAP connection cancelled ESP_GATT_CONN_NONE = 0x0101 No connection to cancel enum esp_gatt_auth_req_t Gatt authentication request type. Values: ESP_GATT_AUTH_REQ_NONE = 0 ESP_GATT_AUTH_REQ_NO_MITM = 1 ESP_GATT_AUTH_REQ_MITM = 2 ESP_GATT_AUTH_REQ_SIGNED_NO_MITM = 3 ESP_GATT_AUTH_REQ_SIGNED_MITM = 4 enum esp_service_source_t Values: ESP_GATT_SERVICE_FROM_REMOTE_DEVICE = 0 ESP_GATT_SERVICE_FROM_NVS_FLASH = 1 ESP_GATT_SERVICE_FROM_UNKNOWN = 2 enum esp_gatt_write_type_t Gatt write type. Values: ESP_GATT_WRITE_TYPE_NO_RSP = 1 Gatt write attribute need no response ESP_GATT_WRITE_TYPE_RSP Gatt write attribute need remote response enum esp_gatt_db_attr_type_t the type of attribute element Values: ESP_GATT_DB_PRIMARY_SERVICE Gattc primary service attribute type in the cache ESP_GATT_DB_SECONDARY_SERVICE Gattc secondary service attribute type in the cache ESP_GATT_DB_CHARACTERISTIC Gattc characteristic attribute type in the cache ESP_GATT_DB_DESCRIPTOR Gattc characteristic descriptor attribute type in the cache Espressif Systems 237 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GATT_DB_INCLUDED_SERVICE Gattc include service attribute type in the cache ESP_GATT_DB_ALL Gattc all the attribute (primary service & secondary service & include service & char & descriptor) type in the cache GATT SERVER API Overview Instructions Application Example Check bluetooth/bluedroid/ble folder in ESP-IDF examples, which contains the following demos and their tutorials: · This is a GATT sever demo and its tutorial. This demo creates a GATT service with an attribute table, which releases the user from adding attributes one by one. This is the recommended method of adding attributes. bluetooth/bluedroid/ble/gatt_server_service_table GATT Server Service Table Example Walkthrough · This is a GATT server demo and its tutorial. This demo creates a GATT service by adding attributes one by one as defined by Bluedroid. The recommended method of adding attributes is presented in example above. bluetooth/bluedroid/ble/gatt_server GATT Server Example Walkthrough · This is a BLE SPP-Like demo. This demo, which acts as a GATT server, can receive data from UART and then send the data to the peer device automatically. bluetooth/bluedroid/ble/ble_spp_server API Reference Header File · components/bt/host/bluedroid/api/include/api/esp_gatts_api.h Functions esp_err_t esp_ble_gatts_register_callback(esp_gatts_cb_t callback) This function is called to register application callbacks with BTA GATTS module. Return · ESP_OK : success · other : failed esp_err_t esp_ble_gatts_app_register(uint16_t app_id) This function is called to register application identifier. Return · ESP_OK : success · other : failed esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if) unregister with GATT Server. Return · ESP_OK : success · other : failed Parameters · [in] gatts_if: GATT server access interface esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatts_if, esp_gatt_srvc_id_t *service_id, uint16_t num_handle) Create a service. When service creation is done, a callback event ESP_GATTS_CREATE_EVT is called to Espressif Systems 238 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference report status and service ID to the profile. The service ID obtained in the callback function needs to be used when adding included service and characteristics/descriptors into the service. Return · ESP_OK : success · other : failed Parameters · [in] gatts_if: GATT server access interface · [in] service_id: service ID. · [in] num_handle: number of handle requested for this service. esp_err_t esp_ble_gatts_create_attr_tab(const esp_gatts_attr_db_t *gatts_attr_db, esp_gatt_if_t gatts_if, uint8_t max_nb_attr, uint8_t 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. · [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 Espressif Systems 239 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Parameters · [in] service_handle: service handle to which this characteristic descriptor is to be added. · [in] perm: descriptor access permission. · [in] descr_uuid: descriptor UUID. · [in] char_descr_val: : Characteristic descriptor value · [in] control: : attribute response control byte esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle) This function is called to delete a service. When this is done, a callback event ESP_GATTS_DELETE_EVT is report with the status. Return · ESP_OK : success · other : failed Parameters · [in] service_handle: service_handle to be deleted. esp_err_t esp_ble_gatts_start_service(uint16_t service_handle) This function is called to start a service. Return · ESP_OK : success · other : failed Parameters · [in] service_handle: the service handle to be started. esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle) This function is called to stop a service. Return · ESP_OK : success · other : failed Parameters · [in] service_handle: - service to be topped. esp_err_t esp_ble_gatts_send_indicate(esp_gatt_if_t gatts_if, uint16_t conn_id, uint16_t attr_handle, uint16_t value_len, uint8_t *value, bool need_confirm) Send indicate or notify to GATT client. Set param need_confirm as false will send notification, otherwise indication. Return · ESP_OK : success · other : failed Parameters · [in] gatts_if: GATT server access interface · [in] conn_id: - connection id to indicate. · [in] attr_handle: - attribute handle to indicate. · [in] value_len: - indicate value length. · [in] value: value to indicate. · [in] need_confirm: - Whether a confirmation is required. false sends a GATT notification, true sends a GATT indication. esp_err_t esp_ble_gatts_send_response(esp_gatt_if_t gatts_if, uint16_t conn_id, uint32_t trans_id, esp_gatt_status_t status, esp_gatt_rsp_t *rsp) This function is called to send a response to a request. Return · ESP_OK : success · other : failed Parameters · [in] gatts_if: GATT server access interface · [in] conn_id: - connection identifier. Espressif Systems 240 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [in] trans_id: - transfer id · [in] status: - response status · [in] rsp: - response data. esp_err_t esp_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t *value) This function is called to set the attribute value by the application. Return · ESP_OK : success · other : failed Parameters · [in] attr_handle: the attribute handle which to be set · [in] length: the value length · [in] value: the pointer to the attribute value esp_gatt_status_t esp_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, const 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. 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 Espressif Systems 241 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference union esp_ble_gatts_cb_param_t #include <esp_gatts_api.h> Gatt server callback parameters union. Public Members struct esp_ble_gatts_cb_param_t::gatts_reg_evt_param reg Gatt server callback param of ESP_GATTS_REG_EVT struct esp_ble_gatts_cb_param_t::gatts_read_evt_param read Gatt server callback param of ESP_GATTS_READ_EVT struct esp_ble_gatts_cb_param_t::gatts_write_evt_param write Gatt server callback param of ESP_GATTS_WRITE_EVT struct esp_ble_gatts_cb_param_t::gatts_exec_write_evt_param exec_write Gatt server callback param of ESP_GATTS_EXEC_WRITE_EVT struct esp_ble_gatts_cb_param_t::gatts_mtu_evt_param mtu Gatt server callback param of ESP_GATTS_MTU_EVT struct esp_ble_gatts_cb_param_t::gatts_conf_evt_param conf Gatt server callback param of ESP_GATTS_CONF_EVT (confirm) struct esp_ble_gatts_cb_param_t::gatts_create_evt_param create Gatt server callback param of ESP_GATTS_CREATE_EVT struct esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt_param add_incl_srvc Gatt server callback param of ESP_GATTS_ADD_INCL_SRVC_EVT struct esp_ble_gatts_cb_param_t::gatts_add_char_evt_param add_char Gatt server callback param of ESP_GATTS_ADD_CHAR_EVT struct esp_ble_gatts_cb_param_t::gatts_add_char_descr_evt_param add_char_descr Gatt server callback param of ESP_GATTS_ADD_CHAR_DESCR_EVT struct esp_ble_gatts_cb_param_t::gatts_delete_evt_param del Gatt server callback param of ESP_GATTS_DELETE_EVT struct esp_ble_gatts_cb_param_t::gatts_start_evt_param start Gatt server callback param of ESP_GATTS_START_EVT struct esp_ble_gatts_cb_param_t::gatts_stop_evt_param stop Gatt server callback param of ESP_GATTS_STOP_EVT struct esp_ble_gatts_cb_param_t::gatts_connect_evt_param connect Gatt server callback param of ESP_GATTS_CONNECT_EVT struct esp_ble_gatts_cb_param_t::gatts_disconnect_evt_param disconnect Gatt server callback param of ESP_GATTS_DISCONNECT_EVT struct esp_ble_gatts_cb_param_t::gatts_open_evt_param open Gatt server callback param of ESP_GATTS_OPEN_EVT struct esp_ble_gatts_cb_param_t::gatts_cancel_open_evt_param cancel_open Gatt server callback param of ESP_GATTS_CANCEL_OPEN_EVT struct esp_ble_gatts_cb_param_t::gatts_close_evt_param close Gatt server callback param of ESP_GATTS_CLOSE_EVT struct esp_ble_gatts_cb_param_t::gatts_congest_evt_param congest Gatt server callback param of ESP_GATTS_CONGEST_EVT struct esp_ble_gatts_cb_param_t::gatts_rsp_evt_param rsp Gatt server callback param of ESP_GATTS_RESPONSE_EVT struct esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_param add_attr_tab Gatt server callback param of ESP_GATTS_CREAT_ATTR_TAB_EVT Espressif Systems 242 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_gatts_cb_param_t::gatts_set_attr_val_evt_param set_attr_val Gatt server callback param of ESP_GATTS_SET_ATTR_VAL_EVT struct esp_ble_gatts_cb_param_t::gatts_send_service_change_evt_param service_change Gatt server callback param of ESP_GATTS_SEND_SERVICE_CHANGE_EVT struct gatts_add_attr_tab_evt_param #include <esp_gatts_api.h> ESP_GATTS_CREAT_ATTR_TAB_EVT. Public Members esp_gatt_status_t status Operation status esp_bt_uuid_t svc_uuid Service uuid type uint8_t svc_inst_id Service id uint16_t num_handle The number of the attribute handle to be added to the gatts database uint16_t *handles The number to the handles struct gatts_add_char_descr_evt_param #include <esp_gatts_api.h> ESP_GATTS_ADD_CHAR_DESCR_EVT. Public Members esp_gatt_status_t status Operation status uint16_t attr_handle Descriptor attribute handle uint16_t service_handle Service attribute handle esp_bt_uuid_t descr_uuid Characteristic descriptor uuid struct gatts_add_char_evt_param #include <esp_gatts_api.h> ESP_GATTS_ADD_CHAR_EVT. Public Members esp_gatt_status_t status Operation status uint16_t attr_handle Characteristic attribute handle uint16_t service_handle Service attribute handle esp_bt_uuid_t char_uuid Characteristic uuid struct gatts_add_incl_srvc_evt_param #include <esp_gatts_api.h> ESP_GATTS_ADD_INCL_SRVC_EVT. Espressif Systems 243 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_gatt_status_t status Operation status uint16_t attr_handle Included service attribute handle uint16_t service_handle Service attribute handle struct gatts_cancel_open_evt_param #include <esp_gatts_api.h> ESP_GATTS_CANCEL_OPEN_EVT. Public Members esp_gatt_status_t status Operation status struct gatts_close_evt_param #include <esp_gatts_api.h> ESP_GATTS_CLOSE_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id struct gatts_conf_evt_param #include <esp_gatts_api.h> ESP_GATTS_CONF_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id uint16_t handle attribute handle uint16_t len The indication or notification value length, len is valid when send notification or indication failed uint8_t *value The indication or notification value , value is valid when send notification or indication failed struct gatts_congest_evt_param #include <esp_gatts_api.h> ESP_GATTS_LISTEN_EVT. ESP_GATTS_CONGEST_EVT Public Members uint16_t conn_id Connection id Espressif Systems 244 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference bool congested Congested or not struct gatts_connect_evt_param #include <esp_gatts_api.h> ESP_GATTS_CONNECT_EVT. Public Members uint16_t conn_id Connection id uint8_t link_role Link role : master role = 0 ; slave role = 1 esp_bd_addr_t remote_bda Remote bluetooth device address esp_gatt_conn_params_t conn_params current Connection parameters struct gatts_create_evt_param #include <esp_gatts_api.h> ESP_GATTS_UNREG_EVT. ESP_GATTS_CREATE_EVT Public Members esp_gatt_status_t status Operation status uint16_t service_handle Service attribute handle esp_gatt_srvc_id_t service_id Service id, include service uuid and other information struct gatts_delete_evt_param #include <esp_gatts_api.h> ESP_GATTS_DELETE_EVT. Public Members esp_gatt_status_t status Operation status uint16_t service_handle Service attribute handle struct gatts_disconnect_evt_param #include <esp_gatts_api.h> ESP_GATTS_DISCONNECT_EVT. Public Members uint16_t conn_id Connection id esp_bd_addr_t remote_bda Remote bluetooth device address esp_gatt_conn_reason_t reason Indicate the reason of disconnection Espressif Systems 245 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct gatts_exec_write_evt_param #include <esp_gatts_api.h> ESP_GATTS_EXEC_WRITE_EVT. Public Members uint16_t conn_id Connection id uint32_t trans_id Transfer id esp_bd_addr_t bda The bluetooth device address which been written uint8_t exec_write_flag Execute write flag struct gatts_mtu_evt_param #include <esp_gatts_api.h> ESP_GATTS_MTU_EVT. Public Members uint16_t conn_id Connection id uint16_t mtu MTU size struct gatts_open_evt_param #include <esp_gatts_api.h> ESP_GATTS_OPEN_EVT. Public Members esp_gatt_status_t status Operation status struct gatts_read_evt_param #include <esp_gatts_api.h> ESP_GATTS_READ_EVT. Public Members uint16_t conn_id Connection id uint32_t trans_id Transfer id esp_bd_addr_t bda The bluetooth device address which been read uint16_t handle The attribute handle uint16_t offset Offset of the value, if the value is too long bool is_long The value is too long or not bool need_rsp The read operation need to do response Espressif Systems 246 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct gatts_reg_evt_param #include <esp_gatts_api.h> ESP_GATTS_REG_EVT. Public Members esp_gatt_status_t status Operation status uint16_t app_id Application id which input in register API struct gatts_rsp_evt_param #include <esp_gatts_api.h> ESP_GATTS_RESPONSE_EVT. Public Members esp_gatt_status_t status Operation status uint16_t handle Attribute handle which send response struct gatts_send_service_change_evt_param #include <esp_gatts_api.h> ESP_GATTS_SEND_SERVICE_CHANGE_EVT. Public Members esp_gatt_status_t status Operation status struct gatts_set_attr_val_evt_param #include <esp_gatts_api.h> ESP_GATTS_SET_ATTR_VAL_EVT. Public Members uint16_t srvc_handle The service handle uint16_t attr_handle The attribute handle esp_gatt_status_t status Operation status struct gatts_start_evt_param #include <esp_gatts_api.h> ESP_GATTS_START_EVT. Public Members esp_gatt_status_t status Operation status uint16_t service_handle Service attribute handle struct gatts_stop_evt_param #include <esp_gatts_api.h> ESP_GATTS_STOP_EVT. Espressif Systems 247 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_gatt_status_t status Operation status uint16_t service_handle Service attribute handle struct gatts_write_evt_param #include <esp_gatts_api.h> ESP_GATTS_WRITE_EVT. Public Members uint16_t conn_id Connection id uint32_t trans_id Transfer id esp_bd_addr_t bda The bluetooth device address which been written uint16_t handle The attribute handle uint16_t offset Offset of the value, if the value is too long bool need_rsp The write operation need to do response bool is_prep This write operation is prepare write uint16_t len The write attribute value length uint8_t *value The write attribute value Macros ESP_GATT_PREP_WRITE_CANCEL Prepare write flag to indicate cancel prepare write ESP_GATT_PREP_WRITE_EXEC Prepare write flag to indicate execute prepare write Type Definitions typedef void (*esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_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 Espressif Systems 248 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference enum esp_gatts_cb_event_t GATT Server callback function events. Values: ESP_GATTS_REG_EVT = 0 When register application id, the event comes ESP_GATTS_READ_EVT = 1 When gatt client request read operation, the event comes ESP_GATTS_WRITE_EVT = 2 When gatt client request write operation, the event comes ESP_GATTS_EXEC_WRITE_EVT = 3 When gatt client request execute write, the event comes ESP_GATTS_MTU_EVT = 4 When set mtu complete, the event comes ESP_GATTS_CONF_EVT = 5 When receive confirm, the event comes ESP_GATTS_UNREG_EVT = 6 When unregister application id, the event comes ESP_GATTS_CREATE_EVT = 7 When create service complete, the event comes ESP_GATTS_ADD_INCL_SRVC_EVT = 8 When add included service complete, the event comes ESP_GATTS_ADD_CHAR_EVT = 9 When add characteristic complete, the event comes ESP_GATTS_ADD_CHAR_DESCR_EVT = 10 When add descriptor complete, the event comes ESP_GATTS_DELETE_EVT = 11 When delete service complete, the event comes ESP_GATTS_START_EVT = 12 When start service complete, the event comes ESP_GATTS_STOP_EVT = 13 When stop service complete, the event comes ESP_GATTS_CONNECT_EVT = 14 When gatt client connect, the event comes ESP_GATTS_DISCONNECT_EVT = 15 When gatt client disconnect, the event comes ESP_GATTS_OPEN_EVT = 16 When connect to peer, the event comes ESP_GATTS_CANCEL_OPEN_EVT = 17 When disconnect from peer, the event comes ESP_GATTS_CLOSE_EVT = 18 When gatt server close, the event comes ESP_GATTS_LISTEN_EVT = 19 When gatt listen to be connected the event comes ESP_GATTS_CONGEST_EVT = 20 When congest happen, the event comes ESP_GATTS_RESPONSE_EVT = 21 When gatt send response complete, the event comes Espressif Systems 249 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GATTS_CREAT_ATTR_TAB_EVT = 22 When gatt create table complete, the event comes ESP_GATTS_SET_ATTR_VAL_EVT = 23 When gatt set attr value complete, the event comes ESP_GATTS_SEND_SERVICE_CHANGE_EVT = 24 When gatt send service change indication complete, the event comes GATT CLIENT API Overview Instructions Application Example Check bluetooth/bluedroid/ble folder in ESP-IDF examples, which contains the following demos and their tutorials: · This is a GATT client demo and its tutorial. This demo can scan for devices, connect to the GATT server and discover its services. bluetooth/bluedroid/ble/gatt_client GATT Client Example Walkthrough · This is a multiple connection demo and its tutorial. This demo can connect to multiple GATT server devices and discover their services. bluetooth/bluedroid/ble/gattc_multi_connect GATT Client Multi-connection Example Walkthrough · This is a BLE SPP-Like demo. This demo, which acts as a GATT client, can receive data from UART and then send the data to the peer device automatically. bluetooth/bluedroid/ble/ble_spp_client API Reference Header File · components/bt/host/bluedroid/api/include/api/esp_gattc_api.h Functions esp_err_t esp_ble_gattc_register_callback(esp_gattc_cb_t callback) This function is called to register application callbacks with GATTC module. Return · ESP_OK: success · other: failed Parameters · [in] callback: : pointer to the application callback function. esp_err_t esp_ble_gattc_app_register(uint16_t app_id) This function is called to register application callbacks with GATTC module. Return · ESP_OK: success · other: failed Parameters · [in] app_id: : Application Identify (UUID), for different application esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if) This function is called to unregister an application from GATTC module. Return · ESP_OK: success · other: failed Espressif Systems 250 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Parameters · [in] gattc_if: Gatt client access interface. esp_err_t esp_ble_gattc_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct) Open a direct connection or add a background auto connection. Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] remote_bda: remote device bluetooth device address. · [in] remote_addr_type: remote device bluetooth device the address type. · [in] is_direct: direct connection or background auto connection(by now, background auto connection is not supported). esp_err_t esp_ble_gattc_aux_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct) esp_err_t esp_ble_gattc_close(esp_gatt_if_t gattc_if, uint16_t conn_id) Close the virtual connection to the GATT server. gattc may have multiple virtual GATT server connections when multiple app_id registered, this API only close one virtual GATT server connection. if there exist other virtual GATT server connections, it does not disconnect the physical connection. if you want to disconnect the physical connection directly, you can use esp_ble_gap_disconnect(esp_bd_addr_t remote_device). Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: connection ID to be closed. esp_err_t esp_ble_gattc_send_mtu_req(esp_gatt_if_t gattc_if, uint16_t conn_id) Configure the MTU size in the GATT channel. This can be done only once per connection. Before using, use esp_ble_gatt_set_local_mtu() to configure the local MTU size. Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: connection ID. esp_err_t esp_ble_gattc_search_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *filter_uuid) This function is called to get service from local cache. This function report service search result by a callback event, and followed by a service search complete event. Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: connection ID. · [in] filter_uuid: a UUID of the service application is interested in. If Null, discover for all services. esp_gatt_status_t esp_ble_gattc_get_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *svc_uuid, esp_gattc_service_elem_t *result, uint16_t *count, uint16_t offset) Find all the service with the given service uuid in the gattc cache, if the svc_uuid is NULL, find all the service. Note: It just get service from local cache, 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. Espressif Systems 251 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: connection ID which identify the server. · [in] svc_uuid: the pointer to the service uuid. · [out] result: The pointer to the service which has been found in the gattc cache. · [inout] count: input the number of service want to find, it will output the number of service has been found in the gattc cache with the given service uuid. · [in] offset: Offset of the service position to get. esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_gattc_char_elem_t *result, uint16_t *count, uint16_t offset) Find all the characteristic with the given service in the gattc cache Note: It just get characteristic from local cache, 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. 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 Espressif Systems 252 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [in] gattc_if: Gatt client access interface. · [in] conn_id: connection ID which identify the server. · [in] start_handle: the attribute start handle · [in] end_handle: the attribute end handle · [in] char_uuid: the characteristic uuid · [out] result: The pointer to the characteristic in the service. · [inout] count: input the number of characteristic want to find, it will output the number of characteristic has been found in the gattc cache with the given service. esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t char_uuid, esp_bt_uuid_t descr_uuid, esp_gattc_descr_elem_t *result, uint16_t *count) Find the descriptor with the given characteristic uuid in the gattc cache Note: It just get descriptor from local cache, 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) 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 Espressif Systems 253 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: connection ID which identify the server. · [in] start_handle: the attribute start handle · [in] end_handle: the attribute end handle · [in] incl_uuid: the include service uuid · [out] result: The pointer to the include service in the given service. · [inout] count: input the number of include service want to find, it will output the number of include service has been found in the gattc cache with the given service. esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_db_attr_type_t type, uint16_t start_handle, uint16_t end_handle, uint16_t char_handle, uint16_t *count) Find the attribute count with the given service or characteristic in the gattc cache. Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: connection ID which identify the server. · [in] type: the attribute type. · [in] start_handle: the attribute start handle, if the type is ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore · [in] end_handle: the attribute end handle, if the type is ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore · [in] char_handle: the characteristic handle, this parameter valid when the type is ESP_GATT_DB_DESCRIPTOR. If the type 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) 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. Espressif Systems 254 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [in] handle: : characteritic handle to read. · [in] auth_req: : authenticate request type esp_err_t esp_ble_gattc_read_by_type(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t *uuid, esp_gatt_auth_req_t auth_req) This function is called to read a 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 · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: : connection ID. · [in] handle: : descriptor handle to read. · [in] auth_req: : authenticate request type esp_err_t esp_ble_gattc_write_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t value_len, uint8_t *value, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req) This function is called to write characteristic value. Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: : connection ID. · [in] handle: : characteristic handle to write. · [in] value_len: length of the value to be written. · [in] value: : the value to be written. · [in] write_type: : the type of attribute write operation. · [in] auth_req: : authentication request. Espressif Systems 255 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_ble_gattc_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t value_len, uint8_t *value, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req) This function is called to write characteristic descriptor value. Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: : connection ID · [in] handle: : descriptor hadle to write. · [in] value_len: length of the value to be written. · [in] value: : the value to be written. · [in] write_type: : the type of attribute write operation. · [in] auth_req: : authentication request. esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t 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. esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t offset, uint16_t value_len, uint8_t *value, esp_gatt_auth_req_t auth_req) This function is called to prepare write a characteristic descriptor value. Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: : connection ID. · [in] handle: : characteristic descriptor handle to prepare write. · [in] offset: : offset of the write value. · [in] value_len: length of the value to be written. · [in] value: : the value to be written. · [in] auth_req: : authentication request. esp_err_t esp_ble_gattc_execute_write(esp_gatt_if_t gattc_if, uint16_t conn_id, bool is_execute) This function is called to execute write a prepare write sequence. Return · ESP_OK: success · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] conn_id: : connection ID. Espressif Systems 256 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [in] is_execute: : execute or cancel. esp_err_t esp_ble_gattc_register_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, uint16_t handle) This function is called to register for notification of a service. Return · ESP_OK: registration succeeds · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] server_bda: : target GATT server. · [in] handle: : GATT characteristic handle. esp_err_t esp_ble_gattc_unregister_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, uint16_t handle) This function is called to de-register for notification of a service. Return · ESP_OK: unregister succeeds · other: failed Parameters · [in] gattc_if: Gatt client access interface. · [in] server_bda: : target GATT server. · [in] handle: : GATT characteristic handle. esp_err_t esp_ble_gattc_cache_refresh(esp_bd_addr_t remote_bda) Refresh the server cache store in the gattc stack of the remote device. If the device is connected, this API will restart the discovery of service information of the remote device. Return · ESP_OK: success · other: failed Parameters · [in] remote_bda: remote device BD address. esp_err_t esp_ble_gattc_cache_assoc(esp_gatt_if_t gattc_if, esp_bd_addr_t src_addr, esp_bd_addr_t assoc_addr, bool is_assoc) Add or delete the associated address with the source address. Note: The role of this API is mainly when the client side has stored a server-side database, when it needs to connect another device, but the 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 Espressif Systems 257 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Parameters · [in] gattc_if: Gatt client access interface. esp_err_t esp_ble_gattc_cache_clean(esp_bd_addr_t remote_bda) Clean the service cache of this device in the gattc stack,. Return · ESP_OK: success · other: failed Parameters · [in] remote_bda: remote device BD address. Unions union esp_ble_gattc_cb_param_t #include <esp_gattc_api.h> Gatt client callback parameters union. Public Members struct esp_ble_gattc_cb_param_t::gattc_reg_evt_param reg Gatt client callback param of ESP_GATTC_REG_EVT struct esp_ble_gattc_cb_param_t::gattc_open_evt_param open Gatt client callback param of ESP_GATTC_OPEN_EVT struct esp_ble_gattc_cb_param_t::gattc_close_evt_param close Gatt client callback param of ESP_GATTC_CLOSE_EVT struct esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param cfg_mtu Gatt client callback param of ESP_GATTC_CFG_MTU_EVT struct esp_ble_gattc_cb_param_t::gattc_search_cmpl_evt_param search_cmpl Gatt client callback param of ESP_GATTC_SEARCH_CMPL_EVT struct esp_ble_gattc_cb_param_t::gattc_search_res_evt_param search_res Gatt client callback param of ESP_GATTC_SEARCH_RES_EVT struct esp_ble_gattc_cb_param_t::gattc_read_char_evt_param read Gatt client callback param of ESP_GATTC_READ_CHAR_EVT struct esp_ble_gattc_cb_param_t::gattc_write_evt_param write Gatt client callback param of ESP_GATTC_WRITE_DESCR_EVT struct esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_param exec_cmpl Gatt client callback param of ESP_GATTC_EXEC_EVT struct esp_ble_gattc_cb_param_t::gattc_notify_evt_param notify Gatt client callback param of ESP_GATTC_NOTIFY_EVT struct esp_ble_gattc_cb_param_t::gattc_srvc_chg_evt_param srvc_chg Gatt client callback param of ESP_GATTC_SRVC_CHG_EVT struct esp_ble_gattc_cb_param_t::gattc_congest_evt_param congest Gatt client callback param of ESP_GATTC_CONGEST_EVT struct esp_ble_gattc_cb_param_t::gattc_reg_for_notify_evt_param reg_for_notify Gatt client callback param of ESP_GATTC_REG_FOR_NOTIFY_EVT struct esp_ble_gattc_cb_param_t::gattc_unreg_for_notify_evt_param unreg_for_notify Gatt client callback param of ESP_GATTC_UNREG_FOR_NOTIFY_EVT struct esp_ble_gattc_cb_param_t::gattc_connect_evt_param connect Gatt client callback param of ESP_GATTC_CONNECT_EVT struct esp_ble_gattc_cb_param_t::gattc_disconnect_evt_param disconnect Gatt client callback param of ESP_GATTC_DISCONNECT_EVT Espressif Systems 258 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_gattc_cb_param_t::gattc_set_assoc_addr_cmp_evt_param set_assoc_cmp Gatt client callback param of ESP_GATTC_SET_ASSOC_EVT struct esp_ble_gattc_cb_param_t::gattc_get_addr_list_evt_param get_addr_list Gatt client callback param of ESP_GATTC_GET_ADDR_LIST_EVT struct esp_ble_gattc_cb_param_t::gattc_queue_full_evt_param queue_full Gatt client callback param of ESP_GATTC_QUEUE_FULL_EVT struct esp_ble_gattc_cb_param_t::gattc_dis_srvc_cmpl_evt_param dis_srvc_cmpl Gatt client callback param of ESP_GATTC_DIS_SRVC_CMPL_EVT struct gattc_cfg_mtu_evt_param #include <esp_gattc_api.h> ESP_GATTC_CFG_MTU_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id uint16_t mtu MTU size struct gattc_close_evt_param #include <esp_gattc_api.h> ESP_GATTC_CLOSE_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id esp_bd_addr_t remote_bda Remote bluetooth device address esp_gatt_conn_reason_t reason The reason of gatt connection close struct gattc_congest_evt_param #include <esp_gattc_api.h> ESP_GATTC_CONGEST_EVT. Public Members uint16_t conn_id Connection id bool congested Congested or not struct gattc_connect_evt_param #include <esp_gattc_api.h> ESP_GATTC_CONNECT_EVT. Espressif Systems 259 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t conn_id Connection id uint8_t link_role Link role : master role = 0 ; slave role = 1 esp_bd_addr_t remote_bda Remote bluetooth device address esp_gatt_conn_params_t conn_params current connection parameters struct gattc_dis_srvc_cmpl_evt_param #include <esp_gattc_api.h> ESP_GATTC_DIS_SRVC_CMPL_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id struct gattc_disconnect_evt_param #include <esp_gattc_api.h> ESP_GATTC_DISCONNECT_EVT. Public Members esp_gatt_conn_reason_t reason disconnection reason uint16_t conn_id Connection id esp_bd_addr_t remote_bda Remote bluetooth device address struct gattc_exec_cmpl_evt_param #include <esp_gattc_api.h> ESP_GATTC_EXEC_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id struct gattc_get_addr_list_evt_param #include <esp_gattc_api.h> ESP_GATTC_GET_ADDR_LIST_EVT. Public Members esp_gatt_status_t status Operation status uint8_t num_addr The number of address in the gattc cache address list Espressif Systems 260 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_bd_addr_t *addr_list The pointer to the address list which has been get from the gattc cache struct gattc_notify_evt_param #include <esp_gattc_api.h> ESP_GATTC_NOTIFY_EVT. Public Members uint16_t conn_id Connection id esp_bd_addr_t remote_bda Remote bluetooth device address uint16_t handle The Characteristic or descriptor handle uint16_t value_len Notify attribute value uint8_t *value Notify attribute value bool is_notify True means notify, false means indicate struct gattc_open_evt_param #include <esp_gattc_api.h> ESP_GATTC_OPEN_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id esp_bd_addr_t remote_bda Remote bluetooth device address uint16_t mtu MTU size struct gattc_queue_full_evt_param #include <esp_gattc_api.h> ESP_GATTC_QUEUE_FULL_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id bool is_full The gattc command queue is full or not struct gattc_read_char_evt_param #include <esp_gattc_api.h> ESP_GATTC_READ_CHAR_EVT, ESP_GATTC_READ_DESCR_EVT. Espressif Systems 261 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id uint16_t handle Characteristic handle uint8_t *value Characteristic value uint16_t value_len Characteristic value length struct gattc_reg_evt_param #include <esp_gattc_api.h> ESP_GATTC_REG_EVT. Public Members esp_gatt_status_t status Operation status uint16_t app_id Application id which input in register API struct gattc_reg_for_notify_evt_param #include <esp_gattc_api.h> ESP_GATTC_REG_FOR_NOTIFY_EVT. Public Members esp_gatt_status_t status Operation status uint16_t handle The characteristic or descriptor handle struct gattc_search_cmpl_evt_param #include <esp_gattc_api.h> ESP_GATTC_SEARCH_CMPL_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id esp_service_source_t searched_service_source The source of the service information struct gattc_search_res_evt_param #include <esp_gattc_api.h> ESP_GATTC_SEARCH_RES_EVT. Espressif Systems 262 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t conn_id Connection id uint16_t start_handle Service start handle uint16_t end_handle Service end handle esp_gatt_id_t srvc_id Service id, include service uuid and other information bool is_primary True if this is the primary service struct gattc_set_assoc_addr_cmp_evt_param #include <esp_gattc_api.h> ESP_GATTC_SET_ASSOC_EVT. Public Members esp_gatt_status_t status Operation status struct gattc_srvc_chg_evt_param #include <esp_gattc_api.h> ESP_GATTC_SRVC_CHG_EVT. Public Members esp_bd_addr_t remote_bda Remote bluetooth device address struct gattc_unreg_for_notify_evt_param #include <esp_gattc_api.h> ESP_GATTC_UNREG_FOR_NOTIFY_EVT. Public Members esp_gatt_status_t status Operation status uint16_t handle The characteristic or descriptor handle struct gattc_write_evt_param #include <esp_gattc_api.h> ESP_GATTC_WRITE_CHAR_EVT, ESP_GATTC_PREP_WRITE_EVT, ESP_GATTC_WRITE_DESCR_EVT. Public Members esp_gatt_status_t status Operation status uint16_t conn_id Connection id uint16_t handle The Characteristic or descriptor handle Espressif Systems 263 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t offset The prepare write offset, this value is valid only when prepare write Type Definitions typedef void (*esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_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 ESP_GATTC_SEARCH_RES_EVT = 7 When GATT service discovery result is got, the event comes ESP_GATTC_READ_DESCR_EVT = 8 When GATT characteristic descriptor read completes, the event comes ESP_GATTC_WRITE_DESCR_EVT = 9 When GATT characteristic descriptor write completes, the event comes ESP_GATTC_NOTIFY_EVT = 10 When GATT notification or indication arrives, the event comes ESP_GATTC_PREP_WRITE_EVT = 11 When GATT prepare-write operation completes, the event comes ESP_GATTC_EXEC_EVT = 12 When write execution completes, the event comes ESP_GATTC_ACL_EVT = 13 When ACL connection is up, the event comes ESP_GATTC_CANCEL_OPEN_EVT = 14 When GATT client ongoing connection is cancelled, the event comes Espressif Systems 264 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 ESP_GATTC_SCAN_FLT_CFG_EVT = 31 When Scan filter configuration completes, the event comes ESP_GATTC_SCAN_FLT_PARAM_EVT = 32 When Scan filter parameters are set, the event comes ESP_GATTC_SCAN_FLT_STATUS_EVT = 33 When Scan filter status is reported, the event comes ESP_GATTC_ADV_VSC_EVT = 34 When advertising vendor spec content event is reported, the event comes ESP_GATTC_REG_FOR_NOTIFY_EVT = 38 When register for notification of a service completes, the event comes ESP_GATTC_UNREG_FOR_NOTIFY_EVT = 39 When unregister for notification of a service completes, the event comes ESP_GATTC_CONNECT_EVT = 40 When the ble physical connection is set up, the event comes ESP_GATTC_DISCONNECT_EVT = 41 When the ble physical connection disconnected, the event comes Espressif Systems 265 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_GATTC_READ_MULTIPLE_EVT = 42 When the ble characteristic or descriptor multiple complete, the event comes ESP_GATTC_QUEUE_FULL_EVT = 43 When the gattc command queue full, the event comes ESP_GATTC_SET_ASSOC_EVT = 44 When the ble gattc set the associated address complete, the event comes ESP_GATTC_GET_ADDR_LIST_EVT = 45 When the ble get gattc address list in cache finish, the event comes ESP_GATTC_DIS_SRVC_CMPL_EVT = 46 When the ble discover service complete, the event comes BLUFI API Overview BLUFI is a profile based GATT to config ESP32 WIFI to connect/disconnect AP or setup a softap and etc. Use should concern these things: 1. The event sent from profile. Then you need to do something as the event indicate. 2. Security reference. You can write your own Security functions such as symmetrical encryption/decryption and checksum functions. Even you can define the 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 Functions esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks) This function is called to receive blufi callback event. Return ESP_OK - success, other - failed Parameters · [in] callbacks: callback functions esp_err_t esp_blufi_profile_init(void) This function is called to initialize blufi_profile. Return ESP_OK - success, other - failed esp_err_t esp_blufi_profile_deinit(void) This function is called to de-initialize blufi_profile. Return ESP_OK - success, other - failed esp_err_t esp_blufi_send_wifi_conn_report(wifi_mode_t opmode, esp_blufi_sta_conn_state_t sta_conn_state, uint8_t softap_conn_num, esp_blufi_extra_info_t *extra_info) This function is called to send wifi connection report. Return ESP_OK - success, other - failed Parameters · opmode: : wifi opmode · sta_conn_state: : station is already in connection or not Espressif Systems 266 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · softap_conn_num: : softap connection number · extra_info: : extra information, such as sta_ssid, softap_ssid and etc. esp_err_t esp_blufi_send_wifi_list(uint16_t apCount, esp_blufi_ap_record_t *list) This function is called to send wifi list. Return ESP_OK - success, other - failed Parameters · apCount: : wifi list count · list: : wifi list uint16_t esp_blufi_get_version(void) Get BLUFI profile version. Return Most 8bit significant is Great version, Least 8bit is Sub version esp_err_t esp_blufi_send_error_info(esp_blufi_error_state_t state) This function is called to send blufi error information. Return ESP_OK - success, other - failed Parameters · state: : error state esp_err_t esp_blufi_send_custom_data(uint8_t *data, uint32_t data_len) This function is called to custom data. Return ESP_OK - success, other - failed Parameters · data: : custom data value · data_len: : the length of custom data Unions union esp_blufi_cb_param_t #include <esp_blufi_api.h> BLUFI callback parameters union. Public Members struct esp_blufi_cb_param_t::blufi_init_finish_evt_param init_finish Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH struct esp_blufi_cb_param_t::blufi_deinit_finish_evt_param deinit_finish Blufi callback param of ESP_BLUFI_EVENT_DEINIT_FINISH struct esp_blufi_cb_param_t::blufi_set_wifi_mode_evt_param wifi_mode Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH struct esp_blufi_cb_param_t::blufi_connect_evt_param connect Blufi callback param of ESP_BLUFI_EVENT_CONNECT struct esp_blufi_cb_param_t::blufi_disconnect_evt_param disconnect Blufi callback param of ESP_BLUFI_EVENT_DISCONNECT struct esp_blufi_cb_param_t::blufi_recv_sta_bssid_evt_param sta_bssid Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_BSSID struct esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_param sta_ssid Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_SSID struct esp_blufi_cb_param_t::blufi_recv_sta_passwd_evt_param sta_passwd Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_PASSWD struct esp_blufi_cb_param_t::blufi_recv_softap_ssid_evt_param softap_ssid Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_SSID Espressif Systems 267 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_blufi_cb_param_t::blufi_recv_softap_passwd_evt_param softap_passwd Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD struct esp_blufi_cb_param_t::blufi_recv_softap_max_conn_num_evt_param softap_max_conn_num Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM struct esp_blufi_cb_param_t::blufi_recv_softap_auth_mode_evt_param softap_auth_mode Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE struct esp_blufi_cb_param_t::blufi_recv_softap_channel_evt_param softap_channel Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL struct esp_blufi_cb_param_t::blufi_recv_username_evt_param username Blufi callback param of ESP_BLUFI_EVENT_RECV_USERNAME struct esp_blufi_cb_param_t::blufi_recv_ca_evt_param ca Blufi callback param of ESP_BLUFI_EVENT_RECV_CA_CERT struct esp_blufi_cb_param_t::blufi_recv_client_cert_evt_param client_cert Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_CERT struct esp_blufi_cb_param_t::blufi_recv_server_cert_evt_param server_cert Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_CERT struct esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_param client_pkey Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY struct esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_param server_pkey Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY struct esp_blufi_cb_param_t::blufi_get_error_evt_param report_error Blufi callback param of ESP_BLUFI_EVENT_REPORT_ERROR struct esp_blufi_cb_param_t::blufi_recv_custom_data_evt_param custom_data Blufi callback param of ESP_BLUFI_EVENT_RECV_CUSTOM_DATA struct blufi_connect_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_CONNECT. Public Members esp_bd_addr_t remote_bda Blufi Remote bluetooth device address uint8_t server_if server interface uint16_t conn_id Connection id struct blufi_deinit_finish_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_DEINIT_FINISH. Public Members esp_blufi_deinit_state_t state De-initial status struct blufi_disconnect_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_DISCONNECT. Espressif Systems 268 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_bd_addr_t remote_bda Blufi Remote bluetooth device address struct blufi_get_error_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_REPORT_ERROR. Public Members esp_blufi_error_state_t state Blufi error state struct blufi_init_finish_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_INIT_FINISH. Public Members esp_blufi_init_state_t state Initial status struct blufi_recv_ca_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CA_CERT. Public Members uint8_t *cert CA certificate point int cert_len CA certificate length struct blufi_recv_client_cert_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CLIENT_CERT Public Members uint8_t *cert Client certificate point int cert_len Client certificate length struct blufi_recv_client_pkey_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY Public Members uint8_t *pkey Client Private Key point, if Client certificate not contain Key int pkey_len Client Private key length struct blufi_recv_custom_data_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_CUSTOM_DATA. Espressif Systems 269 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t *data Custom data uint32_t data_len Custom data Length struct blufi_recv_server_cert_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SERVER_CERT Public Members uint8_t *cert Client certificate point int cert_len Client certificate length struct blufi_recv_server_pkey_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY Public Members uint8_t *pkey Client Private Key point, if Client certificate not contain Key int pkey_len Client Private key length struct blufi_recv_softap_auth_mode_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE. Public Members wifi_auth_mode_t auth_mode Authentication mode struct blufi_recv_softap_channel_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL. Public Members uint8_t channel Authentication mode struct blufi_recv_softap_max_conn_num_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM. Public Members int max_conn_num SSID struct blufi_recv_softap_passwd_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD. Espressif Systems 270 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t *passwd Password int passwd_len Password Length struct blufi_recv_softap_ssid_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_SOFTAP_SSID. Public Members uint8_t *ssid SSID int ssid_len SSID length struct blufi_recv_sta_bssid_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_BSSID. Public Members uint8_t bssid[6] BSSID struct blufi_recv_sta_passwd_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_PASSWD. Public Members uint8_t *passwd Password int passwd_len Password Length struct blufi_recv_sta_ssid_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_STA_SSID. Public Members uint8_t *ssid SSID int ssid_len SSID length struct blufi_recv_username_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_RECV_USERNAME. Public Members uint8_t *name Username point Espressif Systems 271 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int name_len Username length struct blufi_set_wifi_mode_evt_param #include <esp_blufi_api.h> ESP_BLUFI_EVENT_SET_WIFI_MODE. Public Members wifi_mode_t op_mode Wifi operation mode Structures struct esp_blufi_extra_info_t BLUFI extra information structure. Public Members uint8_t sta_bssid[6] BSSID of station interface bool sta_bssid_set is BSSID of station interface set uint8_t *sta_ssid SSID of station interface int sta_ssid_len length of SSID of station interface uint8_t *sta_passwd password of station interface int sta_passwd_len length of password of station interface uint8_t *softap_ssid SSID of softap interface int softap_ssid_len length of SSID of softap interface uint8_t *softap_passwd password of station interface int softap_passwd_len length of password of station interface uint8_t softap_authmode authentication mode of softap interface bool softap_authmode_set is authentication mode of softap interface set uint8_t softap_max_conn_num max connection number of softap interface bool softap_max_conn_num_set is max connection number of softap interface set uint8_t softap_channel channel of softap interface bool softap_channel_set is channel of softap interface set Espressif Systems 272 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_blufi_ap_record_t Description of an WiFi AP. Public Members uint8_t ssid[33] SSID of AP int8_t rssi signal strength of AP struct esp_blufi_callbacks_t BLUFI callback functions type. Public Members esp_blufi_event_cb_t event_cb BLUFI event callback esp_blufi_negotiate_data_handler_t negotiate_data_handler BLUFI negotiate data function for negotiate share key esp_blufi_encrypt_func_t encrypt_func BLUFI encrypt data function with share key generated by negotiate_data_handler esp_blufi_decrypt_func_t decrypt_func BLUFI decrypt data function with share key generated by negotiate_data_handler esp_blufi_checksum_func_t checksum_func BLUFI check sum function (FCS) Macros ESP_BD_ADDR_LEN Bluetooth address length. Type Definitions typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN] Bluetooth device address. typedef void (*esp_blufi_event_cb_t)(esp_blufi_cb_event_t *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. Espressif Systems 273 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return Nonnegative number is encrypted length, if error, return negative number; Parameters · iv8: : initial vector(8bit), normally, blufi core will input packet sequence number · crypt_data: : plain text and encrypted data, the encrypt function must support autochthonous encrypt · crypt_len: : length of plain text typedef int (*esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len) BLUFI decrypt the data after negotiate a share key. Return Nonnegative number is decrypted length, if error, return negative number; Parameters · iv8: : initial vector(8bit), normally, blufi core will input packet sequence number · crypt_data: : encrypted data and plain text, the encrypt function must support autochthonous decrypt · crypt_len: : length of encrypted text typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len) BLUFI checksum. Parameters · iv8: : initial vector(8bit), normally, blufi core will input packet sequence number · data: : data need to checksum · len: : length of data Enumerations enum esp_blufi_cb_event_t Values: ESP_BLUFI_EVENT_INIT_FINISH = 0 ESP_BLUFI_EVENT_DEINIT_FINISH ESP_BLUFI_EVENT_SET_WIFI_OPMODE ESP_BLUFI_EVENT_BLE_CONNECT ESP_BLUFI_EVENT_BLE_DISCONNECT ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP ESP_BLUFI_EVENT_GET_WIFI_STATUS ESP_BLUFI_EVENT_DEAUTHENTICATE_STA ESP_BLUFI_EVENT_RECV_STA_BSSID ESP_BLUFI_EVENT_RECV_STA_SSID ESP_BLUFI_EVENT_RECV_STA_PASSWD ESP_BLUFI_EVENT_RECV_SOFTAP_SSID ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL ESP_BLUFI_EVENT_RECV_USERNAME ESP_BLUFI_EVENT_RECV_CA_CERT ESP_BLUFI_EVENT_RECV_CLIENT_CERT ESP_BLUFI_EVENT_RECV_SERVER_CERT Espressif Systems 274 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE ESP_BLUFI_EVENT_GET_WIFI_LIST ESP_BLUFI_EVENT_REPORT_ERROR ESP_BLUFI_EVENT_RECV_CUSTOM_DATA enum esp_blufi_sta_conn_state_t BLUFI config status. Values: ESP_BLUFI_STA_CONN_SUCCESS = 0x00 ESP_BLUFI_STA_CONN_FAIL = 0x01 enum esp_blufi_init_state_t BLUFI init status. Values: ESP_BLUFI_INIT_OK = 0 ESP_BLUFI_INIT_FAILED enum esp_blufi_deinit_state_t BLUFI deinit status. Values: ESP_BLUFI_DEINIT_OK = 0 ESP_BLUFI_DEINIT_FAILED enum esp_blufi_error_state_t Values: ESP_BLUFI_SEQUENCE_ERROR = 0 ESP_BLUFI_CHECKSUM_ERROR ESP_BLUFI_DECRYPT_ERROR ESP_BLUFI_ENCRYPT_ERROR ESP_BLUFI_INIT_SECURITY_ERROR ESP_BLUFI_DH_MALLOC_ERROR ESP_BLUFI_DH_PARAM_ERROR ESP_BLUFI_READ_PARAM_ERROR ESP_BLUFI_MAKE_PUBLIC_ERROR ESP_BLUFI_DATA_FORMAT_ERROR ESP_BLUFI_CALC_MD5_ERROR 2.3.3 Controller && VHCI Overview Instructions Espressif Systems 275 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 276 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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(). Espressif Systems 277 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 278 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 279 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t normal_adv_size Normal adv size for scan duplicate uint16_t mesh_adv_size Mesh adv size for scan duplicate uint16_t send_adv_reserved_size Controller minimum memory value uint32_t controller_debug_flag Controller debug log flag uint8_t mode Controller mode: BR/EDR, BLE or Dual Mode uint8_t ble_max_conn BLE maximum connection numbers uint8_t bt_max_acl_conn BR/EDR maximum ACL connection numbers uint8_t bt_sco_datapath SCO data path, i.e. HCI or PCM module bool auto_latency BLE auto latency, used to enhance classic BT performance bool bt_legacy_auth_vs_evt BR/EDR Legacy auth complete event required to protect from BIAS attack uint8_t bt_max_sync_conn BR/EDR maximum ACL connection numbers. Effective in menuconfig uint8_t ble_sca BLE low power crystal accuracy index uint8_t pcm_role PCM role (master & slave) uint8_t pcm_polar PCM polar trig (falling clk edge & rising clk edge) bool hli Using high level interrupt or not uint32_t magic Magic number struct esp_vhci_host_callback esp_vhci_host_callback used for vhci call host function to notify what host need to do Public Members void (*notify_host_send_available)(void) callback used to notify that the host can send packet to controller int (*notify_host_recv)(uint8_t *data, uint16_t len) callback used to notify that the controller has a packet to send to the host Macros ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL BT_CONTROLLER_INIT_CONFIG_DEFAULT() Espressif Systems 280 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Type Definitions typedef struct esp_vhci_host_callback esp_vhci_host_callback_t esp_vhci_host_callback used for vhci call host function to notify what host need to do Enumerations enum esp_bt_mode_t Bluetooth mode for controller enable/disable. Values: ESP_BT_MODE_IDLE = 0x00 Bluetooth is not running ESP_BT_MODE_BLE = 0x01 Run BLE mode ESP_BT_MODE_CLASSIC_BT = 0x02 Run Classic BT mode ESP_BT_MODE_BTDM = 0x03 Run dual mode enum [anonymous] BLE sleep clock accuracy(SCA), values for ble_sca field in esp_bt_controller_config_t, currently only ESP_BLE_SCA_500PPM and ESP_BLE_SCA_250PPM are supported. Values: ESP_BLE_SCA_500PPM = 0 BLE SCA at 500ppm ESP_BLE_SCA_250PPM BLE SCA at 250ppm ESP_BLE_SCA_150PPM BLE SCA at 150ppm ESP_BLE_SCA_100PPM BLE SCA at 100ppm ESP_BLE_SCA_75PPM BLE SCA at 75ppm ESP_BLE_SCA_50PPM BLE SCA at 50ppm ESP_BLE_SCA_30PPM BLE SCA at 30ppm ESP_BLE_SCA_20PPM BLE SCA at 20ppm enum esp_bt_controller_status_t Bluetooth controller enable/disable/initialised/de-initialised status. Values: ESP_BT_CONTROLLER_STATUS_IDLE = 0 ESP_BT_CONTROLLER_STATUS_INITED ESP_BT_CONTROLLER_STATUS_ENABLED ESP_BT_CONTROLLER_STATUS_NUM enum esp_ble_power_type_t BLE tx power type ESP_BLE_PWR_TYPE_CONN_HDL0-8: for each connection, and only be set after connection completed. when disconnect, the correspond TX power is not effected. ESP_BLE_PWR_TYPE_ADV : for advertising/scan response. ESP_BLE_PWR_TYPE_SCAN : for scan. Espressif Systems 281 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 282 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.3.4 ESP-BLE-MESH With various features of ESP-BLE-MESH, users can create a managed flooding mesh network for several scenarios, such as lighting, sensor and etc. For an ESP32 to join and work on a ESP-BLE-MESH network, it must be provisioned firstly. By provisioning, the ESP32, as an unprovisioned device, will join the ESP-BLE-MESH network and become a ESP-BLE-MESH node, communicating with other nodes within or beyond the radio range. Apart from ESP-BLE-MESH nodes, inside ESP-BLE-MESH network, there is also ESP32 that works as ESP-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 Espressif Systems 283 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP-BLE-MESH Core API Reference · ESP-BLE-MESH Models API Reference ESP-BLE-MESH Definitions This section contains only one header file, which lists the following items of ESP-BLE-MESH. · ID of all the models and related message opcodes · Structs of model, element and Composition Data · Structs of used by ESP-BLE-MESH Node/Provisioner for provisioning · Structs used to transmit/receive messages · Event types and related event parameters Header File · components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h Unions union esp_ble_mesh_prov_cb_param_t #include <esp_ble_mesh_defs.h> BLE Mesh Node/Provisioner callback parameters union. Public Members struct esp_ble_mesh_prov_cb_param_t::ble_mesh_prov_register_comp_param prov_register_comp Event parameter of ESP_BLE_MESH_PROV_REGISTER_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_unprov_dev_name_comp_param node_set_unprov_dev_name Event parameter of ESP_BLE_MESH_NODE_SET_UNPROV_DEV_NAME_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_prov_enable_comp_param node_prov_enable_comp Event parameter of ESP_BLE_MESH_NODE_PROV_ENABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_prov_disable_comp_param node_prov_disable_comp Event parameter of ESP_BLE_MESH_NODE_PROV_DISABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_link_open_evt_param node_prov_link_open Event parameter of ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_link_close_evt_param node_prov_link_close Event parameter of ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_output_num_evt_param node_prov_output_num Event parameter of ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_output_str_evt_param node_prov_output_str Event parameter of ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_evt_param node_prov_input Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provision_complete_evt_param node_prov_complete Event parameter of ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provision_reset_param node_prov_reset Event parameter of ESP_BLE_MESH_NODE_PROV_RESET_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_oob_pub_key_comp_param node_prov_set_oob_pub_key_co Event parameter of ESP_BLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_number_comp_param node_prov_input_num_comp Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_NUM_COMP_EVT Espressif Systems 284 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_prov_cb_param_t::ble_mesh_input_string_comp_param node_prov_input_str_comp Event parameter of ESP_BLE_MESH_NODE_PROV_INPUT_STR_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_identity_enable_comp_param node_proxy_identity_enabl Event parameter of ESP_BLE_MESH_NODE_PROXY_IDENTITY_ENABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_gatt_enable_comp_param node_proxy_gatt_enable_comp Event parameter of ESP_BLE_MESH_NODE_PROXY_GATT_ENABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_gatt_disable_comp_param node_proxy_gatt_disable_com Event parameter of ESP_BLE_MESH_NODE_PROXY_GATT_DISABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_add_local_net_key_comp_param node_add_net_key_comp Event parameter of ESP_BLE_MESH_NODE_ADD_LOCAL_NET_KEY_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_add_local_app_key_comp_param node_add_app_key_comp Event parameter of ESP_BLE_MESH_NODE_ADD_LOCAL_APP_KEY_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_node_bind_local_mod_app_comp_param node_bind_app_key_to_ Event parameter of ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODEL_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_recv_unprov_adv_pkt_param provisioner_recv_unpr Event parameter of ESP_BLE_MESH_PROVISIONER_RECV_UNPROV_ADV_PKT_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_enable_comp_param provisioner_prov_enable Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_ENABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_disable_comp_param provisioner_prov_disabl Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_DISABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_link_open_evt_param provisioner_prov_link_open Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_LINK_OPEN_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_read_oob_pub_key_evt_param provisioner_prov Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_input_evt_param provisioner_prov_input Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_INPUT_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_output_evt_param provisioner_prov_output Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_OUTPUT_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_link_close_evt_param provisioner_prov_link_clos Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_LINK_CLOSE_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_comp_param provisioner_prov_complete Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_COMPLETE_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_add_unprov_dev_comp_param provisioner_add_unpr Event parameter of ESP_BLE_MESH_PROVISIONER_ADD_UNPROV_DEV_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_dev_with_addr_comp_param provisioner_prov_ Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_DEV_WITH_ADDR_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_delete_dev_comp_param provisioner_delete_dev_c Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_DEV_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_dev_uuid_match_comp_param provisioner_set_de Event parameter of ESP_BLE_MESH_PROVISIONER_SET_DEV_UUID_MATCH_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_prov_data_info_comp_param provisioner_set_pr Event parameter of ESP_BLE_MESH_PROVISIONER_SET_PROV_DATA_INFO_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_static_oob_val_comp_param provisioner_set_sta Event parameter of ESP_BLE_MESH_PROVISIONER_SET_STATIC_OOB_VALUE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_primary_elem_addr_comp_param provisioner_set Event parameter of ESP_BLE_MESH_PROVISIONER_SET_PRIMARY_ELEM_ADDR_COMP_EVT Espressif Systems 285 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_read_oob_pub_key_comp_param provisioner_pro Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_input_num_comp_param provisioner_prov_inp Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_INPUT_NUMBER_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_prov_input_str_comp_param provisioner_prov_inpu Event parameter of ESP_BLE_MESH_PROVISIONER_PROV_INPUT_STRING_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_set_node_name_comp_param provisioner_set_node_ Event parameter of ESP_BLE_MESH_PROVISIONER_SET_NODE_NAME_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_add_local_app_key_comp_param provisioner_add_ap Event parameter of ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_APP_KEY_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_update_local_app_key_comp_param provisioner_upda Event parameter of ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_APP_KEY_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_bind_local_mod_app_comp_param provisioner_bind_ Event parameter of ESP_BLE_MESH_PROVISIONER_BIND_APP_KEY_TO_MODEL_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_add_local_net_key_comp_param provisioner_add_net Event parameter of ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_NET_KEY_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_update_local_net_key_comp_param provisioner_updat Event parameter of ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_NET_KEY_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_store_node_comp_data_comp_param provisioner_stor Event parameter of ESP_BLE_MESH_PROVISIONER_STORE_NODE_COMP_DATA_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_delete_node_with_uuid_comp_param provisioner_dele Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_UUID_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_provisioner_delete_node_with_addr_comp_param provisioner_dele Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_ADDR_COMP_EVT int err_code Indicate the result of enabling/disabling to receive heartbeat messages by the Provisioner Indicate the result of setting the heartbeat filter type by the Provisioner Indicate the result of setting the heartbeat filter address by the Provisioner Indicate the result of directly erasing settings by the Provisioner Indicate the result of opening settings with index by the Provisioner Indicate the result of opening settings with user id by the Provisioner Indicate the result of closing settings with index by the Provisioner Indicate the result of closing settings with user id by the Provisioner Indicate the result of deleting settings with index by the Provisioner Indicate the result of deleting settings with user id by the Provisioner bool enable Indicate enabling or disabling receiving heartbeat messages struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_enable_heartbeat_recv_comp ESP_BLE_MESH_PROVISIONER_ENABLE_HEARTBEAT_RECV_COMP_EVT. Event parameters of ESP_BLE_MESH_PROVISIONER_ENABLE_HEARTBEAT_RECV_COMP_EVT uint8_t type Type of the filter used for receiving heartbeat messages struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_set_heartbeat_filter_type_comp ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_TYPE_COMP_EVT. Event parameters of ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_TYPE_COMP_EVT Espressif Systems 286 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t op Operation (add, remove, clean) uint16_t hb_src Heartbeat source address uint16_t hb_dst Heartbeat destination address struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_set_heartbeat_filter_info_comp ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_INFO_COMP_EVT. Event parameters of ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_INFO_COMP_EVT uint8_t init_ttl Heartbeat InitTTL uint8_t rx_ttl Heartbeat RxTTL uint8_t hops Heartbeat hops (InitTTL - RxTTL + 1) uint16_t feature Bit field of currently active features of the node int8_t rssi RSSI of the heartbeat message struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_recv_heartbeat ESP_BLE_MESH_PROVISIONER_RECV_HEARTBEAT_MESSAGE_EVT. Event parameters of ESP_BLE_MESH_PROVISIONER_RECV_HEARTBEAT_MESSAGE_EVT struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_direct_erase_settings_comp ESP_BLE_MESH_PROVISIONER_DRIECT_ERASE_SETTINGS_COMP_EVT. Event parameters of ESP_BLE_MESH_PROVISIONER_DRIECT_ERASE_SETTINGS_COMP_EVT uint8_t index Index of Provisioner settings struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_open_settings_with_index_comp ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_INDEX_COMP_EVT. Event parameter of ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_INDEX_COMP_EVT char uid[ESP_BLE_MESH_SETTINGS_UID_SIZE + 1] Provisioner settings user id struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_open_settings_with_uid_comp ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_COMP_EVT. Event parameters of ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_close_settings_with_index_comp ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDEX_COMP_EVT. Event parameter of ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDEX_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_close_settings_with_uid_comp ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_COMP_EVT. Event parameters of ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_delete_settings_with_index_comp ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_INDEX_COMP_EVT. Event parameter of ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_INDEX_COMP_EVT Espressif Systems 287 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_prov_cb_param_t::[anonymous] provisioner_delete_settings_with_uid_comp ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_UID_COMP_EVT. Event parameters of ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_UID_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_fast_prov_info_comp_param set_fast_prov_info_comp Event parameter of ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_set_fast_prov_action_comp_param set_fast_prov_action_comp Event parameter of ESP_BLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_heartbeat_msg_recv_param heartbeat_msg_recv Event parameter of ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_enable_comp_param lpn_enable_comp Event parameter of ESP_BLE_MESH_LPN_ENABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_disable_comp_param lpn_disable_comp Event parameter of ESP_BLE_MESH_LPN_DISABLE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_poll_comp_param lpn_poll_comp Event parameter of ESP_BLE_MESH_LPN_POLL_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friendship_establish_param lpn_friendship_establish Event parameter of ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friendship_terminate_param lpn_friendship_terminate Event parameter of ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_establish_param frnd_friendship_establish Event parameter of ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_terminate_param frnd_friendship_terminate Event parameter of ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_recv_adv_pkt_param proxy_client_recv_adv_pkt Event parameter of ESP_BLE_MESH_PROXY_CLIENT_RECV_ADV_PKT_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_connected_param proxy_client_connected Event parameter of ESP_BLE_MESH_PROXY_CLIENT_CONNECTED_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_disconnected_param proxy_client_disconnected Event parameter of ESP_BLE_MESH_PROXY_CLIENT_DISCONNECTED_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_recv_filter_status_param proxy_client_recv_filte Event parameter of ESP_BLE_MESH_PROXY_CLIENT_RECV_FILTER_STATUS_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_connect_comp_param proxy_client_connect_comp Event parameter of ESP_BLE_MESH_PROXY_CLIENT_CONNECT_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_disconnect_comp_param proxy_client_disconnect Event parameter of ESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_set_filter_type_comp_param proxy_client_set_filt Event parameter of ESP_BLE_MESH_PROXY_CLIENT_SET_FILTER_TYPE_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_add_filter_addr_comp_param proxy_client_add_fil Event parameter of ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_client_remove_filter_addr_comp_param proxy_client_remov Event parameter of ESP_BLE_MESH_PROXY_CLIENT_REMOVE_FILTER_ADDR_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_server_connected_param proxy_server_connected Event parameter of ESP_BLE_MESH_PROXY_SERVER_CONNECTED_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_proxy_server_disconnected_param proxy_server_disconnected Event parameter of ESP_BLE_MESH_PROXY_SERVER_DISCONNECTED_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 Espressif Systems 288 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_prov_cb_param_t::ble_mesh_model_unsub_group_addr_comp_param model_unsub_group_addr Event parameters of ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EVT struct esp_ble_mesh_prov_cb_param_t::ble_mesh_deinit_mesh_comp_param deinit_mesh_comp Event parameter of ESP_BLE_MESH_DEINIT_MESH_COMP_EVT struct ble_mesh_deinit_mesh_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_DEINIT_MESH_COMP_EVT. Public Members int err_code Indicate the result of BLE Mesh deinitialization struct ble_mesh_friend_friendship_establish_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT. Public Members uint16_t lpn_addr Low Power Node unicast address struct ble_mesh_friend_friendship_terminate_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT. Public Types enum [anonymous] This enum value is the reason of friendship termination on the friend node side Values: ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_ESTABLISH_FAIL Friend Offer has been sent, but Friend Offer is not received within 1 second, friendship fails to be established ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_POLL_TIMEOUT Friendship is established, PollTimeout timer expires and no Friend Poll/Sub Add/Sub Remove is received ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_RECV_FRND_REQ Receive Friend Request from existing Low Power Node ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_RECV_FRND_CLEAR Receive Friend Clear from other friend node ESP_BLE_MESH_FRND_FRIENDSHIP_TERMINATE_DISABLE Friend feature disabled or corresponding NetKey is deleted Public Members uint16_t lpn_addr Low Power Node unicast address esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_friendship_terminate_param::[anonymous] reason This enum value is the reason of friendship termination on the friend node side Friendship terminated reason struct ble_mesh_heartbeat_msg_recv_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT. Espressif Systems 289 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t hops Heartbeat hops (InitTTL - RxTTL + 1) uint16_t feature Bit field of currently active features of the node struct ble_mesh_input_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_EVT. Public Members esp_ble_mesh_input_action_t action Action of Input OOB Authentication uint8_t size Size of Input OOB Authentication struct ble_mesh_input_number_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_NUM_COMP_EVT. Public Members int err_code Indicate the result of inputting number struct ble_mesh_input_string_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_INPUT_STR_COMP_EVT. Public Members int err_code Indicate the result of inputting string struct ble_mesh_link_close_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT. Public Members esp_ble_mesh_prov_bearer_t bearer Type of the bearer used when device link is closed struct ble_mesh_link_open_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT. Public Members 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. Espressif Systems 290 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members int err_code Indicate the result of disabling LPN functionality struct ble_mesh_lpn_enable_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_ENABLE_COMP_EVT. Public Members int err_code Indicate the result of enabling LPN functionality struct ble_mesh_lpn_friendship_establish_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT. Public Members uint16_t friend_addr Friend Node unicast address struct ble_mesh_lpn_friendship_terminate_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT. Public Members uint16_t friend_addr Friend Node unicast address struct ble_mesh_lpn_poll_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_LPN_POLL_COMP_EVT. Public Members int err_code Indicate the result of sending Friend Poll struct ble_mesh_model_sub_group_addr_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_SUBSCRIBE_GROUP_ADDR_COMP_EVT. Public Members int err_code Indicate the result of local model subscribing group address uint16_t element_addr Element address uint16_t company_id Company ID uint16_t model_id Model ID uint16_t group_addr Group Address Espressif Systems 291 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct ble_mesh_model_unsub_group_addr_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EVT. Public Members int err_code Indicate the result of local model unsubscribing group address uint16_t element_addr Element address uint16_t company_id Company ID uint16_t model_id Model ID uint16_t group_addr Group Address struct ble_mesh_node_add_local_app_key_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_ADD_LOCAL_APP_KEY_COMP_EVT. Public Members int err_code Indicate the result of adding local AppKey by the node uint16_t net_idx NetKey Index uint16_t app_idx AppKey Index struct ble_mesh_node_add_local_net_key_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_ADD_LOCAL_NET_KEY_COMP_EVT. Public Members int err_code Indicate the result of adding local NetKey by the node uint16_t net_idx NetKey Index struct ble_mesh_node_bind_local_mod_app_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODEL_COMP_EVT. 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 Espressif Systems 292 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t model_id Model ID struct ble_mesh_output_num_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVT. Public Members esp_ble_mesh_output_action_t action Action of Output OOB Authentication uint32_t number Number of Output OOB Authentication struct ble_mesh_output_str_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVT. Public Members char string[8] String of Output OOB Authentication struct ble_mesh_prov_disable_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_DISABLE_COMP_EVT. Public Members int err_code Indicate the result of disabling BLE Mesh device struct ble_mesh_prov_enable_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_ENABLE_COMP_EVT. Public Members int err_code Indicate the result of enabling BLE Mesh device struct ble_mesh_prov_register_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROV_REGISTER_COMP_EVT. Public Members int err_code Indicate the result of BLE Mesh initialization struct ble_mesh_provision_complete_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT. Public Members uint16_t net_idx NetKey Index uint8_t net_key[16] NetKey Espressif Systems 293 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t addr Primary address uint8_t flags Flags uint32_t iv_index IV Index struct ble_mesh_provision_reset_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_RESET_EVT. struct ble_mesh_provisioner_add_local_app_key_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_APP_KEY_COMP_EVT. Public Members int err_code Indicate the result of adding local AppKey by the Provisioner uint16_t net_idx NetKey Index uint16_t app_idx AppKey Index struct ble_mesh_provisioner_add_local_net_key_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_NET_KEY_COMP_EVT. Public Members int err_code Indicate the result of adding local NetKey by the Provisioner uint16_t net_idx NetKey Index struct ble_mesh_provisioner_add_unprov_dev_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_ADD_UNPROV_DEV_COMP_EVT. Public Members int err_code Indicate the result of adding device into queue by the Provisioner struct ble_mesh_provisioner_bind_local_mod_app_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_BIND_APP_KEY_TO_MODEL_COMP_EVT. Public Members int err_code Indicate the result of binding AppKey with model by the Provisioner uint16_t element_addr Element address uint16_t app_idx AppKey Index Espressif Systems 294 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t company_id Company ID uint16_t model_id Model ID struct ble_mesh_provisioner_delete_dev_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_DELETE_DEV_COMP_EVT. Public Members int err_code Indicate the result of deleting device by the Provisioner struct ble_mesh_provisioner_delete_node_with_addr_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_ADDR_COMP_EVT. Public Members int err_code Indicate the result of deleting node with unicast address by the Provisioner uint16_t unicast_addr Node unicast address struct ble_mesh_provisioner_delete_node_with_uuid_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_UUID_COMP_EVT. Public Members int err_code Indicate the result of deleting node with uuid by the Provisioner uint8_t uuid[16] Node device uuid struct ble_mesh_provisioner_link_close_evt_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_PROV_LINK_CLOSE_EVT. Public Members 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. Espressif Systems 295 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 296 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 297 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 298 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members int err_code Indicate the result of setting static oob value by the Provisioner struct ble_mesh_provisioner_store_node_comp_data_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_STORE_NODE_COMP_DATA_COMP_EVT. Public Members int err_code Indicate the result of storing node composition data by the Provisioner uint16_t addr Node element address struct ble_mesh_provisioner_update_local_app_key_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_APP_KEY_COMP_EVT. Public Members int err_code Indicate the result of updating local AppKey by the Provisioner uint16_t net_idx NetKey Index uint16_t app_idx AppKey Index struct ble_mesh_provisioner_update_local_net_key_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_NET_KEY_COMP_EVT. Public Members int err_code Indicate the result of updating local NetKey by the Provisioner uint16_t net_idx NetKey Index struct ble_mesh_proxy_client_add_filter_addr_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP_EVT. Public Members int err_code Indicate the result of Proxy Client add filter address uint8_t conn_handle Proxy connection handle uint16_t net_idx Corresponding NetKey Index struct ble_mesh_proxy_client_connect_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_CLIENT_CONNECT_COMP_EVT. Espressif Systems 299 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 300 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 301 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 struct ble_mesh_proxy_server_connected_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_SERVER_CONNECTED_EVT. Public Members uint8_t conn_handle Proxy connection handle struct ble_mesh_proxy_server_disconnected_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_PROXY_SERVER_DISCONNECTED_EVT. Public Members uint8_t conn_handle Proxy connection handle uint8_t reason Proxy disconnect reason struct ble_mesh_set_fast_prov_action_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT. Espressif Systems 302 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t status_action Indicate the result of setting action of fast provisioning struct ble_mesh_set_fast_prov_info_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT. Public Members uint8_t status_unicast Indicate the result of setting unicast address range of fast provisioning uint8_t status_net_idx Indicate the result of setting NetKey Index of fast provisioning uint8_t status_match Indicate the result of setting matching Device UUID of fast provisioning struct ble_mesh_set_oob_pub_key_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EVT. Public Members int err_code Indicate the result of setting OOB Public Key struct ble_mesh_set_unprov_dev_name_comp_param #include <esp_ble_mesh_defs.h> ESP_BLE_MESH_NODE_SET_UNPROV_DEV_NAME_COMP_EVT. Public Members int err_code Indicate the result of setting BLE Mesh device name union esp_ble_mesh_server_state_value_t #include <esp_ble_mesh_defs.h> Server model state value union. Public Members uint8_t onoff The value of the Generic OnOff state The value of the Light LC Light OnOff state struct esp_ble_mesh_server_state_value_t::[anonymous] gen_onoff The Generic OnOff state int16_t level The value of the Generic Level state struct esp_ble_mesh_server_state_value_t::[anonymous] gen_level The Generic Level state uint8_t onpowerup The value of the Generic OnPowerUp state struct esp_ble_mesh_server_state_value_t::[anonymous] gen_onpowerup The Generic OnPowerUp state Espressif Systems 303 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t power The value of the Generic Power Actual state struct esp_ble_mesh_server_state_value_t::[anonymous] gen_power_actual The Generic Power Actual state uint16_t lightness The value of the Light Lightness Actual state The value of the Light Lightness Linear state The value of the Light CTL Lightness state The value of the Light HSL Lightness state The value of the Light xyL Lightness state struct esp_ble_mesh_server_state_value_t::[anonymous] light_lightness_actual The Light Lightness Actual state struct esp_ble_mesh_server_state_value_t::[anonymous] light_lightness_linear The Light Lightness Linear state struct esp_ble_mesh_server_state_value_t::[anonymous] light_ctl_lightness The Light CTL Lightness state uint16_t temperature The value of the Light CTL Temperature state int16_t delta_uv The value of the Light CTL Delta UV state struct esp_ble_mesh_server_state_value_t::[anonymous] light_ctl_temp_delta_uv The Light CTL Temperature & Delta UV states uint16_t hue The value of the Light HSL Hue state uint16_t saturation The value of the Light HSL Saturation state struct esp_ble_mesh_server_state_value_t::[anonymous] light_hsl The Light HSL composite state struct esp_ble_mesh_server_state_value_t::[anonymous] light_hsl_lightness The Light HSL Lightness state struct esp_ble_mesh_server_state_value_t::[anonymous] light_hsl_hue The Light HSL Hue state struct esp_ble_mesh_server_state_value_t::[anonymous] light_hsl_saturation The Light HSL Saturation state struct esp_ble_mesh_server_state_value_t::[anonymous] light_xyl_lightness The Light xyL Lightness state struct esp_ble_mesh_server_state_value_t::[anonymous] light_lc_light_onoff The Light LC Light OnOff state union esp_ble_mesh_model_cb_param_t #include <esp_ble_mesh_defs.h> BLE Mesh model callback parameters union. Public Members struct esp_ble_mesh_model_cb_param_t::ble_mesh_model_operation_evt_param model_operation Event parameter of ESP_BLE_MESH_MODEL_OPERATION_EVT Espressif Systems 304 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Public Members uint32_t opcode Opcode of the received message esp_ble_mesh_model_t *model Pointer to the model which receives the message Espressif Systems 305 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 306 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 307 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 308 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t company_id 16-bit company identifier uint16_t model_id 16-bit model identifier struct esp_ble_mesh_model::[anonymous]::[anonymous] vnd Structure encapsulating a model ID with a company ID union esp_ble_mesh_model::[anonymous] [anonymous] Model ID uint8_t element_idx Internal information, mainly for persistent storage Belongs to Nth element uint8_t model_idx Is the Nth model in the element uint16_t flags Information about what has changed esp_ble_mesh_elem_t *element The Element to which this Model belongs esp_ble_mesh_model_pub_t *const pub Model Publication uint16_t keys[CONFIG_BLE_MESH_MODEL_KEY_COUNT] AppKey List uint16_t groups[CONFIG_BLE_MESH_MODEL_GROUP_COUNT] Subscription List (group or virtual addresses) esp_ble_mesh_model_op_t *op Model operation context esp_ble_mesh_model_cbs_t *cb Model callback structure void *user_data Model-specific user data struct esp_ble_mesh_msg_ctx_t Message sending context. This structure is associated with struct bt_mesh_msg_ctx in mesh_access.h Public Members uint16_t net_idx NetKey Index of the subnet through which to send the message. uint16_t app_idx AppKey Index for message encryption. uint16_t addr Remote address. uint16_t recv_dst Destination address of a received message. Not used for sending. int8_t recv_rssi RSSI of received packet. Not used for sending. uint8_t recv_ttl : 7 Received TTL value. Not used for sending. uint8_t send_rel : 1 Force sending reliably by using segment acknowledgement Espressif Systems 309 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 310 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 311 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t *comp_data Value of Composition Data struct esp_ble_mesh_fast_prov_info_t Context of fast provisioning which need to be set. Public Members uint16_t unicast_min Minimum unicast address used for fast provisioning uint16_t unicast_max Maximum unicast address used for fast provisioning uint16_t net_idx Netkey index used for fast provisioning uint8_t flags Flags used for fast provisioning uint32_t iv_index IV Index used for fast provisioning uint8_t offset Offset of the UUID to be compared uint8_t match_len Length of the UUID to be compared uint8_t match_val[16] Value of UUID to be compared struct esp_ble_mesh_heartbeat_filter_info_t Context of Provisioner heartbeat filter information to be set Public Members uint16_t hb_src Heartbeat source address (unicast address) uint16_t hb_dst Heartbeat destination address (unicast address or group address) struct esp_ble_mesh_client_op_pair_t BLE Mesh client models related definitions. Client model Get/Set message opcode and corresponding Status message opcode Public Members uint32_t cli_op The client message opcode uint32_t status_op The server status opcode corresponding to the client message opcode struct esp_ble_mesh_client_t Client Model user data context. Espressif Systems 312 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 313 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; 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 Espressif Systems 314 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Macros ESP_BLE_MESH_SDU_MAX_LEN < The maximum length of a BLE Mesh message, including Opcode, Payload and TransMIC Length of a short Mesh MIC. ESP_BLE_MESH_MIC_SHORT Length of a long Mesh MIC. ESP_BLE_MESH_MIC_LONG The maximum length of a BLE Mesh provisioned node name ESP_BLE_MESH_NODE_NAME_MAX_LEN The maximum length of a BLE Mesh unprovisioned device name ESP_BLE_MESH_DEVICE_NAME_MAX_LEN The maximum length of settings user id ESP_BLE_MESH_SETTINGS_UID_SIZE Invalid settings index ESP_BLE_MESH_INVALID_SETTINGS_IDX Define the BLE Mesh octet 16 bytes size ESP_BLE_MESH_OCTET16_LEN ESP_BLE_MESH_OCTET8_LEN ESP_BLE_MESH_CID_NVAL Special TTL value to request using configured default TTL ESP_BLE_MESH_TTL_DEFAULT Maximum allowed TTL value ESP_BLE_MESH_TTL_MAX ESP_BLE_MESH_ADDR_UNASSIGNED ESP_BLE_MESH_ADDR_ALL_NODES ESP_BLE_MESH_ADDR_PROXIES ESP_BLE_MESH_ADDR_FRIENDS ESP_BLE_MESH_ADDR_RELAYS ESP_BLE_MESH_KEY_UNUSED ESP_BLE_MESH_KEY_DEV ESP_BLE_MESH_KEY_PRIMARY ESP_BLE_MESH_KEY_ANY Primary Network Key index ESP_BLE_MESH_NET_PRIMARY Relay state value ESP_BLE_MESH_RELAY_DISABLED ESP_BLE_MESH_RELAY_ENABLED ESP_BLE_MESH_RELAY_NOT_SUPPORTED Beacon state value ESP_BLE_MESH_BEACON_DISABLED ESP_BLE_MESH_BEACON_ENABLED GATT Proxy state value ESP_BLE_MESH_GATT_PROXY_DISABLED ESP_BLE_MESH_GATT_PROXY_ENABLED Espressif Systems 315 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 316 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_GET_PUBLISH_TRANSMIT_COUNT(transmit) Decode Publish Retransmit count from a given value. Return Retransmission count (actual transmissions equal to N + 1). Parameters · transmit: Encoded Publish Retransmit count & interval value. ESP_BLE_MESH_GET_PUBLISH_TRANSMIT_INTERVAL(transmit) Decode Publish Retransmit interval from a given value. Callbacks which are not needed to be initialized by users (set with 0 and will be initialized internally) Return Transmission interval in milliseconds. Parameters · transmit: Encoded Publish Retransmit count & interval value. ESP_BLE_MESH_PROV_STATIC_OOB_MAX_LEN Maximum length of string used by Output OOB authentication ESP_BLE_MESH_PROV_OUTPUT_OOB_MAX_LEN Maximum length of string used by Output OOB authentication ESP_BLE_MESH_PROV_INPUT_OOB_MAX_LEN Macros used to define message opcode ESP_BLE_MESH_MODEL_OP_1(b0) ESP_BLE_MESH_MODEL_OP_2(b0, b1) ESP_BLE_MESH_MODEL_OP_3(b0, cid) This macro is associated with BLE_MESH_MODEL_CB in mesh_access.h ESP_BLE_MESH_SIG_MODEL(_id, _op, _pub, _user_data) This macro is associated with BLE_MESH_MODEL_VND_CB in mesh_access.h ESP_BLE_MESH_VENDOR_MODEL(_company, _id, _op, _pub, _user_data) ESP_BLE_MESH_ELEMENT(_loc, _mods, _vnd_mods) Helper to define a BLE Mesh element within an array. In case the element has no SIG or Vendor models, the helper macro ESP_BLE_MESH_MODEL_NONE can be given instead. Note This macro is associated with BLE_MESH_ELEM in mesh_access.h Parameters · _loc: Location Descriptor. · _mods: Array of SIG models. · _vnd_mods: Array of vendor models. ESP_BLE_MESH_PROV(uuid, sta_val, sta_val_len, out_size, out_act, in_size, in_act) BT_OCTET32_LEN BD_ADDR_LEN ESP_BLE_MESH_ADDR_TYPE_PUBLIC ESP_BLE_MESH_ADDR_TYPE_RANDOM ESP_BLE_MESH_ADDR_TYPE_RPA_PUBLIC ESP_BLE_MESH_ADDR_TYPE_RPA_RANDOM ESP_BLE_MESH_MODEL_PUB_DEFINE(_name, _msg_len, _role) Define a model publication context. Parameters · _name: Variable name given to the context. · _msg_len: Length of the publication message. · _role: Role of the device which contains the model. Espressif Systems 317 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_OP(_opcode, _min_len) Define a model operation context. Parameters · _opcode: Message opcode. · _min_len: Message minimum length. ESP_BLE_MESH_MODEL_OP_END Define the terminator for the model operation table. Each model operation struct array must use this terminator as the end tag of the operation unit. ESP_BLE_MESH_MODEL_NONE Helper to define an empty model array. This structure is associated with BLE_MESH_MODEL_NONE in mesh_access.h ADD_DEV_RM_AFTER_PROV_FLAG Device will be removed from queue after provisioned successfully ADD_DEV_START_PROV_NOW_FLAG Start provisioning device immediately ADD_DEV_FLUSHABLE_DEV_FLAG Device can be remove when queue is full and new device is going to added DEL_DEV_ADDR_FLAG DEL_DEV_UUID_FLAG PROV_DATA_NET_IDX_FLAG PROV_DATA_FLAGS_FLAG PROV_DATA_IV_INDEX_FLAG ESP_BLE_MESH_HEARTBEAT_FILTER_ACCEPTLIST ESP_BLE_MESH_HEARTBEAT_FILTER_REJECTLIST Provisioner heartbeat filter operation ESP_BLE_MESH_HEARTBEAT_FILTER_ADD ESP_BLE_MESH_HEARTBEAT_FILTER_REMOVE ESP_BLE_MESH_MODEL_ID_CONFIG_SRV BLE Mesh models related Model ID and Opcode definitions. < Foundation Models ESP_BLE_MESH_MODEL_ID_CONFIG_CLI ESP_BLE_MESH_MODEL_ID_HEALTH_SRV ESP_BLE_MESH_MODEL_ID_HEALTH_CLI Models from the Mesh Model Specification ESP_BLE_MESH_MODEL_ID_GEN_ONOFF_SRV ESP_BLE_MESH_MODEL_ID_GEN_ONOFF_CLI ESP_BLE_MESH_MODEL_ID_GEN_LEVEL_SRV ESP_BLE_MESH_MODEL_ID_GEN_LEVEL_CLI ESP_BLE_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_SRV ESP_BLE_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_CLI ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_SRV ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_SETUP_SRV ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_CLI Espressif Systems 318 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_SRV ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_SETUP_SRV ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_CLI ESP_BLE_MESH_MODEL_ID_GEN_BATTERY_SRV ESP_BLE_MESH_MODEL_ID_GEN_BATTERY_CLI ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_SRV ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_SETUP_SRV ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_CLI ESP_BLE_MESH_MODEL_ID_GEN_ADMIN_PROP_SRV ESP_BLE_MESH_MODEL_ID_GEN_MANUFACTURER_PROP_SRV ESP_BLE_MESH_MODEL_ID_GEN_USER_PROP_SRV ESP_BLE_MESH_MODEL_ID_GEN_CLIENT_PROP_SRV ESP_BLE_MESH_MODEL_ID_GEN_PROP_CLI ESP_BLE_MESH_MODEL_ID_SENSOR_SRV ESP_BLE_MESH_MODEL_ID_SENSOR_SETUP_SRV ESP_BLE_MESH_MODEL_ID_SENSOR_CLI ESP_BLE_MESH_MODEL_ID_TIME_SRV ESP_BLE_MESH_MODEL_ID_TIME_SETUP_SRV ESP_BLE_MESH_MODEL_ID_TIME_CLI ESP_BLE_MESH_MODEL_ID_SCENE_SRV ESP_BLE_MESH_MODEL_ID_SCENE_SETUP_SRV ESP_BLE_MESH_MODEL_ID_SCENE_CLI ESP_BLE_MESH_MODEL_ID_SCHEDULER_SRV ESP_BLE_MESH_MODEL_ID_SCHEDULER_SETUP_SRV ESP_BLE_MESH_MODEL_ID_SCHEDULER_CLI ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_SETUP_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_CLI ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_SETUP_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_CLI ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_TEMP_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SETUP_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_CLI ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_HUE_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SAT_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_SETUP_SRV Espressif Systems 319 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_CLI ESP_BLE_MESH_MODEL_ID_LIGHT_LC_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_LC_SETUP_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_LC_CLI ESP_BLE_MESH_MODEL_OP_BEACON_GET Config Beacon Get ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_GET Config Composition Data Get ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_GET Config Default TTL Get ESP_BLE_MESH_MODEL_OP_GATT_PROXY_GET Config GATT Proxy Get ESP_BLE_MESH_MODEL_OP_RELAY_GET Config Relay Get ESP_BLE_MESH_MODEL_OP_MODEL_PUB_GET Config Model Publication Get ESP_BLE_MESH_MODEL_OP_FRIEND_GET Config Friend Get ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_GET Config Heartbeat Publication Get ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_GET Config Heartbeat Subscription Get ESP_BLE_MESH_MODEL_OP_NET_KEY_GET Config NetKey Get ESP_BLE_MESH_MODEL_OP_APP_KEY_GET Config AppKey Get ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_GET Config Node Identity Get ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_GET Config SIG Model Subscription Get ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_GET Config Vendor Model Subscription Get ESP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_GET Config SIG Model App Get ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_GET Config Vendor Model App Get ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_GET Config Key Refresh Phase Get ESP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_GET Config Low Power Node PollTimeout Get ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_GET Config Network Transmit Get ESP_BLE_MESH_MODEL_OP_BEACON_SET Config Beacon Set ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_SET Config Default TTL Set Espressif Systems 320 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_OP_GATT_PROXY_SET Config GATT Proxy Set ESP_BLE_MESH_MODEL_OP_RELAY_SET Config Relay Set ESP_BLE_MESH_MODEL_OP_MODEL_PUB_SET Config Model Publication Set ESP_BLE_MESH_MODEL_OP_MODEL_SUB_ADD Config Model Subscription Add ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_ADD Config Model Subscription Virtual Address Add ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE Config Model Subscription Delete ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_DELETE Config Model Subscription Virtual Address Delete ESP_BLE_MESH_MODEL_OP_MODEL_SUB_OVERWRITE Config Model Subscription Overwrite ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_OVERWRITE Config Model Subscription Virtual Address Overwrite ESP_BLE_MESH_MODEL_OP_NET_KEY_ADD Config NetKey Add ESP_BLE_MESH_MODEL_OP_APP_KEY_ADD Config AppKey Add ESP_BLE_MESH_MODEL_OP_MODEL_APP_BIND Config Model App Bind ESP_BLE_MESH_MODEL_OP_NODE_RESET Config Node Reset ESP_BLE_MESH_MODEL_OP_FRIEND_SET Config Friend Set ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_SET Config Heartbeat Publication Set ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_SET Config Heartbeat Subscription Set ESP_BLE_MESH_MODEL_OP_NET_KEY_UPDATE Config NetKey Update ESP_BLE_MESH_MODEL_OP_NET_KEY_DELETE Config NetKey Delete ESP_BLE_MESH_MODEL_OP_APP_KEY_UPDATE Config AppKey Update ESP_BLE_MESH_MODEL_OP_APP_KEY_DELETE Config AppKey Delete ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_SET Config Node Identity Set ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_SET Config Key Refresh Phase Set ESP_BLE_MESH_MODEL_OP_MODEL_PUB_VIRTUAL_ADDR_SET Config Model Publication Virtual Address Set Espressif Systems 321 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE_ALL Config Model Subscription Delete All ESP_BLE_MESH_MODEL_OP_MODEL_APP_UNBIND Config Model App Unbind ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_SET Config Network Transmit Set ESP_BLE_MESH_MODEL_OP_BEACON_STATUS ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_STATUS ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_STATUS ESP_BLE_MESH_MODEL_OP_GATT_PROXY_STATUS ESP_BLE_MESH_MODEL_OP_RELAY_STATUS ESP_BLE_MESH_MODEL_OP_MODEL_PUB_STATUS ESP_BLE_MESH_MODEL_OP_MODEL_SUB_STATUS ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_LIST ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_LIST ESP_BLE_MESH_MODEL_OP_NET_KEY_STATUS ESP_BLE_MESH_MODEL_OP_NET_KEY_LIST ESP_BLE_MESH_MODEL_OP_APP_KEY_STATUS ESP_BLE_MESH_MODEL_OP_APP_KEY_LIST ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_STATUS ESP_BLE_MESH_MODEL_OP_MODEL_APP_STATUS ESP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_LIST ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_LIST ESP_BLE_MESH_MODEL_OP_NODE_RESET_STATUS ESP_BLE_MESH_MODEL_OP_FRIEND_STATUS ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_STATUS ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_STATUS ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_STATUS ESP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_STATUS ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_STATUS ESP_BLE_MESH_CFG_STATUS_SUCCESS ESP_BLE_MESH_CFG_STATUS_INVALID_ADDRESS ESP_BLE_MESH_CFG_STATUS_INVALID_MODEL ESP_BLE_MESH_CFG_STATUS_INVALID_APPKEY ESP_BLE_MESH_CFG_STATUS_INVALID_NETKEY ESP_BLE_MESH_CFG_STATUS_INSUFFICIENT_RESOURCES ESP_BLE_MESH_CFG_STATUS_KEY_INDEX_ALREADY_STORED ESP_BLE_MESH_CFG_STATUS_INVALID_PUBLISH_PARAMETERS ESP_BLE_MESH_CFG_STATUS_NOT_A_SUBSCRIBE_MODEL ESP_BLE_MESH_CFG_STATUS_STORAGE_FAILURE Espressif Systems 322 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_CFG_STATUS_FEATURE_NOT_SUPPORTED ESP_BLE_MESH_CFG_STATUS_CANNOT_UPDATE ESP_BLE_MESH_CFG_STATUS_CANNOT_REMOVE ESP_BLE_MESH_CFG_STATUS_CANNOT_BIND ESP_BLE_MESH_CFG_STATUS_TEMP_UNABLE_TO_CHANGE_STATE ESP_BLE_MESH_CFG_STATUS_CANNOT_SET ESP_BLE_MESH_CFG_STATUS_UNSPECIFIED_ERROR ESP_BLE_MESH_CFG_STATUS_INVALID_BINDING ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET Health Fault Get ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_GET Health Period Get ESP_BLE_MESH_MODEL_OP_ATTENTION_GET Health Attention Get ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR Health Fault Clear ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK Health Fault Clear Unacknowledged ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST Health Fault Test ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK Health Fault Test Unacknowledged ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET Health Period Set ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK Health Period Set Unacknowledged ESP_BLE_MESH_MODEL_OP_ATTENTION_SET Health Attention Set ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNACK Health Attention Set Unacknowledged ESP_BLE_MESH_MODEL_OP_HEALTH_CURRENT_STATUS ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_STATUS ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_STATUS ESP_BLE_MESH_MODEL_OP_ATTENTION_STATUS ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_GET ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_STATUS Generic Level Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_GET ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_STATUS Espressif Systems 323 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET_UNACK Generic Default Transition Time Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_GET ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_STATUS Generic Power OnOff Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_GET ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_STATUS Generic Power OnOff Setup Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET_UNACK Generic Power Level Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_GET ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_STATUS ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_GET ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_STATUS ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_GET ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_STATUS ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_GET ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_STATUS Generic Power Level Setup Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET_UNACK Generic Battery Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_GET ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_STATUS Generic Location Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_GET ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_STATUS ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_GET ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_STATUS Generic Location Setup Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET_UNACK Espressif Systems 324 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET_UNACK Generic Manufacturer Property Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES_GET ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES_STATUS ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_GET ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_STATUS Generic Admin Property Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_GET ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_STATUS ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_GET ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_STATUS Generic User Property Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIES_GET ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIES_STATUS ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_GET ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET_UNACK ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_STATUS Generic Client Property Message Opcode ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_GET ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_STATUS ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_GET ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_STATUS ESP_BLE_MESH_MODEL_OP_SENSOR_GET ESP_BLE_MESH_MODEL_OP_SENSOR_STATUS ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_GET ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_STATUS ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_GET ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_STATUS Sensor Setup Message Opcode ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_GET ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET_UNACK ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_STATUS ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_GET ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_STATUS Espressif Systems 325 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_GET ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET_UNACK ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_STATUS ESP_BLE_MESH_MODEL_OP_TIME_GET ESP_BLE_MESH_MODEL_OP_TIME_SET ESP_BLE_MESH_MODEL_OP_TIME_STATUS ESP_BLE_MESH_MODEL_OP_TIME_ROLE_GET ESP_BLE_MESH_MODEL_OP_TIME_ROLE_SET ESP_BLE_MESH_MODEL_OP_TIME_ROLE_STATUS ESP_BLE_MESH_MODEL_OP_TIME_ZONE_GET ESP_BLE_MESH_MODEL_OP_TIME_ZONE_SET ESP_BLE_MESH_MODEL_OP_TIME_ZONE_STATUS ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_GET ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_SET ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_STATUS Scene Message Opcode ESP_BLE_MESH_MODEL_OP_SCENE_GET ESP_BLE_MESH_MODEL_OP_SCENE_RECALL ESP_BLE_MESH_MODEL_OP_SCENE_RECALL_UNACK ESP_BLE_MESH_MODEL_OP_SCENE_STATUS ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_GET ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_STATUS Scene Setup Message Opcode ESP_BLE_MESH_MODEL_OP_SCENE_STORE ESP_BLE_MESH_MODEL_OP_SCENE_STORE_UNACK ESP_BLE_MESH_MODEL_OP_SCENE_DELETE ESP_BLE_MESH_MODEL_OP_SCENE_DELETE_UNACK Scheduler Message Opcode ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_GET ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_STATUS ESP_BLE_MESH_MODEL_OP_SCHEDULER_GET ESP_BLE_MESH_MODEL_OP_SCHEDULER_STATUS Scheduler Setup Message Opcode ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_GET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_STATUS Espressif Systems 326 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_GET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LAST_GET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LAST_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_GET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_GET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_STATUS Light Lightness Setup Message Opcode ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET_UNACK Light CTL Message Opcode ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_GET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_GET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_GET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_GET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_STATUS Light CTL Setup Message Opcode ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET_UNACK Light HSL Message Opcode ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_GET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_GET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_GET Espressif Systems 327 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_GET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_GET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_GET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_STATUS Light HSL Setup Message Opcode ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET_UNACK Light xyL Message Opcode ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_GET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_GET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_GET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_GET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_STATUS Light xyL Setup Message Opcode ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET_UNACK Light Control Message Opcode ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_GET ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET_UNACK ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_GET ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET Espressif Systems 328 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 329 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 330 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_TYPE_LINK_CLOSE_CB ESP_BLE_MESH_TYPE_COMPLETE_CB ESP_BLE_MESH_TYPE_RESET_CB enum esp_ble_mesh_oob_method_t Values: ESP_BLE_MESH_NO_OOB ESP_BLE_MESH_STATIC_OOB ESP_BLE_MESH_OUTPUT_OOB ESP_BLE_MESH_INPUT_OOB enum esp_ble_mesh_output_action_t Values: ESP_BLE_MESH_NO_OUTPUT = 0 ESP_BLE_MESH_BLINK = BIT(0) ESP_BLE_MESH_BEEP = BIT(1) ESP_BLE_MESH_VIBRATE = BIT(2) ESP_BLE_MESH_DISPLAY_NUMBER = BIT(3) ESP_BLE_MESH_DISPLAY_STRING = BIT(4) enum esp_ble_mesh_input_action_t Values: ESP_BLE_MESH_NO_INPUT = 0 ESP_BLE_MESH_PUSH = BIT(0) ESP_BLE_MESH_TWIST = BIT(1) ESP_BLE_MESH_ENTER_NUMBER = BIT(2) ESP_BLE_MESH_ENTER_STRING = BIT(3) enum esp_ble_mesh_prov_bearer_t Values: ESP_BLE_MESH_PROV_ADV = BIT(0) ESP_BLE_MESH_PROV_GATT = BIT(1) enum esp_ble_mesh_prov_oob_info_t Values: ESP_BLE_MESH_PROV_OOB_OTHER = BIT(0) ESP_BLE_MESH_PROV_OOB_URI = BIT(1) ESP_BLE_MESH_PROV_OOB_2D_CODE = BIT(2) ESP_BLE_MESH_PROV_OOB_BAR_CODE = BIT(3) ESP_BLE_MESH_PROV_OOB_NFC = BIT(4) ESP_BLE_MESH_PROV_OOB_NUMBER = BIT(5) ESP_BLE_MESH_PROV_OOB_STRING = BIT(6) ESP_BLE_MESH_PROV_OOB_ON_BOX = BIT(11) ESP_BLE_MESH_PROV_OOB_IN_BOX = BIT(12) ESP_BLE_MESH_PROV_OOB_ON_PAPER = BIT(13) ESP_BLE_MESH_PROV_OOB_IN_MANUAL = BIT(14) Espressif Systems 331 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_PROV_OOB_ON_DEV = BIT(15) enum esp_ble_mesh_dev_role_t Values: ROLE_NODE = 0 ROLE_PROVISIONER ROLE_FAST_PROV enum esp_ble_mesh_fast_prov_action_t Values: FAST_PROV_ACT_NONE FAST_PROV_ACT_ENTER FAST_PROV_ACT_SUSPEND FAST_PROV_ACT_EXIT FAST_PROV_ACT_MAX enum esp_ble_mesh_proxy_filter_type_t Values: PROXY_FILTER_WHITELIST PROXY_FILTER_BLACKLIST enum esp_ble_mesh_prov_cb_event_t Values: ESP_BLE_MESH_PROV_REGISTER_COMP_EVT Initialize BLE Mesh provisioning capabilities and internal data information completion event ESP_BLE_MESH_NODE_SET_UNPROV_DEV_NAME_COMP_EVT Set the unprovisioned device name completion event ESP_BLE_MESH_NODE_PROV_ENABLE_COMP_EVT Enable node provisioning functionality completion event ESP_BLE_MESH_NODE_PROV_DISABLE_COMP_EVT Disable node provisioning functionality completion event ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT Establish a BLE Mesh link event ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT Close a BLE Mesh link event ESP_BLE_MESH_NODE_PROV_OOB_PUB_KEY_EVT Generate Node input OOB public key event ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVT Generate Node Output Number event ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVT Generate Node Output String event ESP_BLE_MESH_NODE_PROV_INPUT_EVT Event requiring the user to input a number or string ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT Provisioning done event ESP_BLE_MESH_NODE_PROV_RESET_EVT Provisioning reset event ESP_BLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EVT Node set oob public key completion event Espressif Systems 332 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 333 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_PROVISIONER_SET_PRIMARY_ELEM_ADDR_COMP_EVT Provisioner set unicast address of primary element completion event ESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_COMP_EVT Provisioner read unprovisioned device OOB public key completion event ESP_BLE_MESH_PROVISIONER_PROV_INPUT_NUMBER_COMP_EVT Provisioner input number completion event ESP_BLE_MESH_PROVISIONER_PROV_INPUT_STRING_COMP_EVT Provisioner input string completion event ESP_BLE_MESH_PROVISIONER_SET_NODE_NAME_COMP_EVT Provisioner set node name completion event ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_APP_KEY_COMP_EVT Provisioner add local app key completion event ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_APP_KEY_COMP_EVT Provisioner update local app key completion event ESP_BLE_MESH_PROVISIONER_BIND_APP_KEY_TO_MODEL_COMP_EVT Provisioner bind local model with local app key completion event ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_NET_KEY_COMP_EVT Provisioner add local network key completion event ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_NET_KEY_COMP_EVT Provisioner update local network key completion event ESP_BLE_MESH_PROVISIONER_STORE_NODE_COMP_DATA_COMP_EVT Provisioner store node composition data completion event ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_UUID_COMP_EVT Provisioner delete node with uuid completion event ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_ADDR_COMP_EVT Provisioner delete node with unicast address completion event ESP_BLE_MESH_PROVISIONER_ENABLE_HEARTBEAT_RECV_COMP_EVT Provisioner start to receive heartbeat message completion event ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_TYPE_COMP_EVT Provisioner set the heartbeat filter type completion event ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_INFO_COMP_EVT Provisioner set the heartbeat filter information completion event ESP_BLE_MESH_PROVISIONER_RECV_HEARTBEAT_MESSAGE_EVT Provisioner receive heartbeat message event ESP_BLE_MESH_PROVISIONER_DRIECT_ERASE_SETTINGS_COMP_EVT Provisioner directly erase settings completion event ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_INDEX_COMP_EVT Provisioner open settings with index completion event ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_WITH_UID_COMP_EVT Provisioner open settings with user id completion event ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDEX_COMP_EVT Provisioner close settings with index completion event ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_COMP_EVT Provisioner close settings with user id completion event ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_INDEX_COMP_EVT Provisioner delete settings with index completion event Espressif Systems 334 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_UID_COMP_EVT Provisioner delete settings with user id completion event ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT Set fast provisioning information (e.g. unicast address range, net_idx, etc.) completion event ESP_BLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT Set fast provisioning action completion event ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT Receive Heartbeat message event ESP_BLE_MESH_LPN_ENABLE_COMP_EVT Enable Low Power Node completion event ESP_BLE_MESH_LPN_DISABLE_COMP_EVT Disable Low Power Node completion event ESP_BLE_MESH_LPN_POLL_COMP_EVT Low Power Node send Friend Poll completion event ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT Low Power Node establishes friendship event ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT Low Power Node terminates friendship event ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT Friend Node establishes friendship event ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT Friend Node terminates friendship event ESP_BLE_MESH_PROXY_CLIENT_RECV_ADV_PKT_EVT Proxy Client receives Network ID advertising packet event ESP_BLE_MESH_PROXY_CLIENT_CONNECTED_EVT Proxy Client establishes connection successfully event ESP_BLE_MESH_PROXY_CLIENT_DISCONNECTED_EVT Proxy Client terminates connection successfully event ESP_BLE_MESH_PROXY_CLIENT_RECV_FILTER_STATUS_EVT Proxy Client receives Proxy Filter Status event ESP_BLE_MESH_PROXY_CLIENT_CONNECT_COMP_EVT Proxy Client connect completion event ESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT Proxy Client disconnect completion event ESP_BLE_MESH_PROXY_CLIENT_SET_FILTER_TYPE_COMP_EVT Proxy Client set filter type completion event ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP_EVT Proxy Client add filter address completion event ESP_BLE_MESH_PROXY_CLIENT_REMOVE_FILTER_ADDR_COMP_EVT Proxy Client remove filter address completion event ESP_BLE_MESH_PROXY_SERVER_CONNECTED_EVT Proxy Server establishes connection successfully event ESP_BLE_MESH_PROXY_SERVER_DISCONNECTED_EVT Proxy Server terminates connection successfully event ESP_BLE_MESH_MODEL_SUBSCRIBE_GROUP_ADDR_COMP_EVT Local model subscribes group address completion event Espressif Systems 335 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADDR_COMP_EVT Local model unsubscribes group address completion event ESP_BLE_MESH_DEINIT_MESH_COMP_EVT De-initialize BLE Mesh stack completion event ESP_BLE_MESH_PROV_EVT_MAX enum [anonymous] BLE Mesh server models related definitions. This enum value is the flag of transition timer operation Values: ESP_BLE_MESH_SERVER_TRANS_TIMER_START ESP_BLE_MESH_SERVER_FLAG_MAX enum esp_ble_mesh_server_state_type_t This enum value is the type of server model states Values: ESP_BLE_MESH_GENERIC_ONOFF_STATE ESP_BLE_MESH_GENERIC_LEVEL_STATE ESP_BLE_MESH_GENERIC_ONPOWERUP_STATE ESP_BLE_MESH_GENERIC_POWER_ACTUAL_STATE ESP_BLE_MESH_LIGHT_LIGHTNESS_ACTUAL_STATE ESP_BLE_MESH_LIGHT_LIGHTNESS_LINEAR_STATE ESP_BLE_MESH_LIGHT_CTL_LIGHTNESS_STATE ESP_BLE_MESH_LIGHT_CTL_TEMP_DELTA_UV_STATE ESP_BLE_MESH_LIGHT_HSL_STATE ESP_BLE_MESH_LIGHT_HSL_LIGHTNESS_STATE ESP_BLE_MESH_LIGHT_HSL_HUE_STATE ESP_BLE_MESH_LIGHT_HSL_SATURATION_STATE ESP_BLE_MESH_LIGHT_XYL_LIGHTNESS_STATE ESP_BLE_MESH_LIGHT_LC_LIGHT_ONOFF_STATE ESP_BLE_MESH_SERVER_MODEL_STATE_MAX enum esp_ble_mesh_model_cb_event_t Values: ESP_BLE_MESH_MODEL_OPERATION_EVT User-defined models receive messages from peer devices (e.g. get, set, status, etc) event ESP_BLE_MESH_MODEL_SEND_COMP_EVT User-defined models send messages completion event ESP_BLE_MESH_MODEL_PUBLISH_COMP_EVT User-defined models publish messages completion event ESP_BLE_MESH_CLIENT_MODEL_RECV_PUBLISH_MSG_EVT User-defined client models receive publish messages event ESP_BLE_MESH_CLIENT_MODEL_SEND_TIMEOUT_EVT Timeout event for the user-defined client models that failed to receive response from peer server models Espressif Systems 336 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 Header File · components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h Espressif Systems 337 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Functions int32_t esp_ble_mesh_get_model_publish_period(esp_ble_mesh_model_t *model) Get the model publish period, the unit is ms. Return Publish period value on success, 0 or (negative) error code from errno.h on failure. Parameters · [in] model: Model instance pointer. uint16_t esp_ble_mesh_get_primary_element_address(void) Get the address of the primary element. Return Address of the primary element on success, or ESP_BLE_MESH_ADDR_UNASSIGNED on failure which means the device has not been provisioned. uint16_t *esp_ble_mesh_is_model_subscribed_to_group(esp_ble_mesh_model_t *model, uint16_t group_addr) Check if the model has subscribed to the given group address. Note: E.g., once a status message is received and the destination address is a group address, the model uses this API to check if it is successfully subscribed to the given group address. Return Pointer to the group address within the Subscription List of the model on success, or NULL on failure which means the model has not subscribed to the given group address. Note: With the pointer to the group address returned, you can reset the group address to 0x0000 in order to unsubscribe the model from the group. Parameters · [in] model: Pointer to the model. · [in] group_addr: Group address. esp_ble_mesh_elem_t *esp_ble_mesh_find_element(uint16_t element_addr) Find the BLE Mesh element pointer via the element address. Return Pointer to the element on success, or NULL on failure. Parameters · [in] element_addr: Element address. uint8_t esp_ble_mesh_get_element_count(void) Get the number of elements that have been registered. Return Number of elements. esp_ble_mesh_model_t *esp_ble_mesh_find_vendor_model(const esp_ble_mesh_elem_t *element, uint16_t company_id, uint16_t model_id) Find the Vendor specific model with the given element, the company ID and the Vendor Model ID. Return Pointer to the Vendor Model on success, or NULL on failure which means the Vendor Model is not found. Parameters · [in] element: Element to which the model belongs. · [in] company_id: A 16-bit company identifier assigned by the Bluetooth SIG. · [in] model_id: A 16-bit vendor-assigned model identifier. esp_ble_mesh_model_t *esp_ble_mesh_find_sig_model(const esp_ble_mesh_elem_t *element, uint16_t model_id) Find the SIG model with the given element and Model id. Return Pointer to the SIG Model on success, or NULL on failure which means the SIG Model is not found. Parameters · [in] element: Element to which the model belongs. · [in] model_id: SIG model identifier. const esp_ble_mesh_comp_t *esp_ble_mesh_get_composition_data(void) Get the Composition data which has been registered. Return Pointer to the Composition data on success, or NULL on failure which means the Composition data is not initialized. Espressif Systems 338 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · [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) Espressif Systems 339 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 esp_err_t esp_ble_mesh_register_custom_model_callback(esp_ble_mesh_model_cb_t call- back) Register BLE Mesh callback for user-defined 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; Espressif Systems 340 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 341 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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 · [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. Espressif Systems 342 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 < 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 Espressif Systems 343 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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. Espressif Systems 344 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · 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 Espressif Systems 345 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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, 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. Espressif Systems 346 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 347 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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. 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 Espressif Systems 348 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 349 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 350 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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. esp_err_t esp_ble_mesh_provisioner_set_primary_elem_addr(uint16_t addr) This function is called by Provisioner to set own Primary element address. Note This API must be invoked when BLE Mesh initialization is completed successfully, and can be invoked before Provisioner functionality is enabled. Once this API is invoked successfully, the prov_unicast_addr value in the struct esp_ble_mesh_prov_t will be ignored, and Provisioner will use this address as its own Espressif Systems 351 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Note This API requires that GATT Proxy support be enabled. Once called, each subnet starts advertising using Node Identity for the next 60 seconds, and after 60s Network ID will be advertised. Under normal conditions, the BLE Mesh Proxy Node Identity and Network ID advertising will be enabled automatically by BLE Mesh stack after the device is provisioned. Return ESP_OK on success or error code otherwise. esp_err_t esp_ble_mesh_proxy_gatt_enable(void) Enable BLE Mesh GATT Proxy Service. Espressif Systems 352 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return ESP_OK on success or error code otherwise. esp_err_t esp_ble_mesh_proxy_gatt_disable(void) Disconnect the BLE Mesh GATT Proxy connection if there is any, and disable the BLE Mesh GATT Proxy Service. Return ESP_OK on success or error code otherwise. esp_err_t esp_ble_mesh_proxy_client_connect(esp_ble_mesh_bd_addr_t addr, esp_ble_mesh_addr_type_t addr_type, uint16_t net_idx) Proxy Client creates a connection with the Proxy Server. Return ESP_OK on success or error code otherwise. Parameters · [in] addr: Device address of the Proxy Server. · [in] addr_type: Device address type(public or static random). · [in] net_idx: NetKey Index related with Network ID in the Mesh Proxy advertising packet. esp_err_t esp_ble_mesh_proxy_client_disconnect(uint8_t conn_handle) Proxy Client terminates a connection with the Proxy Server. Return ESP_OK on success or error code otherwise. Parameters · [in] conn_handle: Proxy connection handle. esp_err_t esp_ble_mesh_proxy_client_set_filter_type(uint8_t conn_handle, uint16_t net_idx, esp_ble_mesh_proxy_filter_type_t filter_type) Proxy Client sets the filter type of the Proxy Server. Return ESP_OK on success or error code otherwise. Parameters · [in] conn_handle: Proxy connection handle. · [in] net_idx: Corresponding NetKey Index. · [in] filter_type: whitelist or blacklist. esp_err_t esp_ble_mesh_proxy_client_add_filter_addr(uint8_t conn_handle, uint16_t net_idx, uint16_t *addr, uint16_t 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 · [in] conn_handle: Proxy connection handle. · [in] net_idx: Corresponding NetKey Index. · [in] addr: Pointer to the filter address. · [in] addr_num: Number of the filter address. Espressif Systems 353 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP-BLE-MESH Models API Reference This section contains ESP-BLE-MESH Model related APIs, event types, event parameters, etc. There are six categories of models: · Configuration Client/Server Models · Health Client/Server Models · Generic Client/Server Models · Sensor Client/Server Models · Time and Scenes Client/Server Models · Lighting Client/Server Models Note: Definitions related to Server Models are being updated, and will be released soon. Configuration Client/Server Models Header File · components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_config_model_api.h Functions esp_err_t esp_ble_mesh_register_config_client_callback(esp_ble_mesh_cfg_client_cb_t 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. Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to esp_ble_mesh_opcode_config_client_set_t in esp_ble_mesh_defs.h Return ESP_OK on success or error code otherwise. Parameters · [in] params: Pointer to BLE Mesh common client parameters. Espressif Systems 354 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [in] set_state: Pointer to a union, each kind of opcode corresponds to one structure inside. Shall not be set to NULL. Unions union esp_ble_mesh_cfg_client_get_state_t #include <esp_ble_mesh_config_model_api.h> For ESP_BLE_MESH_MODEL_OP_BEACON_GET ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_GET ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_GET ESP_BLE_MESH_MODEL_OP_GATT_PROXY_GET ESP_BLE_MESH_MODEL_OP_RELAY_GET ESP_BLE_MESH_MODEL_OP_MODEL_PUB_GET ESP_BLE_MESH_MODEL_OP_FRIEND_GET ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_GET ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_GET the get_state parameter in the esp_ble_mesh_config_client_get_state function should not be set to NULL. Public Members esp_ble_mesh_cfg_model_pub_get_t model_pub_get For ESP_BLE_MESH_MODEL_OP_MODEL_PUB_GET. esp_ble_mesh_cfg_composition_data_get_t comp_data_get For ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_GET. esp_ble_mesh_cfg_sig_model_sub_get_t sig_model_sub_get For ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_GET esp_ble_mesh_cfg_vnd_model_sub_get_t vnd_model_sub_get For ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_GET esp_ble_mesh_cfg_app_key_get_t app_key_get For ESP_BLE_MESH_MODEL_OP_APP_KEY_GET. esp_ble_mesh_cfg_node_identity_get_t node_identity_get For ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_GET. esp_ble_mesh_cfg_sig_model_app_get_t sig_model_app_get For ESP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_GET esp_ble_mesh_cfg_vnd_model_app_get_t vnd_model_app_get For ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_GET esp_ble_mesh_cfg_kr_phase_get_t kr_phase_get For ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_GET esp_ble_mesh_cfg_lpn_polltimeout_get_t lpn_pollto_get For ESP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_GET union esp_ble_mesh_cfg_client_set_state_t #include <esp_ble_mesh_config_model_api.h> For ESP_BLE_MESH_MODEL_OP_BEACON_SET ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_SET ESP_BLE_MESH_MODEL_OP_GATT_PROXY_SET ESP_BLE_MESH_MODEL_OP_RELAY_SET ESP_BLE_MESH_MODEL_OP_MODEL_PUB_SET ESP_BLE_MESH_MODEL_OP_MODEL_SUB_ADD ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_AD ESP_BLE_MESH_MODEL_OP_MODEL_SUB_OVERWRITE ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL ESP_BLE_MESH_MODEL_OP_NET_KEY_ADD ESP_BLE_MESH_MODEL_OP_APP_KEY_ADD ESP_BLE_MESH_MODEL_OP_MODEL_APP_BIND ESP_BLE_MESH_MODEL_OP_NODE_RESET ESP_BLE_MESH_MODEL_OP_FRIEND_SET ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_SET ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_SET the set_state parameter in the esp_ble_mesh_config_client_set_state function should not be set to NULL. Public Members esp_ble_mesh_cfg_beacon_set_t beacon_set For ESP_BLE_MESH_MODEL_OP_BEACON_SET Espressif Systems 355 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_cfg_default_ttl_set_t default_ttl_set For ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_SET esp_ble_mesh_cfg_friend_set_t friend_set For ESP_BLE_MESH_MODEL_OP_FRIEND_SET esp_ble_mesh_cfg_gatt_proxy_set_t gatt_proxy_set For ESP_BLE_MESH_MODEL_OP_GATT_PROXY_SET esp_ble_mesh_cfg_relay_set_t relay_set For ESP_BLE_MESH_MODEL_OP_RELAY_SET esp_ble_mesh_cfg_net_key_add_t net_key_add For ESP_BLE_MESH_MODEL_OP_NET_KEY_ADD esp_ble_mesh_cfg_app_key_add_t app_key_add For ESP_BLE_MESH_MODEL_OP_APP_KEY_ADD esp_ble_mesh_cfg_model_app_bind_t model_app_bind For ESP_BLE_MESH_MODEL_OP_MODEL_APP_BIND esp_ble_mesh_cfg_model_pub_set_t model_pub_set For ESP_BLE_MESH_MODEL_OP_MODEL_PUB_SET esp_ble_mesh_cfg_model_sub_add_t model_sub_add For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_ADD esp_ble_mesh_cfg_model_sub_delete_t model_sub_delete For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE esp_ble_mesh_cfg_model_sub_overwrite_t model_sub_overwrite For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_OVERWRITE esp_ble_mesh_cfg_model_sub_va_add_t model_sub_va_add For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_ADD esp_ble_mesh_cfg_model_sub_va_delete_t model_sub_va_delete For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_DELETE esp_ble_mesh_cfg_model_sub_va_overwrite_t model_sub_va_overwrite For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_OVERWRITE esp_ble_mesh_cfg_heartbeat_pub_set_t heartbeat_pub_set For ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_SET esp_ble_mesh_cfg_heartbeat_sub_set_t heartbeat_sub_set For ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_SET esp_ble_mesh_cfg_model_pub_va_set_t model_pub_va_set For ESP_BLE_MESH_MODEL_OP_MODEL_PUB_VIRTUAL_ADDR_SET esp_ble_mesh_cfg_model_sub_delete_all_t model_sub_delete_all For ESP_BLE_MESH_MODEL_OP_MODEL_SUB_DELETE_ALL esp_ble_mesh_cfg_net_key_update_t net_key_update For ESP_BLE_MESH_MODEL_OP_NET_KEY_UPDATE esp_ble_mesh_cfg_net_key_delete_t net_key_delete For ESP_BLE_MESH_MODEL_OP_NET_KEY_DELETE esp_ble_mesh_cfg_app_key_update_t app_key_update For ESP_BLE_MESH_MODEL_OP_APP_KEY_UPDATE esp_ble_mesh_cfg_app_key_delete_t app_key_delete For ESP_BLE_MESH_MODEL_OP_APP_KEY_DELETE esp_ble_mesh_cfg_node_identity_set_t node_identity_set For ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_SET Espressif Systems 356 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_cfg_model_app_unbind_t model_app_unbind For ESP_BLE_MESH_MODEL_OP_MODEL_APP_UNBIND esp_ble_mesh_cfg_kr_phase_set_t kr_phase_set For ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASE_SET esp_ble_mesh_cfg_net_transmit_set_t net_transmit_set For ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_SET union esp_ble_mesh_cfg_client_common_cb_param_t #include <esp_ble_mesh_config_model_api.h> Configuration Client Model received message union. Public Members esp_ble_mesh_cfg_beacon_status_cb_t beacon_status The beacon status value esp_ble_mesh_cfg_comp_data_status_cb_t comp_data_status The composition data status value esp_ble_mesh_cfg_default_ttl_status_cb_t default_ttl_status The default_ttl status value esp_ble_mesh_cfg_gatt_proxy_status_cb_t gatt_proxy_status The gatt_proxy status value esp_ble_mesh_cfg_relay_status_cb_t relay_status The relay status value esp_ble_mesh_cfg_model_pub_status_cb_t model_pub_status The model publication status value esp_ble_mesh_cfg_model_sub_status_cb_t model_sub_status The model subscription status value esp_ble_mesh_cfg_net_key_status_cb_t netkey_status The netkey status value esp_ble_mesh_cfg_app_key_status_cb_t appkey_status The appkey status value esp_ble_mesh_cfg_mod_app_status_cb_t model_app_status The model app status value esp_ble_mesh_cfg_friend_status_cb_t friend_status The friend status value esp_ble_mesh_cfg_hb_pub_status_cb_t heartbeat_pub_status The heartbeat publication status value esp_ble_mesh_cfg_hb_sub_status_cb_t heartbeat_sub_status The heartbeat subscription status value esp_ble_mesh_cfg_net_trans_status_cb_t net_transmit_status The network transmit status value esp_ble_mesh_cfg_model_sub_list_cb_t model_sub_list The model subscription list value esp_ble_mesh_cfg_net_key_list_cb_t netkey_list The network key index list value esp_ble_mesh_cfg_app_key_list_cb_t appkey_list The application key index list value esp_ble_mesh_cfg_node_id_status_cb_t node_identity_status The node identity status value Espressif Systems 357 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_cfg_model_app_list_cb_t model_app_list The model application key index list value esp_ble_mesh_cfg_kr_phase_status_cb_t kr_phase_status The key refresh phase status value esp_ble_mesh_cfg_lpn_pollto_status_cb_t lpn_timeout_status The low power node poll timeout status value union esp_ble_mesh_cfg_server_state_change_t #include <esp_ble_mesh_config_model_api.h> Configuration Server model state change value union. Public Members esp_ble_mesh_state_change_cfg_mod_pub_set_t mod_pub_set The recv_op in ctx can be used to decide which state is changed. Config Model Publication Set esp_ble_mesh_state_change_cfg_model_sub_add_t mod_sub_add Config Model Subscription Add esp_ble_mesh_state_change_cfg_model_sub_delete_t mod_sub_delete Config Model Subscription Delete esp_ble_mesh_state_change_cfg_netkey_add_t netkey_add Config NetKey Add esp_ble_mesh_state_change_cfg_netkey_update_t netkey_update Config NetKey Update esp_ble_mesh_state_change_cfg_netkey_delete_t netkey_delete Config NetKey Delete esp_ble_mesh_state_change_cfg_appkey_add_t appkey_add Config AppKey Add esp_ble_mesh_state_change_cfg_appkey_update_t appkey_update Config AppKey Update esp_ble_mesh_state_change_cfg_appkey_delete_t appkey_delete Config AppKey Delete esp_ble_mesh_state_change_cfg_model_app_bind_t mod_app_bind Config Model App Bind esp_ble_mesh_state_change_cfg_model_app_unbind_t mod_app_unbind Config Model App Unbind esp_ble_mesh_state_change_cfg_kr_phase_set_t kr_phase_set Config Key Refresh Phase Set union esp_ble_mesh_cfg_server_cb_value_t #include <esp_ble_mesh_config_model_api.h> Configuration Server model callback value union. Public Members esp_ble_mesh_cfg_server_state_change_t state_change ESP_BLE_MESH_CFG_SERVER_STATE_CHANGE_EVT Structures struct esp_ble_mesh_cfg_srv Configuration Server Model context Espressif Systems 358 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_model_t *model Pointer to Configuration Server Model uint8_t net_transmit Network Transmit state uint8_t relay Relay Mode state uint8_t relay_retransmit Relay Retransmit state uint8_t beacon Secure Network Beacon state uint8_t gatt_proxy GATT Proxy state uint8_t friend_state Friend state uint8_t default_ttl Default TTL struct k_delayed_work timer Heartbeat Publication timer uint16_t dst Destination address for Heartbeat messages uint16_t count Number of Heartbeat messages to be sent Number of Heartbeat messages received uint8_t period Period for sending Heartbeat messages uint8_t ttl TTL to be used when sending Heartbeat messages uint16_t feature Bit field indicating features that trigger Heartbeat messages when changed uint16_t net_idx NetKey Index used by Heartbeat Publication struct esp_ble_mesh_cfg_srv::[anonymous] heartbeat_pub Heartbeat Publication int64_t expiry Timestamp when Heartbeat subscription period is expired uint16_t src Source address for Heartbeat messages uint8_t min_hops Minimum hops when receiving Heartbeat messages uint8_t max_hops Maximum hops when receiving Heartbeat messages esp_ble_mesh_cb_t heartbeat_recv_cb Optional heartbeat subscription tracking function struct esp_ble_mesh_cfg_srv::[anonymous] heartbeat_sub Heartbeat Subscription Espressif Systems 359 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_cfg_composition_data_get_t Parameters of Config Composition Data Get. Public Members uint8_t page Page number of the Composition Data. struct esp_ble_mesh_cfg_model_pub_get_t Parameters of Config Model Publication Get. Public Members uint16_t element_addr The element address uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_sig_model_sub_get_t Parameters of Config SIG Model Subscription Get. Public Members uint16_t element_addr The element address uint16_t model_id The model id struct esp_ble_mesh_cfg_vnd_model_sub_get_t Parameters of Config Vendor Model Subscription Get. Public Members uint16_t element_addr The element address uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_app_key_get_t Parameters of Config AppKey Get. Public Members uint16_t net_idx The network key index struct esp_ble_mesh_cfg_node_identity_get_t Parameters of Config Node Identity Get. Espressif Systems 360 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t net_idx The network key index struct esp_ble_mesh_cfg_sig_model_app_get_t Parameters of Config SIG Model App Get. Public Members uint16_t element_addr The element address uint16_t model_id The model id struct esp_ble_mesh_cfg_vnd_model_app_get_t Parameters of Config Vendor Model App Get. Public Members uint16_t element_addr The element address uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_kr_phase_get_t Parameters of Config Key Refresh Phase Get. Public Members uint16_t net_idx The network key index struct esp_ble_mesh_cfg_lpn_polltimeout_get_t Parameters of Config Low Power Node PollTimeout Get. Public Members uint16_t lpn_addr The unicast address of the Low Power node struct esp_ble_mesh_cfg_beacon_set_t Parameters of Config Beacon Set. Public Members uint8_t beacon New Secure Network Beacon state struct esp_ble_mesh_cfg_default_ttl_set_t Parameters of Config Default TTL Set. Espressif Systems 361 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t ttl The default TTL state value struct esp_ble_mesh_cfg_friend_set_t Parameters of Config Friend Set. Public Members uint8_t friend_state The friend state value struct esp_ble_mesh_cfg_gatt_proxy_set_t Parameters of Config GATT Proxy Set. Public Members uint8_t gatt_proxy The GATT Proxy state value struct esp_ble_mesh_cfg_relay_set_t Parameters of Config Relay Set. Public Members uint8_t relay The relay value uint8_t relay_retransmit The relay retransmit value struct esp_ble_mesh_cfg_net_key_add_t Parameters of Config NetKey Add. Public Members uint16_t net_idx The network key index uint8_t net_key[16] The network key value struct esp_ble_mesh_cfg_app_key_add_t Parameters of Config AppKey Add. Public Members uint16_t net_idx The network key index uint16_t app_idx The app key index uint8_t app_key[16] The app key value struct esp_ble_mesh_cfg_model_app_bind_t Parameters of Config Model App Bind. Espressif Systems 362 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t element_addr The element address uint16_t model_app_idx Index of the app key to bind with the model uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_pub_set_t Parameters of Config Model Publication Set. Public Members uint16_t element_addr The element address uint16_t publish_addr Value of the publish address uint16_t publish_app_idx Index of the application key bool cred_flag Value of the Friendship Credential Flag uint8_t publish_ttl Default TTL value for the publishing messages uint8_t publish_period Period for periodic status publishing uint8_t publish_retransmit Number of retransmissions and number of 50-millisecond steps between retransmissions uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_sub_add_t Parameters of Config Model Subscription Add. Public Members uint16_t element_addr The element address uint16_t sub_addr The address to be added to the Subscription List uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_sub_delete_t Parameters of Config Model Subscription Delete. Espressif Systems 363 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t element_addr The element address uint16_t sub_addr The address to be removed from the Subscription List uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_sub_overwrite_t Parameters of Config Model Subscription Overwrite. Public Members uint16_t element_addr The element address uint16_t sub_addr The address to be added to the Subscription List uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_sub_va_add_t Parameters of Config Model Subscription Virtual Address Add. Public Members uint16_t element_addr The element address uint8_t label_uuid[16] The Label UUID of the virtual address to be added to the Subscription List uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_sub_va_delete_t Parameters of Config Model Subscription Virtual Address Delete. Public Members uint16_t element_addr The element address uint8_t label_uuid[16] The Label UUID of the virtual address to be removed from the Subscription List uint16_t model_id The model id Espressif Systems 364 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_sub_va_overwrite_t Parameters of Config Model Subscription Virtual Address Overwrite. Public Members uint16_t element_addr The element address uint8_t label_uuid[16] The Label UUID of the virtual address to be added to the Subscription List uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_pub_va_set_t Parameters of Config Model Publication Virtual Address Set. Public Members uint16_t element_addr The element address uint8_t label_uuid[16] Value of the Label UUID publish address uint16_t publish_app_idx Index of the application key bool cred_flag Value of the Friendship Credential Flag uint8_t publish_ttl Default TTL value for the publishing messages uint8_t publish_period Period for periodic status publishing uint8_t publish_retransmit Number of retransmissions and number of 50-millisecond steps between retransmissions uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_model_sub_delete_all_t Parameters of Config Model Subscription Delete All. Public Members uint16_t element_addr The element address uint16_t model_id The model id Espressif Systems 365 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_net_key_update_t Parameters of Config NetKey Update. Public Members uint16_t net_idx The network key index uint8_t net_key[16] The network key value struct esp_ble_mesh_cfg_net_key_delete_t Parameters of Config NetKey Delete. Public Members uint16_t net_idx The network key index struct esp_ble_mesh_cfg_app_key_update_t Parameters of Config AppKey Update. Public Members uint16_t net_idx The network key index uint16_t app_idx The app key index uint8_t app_key[16] The app key value struct esp_ble_mesh_cfg_app_key_delete_t Parameters of Config AppKey Delete. Public Members uint16_t net_idx The network key index uint16_t app_idx The app key index struct esp_ble_mesh_cfg_node_identity_set_t Parameters of Config Node Identity Set. Public Members uint16_t net_idx The network key index uint8_t identity New Node Identity state struct esp_ble_mesh_cfg_model_app_unbind_t Parameters of Config Model App Unbind. Espressif Systems 366 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t element_addr The element address uint16_t model_app_idx Index of the app key to bind with the model uint16_t model_id The model id uint16_t company_id The company id, if not a vendor model, shall set to 0xFFFF struct esp_ble_mesh_cfg_kr_phase_set_t Parameters of Config Key Refresh Phase Set. Public Members uint16_t net_idx The network key index uint8_t transition New Key Refresh Phase Transition struct esp_ble_mesh_cfg_net_transmit_set_t Parameters of Config Network Transmit Set. Public Members uint8_t net_transmit Network Transmit State struct esp_ble_mesh_cfg_heartbeat_pub_set_t Parameters of Config Model Heartbeat Publication Set. Public Members uint16_t dst Destination address for Heartbeat messages uint8_t count Number of Heartbeat messages to be sent uint8_t period Period for sending Heartbeat messages uint8_t ttl TTL to be used when sending Heartbeat messages uint16_t feature Bit field indicating features that trigger Heartbeat messages when changed uint16_t net_idx NetKey Index struct esp_ble_mesh_cfg_heartbeat_sub_set_t Parameters of Config Model Heartbeat Subscription Set. Espressif Systems 367 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t src Source address for Heartbeat messages uint16_t dst Destination address for Heartbeat messages uint8_t period Period for receiving Heartbeat messages struct esp_ble_mesh_cfg_beacon_status_cb_t Parameter of Config Beacon Status Public Members uint8_t beacon Secure Network Beacon state value struct esp_ble_mesh_cfg_comp_data_status_cb_t Parameters of Config Composition Data Status Public Members uint8_t page Page number of the Composition Data struct net_buf_simple *composition_data Pointer to Composition Data for the identified page struct esp_ble_mesh_cfg_default_ttl_status_cb_t Parameter of Config Default TTL Status Public Members uint8_t default_ttl Default TTL state value struct esp_ble_mesh_cfg_gatt_proxy_status_cb_t Parameter of Config GATT Proxy Status Public Members uint8_t gatt_proxy GATT Proxy state value struct esp_ble_mesh_cfg_relay_status_cb_t Parameters of Config Relay Status Public Members uint8_t relay Relay state value uint8_t retransmit Relay retransmit value(number of retransmissions and number of 10-millisecond steps between retransmissions) Espressif Systems 368 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_cfg_model_pub_status_cb_t Parameters of Config Model Publication Status Public Members uint8_t status Status Code for the request message uint16_t element_addr Address of the element uint16_t publish_addr Value of the publish address uint16_t app_idx Index of the application key bool cred_flag Value of the Friendship Credential Flag uint8_t ttl Default TTL value for the outgoing messages uint8_t period Period for periodic status publishing uint8_t transmit Number of retransmissions and number of 50-millisecond steps between retransmissions uint16_t company_id Company ID uint16_t model_id Model ID struct esp_ble_mesh_cfg_model_sub_status_cb_t Parameters of Config Model Subscription Status Public Members uint8_t status Status Code for the request message uint16_t element_addr Address of the element uint16_t sub_addr Value of the address uint16_t company_id Company ID uint16_t model_id Model ID struct esp_ble_mesh_cfg_net_key_status_cb_t Parameters of Config NetKey Status Public Members uint8_t status Status Code for the request message Espressif Systems 369 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t net_idx Index of the NetKey struct esp_ble_mesh_cfg_app_key_status_cb_t Parameters of Config AppKey Status Public Members uint8_t status Status Code for the request message uint16_t net_idx Index of the NetKey uint16_t app_idx Index of the application key struct esp_ble_mesh_cfg_mod_app_status_cb_t Parameters of Config Model App Status Public Members uint8_t status Status Code for the request message uint16_t element_addr Address of the element uint16_t app_idx Index of the application key uint16_t company_id Company ID uint16_t model_id Model ID struct esp_ble_mesh_cfg_friend_status_cb_t Parameter of Config Friend Status Public Members uint8_t friend_state Friend state value struct esp_ble_mesh_cfg_hb_pub_status_cb_t Parameters of Config Heartbeat Publication Status Public Members uint8_t status Status Code for the request message uint16_t dst Destination address for Heartbeat messages uint8_t count Number of Heartbeat messages remaining to be sent uint8_t period Period for sending Heartbeat messages Espressif Systems 370 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t ttl TTL to be used when sending Heartbeat messages uint16_t features Features that trigger Heartbeat messages when changed uint16_t net_idx Index of the NetKey struct esp_ble_mesh_cfg_hb_sub_status_cb_t Parameters of Config Heartbeat Subscription Status Public Members uint8_t status Status Code for the request message uint16_t src Source address for Heartbeat messages uint16_t dst Destination address for Heartbeat messages uint8_t period Remaining Period for processing Heartbeat messages uint8_t count Number of Heartbeat messages received uint8_t min_hops Minimum hops when receiving Heartbeat messages uint8_t max_hops Maximum hops when receiving Heartbeat messages struct esp_ble_mesh_cfg_net_trans_status_cb_t Parameters of Config Network Transmit Status Public Members uint8_t net_trans_count : 3 Number of transmissions for each Network PDU originating from the node uint8_t net_trans_step : 5 Maximum hops when receiving Heartbeat messages struct esp_ble_mesh_cfg_model_sub_list_cb_t Parameters of Config SIG/Vendor Subscription List Public Members uint8_t status Status Code for the request message uint16_t element_addr Address of the element uint16_t company_id Company ID uint16_t model_id Model ID Espressif Systems 371 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct net_buf_simple *sub_addr A block of all addresses from the Subscription List struct esp_ble_mesh_cfg_net_key_list_cb_t Parameter of Config NetKey List Public Members struct net_buf_simple *net_idx A list of NetKey Indexes known to the node struct esp_ble_mesh_cfg_app_key_list_cb_t Parameters of Config AppKey List Public Members uint8_t status Status Code for the request message uint16_t net_idx NetKey Index of the NetKey that the AppKeys are bound to struct net_buf_simple *app_idx A list of AppKey indexes that are bound to the NetKey identified by NetKeyIndex struct esp_ble_mesh_cfg_node_id_status_cb_t Parameters of Config Node Identity Status Public Members uint8_t status Status Code for the request message uint16_t net_idx Index of the NetKey uint8_t identity Node Identity state struct esp_ble_mesh_cfg_model_app_list_cb_t Parameters of Config SIG/Vendor Model App List Public Members uint8_t status Status Code for the request message uint16_t element_addr Address of the element uint16_t company_id Company ID uint16_t model_id Model ID struct net_buf_simple *app_idx All AppKey indexes bound to the Model struct esp_ble_mesh_cfg_kr_phase_status_cb_t Parameters of Config Key Refresh Phase Status Espressif Systems 372 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t status Status Code for the request message uint16_t net_idx Index of the NetKey uint8_t phase Key Refresh Phase state struct esp_ble_mesh_cfg_lpn_pollto_status_cb_t Parameters of Config Low Power Node PollTimeout Status Public Members uint16_t lpn_addr The unicast address of the Low Power node int32_t poll_timeout The current value of the PollTimeout timer of the Low Power node struct esp_ble_mesh_cfg_client_cb_param_t Configuration Client Model callback parameters Public Members int error_code Appropriate error code esp_ble_mesh_client_common_param_t *params The client common parameters esp_ble_mesh_cfg_client_common_cb_param_t status_cb The config status message callback values struct esp_ble_mesh_state_change_cfg_mod_pub_set_t Configuration Server model related context. Public Members uint16_t element_addr Element Address uint16_t pub_addr Publish Address uint16_t app_idx AppKey Index bool cred_flag Friendship Credential Flag uint8_t pub_ttl Publish TTL uint8_t pub_period Publish Period uint8_t pub_retransmit Publish Retransmit Espressif Systems 373 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t company_id Company ID uint16_t model_id Model ID struct esp_ble_mesh_state_change_cfg_model_sub_add_t Parameters of Config Model Subscription Add Public Members uint16_t element_addr Element Address uint16_t sub_addr Subscription Address uint16_t company_id Company ID uint16_t model_id Model ID struct esp_ble_mesh_state_change_cfg_model_sub_delete_t Parameters of Config Model Subscription Delete Public Members uint16_t element_addr Element Address uint16_t sub_addr Subscription Address uint16_t company_id Company ID uint16_t model_id Model ID struct esp_ble_mesh_state_change_cfg_netkey_add_t Parameters of Config NetKey Add Public Members uint16_t net_idx NetKey Index uint8_t net_key[16] NetKey struct esp_ble_mesh_state_change_cfg_netkey_update_t Parameters of Config NetKey Update Public Members uint16_t net_idx NetKey Index uint8_t net_key[16] NetKey Espressif Systems 374 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_state_change_cfg_netkey_delete_t Parameter of Config NetKey Delete Public Members uint16_t net_idx NetKey Index struct esp_ble_mesh_state_change_cfg_appkey_add_t Parameters of Config AppKey Add Public Members uint16_t net_idx NetKey Index uint16_t app_idx AppKey Index uint8_t app_key[16] AppKey struct esp_ble_mesh_state_change_cfg_appkey_update_t Parameters of Config AppKey Update Public Members uint16_t net_idx NetKey Index uint16_t app_idx AppKey Index uint8_t app_key[16] AppKey struct esp_ble_mesh_state_change_cfg_appkey_delete_t Parameters of Config AppKey Delete Public Members uint16_t net_idx NetKey Index uint16_t app_idx AppKey Index struct esp_ble_mesh_state_change_cfg_model_app_bind_t Parameters of Config Model App Bind Public Members uint16_t element_addr Element Address uint16_t app_idx AppKey Index uint16_t company_id Company ID Espressif Systems 375 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t model_id Model ID struct esp_ble_mesh_state_change_cfg_model_app_unbind_t Parameters of Config Model App Unbind Public Members uint16_t element_addr Element Address uint16_t app_idx AppKey Index uint16_t company_id Company ID uint16_t model_id Model ID struct esp_ble_mesh_state_change_cfg_kr_phase_set_t Parameters of Config Key Refresh Phase Set Public Members uint16_t net_idx NetKey Index uint8_t kr_phase New Key Refresh Phase Transition struct esp_ble_mesh_cfg_server_cb_param_t Configuration Server model callback parameters Public Members esp_ble_mesh_model_t *model Pointer to the server model structure esp_ble_mesh_msg_ctx_t ctx Context of the received message esp_ble_mesh_cfg_server_cb_value_t value Value of the received configuration messages Macros ESP_BLE_MESH_MODEL_CFG_SRV(srv_data) Define a new Config Server Model. Note The Config Server Model can only be included by a Primary Element. Return New Config Server Model instance. Parameters · srv_data: Pointer to a unique Config Server Model user_data. ESP_BLE_MESH_MODEL_CFG_CLI(cli_data) Define a new Config Client Model. Note The Config Client Model can only be included by a Primary Element. Return New Config Client Model instance. Parameters · cli_data: Pointer to a unique struct esp_ble_mesh_client_t. Espressif Systems 376 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Type Definitions typedef struct esp_ble_mesh_cfg_srv esp_ble_mesh_cfg_srv_t Configuration Server Model context typedef void (*esp_ble_mesh_cfg_client_cb_t)(esp_ble_mesh_cfg_client_cb_event_t event, esp_ble_mesh_cfg_client_cb_param_t *param) Bluetooth Mesh Config Client and Server Model functions. Configuration Client Model callback function type Parameters · event: Event type · param: Pointer to callback parameter typedef void (*esp_ble_mesh_cfg_server_cb_t)(esp_ble_mesh_cfg_server_cb_event_t event, esp_ble_mesh_cfg_server_cb_param_t *param) Configuration Server Model callback function type. Parameters · event: Event type · param: Pointer to callback parameter Enumerations enum esp_ble_mesh_cfg_client_cb_event_t This enum value is the event of Configuration Client Model Values: ESP_BLE_MESH_CFG_CLIENT_GET_STATE_EVT ESP_BLE_MESH_CFG_CLIENT_SET_STATE_EVT ESP_BLE_MESH_CFG_CLIENT_PUBLISH_EVT ESP_BLE_MESH_CFG_CLIENT_TIMEOUT_EVT ESP_BLE_MESH_CFG_CLIENT_EVT_MAX enum esp_ble_mesh_cfg_server_cb_event_t This enum value is the event of Configuration Server model Values: ESP_BLE_MESH_CFG_SERVER_STATE_CHANGE_EVT ESP_BLE_MESH_CFG_SERVER_EVT_MAX Health Client/Server Models Header File · components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_health_model_api.h Functions esp_err_t esp_ble_mesh_register_health_client_callback(esp_ble_mesh_health_client_cb_t callback) Register BLE Mesh Health Model callback, the callback will report Health Client & Server Model events. Return ESP_OK on success or error code otherwise. Parameters · [in] callback: Pointer to the callback function. esp_err_t esp_ble_mesh_register_health_server_callback(esp_ble_mesh_health_server_cb_t Register BLE Mesh Health Server Model callback. callback) Espressif Systems 377 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return ESP_OK on success or error code otherwise. Parameters · [in] callback: Pointer to the callback function. esp_err_t esp_ble_mesh_health_client_get_state(esp_ble_mesh_client_common_param_t *params, esp_ble_mesh_health_client_get_state_t *get_state) This function is called to get the Health Server states using the Health Client Model get messages. Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to esp_ble_mesh_opcode_health_client_get_t in esp_ble_mesh_defs.h Return ESP_OK on success or error code otherwise. Parameters · [in] params: Pointer to BLE Mesh common client parameters. · [in] get_state: Pointer to a union, each kind of opcode corresponds to one structure inside. Shall not be set to NULL. esp_err_t esp_ble_mesh_health_client_set_state(esp_ble_mesh_client_common_param_t *params, esp_ble_mesh_health_client_set_state_t *set_state) This function is called to set the Health Server states using the Health Client Model set messages. Note If you want to find the opcodes and corresponding meanings accepted by this API, please refer to esp_ble_mesh_opcode_health_client_set_t in esp_ble_mesh_defs.h Return ESP_OK on success or error code otherwise. Parameters · [in] params: Pointer to BLE Mesh common client parameters. · [in] set_state: Pointer to a union, each kind of opcode corresponds to one structure inside. Shall not be set to NULL. esp_err_t esp_ble_mesh_health_server_fault_update(esp_ble_mesh_elem_t *element) This function is called by the Health Server Model to update the context of its Health Current status. Return ESP_OK on success or error code otherwise. Parameters · [in] element: The element to which the Health Server Model belongs. Unions union esp_ble_mesh_health_client_get_state_t #include <esp_ble_mesh_health_model_api.h> For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET ESP_BLE_MESH_MODEL_OP_ATTENTION_GET ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_GET the get_state parameter in the esp_ble_mesh_health_client_get_state function should not be set to NULL. Public Members esp_ble_mesh_health_fault_get_t fault_get For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET. union esp_ble_mesh_health_client_set_state_t #include <esp_ble_mesh_health_model_api.h> For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_ ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK ESP_BLE_MESH_MODEL_OP_ATTENTION_SET ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNACK the set_state parameter in the esp_ble_mesh_health_client_set_state function should not be set to NULL. Public Members esp_ble_mesh_health_attention_set_t attention_set For ESP_BLE_MESH_MODEL_OP_ATTENTION_SET or ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNA Espressif Systems 378 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_health_period_set_t period_set For ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET or ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SET_UNACK. esp_ble_mesh_health_fault_test_t fault_test For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST or ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK. esp_ble_mesh_health_fault_clear_t fault_clear For ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR or ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK. union esp_ble_mesh_health_client_common_cb_param_t #include <esp_ble_mesh_health_model_api.h> Health Client Model received message union. Public Members esp_ble_mesh_health_current_status_cb_t current_status The health current status value esp_ble_mesh_health_fault_status_cb_t fault_status The health fault status value esp_ble_mesh_health_period_status_cb_t period_status The health period status value esp_ble_mesh_health_attention_status_cb_t attention_status The health attention status value union esp_ble_mesh_health_server_cb_param_t #include <esp_ble_mesh_health_model_api.h> Health Server Model callback parameters union. Public Members esp_ble_mesh_health_fault_update_comp_cb_t fault_update_comp ESP_BLE_MESH_HEALTH_SERVER_FAULT_UPDATE_COMP_EVT esp_ble_mesh_health_fault_clear_cb_t fault_clear ESP_BLE_MESH_HEALTH_SERVER_FAULT_CLEAR_EVT esp_ble_mesh_health_fault_test_cb_t fault_test ESP_BLE_MESH_HEALTH_SERVER_FAULT_TEST_EVT esp_ble_mesh_health_attention_on_cb_t attention_on ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_ON_EVT esp_ble_mesh_health_attention_off_cb_t attention_off ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_OFF_EVT Structures struct esp_ble_mesh_health_srv_cb_t ESP BLE Mesh Health Server callback Public Members esp_ble_mesh_cb_t fault_clear Clear health registered faults. Initialized by the stack. esp_ble_mesh_cb_t fault_test Run a specific health test. Initialized by the stack. Espressif Systems 379 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_cb_t attention_on Health attention on callback. Initialized by the stack. esp_ble_mesh_cb_t attention_off Health attention off callback. Initialized by the stack. struct esp_ble_mesh_health_test_t ESP BLE Mesh Health Server test Context Public Members uint8_t id_count Number of Health self-test ID const uint8_t *test_ids Array of Health self-test IDs uint16_t company_id Company ID used to identify the Health Fault state uint8_t prev_test_id Current test ID of the health fault test uint8_t current_faults[ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE] Array of current faults uint8_t registered_faults[ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE] Array of registered faults struct esp_ble_mesh_health_srv_t ESP BLE Mesh Health Server Model Context Public Members esp_ble_mesh_model_t *model Pointer to Health Server Model esp_ble_mesh_health_srv_cb_t health_cb Health callback struct struct k_delayed_work attention_timer Attention Timer state bool attention_timer_start Attention Timer start flag esp_ble_mesh_health_test_t health_test Health Server fault test struct esp_ble_mesh_health_fault_get_t Parameter of Health Fault Get Public Members uint16_t company_id Bluetooth assigned 16-bit Company ID struct esp_ble_mesh_health_attention_set_t Parameter of Health Attention Set Espressif Systems 380 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t attention Value of the Attention Timer state struct esp_ble_mesh_health_period_set_t Parameter of Health Period Set Public Members uint8_t fast_period_divisor Divider for the Publish Period struct esp_ble_mesh_health_fault_test_t Parameter of Health Fault Test Public Members uint16_t company_id Bluetooth assigned 16-bit Company ID uint8_t test_id ID of a specific test to be performed struct esp_ble_mesh_health_fault_clear_t Parameter of Health Fault Clear Public Members uint16_t company_id Bluetooth assigned 16-bit Company ID struct esp_ble_mesh_health_current_status_cb_t Parameters of Health Current Status Public Members uint8_t test_id ID of a most recently performed test uint16_t company_id Bluetooth assigned 16-bit Company ID struct net_buf_simple *fault_array FaultArray field contains a sequence of 1-octet fault values struct esp_ble_mesh_health_fault_status_cb_t Parameters of Health Fault Status Public Members uint8_t test_id ID of a most recently performed test uint16_t company_id Bluetooth assigned 16-bit Company ID struct net_buf_simple *fault_array FaultArray field contains a sequence of 1-octet fault values Espressif Systems 381 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_health_period_status_cb_t Parameter of Health Period Status Public Members uint8_t fast_period_divisor Divider for the Publish Period struct esp_ble_mesh_health_attention_status_cb_t Parameter of Health Attention Status Public Members uint8_t attention Value of the Attention Timer state struct esp_ble_mesh_health_client_cb_param_t Health Client Model callback parameters Public Members int error_code Appropriate error code esp_ble_mesh_client_common_param_t *params The client common parameters. esp_ble_mesh_health_client_common_cb_param_t status_cb The health message status callback values struct esp_ble_mesh_health_fault_update_comp_cb_t Parameter of publishing Health Current Status completion event Public Members int error_code The result of publishing Health Current Status esp_ble_mesh_elem_t *element Pointer to the element which contains the Health Server Model struct esp_ble_mesh_health_fault_clear_cb_t Parameters of Health Fault Clear event Public Members esp_ble_mesh_model_t *model Pointer to the Health Server Model uint16_t company_id Bluetooth assigned 16-bit Company ID struct esp_ble_mesh_health_fault_test_cb_t Parameters of Health Fault Test event Espressif Systems 382 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_model_t *model Pointer to the Health Server Model uint8_t test_id ID of a specific test to be performed uint16_t company_id Bluetooth assigned 16-bit Company ID struct esp_ble_mesh_health_attention_on_cb_t Parameter of Health Attention On event Public Members esp_ble_mesh_model_t *model Pointer to the Health Server Model uint8_t time Duration of attention timer on (in seconds) struct esp_ble_mesh_health_attention_off_cb_t Parameter of Health Attention Off event Public Members esp_ble_mesh_model_t *model Pointer to the Health Server Model Macros ESP_BLE_MESH_MODEL_HEALTH_SRV(srv, pub) Define a new Health Server Model. Note The Health Server Model can only be included by a Primary Element. Return New Health Server Model instance. Parameters · srv: Pointer to the unique struct esp_ble_mesh_health_srv_t. · pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. ESP_BLE_MESH_MODEL_HEALTH_CLI(cli_data) Define a new Health Client Model. Note This API needs to be called for each element on which the application needs to have a Health Client Model. Return New Health Client Model instance. Parameters · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_HEALTH_PUB_DEFINE(_name, _max, _role) A helper to define a health publication context Parameters · _name: Name given to the publication context variable. · _max: Maximum number of faults the element can have. · _role: Role of the device which contains the model. ESP_BLE_MESH_HEALTH_STANDARD_TEST SIG identifier of Health Fault Test. 0x01 ~ 0xFF: Vendor Specific Test. Espressif Systems 383 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_NO_FAULT Fault values of Health Fault Test. 0x33 ~ 0x7F: Reserved for Future Use. 0x80 ~ 0xFF: Vendor Specific Warning/Error. ESP_BLE_MESH_BATTERY_LOW_WARNING ESP_BLE_MESH_BATTERY_LOW_ERROR ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_LOW_WARNING ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_LOW_ERROR ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_WARNING ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_ERROR ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_WARNING ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_ERROR ESP_BLE_MESH_NO_LOAD_WARNING ESP_BLE_MESH_NO_LOAD_ERROR ESP_BLE_MESH_OVERLOAD_WARNING ESP_BLE_MESH_OVERLOAD_ERROR ESP_BLE_MESH_OVERHEAT_WARNING ESP_BLE_MESH_OVERHEAT_ERROR ESP_BLE_MESH_CONDENSATION_WARNING ESP_BLE_MESH_CONDENSATION_ERROR ESP_BLE_MESH_VIBRATION_WARNING ESP_BLE_MESH_VIBRATION_ERROR ESP_BLE_MESH_CONFIGURATION_WARNING ESP_BLE_MESH_CONFIGURATION_ERROR ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_WARNING ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_ERROR ESP_BLE_MESH_MEMORY_WARNING ESP_BLE_MESH_MEMORY_ERROR ESP_BLE_MESH_SELF_TEST_WARNING ESP_BLE_MESH_SELF_TEST_ERROR ESP_BLE_MESH_INPUT_TOO_LOW_WARNING ESP_BLE_MESH_INPUT_TOO_LOW_ERROR ESP_BLE_MESH_INPUT_TOO_HIGH_WARNING ESP_BLE_MESH_INPUT_TOO_HIGH_ERROR ESP_BLE_MESH_INPUT_NO_CHANGE_WARNING ESP_BLE_MESH_INPUT_NO_CHANGE_ERROR ESP_BLE_MESH_ACTUATOR_BLOCKED_WARNING ESP_BLE_MESH_ACTUATOR_BLOCKED_ERROR ESP_BLE_MESH_HOUSING_OPENED_WARNING ESP_BLE_MESH_HOUSING_OPENED_ERROR ESP_BLE_MESH_TAMPER_WARNING Espressif Systems 384 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_TAMPER_ERROR ESP_BLE_MESH_DEVICE_MOVED_WARNING ESP_BLE_MESH_DEVICE_MOVED_ERROR ESP_BLE_MESH_DEVICE_DROPPED_WARNING ESP_BLE_MESH_DEVICE_DROPPED_ERROR ESP_BLE_MESH_OVERFLOW_WARNING ESP_BLE_MESH_OVERFLOW_ERROR ESP_BLE_MESH_EMPTY_WARNING ESP_BLE_MESH_EMPTY_ERROR ESP_BLE_MESH_INTERNAL_BUS_WARNING ESP_BLE_MESH_INTERNAL_BUS_ERROR ESP_BLE_MESH_MECHANISM_JAMMED_WARNING ESP_BLE_MESH_MECHANISM_JAMMED_ERROR ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE Type Definitions typedef void (*esp_ble_mesh_health_client_cb_t)(esp_ble_mesh_health_client_cb_event_t event, esp_ble_mesh_health_client_cb_param_t *param) Bluetooth Mesh Health Client and Server Model function. Health Client Model callback function type Parameters · event: Event type · param: Pointer to callback parameter typedef void (*esp_ble_mesh_health_server_cb_t)(esp_ble_mesh_health_server_cb_event_t event, esp_ble_mesh_health_server_cb_param_t *param) Health Server Model callback function type. Parameters · event: Event type · param: Pointer to callback parameter Enumerations enum esp_ble_mesh_health_client_cb_event_t This enum value is the event of Health Client Model Values: ESP_BLE_MESH_HEALTH_CLIENT_GET_STATE_EVT ESP_BLE_MESH_HEALTH_CLIENT_SET_STATE_EVT ESP_BLE_MESH_HEALTH_CLIENT_PUBLISH_EVT ESP_BLE_MESH_HEALTH_CLIENT_TIMEOUT_EVT ESP_BLE_MESH_HEALTH_CLIENT_EVT_MAX enum esp_ble_mesh_health_server_cb_event_t This enum value is the event of Health Server Model Values: ESP_BLE_MESH_HEALTH_SERVER_FAULT_UPDATE_COMP_EVT Espressif Systems 385 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_HEALTH_SERVER_FAULT_CLEAR_EVT ESP_BLE_MESH_HEALTH_SERVER_FAULT_TEST_EVT ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_ON_EVT ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_OFF_EVT ESP_BLE_MESH_HEALTH_SERVER_EVT_MAX Generic Client/Server Models Header File · components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_generic_model_api.h Functions esp_err_t esp_ble_mesh_register_generic_client_callback(esp_ble_mesh_generic_client_cb_t 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 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. Espressif Systems 386 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_gen_user_property_get_t user_property_get For ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_GET esp_ble_mesh_gen_admin_property_get_t admin_property_get For ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_GET esp_ble_mesh_gen_manufacturer_property_get_t manufacturer_property_get For ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET esp_ble_mesh_gen_client_properties_get_t client_properties_get For ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_GET union esp_ble_mesh_generic_client_set_state_t #include <esp_ble_mesh_generic_model_api.h> Generic Client Model set message union. Public Members esp_ble_mesh_gen_onoff_set_t onoff_set For ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET & ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET_UN esp_ble_mesh_gen_level_set_t level_set For ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET & ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET_UNA esp_ble_mesh_gen_delta_set_t delta_set For ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET & ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET_UN esp_ble_mesh_gen_move_set_t move_set For ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET & ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET_UNA esp_ble_mesh_gen_def_trans_time_set_t def_trans_time_set For ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET & ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET_UNACK esp_ble_mesh_gen_onpowerup_set_t power_set For ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET & ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SET_UNACK esp_ble_mesh_gen_power_level_set_t power_level_set For ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET & ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET_UNACK esp_ble_mesh_gen_power_default_set_t power_default_set For ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET & ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET_UNACK esp_ble_mesh_gen_power_range_set_t power_range_set For ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET & ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET_UNACK esp_ble_mesh_gen_loc_global_set_t loc_global_set For ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET & ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SET_UNACK esp_ble_mesh_gen_loc_local_set_t loc_local_set For ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET & ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SET_UNACK esp_ble_mesh_gen_user_property_set_t user_property_set For ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET & ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_SET_UNACK esp_ble_mesh_gen_admin_property_set_t admin_property_set For ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET & ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET_UNACK Espressif Systems 387 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_gen_manufacturer_property_set_t manufacturer_property_set For ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET & ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_SET_UNACK union esp_ble_mesh_gen_client_status_cb_t #include <esp_ble_mesh_generic_model_api.h> Generic Client Model received message union. Public Members esp_ble_mesh_gen_onoff_status_cb_t onoff_status For ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_STATUS esp_ble_mesh_gen_level_status_cb_t level_status For ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_STATUS esp_ble_mesh_gen_def_trans_time_status_cb_t def_trans_time_status For ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_STATUS esp_ble_mesh_gen_onpowerup_status_cb_t onpowerup_status For ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_STATUS esp_ble_mesh_gen_power_level_status_cb_t power_level_status For ESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_STATUS esp_ble_mesh_gen_power_last_status_cb_t power_last_status For ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_STATUS esp_ble_mesh_gen_power_default_status_cb_t power_default_status For ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_STATUS esp_ble_mesh_gen_power_range_status_cb_t power_range_status For ESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_STATUS esp_ble_mesh_gen_battery_status_cb_t battery_status For ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_STATUS esp_ble_mesh_gen_loc_global_status_cb_t location_global_status For ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_STATUS esp_ble_mesh_gen_loc_local_status_cb_t location_local_status ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_STATUS esp_ble_mesh_gen_user_properties_status_cb_t user_properties_status ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTIES_STATUS esp_ble_mesh_gen_user_property_status_cb_t user_property_status ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_STATUS esp_ble_mesh_gen_admin_properties_status_cb_t admin_properties_status ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_STATUS esp_ble_mesh_gen_admin_property_status_cb_t admin_property_status ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_STATUS esp_ble_mesh_gen_manufacturer_properties_status_cb_t manufacturer_properties_status ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTIES_STATUS esp_ble_mesh_gen_manufacturer_property_status_cb_t manufacturer_property_status ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_PROPERTY_STATUS esp_ble_mesh_gen_client_properties_status_cb_t client_properties_status ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_STATUS union esp_ble_mesh_generic_server_state_change_t #include <esp_ble_mesh_generic_model_api.h> Generic Server Model state change value union. Espressif Systems 388 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_state_change_gen_onoff_set_t onoff_set The recv_op in ctx can be used to decide which state is changed. Generic OnOff Set esp_ble_mesh_state_change_gen_level_set_t level_set Generic Level Set esp_ble_mesh_state_change_gen_delta_set_t delta_set Generic Delta Set esp_ble_mesh_state_change_gen_move_set_t move_set Generic Move Set esp_ble_mesh_state_change_gen_def_trans_time_set_t def_trans_time_set Generic Default Transition Time Set esp_ble_mesh_state_change_gen_onpowerup_set_t onpowerup_set Generic OnPowerUp Set esp_ble_mesh_state_change_gen_power_level_set_t power_level_set Generic Power Level Set esp_ble_mesh_state_change_gen_power_default_set_t power_default_set Generic Power Default Set esp_ble_mesh_state_change_gen_power_range_set_t power_range_set Generic Power Range Set esp_ble_mesh_state_change_gen_loc_global_set_t loc_global_set Generic Location Global Set esp_ble_mesh_state_change_gen_loc_local_set_t loc_local_set Generic Location Local Set esp_ble_mesh_state_change_gen_user_property_set_t user_property_set Generic User Property Set esp_ble_mesh_state_change_gen_admin_property_set_t admin_property_set Generic Admin Property Set esp_ble_mesh_state_change_gen_manu_property_set_t manu_property_set Generic Manufacturer Property Set union esp_ble_mesh_generic_server_recv_get_msg_t #include <esp_ble_mesh_generic_model_api.h> Generic Server Model received get message union. Public Members esp_ble_mesh_server_recv_gen_user_property_get_t user_property Generic User Property Get esp_ble_mesh_server_recv_gen_admin_property_get_t admin_property Generic Admin Property Get esp_ble_mesh_server_recv_gen_manufacturer_property_get_t manu_property Generic Manufacturer Property Get esp_ble_mesh_server_recv_gen_client_properties_get_t client_properties Generic Client Properties Get union esp_ble_mesh_generic_server_recv_set_msg_t #include <esp_ble_mesh_generic_model_api.h> Generic Server Model received set message union. Espressif Systems 389 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_server_recv_gen_onoff_set_t onoff Generic OnOff Set/Generic OnOff Set Unack esp_ble_mesh_server_recv_gen_level_set_t level Generic Level Set/Generic Level Set Unack esp_ble_mesh_server_recv_gen_delta_set_t delta Generic Delta Set/Generic Delta Set Unack esp_ble_mesh_server_recv_gen_move_set_t move Generic Move Set/Generic Move Set Unack esp_ble_mesh_server_recv_gen_def_trans_time_set_t def_trans_time Generic Default Transition Time Set/Generic Default Transition Time Set Unack esp_ble_mesh_server_recv_gen_onpowerup_set_t onpowerup Generic OnPowerUp Set/Generic OnPowerUp Set Unack esp_ble_mesh_server_recv_gen_power_level_set_t power_level Generic Power Level Set/Generic Power Level Set Unack esp_ble_mesh_server_recv_gen_power_default_set_t power_default Generic Power Default Set/Generic Power Default Set Unack esp_ble_mesh_server_recv_gen_power_range_set_t power_range Generic Power Range Set/Generic Power Range Set Unack esp_ble_mesh_server_recv_gen_loc_global_set_t location_global Generic Location Global Set/Generic Location Global Set Unack esp_ble_mesh_server_recv_gen_loc_local_set_t location_local Generic Location Local Set/Generic Location Local Set Unack esp_ble_mesh_server_recv_gen_user_property_set_t user_property Generic User Property Set/Generic User Property Set Unack esp_ble_mesh_server_recv_gen_admin_property_set_t admin_property Generic Admin Property Set/Generic Admin Property Set Unack esp_ble_mesh_server_recv_gen_manufacturer_property_set_t manu_property Generic Manufacturer Property Set/Generic Manufacturer Property Set Unack union esp_ble_mesh_generic_server_cb_value_t #include <esp_ble_mesh_generic_model_api.h> Generic Server Model callback value union. Public Members esp_ble_mesh_generic_server_state_change_t state_change ESP_BLE_MESH_GENERIC_SERVER_STATE_CHANGE_EVT esp_ble_mesh_generic_server_recv_get_msg_t get ESP_BLE_MESH_GENERIC_SERVER_RECV_GET_MSG_EVT esp_ble_mesh_generic_server_recv_set_msg_t set ESP_BLE_MESH_GENERIC_SERVER_RECV_SET_MSG_EVT Structures struct esp_ble_mesh_gen_onoff_set_t Bluetooth Mesh Generic Client Model Get and Set parameters structure. Parameters of Generic OnOff Set. Espressif Systems 390 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate if optional parameters are included uint8_t onoff Target value of Generic OnOff state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_gen_level_set_t Parameters of Generic Level Set. Public Members bool op_en Indicate if optional parameters are included int16_t level Target value of Generic Level state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_gen_delta_set_t Parameters of Generic Delta Set. Public Members bool op_en Indicate if optional parameters are included int32_t level Delta change of Generic Level state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_gen_move_set_t Parameters of Generic Move Set. Public Members bool op_en Indicate if optional parameters are included Espressif Systems 391 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int16_t delta_level Delta Level step to calculate Move speed for Generic Level state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_gen_def_trans_time_set_t Parameter of Generic Default Transition Time Set. Public Members uint8_t trans_time The value of the Generic Default Transition Time state struct esp_ble_mesh_gen_onpowerup_set_t Parameter of Generic OnPowerUp Set. Public Members uint8_t onpowerup The value of the Generic OnPowerUp state struct esp_ble_mesh_gen_power_level_set_t Parameters of Generic Power Level Set. Public Members bool op_en Indicate if optional parameters are included uint16_t power Target value of Generic Power Actual state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_gen_power_default_set_t Parameter of Generic Power Default Set. Public Members uint16_t power The value of the Generic Power Default state struct esp_ble_mesh_gen_power_range_set_t Parameters of Generic Power Range Set. Espressif Systems 392 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t range_min Value of Range Min field of Generic Power Range state uint16_t range_max Value of Range Max field of Generic Power Range state struct esp_ble_mesh_gen_loc_global_set_t Parameters of Generic Location Global Set. Public Members int32_t global_latitude Global Coordinates (Latitude) int32_t global_longitude Global Coordinates (Longitude) int16_t global_altitude Global Altitude struct esp_ble_mesh_gen_loc_local_set_t Parameters of Generic Location Local Set. Public Members int16_t local_north Local Coordinates (North) int16_t local_east Local Coordinates (East) int16_t local_altitude Local Altitude uint8_t floor_number Floor Number uint16_t uncertainty Uncertainty struct esp_ble_mesh_gen_user_property_get_t Parameter of Generic User Property Get. Public Members uint16_t property_id Property ID identifying a Generic User Property struct esp_ble_mesh_gen_user_property_set_t Parameters of Generic User Property Set. Public Members uint16_t property_id Property ID identifying a Generic User Property struct net_buf_simple *property_value Raw value for the User Property Espressif Systems 393 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_gen_admin_property_get_t Parameter of Generic Admin Property Get. Public Members uint16_t property_id Property ID identifying a Generic Admin Property struct esp_ble_mesh_gen_admin_property_set_t Parameters of Generic Admin Property Set. Public Members uint16_t property_id Property ID identifying a Generic Admin Property uint8_t user_access Enumeration indicating user access struct net_buf_simple *property_value Raw value for the Admin Property struct esp_ble_mesh_gen_manufacturer_property_get_t Parameter of Generic Manufacturer Property Get. Public Members uint16_t property_id Property ID identifying a Generic Manufacturer Property struct esp_ble_mesh_gen_manufacturer_property_set_t Parameters of Generic Manufacturer Property Set. Public Members uint16_t property_id Property ID identifying a Generic Manufacturer Property uint8_t user_access Enumeration indicating user access struct esp_ble_mesh_gen_client_properties_get_t Parameter of Generic Client Properties Get. Public Members uint16_t property_id A starting Client Property ID present within an element struct esp_ble_mesh_gen_onoff_status_cb_t Bluetooth Mesh Generic Client Model Get and Set callback parameters structure. Parameters of Generic OnOff Status. Espressif Systems 394 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate if optional parameters are included uint8_t present_onoff Current value of Generic OnOff state uint8_t target_onoff Target value of Generic OnOff state (optional) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_gen_level_status_cb_t Parameters of Generic Level Status. Public Members bool op_en Indicate if optional parameters are included int16_t present_level Current value of Generic Level state int16_t target_level Target value of the Generic Level state (optional) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_gen_def_trans_time_status_cb_t Parameter of Generic Default Transition Time Status. Public Members uint8_t trans_time The value of the Generic Default Transition Time state struct esp_ble_mesh_gen_onpowerup_status_cb_t Parameter of Generic OnPowerUp Status. Public Members uint8_t onpowerup The value of the Generic OnPowerUp state struct esp_ble_mesh_gen_power_level_status_cb_t Parameters of Generic Power Level Status. Public Members bool op_en Indicate if optional parameters are included uint16_t present_power Current value of Generic Power Actual state uint16_t target_power Target value of Generic Power Actual state (optional) Espressif Systems 395 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_gen_power_last_status_cb_t Parameter of Generic Power Last Status. Public Members uint16_t power The value of the Generic Power Last state struct esp_ble_mesh_gen_power_default_status_cb_t Parameter of Generic Power Default Status. Public Members uint16_t power The value of the Generic Default Last state struct esp_ble_mesh_gen_power_range_status_cb_t Parameters of Generic Power Range Status. Public Members uint8_t status_code Status Code for the request message uint16_t range_min Value of Range Min field of Generic Power Range state uint16_t range_max Value of Range Max field of Generic Power Range state struct esp_ble_mesh_gen_battery_status_cb_t Parameters of Generic Battery Status. Public Members uint32_t battery_level : 8 Value of Generic Battery Level state uint32_t time_to_discharge : 24 Value of Generic Battery Time to Discharge state uint32_t time_to_charge : 24 Value of Generic Battery Time to Charge state uint32_t flags : 8 Value of Generic Battery Flags state struct esp_ble_mesh_gen_loc_global_status_cb_t Parameters of Generic Location Global Status. Public Members int32_t global_latitude Global Coordinates (Latitude) int32_t global_longitude Global Coordinates (Longitude) Espressif Systems 396 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int16_t global_altitude Global Altitude struct esp_ble_mesh_gen_loc_local_status_cb_t Parameters of Generic Location Local Status. Public Members int16_t local_north Local Coordinates (North) int16_t local_east Local Coordinates (East) int16_t local_altitude Local Altitude uint8_t floor_number Floor Number uint16_t uncertainty Uncertainty struct esp_ble_mesh_gen_user_properties_status_cb_t Parameter of Generic User Properties Status. Public Members struct net_buf_simple *property_ids Buffer contains a sequence of N User Property IDs struct esp_ble_mesh_gen_user_property_status_cb_t Parameters of Generic User Property Status. Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property ID identifying a Generic User Property uint8_t user_access Enumeration indicating user access (optional) struct net_buf_simple *property_value Raw value for the User Property (C.1) struct esp_ble_mesh_gen_admin_properties_status_cb_t Parameter of Generic Admin Properties Status. Public Members struct net_buf_simple *property_ids Buffer contains a sequence of N Admin Property IDs struct esp_ble_mesh_gen_admin_property_status_cb_t Parameters of Generic Admin Property Status. Espressif Systems 397 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property ID identifying a Generic Admin Property uint8_t user_access Enumeration indicating user access (optional) struct net_buf_simple *property_value Raw value for the Admin Property (C.1) struct esp_ble_mesh_gen_manufacturer_properties_status_cb_t Parameter of Generic Manufacturer Properties Status. Public Members struct net_buf_simple *property_ids Buffer contains a sequence of N Manufacturer Property IDs struct esp_ble_mesh_gen_manufacturer_property_status_cb_t Parameters of Generic Manufacturer Property Status. Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property ID identifying a Generic Manufacturer Property uint8_t user_access Enumeration indicating user access (optional) struct net_buf_simple *property_value Raw value for the Manufacturer Property (C.1) struct esp_ble_mesh_gen_client_properties_status_cb_t Parameter of Generic Client Properties Status. Public Members struct net_buf_simple *property_ids Buffer contains a sequence of N Client Property IDs struct esp_ble_mesh_generic_client_cb_param_t Generic Client Model callback parameters Public Members int error_code Appropriate error code esp_ble_mesh_client_common_param_t *params The client common parameters. esp_ble_mesh_gen_client_status_cb_t status_cb The generic status message callback values Espressif Systems 398 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_gen_onoff_state_t Parameters of Generic OnOff state Public Members uint8_t onoff The present value of the Generic OnOff state uint8_t target_onoff The target value of the Generic OnOff state struct esp_ble_mesh_gen_onoff_srv_t User data of Generic OnOff Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic OnOff Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_onoff_state_t state Parameters of the Generic OnOff state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition struct esp_ble_mesh_gen_level_state_t Parameters of Generic Level state Public Members int16_t level The present value of the Generic Level state int16_t target_level The target value of the Generic Level state int16_t last_level When a new transaction starts, level should be set to last_last, and use 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 Espressif Systems 399 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_model_t *model Pointer to the Generic Level Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_level_state_t state Parameters of the Generic Level state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition int32_t tt_delta_level Delta change value of level state transition struct esp_ble_mesh_gen_def_trans_time_state_t Parameter of Generic Default Transition Time state Public Members uint8_t trans_time The value of the Generic Default Transition Time state struct esp_ble_mesh_gen_def_trans_time_srv_t User data of Generic Default Transition Time Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Default Transition Time Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_def_trans_time_state_t state Parameters of the Generic Default Transition Time state struct esp_ble_mesh_gen_onpowerup_state_t Parameter of Generic OnPowerUp state Public Members uint8_t onpowerup The value of the Generic OnPowerUp state struct esp_ble_mesh_gen_power_onoff_srv_t User data of Generic Power OnOff Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Power OnOff Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages Espressif Systems 400 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_gen_onpowerup_state_t *state Parameters of the Generic OnPowerUp state struct esp_ble_mesh_gen_power_onoff_setup_srv_t User data of Generic Power OnOff Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Power OnOff Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_onpowerup_state_t *state Parameters of the Generic OnPowerUp state struct esp_ble_mesh_gen_power_level_state_t Parameters of Generic Power Level state Public Members uint16_t power_actual The present value of the Generic Power Actual state uint16_t target_power_actual The target value of the Generic Power Actual state uint16_t power_last The value of the Generic Power Last state uint16_t power_default The value of the Generic Power Default state uint8_t status_code The status code of setting Generic Power Range state uint16_t power_range_min The minimum value of the Generic Power Range state uint16_t power_range_max The maximum value of the Generic Power Range state struct esp_ble_mesh_gen_power_level_srv_t User data of Generic Power Level Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Power Level Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_power_level_state_t *state Parameters of the Generic Power Level state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition Espressif Systems 401 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int32_t tt_delta_level Delta change value of level state transition struct esp_ble_mesh_gen_power_level_setup_srv_t User data of Generic Power Level Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Power Level Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_power_level_state_t *state Parameters of the Generic Power Level state struct esp_ble_mesh_gen_battery_state_t Parameters of Generic Battery state Public Members uint32_t battery_level : 8 The value of the Generic Battery Level state uint32_t time_to_discharge : 24 The value of the Generic Battery Time to Discharge state uint32_t time_to_charge : 24 The value of the Generic Battery Time to Charge state uint32_t battery_flags : 8 The value of the Generic Battery Flags state struct esp_ble_mesh_gen_battery_srv_t User data of Generic Battery Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Battery Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_battery_state_t state Parameters of the Generic Battery state struct esp_ble_mesh_gen_location_state_t Parameters of Generic Location state Public Members int32_t global_latitude The value of the Global Latitude field int32_t global_longitude The value of the Global Longitude field int16_t global_altitude The value of the Global Altitude field Espressif Systems 402 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int16_t local_north The value of the Local North field int16_t local_east The value of the Local East field int16_t local_altitude The value of the Local Altitude field uint8_t floor_number The value of the Floor Number field uint16_t uncertainty The value of the Uncertainty field struct esp_ble_mesh_gen_location_srv_t User data of Generic Location Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Location Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_location_state_t *state Parameters of the Generic Location state struct esp_ble_mesh_gen_location_setup_srv_t User data of Generic Location Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Location Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_gen_location_state_t *state Parameters of the Generic Location state struct esp_ble_mesh_generic_property_t Parameters of Generic Property states Public Members uint16_t id The value of User/Admin/Manufacturer Property ID uint8_t user_access The value of User Access field uint8_t admin_access The value of Admin Access field uint8_t manu_access The value of Manufacturer Access field struct net_buf_simple *val The value of User/Admin/Manufacturer Property Espressif Systems 403 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_gen_user_prop_srv_t User data of Generic User Property Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic User Property Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages uint8_t property_count Generic User Property count esp_ble_mesh_generic_property_t *properties Parameters of the Generic User Property state struct esp_ble_mesh_gen_admin_prop_srv_t User data of Generic Admin Property Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Admin Property Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages uint8_t property_count Generic Admin Property count esp_ble_mesh_generic_property_t *properties Parameters of the Generic Admin Property state struct esp_ble_mesh_gen_manu_prop_srv_t User data of Generic Manufacturer Property Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Manufacturer Property Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages uint8_t property_count Generic Manufacturer Property count esp_ble_mesh_generic_property_t *properties Parameters of the Generic Manufacturer Property state struct esp_ble_mesh_gen_client_prop_srv_t User data of Generic Client Property Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Generic Client Property Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages Espressif Systems 404 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t id_count Generic Client Property ID count uint16_t *property_ids Parameters of the Generic Client Property state struct esp_ble_mesh_state_change_gen_onoff_set_t Parameter of Generic OnOff Set state change event Public Members uint8_t onoff The value of Generic OnOff state struct esp_ble_mesh_state_change_gen_level_set_t Parameter of Generic Level Set state change event Public Members int16_t level The value of Generic Level state struct esp_ble_mesh_state_change_gen_delta_set_t Parameter of Generic Delta Set state change event Public Members int16_t level The value of Generic Level state struct esp_ble_mesh_state_change_gen_move_set_t Parameter of Generic Move Set state change event Public Members int16_t level The value of Generic Level state struct esp_ble_mesh_state_change_gen_def_trans_time_set_t Parameter of Generic Default Transition Time Set state change event Public Members uint8_t trans_time The value of Generic Default Transition Time state struct esp_ble_mesh_state_change_gen_onpowerup_set_t Parameter of Generic OnPowerUp Set state change event Public Members uint8_t onpowerup The value of Generic OnPowerUp state struct esp_ble_mesh_state_change_gen_power_level_set_t Parameter of Generic Power Level Set state change event Espressif Systems 405 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t power The value of Generic Power Actual state struct esp_ble_mesh_state_change_gen_power_default_set_t Parameter of Generic Power Default Set state change event Public Members uint16_t power The value of Generic Power Default state struct esp_ble_mesh_state_change_gen_power_range_set_t Parameters of Generic Power Range Set state change event Public Members uint16_t range_min The minimum value of Generic Power Range state uint16_t range_max The maximum value of Generic Power Range state struct esp_ble_mesh_state_change_gen_loc_global_set_t Parameters of Generic Location Global Set state change event Public Members int32_t latitude The Global Latitude value of Generic Location state int32_t longitude The Global Longitude value of Generic Location state int16_t altitude The Global Altitude value of Generic Location state struct esp_ble_mesh_state_change_gen_loc_local_set_t Parameters of Generic Location Local Set state change event Public Members int16_t north The Local North value of Generic Location state int16_t east The Local East value of Generic Location state int16_t altitude The Local Altitude value of Generic Location state uint8_t floor_number The Floor Number value of Generic Location state uint16_t uncertainty The Uncertainty value of Generic Location state struct esp_ble_mesh_state_change_gen_user_property_set_t Parameters of Generic User Property Set state change event Espressif Systems 406 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t id The property id of Generic User Property state struct net_buf_simple *value The property value of Generic User Property state struct esp_ble_mesh_state_change_gen_admin_property_set_t Parameters of Generic Admin Property Set state change event Public Members uint16_t id The property id of Generic Admin Property state uint8_t access The property access of Generic Admin Property state struct net_buf_simple *value The property value of Generic Admin Property state struct esp_ble_mesh_state_change_gen_manu_property_set_t Parameters of Generic Manufacturer Property Set state change event Public Members uint16_t id The property id of Generic Manufacturer Property state uint8_t access The property value of Generic Manufacturer Property state struct esp_ble_mesh_server_recv_gen_user_property_get_t Context of the received Generic User Property Get message Public Members uint16_t property_id Property ID identifying a Generic User Property struct esp_ble_mesh_server_recv_gen_admin_property_get_t Context of the received Generic Admin Property Get message Public Members uint16_t property_id Property ID identifying a Generic Admin Property struct esp_ble_mesh_server_recv_gen_manufacturer_property_get_t Context of the received Generic Manufacturer Property message Public Members uint16_t property_id Property ID identifying a Generic Manufacturer Property struct esp_ble_mesh_server_recv_gen_client_properties_get_t Context of the received Generic Client Properties Get message Espressif Systems 407 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t property_id A starting Client Property ID present within an element struct esp_ble_mesh_server_recv_gen_onoff_set_t Context of the received Generic OnOff Set message Public Members bool op_en Indicate if optional parameters are included uint8_t onoff Target value of Generic OnOff state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_gen_level_set_t Context of the received Generic Level Set message Public Members bool op_en Indicate if optional parameters are included int16_t level Target value of Generic Level state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_gen_delta_set_t Context of the received Generic Delta Set message Public Members bool op_en Indicate if optional parameters are included int32_t delta_level Delta change of Generic Level state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) Espressif Systems 408 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_gen_move_set_t Context of the received Generic Move Set message Public Members bool op_en Indicate if optional parameters are included int16_t delta_level Delta Level step to calculate Move speed for Generic Level state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_gen_def_trans_time_set_t Context of the received Generic Default Transition Time Set message Public Members uint8_t trans_time The value of the Generic Default Transition Time state struct esp_ble_mesh_server_recv_gen_onpowerup_set_t Context of the received Generic OnPowerUp Set message Public Members uint8_t onpowerup The value of the Generic OnPowerUp state struct esp_ble_mesh_server_recv_gen_power_level_set_t Context of the received Generic Power Level Set message Public Members bool op_en Indicate if optional parameters are included uint16_t power Target value of Generic Power Actual state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_gen_power_default_set_t Context of the received Generic Power Default Set message Espressif Systems 409 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t power The value of the Generic Power Default state struct esp_ble_mesh_server_recv_gen_power_range_set_t Context of the received Generic Power Range Set message Public Members uint16_t range_min Value of Range Min field of Generic Power Range state uint16_t range_max Value of Range Max field of Generic Power Range state struct esp_ble_mesh_server_recv_gen_loc_global_set_t Context of the received Generic Location Global Set message Public Members int32_t global_latitude Global Coordinates (Latitude) int32_t global_longitude Global Coordinates (Longitude) int16_t global_altitude Global Altitude struct esp_ble_mesh_server_recv_gen_loc_local_set_t Context of the received Generic Location Local Set message Public Members int16_t local_north Local Coordinates (North) int16_t local_east Local Coordinates (East) int16_t local_altitude Local Altitude uint8_t floor_number Floor Number uint16_t uncertainty Uncertainty struct esp_ble_mesh_server_recv_gen_user_property_set_t Context of the received Generic User Property Set message Public Members uint16_t property_id Property ID identifying a Generic User Property struct net_buf_simple *property_value Raw value for the User Property Espressif Systems 410 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_server_recv_gen_admin_property_set_t Context of the received Generic Admin Property Set message Public Members uint16_t property_id Property ID identifying a Generic Admin Property uint8_t user_access Enumeration indicating user access struct net_buf_simple *property_value Raw value for the Admin Property struct esp_ble_mesh_server_recv_gen_manufacturer_property_set_t Context of the received Generic Manufacturer Property Set message Public Members uint16_t property_id Property ID identifying a Generic Manufacturer Property uint8_t user_access Enumeration indicating user access struct esp_ble_mesh_generic_server_cb_param_t Generic Server Model callback parameters Public Members esp_ble_mesh_model_t *model Pointer to Generic Server Models esp_ble_mesh_msg_ctx_t ctx Context of the received messages esp_ble_mesh_generic_server_cb_value_t value Value of the received Generic Messages Macros ESP_BLE_MESH_MODEL_GEN_ONOFF_CLI(cli_pub, cli_data) Define a new Generic OnOff Client Model. Note This API needs to be called for each element on which the application needs to have a Generic OnOff Client Model. Return New Generic OnOff Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_GEN_LEVEL_CLI(cli_pub, cli_data) Define a new Generic Level Client Model. Note This API needs to be called for each element on which the application needs to have a Generic Level Client Model. Return New Generic Level Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. Espressif Systems 411 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_GEN_DEF_TRANS_TIME_CLI(cli_pub, cli_data) Define a new Generic Default Transition Time Client Model. Note This API needs to be called for each element on which the application needs to have a Generic Default Transition Time Client Model. Return New Generic Default Transition Time Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_CLI(cli_pub, cli_data) Define a new Generic Power OnOff Client Model. Note This API needs to be called for each element on which the application needs to have a Generic Power OnOff Client Model. Return New Generic Power OnOff Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_CLI(cli_pub, cli_data) Define a new Generic Power Level Client Model. Note This API needs to be called for each element on which the application needs to have a Generic Power Level Client Model. Return New Generic Power Level Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_GEN_BATTERY_CLI(cli_pub, cli_data) Define a new Generic Battery Client Model. Note This API needs to be called for each element on which the application needs to have a Generic Battery Client Model. Return New Generic Battery Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_GEN_LOCATION_CLI(cli_pub, cli_data) Define a new Generic Location Client Model. Note This API needs to be called for each element on which the application needs to have a Generic Location Client Model. Return New Generic Location Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_GEN_PROPERTY_CLI(cli_pub, cli_data) Define a new Generic Property Client Model. Note This API needs to be called for each element on which the application needs to have a Generic Property Client Model. Return New Generic Location Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_GEN_ONOFF_SRV(srv_pub, srv_data) Generic Server Models related context. Define a new Generic OnOff Server Model. Espressif Systems 412 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note 1. The Generic OnOff Server Model is a root model. 1. This model shall support model publication and model subscription. Return New Generic OnOff Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_onoff_srv_t. ESP_BLE_MESH_MODEL_GEN_LEVEL_SRV(srv_pub, srv_data) Define a new Generic Level Server Model. Note 1. The Generic Level Server Model is a root model. 1. This model shall support model publication and model subscription. Return New Generic Level Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_level_srv_t. ESP_BLE_MESH_MODEL_GEN_DEF_TRANS_TIME_SRV(srv_pub, srv_data) Define a new Generic Default Transition Time Server Model. Note 1. The Generic Default Transition Time Server Model is a root model. 1. This model shall support model publication and model subscription. Return New Generic Default Transition Time Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_def_trans_time_srv_t. ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_SRV(srv_pub, srv_data) Define a new Generic Power OnOff Server Model. Note 1. The Generic Power OnOff Server model extends the Generic OnOff Server model. When this model is present on an element, the corresponding Generic Power OnOff Setup Server model shall also be present. 1. This model may be used to represent a variety of devices that do not fit any of the model descriptions that have been defined but support the generic properties of On/Off. 2. This model shall support model publication and model subscription. Return New Generic Power OnOff Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_power_onoff_srv_t. ESP_BLE_MESH_MODEL_GEN_POWER_ONOFF_SETUP_SRV(srv_pub, srv_data) Define a new Generic Power OnOff Setup Server Model. Note 1. The Generic Power OnOff Setup Server model extends the Generic Power OnOff Server model and the Generic Default Transition Time Server model. 1. This model shall support model subscription. Return New Generic Power OnOff Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_power_onoff_setup_srv_t. ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_SRV(srv_pub, srv_data) Define a new Generic Power Level Server Model. Note 1. The Generic Power Level Server model extends the Generic Power OnOff Server model and the Generic Level Server model. When this model is present on an Element, the corresponding Generic Power Level Setup Server model shall also be present. 1. This model shall support model publication and model subscription. Return New Generic Power Level Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_power_level_srv_t. Espressif Systems 413 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_GEN_POWER_LEVEL_SETUP_SRV(srv_pub, srv_data) Define a new Generic Power Level Setup Server Model. Note 1. The Generic Power Level Setup Server model extends the Generic Power Level Server model and the Generic Power OnOff Setup Server model. 1. This model shall support model subscription. Return New Generic Power Level Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_power_level_setup_srv_t. ESP_BLE_MESH_MODEL_GEN_BATTERY_SRV(srv_pub, srv_data) Define a new Generic Battery Server Model. Note 1. The Generic Battery Server Model is a root model. 1. This model shall support model publication and model subscription. 2. The model may be used to represent an element that is powered by a battery. Return New Generic Battery Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_battery_srv_t. ESP_BLE_MESH_MODEL_GEN_LOCATION_SRV(srv_pub, srv_data) Define a new Generic Location Server Model. Note 1. The Generic Location Server model is a root model. When this model is present on an Element, the corresponding Generic Location Setup Server model shall also be present. 1. This model shall support model publication and model subscription. 2. The model may be used to represent an element that knows its location (global or local). Return New Generic Location Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_location_srv_t. ESP_BLE_MESH_MODEL_GEN_LOCATION_SETUP_SRV(srv_pub, srv_data) Define a new Generic Location Setup Server Model. Note 1. The Generic Location Setup Server model extends the Generic Location Server model. 1. This model shall support model subscription. Return New Generic Location Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_location_setup_srv_t. ESP_BLE_MESH_MODEL_GEN_USER_PROP_SRV(srv_pub, srv_data) Define a new Generic User Property Server Model. Note 1. The Generic User Property Server model is a root model. 1. This model shall support model publication and model subscription. Return New Generic User Property Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_user_prop_srv_t. ESP_BLE_MESH_MODEL_GEN_ADMIN_PROP_SRV(srv_pub, srv_data) Define a new Generic Admin Property Server Model. Note 1. The Generic Admin Property Server model extends the Generic User Property Server model. 1. This model shall support model publication and model subscription. Return New Generic Admin Property Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_admin_prop_srv_t. Espressif Systems 414 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_GEN_MANUFACTURER_PROP_SRV(srv_pub, srv_data) Define a new Generic Manufacturer Property Server Model. Note 1. The Generic Manufacturer Property Server model extends the Generic User Property Server model. 1. This model shall support model publication and model subscription. Return New Generic Manufacturer Property Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_manu_prop_srv_t. ESP_BLE_MESH_MODEL_GEN_CLIENT_PROP_SRV(srv_pub, srv_data) Define a new Generic User Property Server Model. Note 1. The Generic Client Property Server model is a root model. 1. This model shall support model publication and model subscription. Return New Generic Client Property Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_gen_client_prop_srv_t. Type Definitions typedef void (*esp_ble_mesh_generic_client_cb_t)(esp_ble_mesh_generic_client_cb_event_t event, esp_ble_mesh_generic_client_cb_param_t *param) Bluetooth Mesh Generic Client Model function. Generic Client Model callback function type Parameters · event: Event type · param: Pointer to callback parameter typedef void (*esp_ble_mesh_generic_server_cb_t)(esp_ble_mesh_generic_server_cb_event_t event, esp_ble_mesh_generic_server_cb_param_t 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 Espressif Systems 415 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_GEN_USER_ACCESS_READ ESP_BLE_MESH_GEN_USER_ACCESS_WRITE ESP_BLE_MESH_GEN_USER_ACCESS_READ_WRITE enum esp_ble_mesh_gen_admin_prop_access_t This enum value is the access value of Generic Admin Property Values: ESP_BLE_MESH_GEN_ADMIN_NOT_USER_PROP ESP_BLE_MESH_GEN_ADMIN_ACCESS_READ ESP_BLE_MESH_GEN_ADMIN_ACCESS_WRITE ESP_BLE_MESH_GEN_ADMIN_ACCESS_READ_WRITE enum esp_ble_mesh_gen_manu_prop_access_t This enum value is the access value of Generic Manufacturer Property Values: ESP_BLE_MESH_GEN_MANU_NOT_USER_PROP ESP_BLE_MESH_GEN_MANU_ACCESS_READ enum esp_ble_mesh_generic_server_cb_event_t This enum value is the event of Generic Server Model Values: ESP_BLE_MESH_GENERIC_SERVER_STATE_CHANGE_EVT 1. When get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, no event will be callback to the application layer when Generic Get messages are received. 2. When set_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, this event will be callback to the application layer when Generic Set/Set Unack messages are received. ESP_BLE_MESH_GENERIC_SERVER_RECV_GET_MSG_EVT When get_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Generic Get messages are received. ESP_BLE_MESH_GENERIC_SERVER_RECV_SET_MSG_EVT When set_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Generic Set/Set Unack messages are received. ESP_BLE_MESH_GENERIC_SERVER_EVT_MAX Sensor Client/Server Models Header File · components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h Functions esp_err_t esp_ble_mesh_register_sensor_client_callback(esp_ble_mesh_sensor_client_cb_t 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. Espressif Systems 416 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_ble_mesh_sensor_client_get_state(esp_ble_mesh_client_common_param_t *params, esp_ble_mesh_sensor_client_get_state_t *get_state) Get the value of Sensor Server Model states using the Sensor Client Model get messages. Note If you want to know the opcodes and corresponding meanings accepted by this API, please refer to esp_ble_mesh_sensor_message_opcode_t in esp_ble_mesh_defs.h Return ESP_OK on success or error code otherwise. Parameters · [in] params: Pointer to BLE Mesh common client parameters. · [in] get_state: Pointer to sensor get message value. Shall not be set to NULL. esp_err_t esp_ble_mesh_sensor_client_set_state(esp_ble_mesh_client_common_param_t *params, esp_ble_mesh_sensor_client_set_state_t *set_state) Set the value of Sensor Server Model states using the Sensor Client Model set messages. Note If you want to know the opcodes and corresponding meanings accepted by this API, please refer to esp_ble_mesh_sensor_message_opcode_t in esp_ble_mesh_defs.h Return ESP_OK on success or error code otherwise. Parameters · [in] params: Pointer to BLE Mesh common client parameters. · [in] set_state: Pointer to sensor set message value. Shall not be set to NULL. esp_err_t esp_ble_mesh_register_sensor_server_callback(esp_ble_mesh_sensor_server_cb_t 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. Espressif Systems 417 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_sensor_cadence_set_t cadence_set For ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET & ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET_UNACK esp_ble_mesh_sensor_setting_set_t setting_set For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET & ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET_UNACK union esp_ble_mesh_sensor_client_status_cb_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Client Model received message union. Public Members esp_ble_mesh_sensor_descriptor_status_cb_t descriptor_status For ESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_STATUS esp_ble_mesh_sensor_cadence_status_cb_t cadence_status For ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_STATUS esp_ble_mesh_sensor_settings_status_cb_t settings_status For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_STATUS esp_ble_mesh_sensor_setting_status_cb_t setting_status For ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_STATUS esp_ble_mesh_sensor_status_cb_t sensor_status For ESP_BLE_MESH_MODEL_OP_SENSOR_STATUS esp_ble_mesh_sensor_column_status_cb_t column_status For ESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_STATUS esp_ble_mesh_sensor_series_status_cb_t series_status For ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_STATUS union esp_ble_mesh_sensor_server_state_change_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model state change value union. Public Members esp_ble_mesh_state_change_sensor_cadence_set_t sensor_cadence_set The recv_op in ctx can be used to decide which state is changed. Sensor Cadence Set esp_ble_mesh_state_change_sensor_setting_set_t sensor_setting_set Sensor Setting Set union esp_ble_mesh_sensor_server_recv_get_msg_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model received get message union. Public Members esp_ble_mesh_server_recv_sensor_descriptor_get_t sensor_descriptor Sensor Descriptor Get esp_ble_mesh_server_recv_sensor_cadence_get_t sensor_cadence Sensor Cadence Get esp_ble_mesh_server_recv_sensor_settings_get_t sensor_settings Sensor Settings Get esp_ble_mesh_server_recv_sensor_setting_get_t sensor_setting Sensor Setting Get Espressif Systems 418 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_server_recv_sensor_get_t sensor_data Sensor Get esp_ble_mesh_server_recv_sensor_column_get_t sensor_column Sensor Column Get esp_ble_mesh_server_recv_sensor_series_get_t sensor_series Sensor Series Get union esp_ble_mesh_sensor_server_recv_set_msg_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model received set message union. Public Members esp_ble_mesh_server_recv_sensor_cadence_set_t sensor_cadence Sensor Cadence Set esp_ble_mesh_server_recv_sensor_setting_set_t sensor_setting Sensor Setting Set union esp_ble_mesh_sensor_server_cb_value_t #include <esp_ble_mesh_sensor_model_api.h> Sensor Server Model callback value union. Public Members esp_ble_mesh_sensor_server_state_change_t state_change ESP_BLE_MESH_SENSOR_SERVER_STATE_CHANGE_EVT esp_ble_mesh_sensor_server_recv_get_msg_t get ESP_BLE_MESH_SENSOR_SERVER_RECV_GET_MSG_EVT esp_ble_mesh_sensor_server_recv_set_msg_t set ESP_BLE_MESH_SENSOR_SERVER_RECV_SET_MSG_EVT Structures struct esp_ble_mesh_sensor_descriptor_get_t Bluetooth Mesh Sensor Client Model Get and Set parameters structure. Parameters of Sensor Descriptor Get Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property ID of a sensor (optional) struct esp_ble_mesh_sensor_cadence_get_t Parameter of Sensor Cadence Get Public Members uint16_t property_id Property ID of a sensor struct esp_ble_mesh_sensor_cadence_set_t Parameters of Sensor Cadence Set Espressif Systems 419 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t property_id Property ID for the sensor uint8_t fast_cadence_period_divisor : 7 Divisor for the publish period uint8_t status_trigger_type : 1 The unit and format of the Status Trigger Delta fields struct net_buf_simple *status_trigger_delta_down Delta down value that triggers a status message struct net_buf_simple *status_trigger_delta_up Delta up value that triggers a status message uint8_t status_min_interval Minimum interval between two consecutive Status messages struct net_buf_simple *fast_cadence_low Low value for the fast cadence range struct net_buf_simple *fast_cadence_high Fast value for the fast cadence range struct esp_ble_mesh_sensor_settings_get_t Parameter of Sensor Settings Get Public Members uint16_t sensor_property_id Property ID of a sensor struct esp_ble_mesh_sensor_setting_get_t Parameters of Sensor Setting Get Public Members uint16_t sensor_property_id Property ID of a sensor uint16_t sensor_setting_property_id Setting ID identifying a setting within a sensor struct esp_ble_mesh_sensor_setting_set_t Parameters of Sensor Setting Set Public Members uint16_t sensor_property_id Property ID identifying a sensor uint16_t sensor_setting_property_id Setting ID identifying a setting within a sensor struct net_buf_simple *sensor_setting_raw Raw value for the setting struct esp_ble_mesh_sensor_get_t Parameters of Sensor Get Espressif Systems 420 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property ID for the sensor (optional) struct esp_ble_mesh_sensor_column_get_t Parameters of Sensor Column Get Public Members uint16_t property_id Property identifying a sensor struct net_buf_simple *raw_value_x Raw value identifying a column struct esp_ble_mesh_sensor_series_get_t Parameters of Sensor Series Get Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property identifying a sensor struct net_buf_simple *raw_value_x1 Raw value identifying a starting column (optional) struct net_buf_simple *raw_value_x2 Raw value identifying an ending column (C.1) struct esp_ble_mesh_sensor_descriptor_status_cb_t Bluetooth Mesh Sensor Client Model Get and Set callback parameters structure. Parameter of Sensor Descriptor Status Public Members struct net_buf_simple *descriptor Sequence of 8-octet sensor descriptors (optional) struct esp_ble_mesh_sensor_cadence_status_cb_t Parameters of Sensor Cadence Status Public Members uint16_t property_id Property for the sensor struct net_buf_simple *sensor_cadence_value Value of sensor cadence state struct esp_ble_mesh_sensor_settings_status_cb_t Parameters of Sensor Settings Status Espressif Systems 421 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t sensor_property_id Property ID identifying a sensor struct net_buf_simple *sensor_setting_property_ids A sequence of N sensor setting property IDs (optional) struct esp_ble_mesh_sensor_setting_status_cb_t Parameters of Sensor Setting Status Public Members bool op_en Indicate id optional parameters are included uint16_t sensor_property_id Property ID identifying a sensor uint16_t sensor_setting_property_id Setting ID identifying a setting within a sensor uint8_t sensor_setting_access Read/Write access rights for the setting (optional) struct net_buf_simple *sensor_setting_raw Raw value for the setting struct esp_ble_mesh_sensor_status_cb_t Parameter of Sensor Status Public Members struct net_buf_simple *marshalled_sensor_data Value of sensor data state (optional) struct esp_ble_mesh_sensor_column_status_cb_t Parameters of Sensor Column Status Public Members uint16_t property_id Property identifying a sensor and the Y axis struct net_buf_simple *sensor_column_value Left values of sensor column status struct esp_ble_mesh_sensor_series_status_cb_t Parameters of Sensor Series Status Public Members uint16_t property_id Property identifying a sensor and the Y axis struct net_buf_simple *sensor_series_value Left values of sensor series status struct esp_ble_mesh_sensor_client_cb_param_t Sensor Client Model callback parameters Espressif Systems 422 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members int error_code 0: success, otherwise failure. For the error code values please refer to errno.h file. A negative sign is added to the standard error codes in errno.h. esp_ble_mesh_client_common_param_t *params The client common parameters. esp_ble_mesh_sensor_client_status_cb_t status_cb The sensor status message callback values struct esp_ble_mesh_sensor_descriptor_t Parameters of Sensor Descriptor state Public Members uint32_t positive_tolerance : 12 The value of Sensor Positive Tolerance field uint32_t negative_tolerance : 12 The value of Sensor Negative Tolerance field uint32_t sampling_function : 8 The value of Sensor Sampling Function field uint8_t measure_period The value of Sensor Measurement Period field uint8_t update_interval The value of Sensor Update Interval field struct esp_ble_mesh_sensor_setting_t Parameters of Sensor Setting state Public Members uint16_t property_id The value of Sensor Setting Property ID field uint8_t access The value of Sensor Setting Access field struct net_buf_simple *raw The value of Sensor Setting Raw field struct esp_ble_mesh_sensor_cadence_t Parameters of Sensor Cadence state Public Members uint8_t period_divisor : 7 The value of Fast Cadence Period Divisor field uint8_t trigger_type : 1 The value of Status Trigger Type field struct net_buf_simple *trigger_delta_down Note: The parameter 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 Espressif Systems 423 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct net_buf_simple *trigger_delta_up The value of Status Trigger Delta Up field uint8_t min_interval The value of Status Min Interval field struct net_buf_simple *fast_cadence_low The value of Fast Cadence Low field struct net_buf_simple *fast_cadence_high The value of Fast Cadence High field struct esp_ble_mesh_sensor_data_t Parameters of Sensor Data state Public Members uint8_t format : 1 Format A: The Length field is a 1-based uint4 value (valid range 0x00xF, representing range of 1 16). 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 Espressif Systems 424 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_sensor_cadence_t *cadence The Sensor Cadence state may be not supported by sensors based on device properties 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 const uint8_t state_count Sensor state count esp_ble_mesh_sensor_state_t *states Parameters of the Sensor states struct esp_ble_mesh_sensor_setup_srv_t User data of Sensor Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Sensor Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages const uint8_t state_count Sensor state count esp_ble_mesh_sensor_state_t *states Parameters of the Sensor states struct esp_ble_mesh_state_change_sensor_cadence_set_t Parameters of Sensor Cadence Set state change event Public Members uint16_t property_id The value of Sensor Property ID state uint8_t period_divisor : 7 The value of Fast Cadence Period Divisor state uint8_t trigger_type : 1 The value of Status Trigger Type state struct net_buf_simple *trigger_delta_down The value of Status Trigger Delta Down state Espressif Systems 425 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct net_buf_simple *trigger_delta_up The value of Status Trigger Delta Up state uint8_t min_interval The value of Status Min Interval state struct net_buf_simple *fast_cadence_low The value of Fast Cadence Low state struct net_buf_simple *fast_cadence_high The value of Fast Cadence High state struct esp_ble_mesh_state_change_sensor_setting_set_t Parameters of Sensor Setting Set state change event Public Members uint16_t property_id The value of Sensor Property ID state uint16_t setting_property_id The value of Sensor Setting Property ID state struct net_buf_simple *setting_value The value of Sensor Property Value state struct esp_ble_mesh_server_recv_sensor_descriptor_get_t Context of the received Sensor Descriptor Get message Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property ID of a sensor (optional) struct esp_ble_mesh_server_recv_sensor_cadence_get_t Context of the received Sensor Cadence Get message Public Members uint16_t property_id Property ID of a sensor struct esp_ble_mesh_server_recv_sensor_settings_get_t Context of the received Sensor Settings Get message Public Members uint16_t property_id Property ID of a sensor struct esp_ble_mesh_server_recv_sensor_setting_get_t Context of the received Sensor Setting Get message Espressif Systems 426 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t property_id Property ID of a sensor uint16_t setting_property_id Setting ID identifying a setting within a sensor struct esp_ble_mesh_server_recv_sensor_get_t Context of the received Sensor Get message Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property ID for the sensor (optional) struct esp_ble_mesh_server_recv_sensor_column_get_t Context of the received Sensor Column Get message Public Members uint16_t property_id Property identifying a sensor struct net_buf_simple *raw_value_x Raw value identifying a column struct esp_ble_mesh_server_recv_sensor_series_get_t Context of the received Sensor Series Get message Public Members bool op_en Indicate if optional parameters are included uint16_t property_id Property identifying a sensor struct net_buf_simple *raw_value Raw value containing X1 and X2 (optional) struct esp_ble_mesh_server_recv_sensor_cadence_set_t Context of the received Sensor Cadence Set message Public Members uint16_t property_id Property ID for the sensor struct net_buf_simple *cadence Value of Sensor Cadence state struct esp_ble_mesh_server_recv_sensor_setting_set_t Context of the received Sensor Setting Set message Espressif Systems 427 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t property_id Property ID identifying a sensor uint16_t setting_property_id Setting ID identifying a setting within a sensor struct net_buf_simple *setting_raw Raw value for the setting struct esp_ble_mesh_sensor_server_cb_param_t Sensor Server Model callback parameters Public Members esp_ble_mesh_model_t *model Pointer to Sensor Server Models esp_ble_mesh_msg_ctx_t ctx Context of the received messages esp_ble_mesh_sensor_server_cb_value_t value Value of the received Sensor Messages Macros ESP_BLE_MESH_MODEL_SENSOR_CLI(cli_pub, cli_data) Define a new Sensor Client Model. Note This API needs to be called for each element on which the application needs to have a Sensor Client Model. Return New Sensor Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_SENSOR_SRV(srv_pub, srv_data) Sensor Server Models related context. Define a new Sensor Server Model. Note 1. The Sensor Server model is a root model. When this model is present on an element, the corresponding Sensor Setup Server model shall also be present. 1. This model shall support model publication and model subscription. Return New Sensor Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_sensor_srv_t. ESP_BLE_MESH_MODEL_SENSOR_SETUP_SRV(srv_pub, srv_data) Define a new Sensor Setup Server Model. Note 1. The Sensor Setup Server model extends the Sensor Server model. 1. This model shall support model publication and model subscription. Return New Sensor Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_sensor_setup_srv_t. ESP_BLE_MESH_INVALID_SENSOR_PROPERTY_ID Invalid Sensor Property ID ESP_BLE_MESH_SENSOR_PROPERTY_ID_LEN Length of Sensor Property ID Espressif Systems 428 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_SENSOR_DESCRIPTOR_LEN Length of Sensor Descriptor state ESP_BLE_MESH_SENSOR_UNSPECIFIED_POS_TOLERANCE Unspecified Sensor Positive Tolerance ESP_BLE_MESH_SENSOR_UNSPECIFIED_NEG_TOLERANCE Unspecified Sensor Negative Tolerance ESP_BLE_MESH_SENSOR_NOT_APPL_MEASURE_PERIOD Not applicable Sensor Measurement Period ESP_BLE_MESH_SENSOR_NOT_APPL_UPDATE_INTERVAL Not applicable Sensor Update Interval ESP_BLE_MESH_INVALID_SENSOR_SETTING_PROPERTY_ID Invalid Sensor Setting Property ID ESP_BLE_MESH_SENSOR_SETTING_PROPERTY_ID_LEN Length of Sensor Setting Property ID ESP_BLE_MESH_SENSOR_SETTING_ACCESS_LEN Length of Sensor Setting Access ESP_BLE_MESH_SENSOR_SETTING_ACCESS_READ Sensor Setting Access - Read ESP_BLE_MESH_SENSOR_SETTING_ACCESS_READ_WRITE Sensor Setting Access - Read & Write ESP_BLE_MESH_SENSOR_DIVISOR_TRIGGER_TYPE_LEN Length of Sensor Divisor Trigger Type ESP_BLE_MESH_SENSOR_STATUS_MIN_INTERVAL_LEN Length of Sensor Status Min Interval ESP_BLE_MESH_SENSOR_PERIOD_DIVISOR_MAX_VALUE Maximum value of Sensor Period Divisor ESP_BLE_MESH_SENSOR_STATUS_MIN_INTERVAL_MAX Maximum value of Sensor Status Min Interval ESP_BLE_MESH_SENSOR_STATUS_TRIGGER_TYPE_CHAR Sensor Status Trigger Type - Format Type of the characteristic that the Sensor Property ID state references ESP_BLE_MESH_SENSOR_STATUS_TRIGGER_TYPE_UINT16 Sensor Status Trigger Type - Format Type 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. Espressif Systems 429 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note Multiple sensor data may be concatenated. Make sure the _data pointer is updated before getting the format of the corresponding sensor data. Return Format of the sensor data. Parameters · _data: Pointer to the start of the sensor data. ESP_BLE_MESH_GET_SENSOR_DATA_LENGTH(_data, _fmt) Get length of the sensor data. Note Multiple sensor data may be concatenated. Make sure the _data pointer is updated before getting the length of the corresponding sensor data. Return Length (zero-based) of the sensor data. Parameters · _data: Pointer to the start of the sensor data. · _fmt: Format of the sensor data. ESP_BLE_MESH_GET_SENSOR_DATA_PROPERTY_ID(_data, _fmt) Get Sensor Property ID of the sensor data. Note Multiple sensor data may be concatenated. Make sure the _data pointer is updated before getting Sensor Property ID of the corresponding sensor data. Return Sensor Property ID of the sensor data. Parameters · _data: Pointer to the start of the sensor data. · _fmt: Format of the sensor data. ESP_BLE_MESH_SENSOR_DATA_FORMAT_A_MPID(_len, _id) Generate a MPID value for sensor data with Format A. Note 1. The Format field is 0b0 and indicates that Format A is used. 1. The Length field is a 1-based uint4 value (valid range 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 Espressif Systems 430 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · event: Event type · param: Pointer to callback parameter typedef void (*esp_ble_mesh_sensor_server_cb_t)(esp_ble_mesh_sensor_server_cb_event_t event, esp_ble_mesh_sensor_server_cb_param_t *param) Bluetooth Mesh Sensor Server Model function. Sensor Server Model callback function type Parameters · event: Event type · param: Pointer to callback parameter Enumerations enum esp_ble_mesh_sensor_client_cb_event_t This enum value is the event of Sensor Client Model Values: ESP_BLE_MESH_SENSOR_CLIENT_GET_STATE_EVT ESP_BLE_MESH_SENSOR_CLIENT_SET_STATE_EVT ESP_BLE_MESH_SENSOR_CLIENT_PUBLISH_EVT ESP_BLE_MESH_SENSOR_CLIENT_TIMEOUT_EVT ESP_BLE_MESH_SENSOR_CLIENT_EVT_MAX enum esp_ble_mesh_sensor_sample_func This enum value is value of Sensor Sampling Function Values: ESP_BLE_MESH_SAMPLE_FUNC_UNSPECIFIED ESP_BLE_MESH_SAMPLE_FUNC_INSTANTANEOUS ESP_BLE_MESH_SAMPLE_FUNC_ARITHMETIC_MEAN ESP_BLE_MESH_SAMPLE_FUNC_RMS ESP_BLE_MESH_SAMPLE_FUNC_MAXIMUM ESP_BLE_MESH_SAMPLE_FUNC_MINIMUM ESP_BLE_MESH_SAMPLE_FUNC_ACCUMULATED ESP_BLE_MESH_SAMPLE_FUNC_COUNT enum esp_ble_mesh_sensor_server_cb_event_t This enum value is the event of Sensor Server Model Values: ESP_BLE_MESH_SENSOR_SERVER_STATE_CHANGE_EVT 1. When get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, no event will be callback to the application layer when Sensor Get messages are received. 2. When set_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, this event will be callback to the application layer when Sensor Set/Set Unack messages are received. ESP_BLE_MESH_SENSOR_SERVER_RECV_GET_MSG_EVT When get_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Sensor Get messages are received. ESP_BLE_MESH_SENSOR_SERVER_RECV_SET_MSG_EVT When set_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Sensor Set/Set Unack messages are received. ESP_BLE_MESH_SENSOR_SERVER_EVT_MAX Espressif Systems 431 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Time and Scenes Client/Server Models Header File · components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h Functions esp_err_t esp_ble_mesh_register_time_scene_client_callback(esp_ble_mesh_time_scene_client_cb_t 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 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. Espressif Systems 432 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_time_set_t time_set For ESP_BLE_MESH_MODEL_OP_TIME_SET esp_ble_mesh_time_zone_set_t time_zone_set For ESP_BLE_MESH_MODEL_OP_TIME_ZONE_SET esp_ble_mesh_tai_utc_delta_set_t tai_utc_delta_set For ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_SET esp_ble_mesh_time_role_set_t time_role_set For ESP_BLE_MESH_MODEL_OP_TIME_ROLE_SET esp_ble_mesh_scene_store_t scene_store For ESP_BLE_MESH_MODEL_OP_SCENE_STORE & ESP_BLE_MESH_MODEL_OP_SCENE_STORE_UNACK esp_ble_mesh_scene_recall_t scene_recall For ESP_BLE_MESH_MODEL_OP_SCENE_RECALL & ESP_BLE_MESH_MODEL_OP_SCENE_RECALL_UNAC esp_ble_mesh_scene_delete_t scene_delete For ESP_BLE_MESH_MODEL_OP_SCENE_DELETE & ESP_BLE_MESH_MODEL_OP_SCENE_DELETE_UNAC esp_ble_mesh_scheduler_act_set_t scheduler_act_set For ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET & ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET_UNACK union esp_ble_mesh_time_scene_client_status_cb_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Client Model received message union. Public Members esp_ble_mesh_time_status_cb_t time_status For ESP_BLE_MESH_MODEL_OP_TIME_STATUS esp_ble_mesh_time_zone_status_cb_t time_zone_status For ESP_BLE_MESH_MODEL_OP_TIME_ZONE_STATUS esp_ble_mesh_tai_utc_delta_status_cb_t tai_utc_delta_status For ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_STATUS esp_ble_mesh_time_role_status_cb_t time_role_status For ESP_BLE_MESH_MODEL_OP_TIME_ROLE_STATUS esp_ble_mesh_scene_status_cb_t scene_status For ESP_BLE_MESH_MODEL_OP_SCENE_STATUS esp_ble_mesh_scene_register_status_cb_t scene_register_status For ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_STATUS esp_ble_mesh_scheduler_status_cb_t scheduler_status For ESP_BLE_MESH_MODEL_OP_SCHEDULER_STATUS esp_ble_mesh_scheduler_act_status_cb_t scheduler_act_status For ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_STATUS union esp_ble_mesh_time_scene_server_state_change_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model state change value union. Public Members esp_ble_mesh_state_change_time_set_t time_set The recv_op in ctx can be used to decide which state is changed. Time Set Espressif Systems 433 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_state_change_time_status_t time_status Time Status esp_ble_mesh_state_change_time_zone_set_t time_zone_set Time Zone Set esp_ble_mesh_state_change_tai_utc_delta_set_t tai_utc_delta_set TAI UTC Delta Set esp_ble_mesh_state_change_time_role_set_t time_role_set Time Role Set esp_ble_mesh_state_change_scene_store_t scene_store Scene Store esp_ble_mesh_state_change_scene_recall_t scene_recall Scene Recall esp_ble_mesh_state_change_scene_delete_t scene_delete Scene Delete esp_ble_mesh_state_change_scheduler_act_set_t scheduler_act_set Scheduler Action Set union esp_ble_mesh_time_scene_server_recv_get_msg_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received get message union. Public Members esp_ble_mesh_server_recv_scheduler_act_get_t scheduler_act Scheduler Action Get union esp_ble_mesh_time_scene_server_recv_set_msg_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received set message union. Public Members esp_ble_mesh_server_recv_time_set_t time Time Set esp_ble_mesh_server_recv_time_zone_set_t time_zone Time Zone Set esp_ble_mesh_server_recv_tai_utc_delta_set_t tai_utc_delta TAI-UTC Delta Set esp_ble_mesh_server_recv_time_role_set_t time_role Time Role Set esp_ble_mesh_server_recv_scene_store_t scene_store Scene Store/Scene Store Unack esp_ble_mesh_server_recv_scene_recall_t scene_recall Scene Recall/Scene Recall Unack esp_ble_mesh_server_recv_scene_delete_t scene_delete Scene Delete/Scene Delete Unack esp_ble_mesh_server_recv_scheduler_act_set_t scheduler_act Scheduler Action Set/Scheduler Action Set Unack union esp_ble_mesh_time_scene_server_recv_status_msg_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model received status message union. Espressif Systems 434 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_server_recv_time_status_t time_status Time Status union esp_ble_mesh_time_scene_server_cb_value_t #include <esp_ble_mesh_time_scene_model_api.h> Time Scene Server Model callback value union. Public Members esp_ble_mesh_time_scene_server_state_change_t state_change ESP_BLE_MESH_TIME_SCENE_SERVER_STATE_CHANGE_EVT esp_ble_mesh_time_scene_server_recv_get_msg_t get ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_GET_MSG_EVT esp_ble_mesh_time_scene_server_recv_set_msg_t set ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_SET_MSG_EVT esp_ble_mesh_time_scene_server_recv_status_msg_t status ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_STATUS_MSG_EVT Structures struct esp_ble_mesh_time_set_t Bluetooth Mesh Time Scene Client Model Get and Set parameters structure. Parameters of Time Set Public Members uint8_t tai_seconds[5] The current TAI time in seconds uint8_t sub_second The sub-second time in units of 1/256 second uint8_t uncertainty The estimated uncertainty in 10-millisecond steps uint16_t time_authority : 1 0 = No Time Authority, 1 = Time Authority uint16_t tai_utc_delta : 15 Current difference between TAI and UTC in seconds uint8_t time_zone_offset The local time zone offset in 15-minute increments struct esp_ble_mesh_time_zone_set_t Parameters of Time Zone Set Public Members uint8_t time_zone_offset_new Upcoming local time zone offset uint8_t tai_zone_change[5] TAI Seconds time of the upcoming Time Zone Offset change struct esp_ble_mesh_tai_utc_delta_set_t Parameters of TAI-UTC Delta Set Espressif Systems 435 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t tai_utc_delta_new : 15 Upcoming difference between TAI and UTC in seconds uint16_t padding : 1 Always 0b0. Other values are Prohibited. uint8_t tai_delta_change[5] TAI Seconds time of the upcoming TAI-UTC Delta change struct esp_ble_mesh_time_role_set_t Parameter of Time Role Set Public Members uint8_t time_role The Time Role for the element struct esp_ble_mesh_scene_store_t Parameter of Scene Store Public Members uint16_t scene_number The number of scenes to be stored struct esp_ble_mesh_scene_recall_t Parameters of Scene Recall Public Members bool op_en Indicate if optional parameters are included uint16_t scene_number The number of scenes to be recalled uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_scene_delete_t Parameter of Scene Delete Public Members uint16_t scene_number The number of scenes to be deleted struct esp_ble_mesh_scheduler_act_get_t Parameter of Scheduler Action Get Espressif Systems 436 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t index Index of the Schedule Register entry to get struct esp_ble_mesh_scheduler_act_set_t Parameters of Scheduler Action Set Public Members uint64_t index : 4 Index of the Schedule Register entry to set uint64_t year : 7 Scheduled year for the action uint64_t month : 12 Scheduled month for the action uint64_t day : 5 Scheduled day of the month for the action uint64_t hour : 5 Scheduled hour for the action uint64_t minute : 6 Scheduled minute for the action uint64_t second : 6 Scheduled second for the action uint64_t day_of_week : 7 Schedule days of the week for the action uint64_t action : 4 Action to be performed at the scheduled time uint64_t trans_time : 8 Transition time for this action uint16_t scene_number Transition time for this action struct esp_ble_mesh_time_status_cb_t Bluetooth Mesh Time Scene Client Model Get and Set callback parameters structure. Parameters of Time Status Public Members uint8_t tai_seconds[5] The current TAI time in seconds uint8_t sub_second The sub-second time in units of 1/256 second uint8_t uncertainty The estimated uncertainty in 10-millisecond steps uint16_t time_authority : 1 0 = No Time Authority, 1 = Time Authority uint16_t tai_utc_delta : 15 Current difference between TAI and UTC in seconds Espressif Systems 437 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t time_zone_offset The local time zone offset in 15-minute increments struct esp_ble_mesh_time_zone_status_cb_t Parameters of Time Zone Status Public Members uint8_t time_zone_offset_curr Current local time zone offset uint8_t time_zone_offset_new Upcoming local time zone offset uint8_t tai_zone_change[5] TAI Seconds time of the upcoming Time Zone Offset change struct esp_ble_mesh_tai_utc_delta_status_cb_t Parameters of TAI-UTC Delta Status Public Members uint16_t tai_utc_delta_curr : 15 Current difference between TAI and UTC in seconds uint16_t padding_1 : 1 Always 0b0. Other values are Prohibited. uint16_t tai_utc_delta_new : 15 Upcoming difference between TAI and UTC in seconds uint16_t padding_2 : 1 Always 0b0. Other values are Prohibited. uint8_t tai_delta_change[5] TAI Seconds time of the upcoming TAI-UTC Delta change struct esp_ble_mesh_time_role_status_cb_t Parameter of Time Role Status Public Members uint8_t time_role The Time Role for the element struct esp_ble_mesh_scene_status_cb_t Parameters of Scene Status Public Members bool op_en Indicate if optional parameters are included uint8_t status_code Status code of the last operation uint16_t current_scene Scene Number of the current scene uint16_t target_scene Scene Number of the target scene (optional) Espressif Systems 438 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_scene_register_status_cb_t Parameters of Scene Register Status Public Members uint8_t status_code Status code for the previous operation uint16_t current_scene Scene Number of the current scene struct net_buf_simple *scenes A list of scenes stored within an element struct esp_ble_mesh_scheduler_status_cb_t Parameter of Scheduler Status Public Members uint16_t schedules Bit field indicating defined Actions in the Schedule Register struct esp_ble_mesh_scheduler_act_status_cb_t Parameters of Scheduler Action Status Public Members uint64_t index : 4 Enumerates (selects) a Schedule Register entry uint64_t year : 7 Scheduled year for the action uint64_t month : 12 Scheduled month for the action uint64_t day : 5 Scheduled day of the month for the action uint64_t hour : 5 Scheduled hour for the action uint64_t minute : 6 Scheduled minute for the action uint64_t second : 6 Scheduled second for the action uint64_t day_of_week : 7 Schedule days of the week for the action uint64_t action : 4 Action to be performed at the scheduled time uint64_t trans_time : 8 Transition time for this action uint16_t scene_number Transition time for this action Espressif Systems 439 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_time_scene_client_cb_param_t Time Scene Client Model callback parameters Public Members int error_code Appropriate error code esp_ble_mesh_client_common_param_t *params The client common parameters. esp_ble_mesh_time_scene_client_status_cb_t status_cb The scene status message callback values struct esp_ble_mesh_time_state_t Parameters of Time state Public Members uint8_t tai_seconds[5] The value of the TAI Seconds state uint8_t subsecond The value of the Subsecond field uint8_t uncertainty The value of the Uncertainty field uint8_t time_zone_offset_curr The value of the Time Zone Offset Current field uint8_t time_zone_offset_new The value of the Time Zone Offset New state uint8_t tai_zone_change[5] The value of the TAI of Zone Chaneg field uint16_t time_authority : 1 The value of the Time Authority bit uint16_t tai_utc_delta_curr : 15 The value of the TAI-UTC Delta Current state uint16_t tai_utc_delta_new : 15 The value of the TAI-UTC Delta New state uint8_t tai_delta_change[5] The value of the TAI of Delta Change field struct esp_ble_mesh_time_state_t::[anonymous] time Parameters of the Time state uint8_t time_role The value of the Time Role state struct esp_ble_mesh_time_srv_t User data of Time Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Time Server Model. Initialized internally. Espressif Systems 440 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_time_state_t *state Parameters of the Time state struct esp_ble_mesh_time_setup_srv_t User data of Time Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Time Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_time_state_t *state Parameters of the Time state struct esp_ble_mesh_scene_register_t 1. Scene Store is an operation of storing values of a present state of an element. 2. The structure and meaning of the stored state is determined by a model. States to be stored are specified by each model. 3. The Scene Store operation shall persistently store all values of all states marked as Stored with Scene for all models present on all elements of a node. 4. If a model is extending another model, the extending model shall determine the Stored with Scene be- havior of that model. Parameters of Scene Register state Public Members uint16_t scene_number The value of the Scene Number uint8_t scene_type The value of the Scene Type struct net_buf_simple *scene_value Scene value may use a union to represent later, the union contains structures of all the model states which can be stored in a scene. The value of the Scene Value struct esp_ble_mesh_scenes_state_t Parameters of Scenes state. Scenes serve as memory banks for storage of states (e.g., a power level or a light level/color). Values of states of an element can be stored as a scene and can be recalled later from the scene memory. A scene is represented by a Scene Number, which is a 16-bit non-zero, mesh-wide value. (There can be a maximum of 65535 scenes in a mesh network.) The meaning of a scene, as well as the state storage container associated with it, are determined by a model. The Scenes state change may start numerous parallel model transitions. In that case, each individual model handles the transition internally. The scene transition is defined as a group of individual model transitions started by a Scene Recall operation. The scene transition is in progress when at least one transition from the group of individual model transitions is in progress. Espressif Systems 441 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. When the scene transition is not in progress, the value of the Target Scene state shall be set to 0x0000. The value of the Target Scene state uint8_t status_code The status code of the last scene operation bool in_progress Indicate if the scene transition is in progress struct esp_ble_mesh_scene_srv_t User data of Scene Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Scene Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_scenes_state_t *state Parameters of the Scenes state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition struct esp_ble_mesh_scene_setup_srv_t User data of Scene Setup Server Model Espressif Systems 442 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_model_t *model Pointer to the Scene Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_scenes_state_t *state Parameters of the Scenes state struct esp_ble_mesh_schedule_register_t Parameters of Scheduler Register state Public Members bool in_use Indicate if the registered schedule is in use uint64_t year : 7 The value of Scheduled year for the action uint64_t month : 12 The value of Scheduled month for the action uint64_t day : 5 The value of Scheduled day of the month for the action uint64_t hour : 5 The value of Scheduled hour for the action uint64_t minute : 6 The value of Scheduled minute for the action uint64_t second : 6 The value of Scheduled second for the action uint64_t day_of_week : 7 The value of Schedule days of the week for the action uint64_t action : 4 The value of Action to be performed at the scheduled time uint64_t trans_time : 8 The value of Transition time for this action uint16_t scene_number The value of Scene Number to be used for some actions struct esp_ble_mesh_scheduler_state_t Parameters of Scheduler state Public Members const uint8_t schedule_count Scheduler count esp_ble_mesh_schedule_register_t *schedules Up to 16 scheduled entries struct esp_ble_mesh_scheduler_srv_t User data of Scheduler Server Model Espressif Systems 443 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_model_t *model Pointer to the Scheduler Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_scheduler_state_t *state Parameters of the Scheduler state struct esp_ble_mesh_scheduler_setup_srv_t User data of Scheduler Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Scheduler Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_scheduler_state_t *state Parameters of the Scheduler state struct esp_ble_mesh_state_change_time_set_t Parameters of Time Set state change event Public Members uint8_t tai_seconds[5] The current TAI time in seconds uint8_t subsecond The sub-second time in units of 1/256 second uint8_t uncertainty The estimated uncertainty in 10-millisecond steps uint16_t time_authority : 1 0 = No Time Authority, 1 = Time Authority uint16_t tai_utc_delta_curr : 15 Current difference between TAI and UTC in seconds uint8_t time_zone_offset_curr The local time zone offset in 15-minute increments struct esp_ble_mesh_state_change_time_status_t Parameters of Time Status state change event Public Members uint8_t tai_seconds[5] The current TAI time in seconds uint8_t subsecond The sub-second time in units of 1/256 second uint8_t uncertainty The estimated uncertainty in 10-millisecond steps Espressif Systems 444 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t time_authority : 1 0 = No Time Authority, 1 = Time Authority uint16_t tai_utc_delta_curr : 15 Current difference between TAI and UTC in seconds uint8_t time_zone_offset_curr The local time zone offset in 15-minute increments struct esp_ble_mesh_state_change_time_zone_set_t Parameters of Time Zone Set state change event Public Members uint8_t time_zone_offset_new Upcoming local time zone offset uint8_t tai_zone_change[5] TAI Seconds time of the upcoming Time Zone Offset change struct esp_ble_mesh_state_change_tai_utc_delta_set_t Parameters of TAI UTC Delta Set state change event Public Members uint16_t tai_utc_delta_new : 15 Upcoming difference between TAI and UTC in seconds uint8_t tai_delta_change[5] TAI Seconds time of the upcoming TAI-UTC Delta change struct esp_ble_mesh_state_change_time_role_set_t Parameter of Time Role Set state change event Public Members uint8_t time_role The Time Role for the element struct esp_ble_mesh_state_change_scene_store_t Parameter of Scene Store state change event Public Members uint16_t scene_number The number of scenes to be stored struct esp_ble_mesh_state_change_scene_recall_t Parameter of Scene Recall state change event Public Members uint16_t scene_number The number of scenes to be recalled struct esp_ble_mesh_state_change_scene_delete_t Parameter of Scene Delete state change event Espressif Systems 445 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t scene_number The number of scenes to be deleted struct esp_ble_mesh_state_change_scheduler_act_set_t Parameter of Scheduler Action Set state change event Public Members uint64_t index : 4 Index of the Schedule Register entry to set uint64_t year : 7 Scheduled year for the action uint64_t month : 12 Scheduled month for the action uint64_t day : 5 Scheduled day of the month for the action uint64_t hour : 5 Scheduled hour for the action uint64_t minute : 6 Scheduled minute for the action uint64_t second : 6 Scheduled second for the action uint64_t day_of_week : 7 Schedule days of the week for the action uint64_t action : 4 Action to be performed at the scheduled time uint64_t trans_time : 8 Transition time for this action uint16_t scene_number Scene number to be used for some actions struct esp_ble_mesh_server_recv_scheduler_act_get_t Context of the received Scheduler Action Get message Public Members uint8_t index Index of the Schedule Register entry to get struct esp_ble_mesh_server_recv_time_set_t Context of the received Time Set message Public Members uint8_t tai_seconds[5] The current TAI time in seconds uint8_t subsecond The sub-second time in units of 1/256 second Espressif Systems 446 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t uncertainty The estimated uncertainty in 10-millisecond steps uint16_t time_authority : 1 0 = No Time Authority, 1 = Time Authority uint16_t tai_utc_delta : 15 Current difference between TAI and UTC in seconds uint8_t time_zone_offset The local time zone offset in 15-minute increments struct esp_ble_mesh_server_recv_time_zone_set_t Context of the received Time Zone Set message Public Members uint8_t time_zone_offset_new Upcoming local time zone offset uint8_t tai_zone_change[5] TAI Seconds time of the upcoming Time Zone Offset change struct esp_ble_mesh_server_recv_tai_utc_delta_set_t Context of the received TAI UTC Delta Set message Public Members uint16_t tai_utc_delta_new : 15 Upcoming difference between TAI and UTC in seconds uint16_t padding : 1 Always 0b0. Other values are Prohibited. uint8_t tai_delta_change[5] TAI Seconds time of the upcoming TAI-UTC Delta change struct esp_ble_mesh_server_recv_time_role_set_t Context of the received Time Role Set message Public Members uint8_t time_role The Time Role for the element struct esp_ble_mesh_server_recv_scene_store_t Context of the received Scene Store message Public Members uint16_t scene_number The number of scenes to be stored struct esp_ble_mesh_server_recv_scene_recall_t Context of the received Scene Recall message Espressif Systems 447 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate if optional parameters are included uint16_t scene_number The number of scenes to be recalled uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_scene_delete_t Context of the received Scene Delete message Public Members uint16_t scene_number The number of scenes to be deleted struct esp_ble_mesh_server_recv_scheduler_act_set_t Context of the received Scheduler Action Set message Public Members uint64_t index : 4 Index of the Schedule Register entry to set uint64_t year : 7 Scheduled year for the action uint64_t month : 12 Scheduled month for the action uint64_t day : 5 Scheduled day of the month for the action uint64_t hour : 5 Scheduled hour for the action uint64_t minute : 6 Scheduled minute for the action uint64_t second : 6 Scheduled second for the action uint64_t day_of_week : 7 Schedule days of the week for the action uint64_t action : 4 Action to be performed at the scheduled time uint64_t trans_time : 8 Transition time for this action uint16_t scene_number Scene number to be used for some actions struct esp_ble_mesh_server_recv_time_status_t Context of the received Time Status message Espressif Systems 448 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t tai_seconds[5] The current TAI time in seconds uint8_t subsecond The sub-second time in units of 1/256 second uint8_t uncertainty The estimated uncertainty in 10-millisecond steps uint16_t time_authority : 1 0 = No Time Authority, 1 = Time Authority uint16_t tai_utc_delta : 15 Current difference between TAI and UTC in seconds uint8_t time_zone_offset The local time zone offset in 15-minute increments struct esp_ble_mesh_time_scene_server_cb_param_t Time Scene Server Model callback parameters Public Members esp_ble_mesh_model_t *model Pointer to Time and Scenes Server Models esp_ble_mesh_msg_ctx_t ctx Context of the received messages esp_ble_mesh_time_scene_server_cb_value_t value Value of the received Time and Scenes Messages Macros ESP_BLE_MESH_MODEL_TIME_CLI(cli_pub, cli_data) Define a new Time Client Model. Note This API needs to be called for each element on which the application needs to have a Time Client Model. Return New Time Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_SCENE_CLI(cli_pub, cli_data) Define a new Scene Client Model. Note This API needs to be called for each element on which the application needs to have a Scene Client Model. Return New Scene Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_SCHEDULER_CLI(cli_pub, cli_data) Define a new Scheduler Client Model. Note This API needs to be called for each element on which the application needs to have a Scheduler Client Model. Return New Scheduler Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. Espressif Systems 449 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_TIME_SRV(srv_pub, srv_data) Time Scene Server Models related context. Define a new Time Server Model. Note 1. The Time Server model is a root model. When this model is present on an Element, the corresponding Time Setup Server model shall also be present. 1. This model shall support model publication and model subscription. Return New Time Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_time_srv_t. ESP_BLE_MESH_MODEL_TIME_SETUP_SRV(srv_data) Define a new Time Setup Server Model. Note 1. The Time Setup Server model extends the Time Server model. Time is sensitive information that is propagated across a mesh network. 1. Only an authorized Time Client should be allowed to change the Time and Time Role states. A dedicated application key Bluetooth SIG Proprietary should be used on the Time Setup Server to restrict access to the server to only authorized Time Clients. 2. This model does not support subscribing nor publishing. Return New Time Setup Server Model instance. Parameters · srv_data: Pointer to the unique struct esp_ble_mesh_time_setup_srv_t. ESP_BLE_MESH_MODEL_SCENE_SRV(srv_pub, srv_data) Define a new Scene Server Model. Note 1. The Scene Server model is a root model. When this model is present on an Element, the corresponding Scene Setup Server model shall also be present. 1. This model shall support model publication and model subscription. 2. The model may be present only on the Primary element of a node. Return New Scene Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_scene_srv_t. ESP_BLE_MESH_MODEL_SCENE_SETUP_SRV(srv_pub, srv_data) Define a new Scene Setup Server Model. Note 1. The Scene Setup Server model extends the Scene Server model and the Generic Default Transition Time Server model. 1. This model shall support model subscription. 2. The model may be present only on the Primary element of a node. Return New Scene Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_scene_setup_srv_t. ESP_BLE_MESH_MODEL_SCHEDULER_SRV(srv_pub, srv_data) Define a new Scheduler Server Model. Note 1. The Scheduler Server model extends the Scene Server model. When this model is present on an Element, the corresponding Scheduler Setup Server model shall also be present. 1. This model shall support model publication and model subscription. 2. The model may be present only on the Primary element of a node. 3. The model requires the Time Server model shall be present on the element. Return New Scheduler Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_scheduler_srv_t. Espressif Systems 450 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_SCHEDULER_SETUP_SRV(srv_pub, srv_data) Define a new Scheduler Setup Server Model. Note 1. The Scheduler Setup Server model extends the Scheduler Server and the Scene Setup Server models. 1. This model shall support model subscription. 2. The model may be present only on the Primary element of a node. Return New Scheduler Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_scheduler_setup_srv_t. ESP_BLE_MESH_UNKNOWN_TAI_SECONDS Unknown TAI Seconds ESP_BLE_MESH_UNKNOWN_TAI_ZONE_CHANGE Unknown TAI of Zone Change ESP_BLE_MESH_UNKNOWN_TAI_DELTA_CHANGE Unknown TAI of Delta Change ESP_BLE_MESH_TAI_UTC_DELTA_MAX_VALUE Maximum TAI-UTC Delta value ESP_BLE_MESH_TAI_SECONDS_LEN Length of TAI Seconds ESP_BLE_MESH_TAI_OF_ZONE_CHANGE_LEN Length of TAI of Zone Change ESP_BLE_MESH_TAI_OF_DELTA_CHANGE_LEN Length of TAI of Delta Change ESP_BLE_MESH_INVALID_SCENE_NUMBER Invalid Scene Number ESP_BLE_MESH_SCENE_NUMBER_LEN Length of the Scene Number ESP_BLE_MESH_SCHEDULE_YEAR_ANY_YEAR Any year of the Scheduled year ESP_BLE_MESH_SCHEDULE_DAY_ANY_DAY Any day of the Scheduled day ESP_BLE_MESH_SCHEDULE_HOUR_ANY_HOUR Any hour of the Scheduled hour ESP_BLE_MESH_SCHEDULE_HOUR_ONCE_A_DAY Any hour of the Scheduled Day ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_HOUR Any minute of the Scheduled hour ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_MIN Every 15 minutes of the Scheduled hour ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_MIN Every 20 minutes of the Scheduled hour ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_HOUR Once of the Scheduled hour ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_MIN Any second of the Scheduled minute ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_SEC Every 15 seconds of the Scheduled minute Espressif Systems 451 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_SEC Every 20 seconds of the Scheduled minute ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_MIN Once of the Scheduled minute ESP_BLE_MESH_SCHEDULE_ACT_TURN_OFF Scheduled Action - Turn Off ESP_BLE_MESH_SCHEDULE_ACT_TURN_ON Scheduled Action - Turn On ESP_BLE_MESH_SCHEDULE_ACT_SCENE_RECALL Scheduled Action - Scene Recall ESP_BLE_MESH_SCHEDULE_ACT_NO_ACTION Scheduled Action - No Action ESP_BLE_MESH_SCHEDULE_SCENE_NO_SCENE Scheduled Scene - No Scene ESP_BLE_MESH_SCHEDULE_ENTRY_MAX_INDEX Maximum number of Scheduled entries ESP_BLE_MESH_TIME_NONE Time Role - None ESP_BLE_MESH_TIME_AUTHORITY Time Role - Mesh Time Authority ESP_BLE_MESH_TIME_RELAY Time Role - Mesh Time Relay ESP_BLE_MESH_TIME_CLINET Time Role - Mesh Time Client ESP_BLE_MESH_SCENE_SUCCESS Scene operation - Success ESP_BLE_MESH_SCENE_REG_FULL Scene operation - Scene Register Full ESP_BLE_MESH_SCENE_NOT_FOUND Scene operation - Scene Not Found Type Definitions typedef void (*esp_ble_mesh_time_scene_client_cb_t)(esp_ble_mesh_time_scene_client_cb_event_t event, esp_ble_mesh_time_scene_client_cb_param_t *param) Bluetooth Mesh Time Scene Client Model function. Time Scene Client Model callback function type Parameters · event: Event type · param: Pointer to callback parameter typedef void (*esp_ble_mesh_time_scene_server_cb_t)(esp_ble_mesh_time_scene_server_cb_event_t event, esp_ble_mesh_time_scene_server_cb_param_t Bluetooth Mesh Time and Scenes Server Model function. *param) Time Scene Server Model callback function type Parameters · event: Event type Espressif Systems 452 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · param: Pointer to callback parameter Enumerations enum esp_ble_mesh_time_scene_client_cb_event_t This enum value is the event of Time Scene Client Model Values: ESP_BLE_MESH_TIME_SCENE_CLIENT_GET_STATE_EVT ESP_BLE_MESH_TIME_SCENE_CLIENT_SET_STATE_EVT ESP_BLE_MESH_TIME_SCENE_CLIENT_PUBLISH_EVT ESP_BLE_MESH_TIME_SCENE_CLIENT_TIMEOUT_EVT ESP_BLE_MESH_TIME_SCENE_CLIENT_EVT_MAX enum esp_ble_mesh_time_scene_server_cb_event_t This enum value is the event of Time Scene Server Model Values: ESP_BLE_MESH_TIME_SCENE_SERVER_STATE_CHANGE_EVT 1. When get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, no event will be callback to the application layer when Time Scene Get messages are received. 2. When set_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, this event will be callback to the application layer when Time Scene Set/Set Unack messages are received. ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_GET_MSG_EVT When get_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Time Scene Get messages are received. ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_SET_MSG_EVT When set_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Time Scene Set/Set Unack messages are received. ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_STATUS_MSG_EVT When status_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when TIme Status message is received. ESP_BLE_MESH_TIME_SCENE_SERVER_EVT_MAX Lighting Client/Server Models Header File · components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_lighting_model_api.h Functions esp_err_t esp_ble_mesh_register_light_client_callback(esp_ble_mesh_light_client_cb_t 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 Espressif Systems 453 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return ESP_OK on success or error code otherwise. Parameters · [in] params: Pointer to BLE Mesh common client parameters. · [in] get_state: Pointer of light get message value. Shall not be set to NULL. esp_err_t esp_ble_mesh_light_client_set_state(esp_ble_mesh_client_common_param_t *params, esp_ble_mesh_light_client_set_state_t *set_state) Set the value of Light Server Model states using the Light Client Model set messages. Note If you want to know the opcodes and corresponding meanings accepted by this API, please refer to esp_ble_mesh_light_message_opcode_t in esp_ble_mesh_defs.h Return ESP_OK on success or error code otherwise. Parameters · [in] params: Pointer to BLE Mesh common client parameters. · [in] set_state: Pointer of light set message value. Shall not be set to NULL. esp_err_t esp_ble_mesh_register_lighting_server_callback(esp_ble_mesh_lighting_server_cb_t 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 union esp_ble_mesh_light_client_set_state_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Client Model set message union. Public Members esp_ble_mesh_light_lightness_set_t lightness_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SET_UNACK esp_ble_mesh_light_lightness_linear_set_t lightness_linear_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_SET_UNACK esp_ble_mesh_light_lightness_default_set_t lightness_default_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_SET_UNACK esp_ble_mesh_light_lightness_range_set_t lightness_range_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_SET_UNACK esp_ble_mesh_light_ctl_set_t ctl_set For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET_UNA esp_ble_mesh_light_ctl_temperature_set_t ctl_temperature_set For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_SET_UNACK Espressif Systems 454 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_light_ctl_temperature_range_set_t ctl_temperature_range_set For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_SET_UNACK esp_ble_mesh_light_ctl_default_set_t ctl_default_set For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_SET_UNACK esp_ble_mesh_light_hsl_set_t hsl_set For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET_UNAC esp_ble_mesh_light_hsl_hue_set_t hsl_hue_set For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE esp_ble_mesh_light_hsl_saturation_set_t hsl_saturation_set For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET_UNACK esp_ble_mesh_light_hsl_default_set_t hsl_default_set For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET_UNACK esp_ble_mesh_light_hsl_range_set_t hsl_range_set For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET_UNACK esp_ble_mesh_light_xyl_set_t xyl_set For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_SET_UNA esp_ble_mesh_light_xyl_default_set_t xyl_default_set For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET_UNACK esp_ble_mesh_light_xyl_range_set_t xyl_range_set For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET_UNACK esp_ble_mesh_light_lc_mode_set_t lc_mode_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_SET_UNACK esp_ble_mesh_light_lc_om_set_t lc_om_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET esp_ble_mesh_light_lc_light_onoff_set_t lc_light_onoff_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET_UNACK esp_ble_mesh_light_lc_property_set_t lc_property_set For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET & ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_SET_UNACK union esp_ble_mesh_light_client_status_cb_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Client Model received message union. Public Members esp_ble_mesh_light_lightness_status_cb_t lightness_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_STATUS esp_ble_mesh_light_lightness_linear_status_cb_t lightness_linear_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LINEAR_STATUS esp_ble_mesh_light_lightness_last_status_cb_t lightness_last_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LAST_STATUS Espressif Systems 455 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_light_lightness_default_status_cb_t lightness_default_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEFAULT_STATUS esp_ble_mesh_light_lightness_range_status_cb_t lightness_range_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_RANGE_STATUS esp_ble_mesh_light_ctl_status_cb_t ctl_status For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_STATUS esp_ble_mesh_light_ctl_temperature_status_cb_t ctl_temperature_status For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_STATUS esp_ble_mesh_light_ctl_temperature_range_status_cb_t ctl_temperature_range_status For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERATURE_RANGE_STATUS esp_ble_mesh_light_ctl_default_status_cb_t ctl_default_status For ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULT_STATUS esp_ble_mesh_light_hsl_status_cb_t hsl_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_STATUS esp_ble_mesh_light_hsl_target_status_cb_t hsl_target_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_STATUS esp_ble_mesh_light_hsl_hue_status_cb_t hsl_hue_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_STATUS esp_ble_mesh_light_hsl_saturation_status_cb_t hsl_saturation_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_STATUS esp_ble_mesh_light_hsl_default_status_cb_t hsl_default_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_STATUS esp_ble_mesh_light_hsl_range_status_cb_t hsl_range_status For ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_STATUS esp_ble_mesh_light_xyl_status_cb_t xyl_status For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_STATUS esp_ble_mesh_light_xyl_target_status_cb_t xyl_target_status For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_TARGET_STATUS esp_ble_mesh_light_xyl_default_status_cb_t xyl_default_status For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_STATUS esp_ble_mesh_light_xyl_range_status_cb_t xyl_range_status For ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_STATUS esp_ble_mesh_light_lc_mode_status_cb_t lc_mode_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_STATUS esp_ble_mesh_light_lc_om_status_cb_t lc_om_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_STATUS esp_ble_mesh_light_lc_light_onoff_status_cb_t lc_light_onoff_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_LIGHT_ONOFF_STATUS esp_ble_mesh_light_lc_property_status_cb_t lc_property_status For ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTY_STATUS union esp_ble_mesh_lighting_server_state_change_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model state change value union. Public Members esp_ble_mesh_state_change_light_lightness_set_t lightness_set The recv_op in ctx can be used to decide which state is changed. Light Lightness Set Espressif Systems 456 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_state_change_light_lightness_linear_set_t lightness_linear_set Light Lightness Linear Set esp_ble_mesh_state_change_light_lightness_default_set_t lightness_default_set Light Lightness Default Set esp_ble_mesh_state_change_light_lightness_range_set_t lightness_range_set Light Lightness Range Set esp_ble_mesh_state_change_light_ctl_set_t ctl_set Light CTL Set esp_ble_mesh_state_change_light_ctl_temperature_set_t ctl_temp_set Light CTL Temperature Set esp_ble_mesh_state_change_light_ctl_temperature_range_set_t ctl_temp_range_set Light CTL Temperature Range Set esp_ble_mesh_state_change_light_ctl_default_set_t ctl_default_set Light CTL Default Set esp_ble_mesh_state_change_light_hsl_set_t hsl_set Light HSL Set esp_ble_mesh_state_change_light_hsl_hue_set_t hsl_hue_set Light HSL Hue Set esp_ble_mesh_state_change_light_hsl_saturation_set_t hsl_saturation_set Light HSL Saturation Set esp_ble_mesh_state_change_light_hsl_default_set_t hsl_default_set Light HSL Default Set esp_ble_mesh_state_change_light_hsl_range_set_t hsl_range_set Light HSL Range Set esp_ble_mesh_state_change_light_xyl_set_t xyl_set Light xyL Set esp_ble_mesh_state_change_light_xyl_default_set_t xyl_default_set Light xyL Default Set esp_ble_mesh_state_change_light_xyl_range_set_t xyl_range_set Light xyL Range Set esp_ble_mesh_state_change_light_lc_mode_set_t lc_mode_set Light LC Mode Set esp_ble_mesh_state_change_light_lc_om_set_t lc_om_set Light LC Occupancy Mode Set esp_ble_mesh_state_change_light_lc_light_onoff_set_t lc_light_onoff_set Light LC Light OnOff Set esp_ble_mesh_state_change_light_lc_property_set_t lc_property_set Light LC Property Set esp_ble_mesh_state_change_sensor_status_t sensor_status Sensor Status union esp_ble_mesh_lighting_server_recv_get_msg_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received get message union. Public Members esp_ble_mesh_server_recv_light_lc_property_get_t lc_property Light LC Property Get Espressif Systems 457 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference union esp_ble_mesh_lighting_server_recv_set_msg_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received set message union. Public Members esp_ble_mesh_server_recv_light_lightness_set_t lightness Light Lightness Set/Light Lightness Set Unack esp_ble_mesh_server_recv_light_lightness_linear_set_t lightness_linear Light Lightness Linear Set/Light Lightness Linear Set Unack esp_ble_mesh_server_recv_light_lightness_default_set_t lightness_default Light Lightness Default Set/Light Lightness Default Set Unack esp_ble_mesh_server_recv_light_lightness_range_set_t lightness_range Light Lightness Range Set/Light Lightness Range Set Unack esp_ble_mesh_server_recv_light_ctl_set_t ctl Light CTL Set/Light CTL Set Unack esp_ble_mesh_server_recv_light_ctl_temperature_set_t ctl_temp Light CTL Temperature Set/Light CTL Temperature Set Unack esp_ble_mesh_server_recv_light_ctl_temperature_range_set_t ctl_temp_range Light CTL Temperature Range Set/Light CTL Temperature Range Set Unack esp_ble_mesh_server_recv_light_ctl_default_set_t ctl_default Light CTL Default Set/Light CTL Default Set Unack esp_ble_mesh_server_recv_light_hsl_set_t hsl Light HSL Set/Light HSL Set Unack esp_ble_mesh_server_recv_light_hsl_hue_set_t hsl_hue Light HSL Hue Set/Light HSL Hue Set Unack esp_ble_mesh_server_recv_light_hsl_saturation_set_t hsl_saturation Light HSL Saturation Set/Light HSL Saturation Set Unack esp_ble_mesh_server_recv_light_hsl_default_set_t hsl_default Light HSL Default Set/Light HSL Default Set Unack esp_ble_mesh_server_recv_light_hsl_range_set_t hsl_range Light HSL Range Set/Light HSL Range Set Unack esp_ble_mesh_server_recv_light_xyl_set_t xyl Light xyL Set/Light xyL Set Unack esp_ble_mesh_server_recv_light_xyl_default_set_t xyl_default Light xyL Default Set/Light xyL Default Set Unack esp_ble_mesh_server_recv_light_xyl_range_set_t xyl_range Light xyL Range Set/Light xyL Range Set Unack esp_ble_mesh_server_recv_light_lc_mode_set_t lc_mode Light LC Mode Set/Light LC Mode Set Unack esp_ble_mesh_server_recv_light_lc_om_set_t lc_om Light LC OM Set/Light LC OM Set Unack esp_ble_mesh_server_recv_light_lc_light_onoff_set_t lc_light_onoff Light LC Light OnOff Set/Light LC Light OnOff Set Unack esp_ble_mesh_server_recv_light_lc_property_set_t lc_property Light LC Property Set/Light LC Property Set Unack union esp_ble_mesh_lighting_server_recv_status_msg_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model received status message union. Espressif Systems 458 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_server_recv_sensor_status_t sensor_status Sensor Status union esp_ble_mesh_lighting_server_cb_value_t #include <esp_ble_mesh_lighting_model_api.h> Lighting Server Model callback value union. Public Members esp_ble_mesh_lighting_server_state_change_t state_change ESP_BLE_MESH_LIGHTING_SERVER_STATE_CHANGE_EVT esp_ble_mesh_lighting_server_recv_get_msg_t get ESP_BLE_MESH_LIGHTING_SERVER_RECV_GET_MSG_EVT esp_ble_mesh_lighting_server_recv_set_msg_t set ESP_BLE_MESH_LIGHTING_SERVER_RECV_SET_MSG_EVT esp_ble_mesh_lighting_server_recv_status_msg_t status ESP_BLE_MESH_LIGHTING_SERVER_RECV_STATUS_MSG_EVT Structures struct esp_ble_mesh_light_lightness_set_t Bluetooth Mesh Light Lightness Client Model Get and Set parameters structure. Parameters of Light Lightness Set Public Members bool op_en Indicate if optional parameters are included uint16_t lightness Target value of light lightness actual state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_lightness_linear_set_t Parameters of Light Lightness Linear Set Public Members bool op_en Indicate if optional parameters are included uint16_t lightness Target value of light lightness linear state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) Espressif Systems 459 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_lightness_default_set_t Parameter of Light Lightness Default Set Public Members uint16_t lightness The value of the Light Lightness Default state struct esp_ble_mesh_light_lightness_range_set_t Parameters of Light Lightness Range Set Public Members uint16_t range_min Value of range min field of light lightness range state uint16_t range_max Value of range max field of light lightness range state struct esp_ble_mesh_light_ctl_set_t Parameters of Light CTL Set Public Members bool op_en Indicate if optional parameters are included uint16_t ctl_lightness Target value of light ctl lightness state uint16_t ctl_temperatrue Target value of light ctl temperature state int16_t ctl_delta_uv Target value of light ctl delta UV state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_ctl_temperature_set_t Parameters of Light CTL Temperature Set Public Members bool op_en Indicate if optional parameters are included uint16_t ctl_temperatrue Target value of light ctl temperature state int16_t ctl_delta_uv Target value of light ctl delta UV state Espressif Systems 460 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_ctl_temperature_range_set_t Parameters of Light CTL Temperature Range Set Public Members uint16_t range_min Value of temperature range min field of light ctl temperature range state uint16_t range_max Value of temperature range max field of light ctl temperature range state struct esp_ble_mesh_light_ctl_default_set_t Parameters of Light CTL Default Set Public Members uint16_t lightness Value of light lightness default state uint16_t temperature Value of light temperature default state int16_t delta_uv Value of light delta UV default state struct esp_ble_mesh_light_hsl_set_t Parameters of Light HSL Set Public Members bool op_en Indicate if optional parameters are included uint16_t hsl_lightness Target value of light hsl lightness state uint16_t hsl_hue Target value of light hsl hue state uint16_t hsl_saturation Target value of light hsl saturation state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_hsl_hue_set_t Parameters of Light HSL Hue Set Espressif Systems 461 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate if optional parameters are included uint16_t hue Target value of light hsl hue state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_hsl_saturation_set_t Parameters of Light HSL Saturation Set Public Members bool op_en Indicate if optional parameters are included uint16_t saturation Target value of light hsl hue state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_hsl_default_set_t Parameters of Light HSL Default Set Public Members uint16_t lightness Value of light lightness default state uint16_t hue Value of light hue default state uint16_t saturation Value of light saturation default state struct esp_ble_mesh_light_hsl_range_set_t Parameters of Light HSL Range Set Public Members uint16_t hue_range_min Value of hue range min field of light hsl hue range state uint16_t hue_range_max Value of hue range max field of light hsl hue range state Espressif Systems 462 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t saturation_range_min Value of saturation range min field of light hsl saturation range state uint16_t saturation_range_max Value of saturation range max field of light hsl saturation range state struct esp_ble_mesh_light_xyl_set_t Parameters of Light xyL Set Public Members bool op_en Indicate whether optional parameters included uint16_t xyl_lightness The target value of the Light xyL Lightness state uint16_t xyl_x The target value of the Light xyL x state uint16_t xyl_y The target value of the Light xyL y state uint8_t tid Transaction Identifier uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_xyl_default_set_t Parameters of Light xyL Default Set Public Members uint16_t lightness The value of the Light Lightness Default state uint16_t xyl_x The value of the Light xyL x Default state uint16_t xyl_y The value of the Light xyL y Default state struct esp_ble_mesh_light_xyl_range_set_t Parameters of Light xyL Range Set Public Members uint16_t xyl_x_range_min The value of the xyL x Range Min field of the Light xyL x Range state uint16_t xyl_x_range_max The value of the xyL x Range Max field of the Light xyL x Range state uint16_t xyl_y_range_min The value of the xyL y Range Min field of the Light xyL y Range state uint16_t xyl_y_range_max The value of the xyL y Range Max field of the Light xyL y Range state Espressif Systems 463 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_light_lc_mode_set_t Parameter of Light LC Mode Set Public Members uint8_t mode The target value of the Light LC Mode state struct esp_ble_mesh_light_lc_om_set_t Parameter of Light LC OM Set Public Members uint8_t mode The target value of the Light LC Occupancy Mode state struct esp_ble_mesh_light_lc_light_onoff_set_t Parameters of Light LC Light OnOff Set Public Members bool op_en Indicate whether optional parameters included uint8_t light_onoff The target value of the Light LC Light OnOff state uint8_t tid Transaction Identifier uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_light_lc_property_get_t Parameter of Light LC Property Get Public Members uint16_t property_id Property ID identifying a Light LC Property struct esp_ble_mesh_light_lc_property_set_t Parameters of Light LC Property Set Public Members uint16_t property_id Property ID identifying a Light LC Property struct net_buf_simple *property_value Raw value for the Light LC Property struct esp_ble_mesh_light_lightness_status_cb_t Bluetooth Mesh Light Lightness Client Model Get and Set callback parameters structure. Parameters of Light Lightness Status Espressif Systems 464 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate if optional parameters are included uint16_t present_lightness Current value of light lightness actual state uint16_t target_lightness Target value of light lightness actual state (optional) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_light_lightness_linear_status_cb_t Parameters of Light Lightness Linear Status Public Members bool op_en Indicate if optional parameters are included uint16_t present_lightness Current value of light lightness linear state uint16_t target_lightness Target value of light lightness linear state (optional) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_light_lightness_last_status_cb_t Parameter of Light Lightness Last Status Public Members uint16_t lightness The value of the Light Lightness Last state struct esp_ble_mesh_light_lightness_default_status_cb_t Parameter of Light Lightness Default Status Public Members uint16_t lightness The value of the Light Lightness default State struct esp_ble_mesh_light_lightness_range_status_cb_t Parameters of Light Lightness Range Status Public Members uint8_t status_code Status Code for the request message uint16_t range_min Value of range min field of light lightness range state uint16_t range_max Value of range max field of light lightness range state Espressif Systems 465 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_light_ctl_status_cb_t Parameters of Light CTL Status Public Members bool op_en Indicate if optional parameters are included uint16_t present_ctl_lightness Current value of light ctl lightness state uint16_t present_ctl_temperature Current value of light ctl temperature state uint16_t target_ctl_lightness Target value of light ctl lightness state (optional) uint16_t target_ctl_temperature Target value of light ctl temperature state (C.1) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_light_ctl_temperature_status_cb_t Parameters of Light CTL Temperature Status Public Members bool op_en Indicate if optional parameters are included uint16_t present_ctl_temperature Current value of light ctl temperature state uint16_t present_ctl_delta_uv Current value of light ctl delta UV state uint16_t target_ctl_temperature Target value of light ctl temperature state (optional) uint16_t target_ctl_delta_uv Target value of light ctl delta UV state (C.1) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_light_ctl_temperature_range_status_cb_t Parameters of Light CTL Temperature Range Status Public Members uint8_t status_code Status code for the request message uint16_t range_min Value of temperature range min field of light ctl temperature range state uint16_t range_max Value of temperature range max field of light ctl temperature range state struct esp_ble_mesh_light_ctl_default_status_cb_t Parameters of Light CTL Default Status Espressif Systems 466 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t lightness Value of light lightness default state uint16_t temperature Value of light temperature default state int16_t delta_uv Value of light delta UV default state struct esp_ble_mesh_light_hsl_status_cb_t Parameters of Light HSL Status Public Members bool op_en Indicate if optional parameters are included uint16_t hsl_lightness Current value of light hsl lightness state uint16_t hsl_hue Current value of light hsl hue state uint16_t hsl_saturation Current value of light hsl saturation state uint8_t remain_time Time to complete state transition (optional) struct esp_ble_mesh_light_hsl_target_status_cb_t Parameters of Light HSL Target Status Public Members bool op_en Indicate if optional parameters are included uint16_t hsl_lightness_target Target value of light hsl lightness state uint16_t hsl_hue_target Target value of light hsl hue state uint16_t hsl_saturation_target Target value of light hsl saturation state uint8_t remain_time Time to complete state transition (optional) struct esp_ble_mesh_light_hsl_hue_status_cb_t Parameters of Light HSL Hue Status Public Members bool op_en Indicate if optional parameters are included uint16_t present_hue Current value of light hsl hue state Espressif Systems 467 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t target_hue Target value of light hsl hue state (optional) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_light_hsl_saturation_status_cb_t Parameters of Light HSL Saturation Status Public Members bool op_en Indicate if optional parameters are included uint16_t present_saturation Current value of light hsl saturation state uint16_t target_saturation Target value of light hsl saturation state (optional) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_light_hsl_default_status_cb_t Parameters of Light HSL Default Status Public Members uint16_t lightness Value of light lightness default state uint16_t hue Value of light hue default state uint16_t saturation Value of light saturation default state struct esp_ble_mesh_light_hsl_range_status_cb_t Parameters of Light HSL Range Status Public Members uint8_t status_code Status code for the request message uint16_t hue_range_min Value of hue range min field of light hsl hue range state uint16_t hue_range_max Value of hue range max field of light hsl hue range state uint16_t saturation_range_min Value of saturation range min field of light hsl saturation range state uint16_t saturation_range_max Value of saturation range max field of light hsl saturation range state struct esp_ble_mesh_light_xyl_status_cb_t Parameters of Light xyL Status Espressif Systems 468 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate whether optional parameters included uint16_t xyl_lightness The present value of the Light xyL Lightness state uint16_t xyl_x The present value of the Light xyL x state uint16_t xyl_y The present value of the Light xyL y state uint8_t remain_time Time to complete state transition (optional) struct esp_ble_mesh_light_xyl_target_status_cb_t Parameters of Light xyL Target Status Public Members bool op_en Indicate whether optional parameters included uint16_t target_xyl_lightness The target value of the Light xyL Lightness state uint16_t target_xyl_x The target value of the Light xyL x state uint16_t target_xyl_y The target value of the Light xyL y state uint8_t remain_time Time to complete state transition (optional) struct esp_ble_mesh_light_xyl_default_status_cb_t Parameters of Light xyL Default Status Public Members uint16_t lightness The value of the Light Lightness Default state uint16_t xyl_x The value of the Light xyL x Default state uint16_t xyl_y The value of the Light xyL y Default state struct esp_ble_mesh_light_xyl_range_status_cb_t Parameters of Light xyL Range Status Public Members uint8_t status_code Status Code for the requesting message uint16_t xyl_x_range_min The value of the xyL x Range Min field of the Light xyL x Range state Espressif Systems 469 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t xyl_x_range_max The value of the xyL x Range Max field of the Light xyL x Range state uint16_t xyl_y_range_min The value of the xyL y Range Min field of the Light xyL y Range state uint16_t xyl_y_range_max The value of the xyL y Range Max field of the Light xyL y Range state struct esp_ble_mesh_light_lc_mode_status_cb_t Parameter of Light LC Mode Status Public Members uint8_t mode The present value of the Light LC Mode state struct esp_ble_mesh_light_lc_om_status_cb_t Parameter of Light LC OM Status Public Members uint8_t mode The present value of the Light LC Occupancy Mode state struct esp_ble_mesh_light_lc_light_onoff_status_cb_t Parameters of Light LC Light OnOff Status Public Members bool op_en Indicate whether optional parameters included uint8_t present_light_onoff The present value of the Light LC Light OnOff state uint8_t target_light_onoff The target value of the Light LC Light OnOff state (Optional) uint8_t remain_time Time to complete state transition (C.1) struct esp_ble_mesh_light_lc_property_status_cb_t Parameters of Light LC Property Status Public Members uint16_t property_id Property ID identifying a Light LC Property struct net_buf_simple *property_value Raw value for the Light LC Property struct esp_ble_mesh_light_client_cb_param_t Lighting Client Model callback parameters Espressif Systems 470 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members int error_code Appropriate error code esp_ble_mesh_client_common_param_t *params The client common parameters. esp_ble_mesh_light_client_status_cb_t status_cb The light status message callback values struct esp_ble_mesh_light_lightness_state_t Parameters of Light Lightness state Public Members uint16_t lightness_linear The present value of Light Lightness Linear state uint16_t target_lightness_linear The target value of Light Lightness Linear state uint16_t lightness_actual The present value of Light Lightness Actual state uint16_t target_lightness_actual The target value of Light Lightness Actual state uint16_t lightness_last The value of Light Lightness Last state uint16_t lightness_default The value of Light Lightness Default state uint8_t status_code The status code of setting Light Lightness Range state uint16_t lightness_range_min The minimum value of Light Lightness Range state uint16_t lightness_range_max The maximum value of Light Lightness Range state struct esp_ble_mesh_light_lightness_srv_t User data of Light Lightness Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting Lightness Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_lightness_state_t *state Parameters of the Light Lightness state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t actual_transition Parameters of state transition esp_ble_mesh_state_transition_t linear_transition Parameters of state transition Espressif Systems 471 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int32_t tt_delta_lightness_actual Delta change value of lightness actual state transition int32_t tt_delta_lightness_linear Delta change value of lightness linear state transition struct esp_ble_mesh_light_lightness_setup_srv_t User data of Light Lightness Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting Lightness Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_lightness_state_t *state Parameters of the Light Lightness state struct esp_ble_mesh_light_ctl_state_t Parameters of Light CTL state Public Members uint16_t lightness The present value of Light CTL Lightness state uint16_t target_lightness The target value of Light CTL Lightness state uint16_t temperature The present value of Light CTL Temperature state uint16_t target_temperature The target value of Light CTL Temperature state int16_t delta_uv The present value of Light CTL Delta UV state int16_t target_delta_uv The target value of Light CTL Delta UV state uint8_t status_code The statue code of setting Light CTL Temperature Range state uint16_t temperature_range_min The minimum value of Light CTL Temperature Range state uint16_t temperature_range_max The maximum value of Light CTL Temperature Range state uint16_t lightness_default The value of Light Lightness Default state uint16_t temperature_default The value of Light CTL Temperature Default state int16_t delta_uv_default The value of Light CTL Delta UV Default state struct esp_ble_mesh_light_ctl_srv_t User data of Light CTL Server Model Espressif Systems 472 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_ble_mesh_model_t *model Pointer to the Lighting CTL Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_ctl_state_t *state Parameters of the Light CTL state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition int32_t tt_delta_lightness Delta change value of lightness state transition int32_t tt_delta_temperature Delta change value of temperature state transition int32_t tt_delta_delta_uv Delta change value of delta uv state transition struct esp_ble_mesh_light_ctl_setup_srv_t User data of Light CTL Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting CTL Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_ctl_state_t *state Parameters of the Light CTL state struct esp_ble_mesh_light_ctl_temp_srv_t User data of Light CTL Temperature Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting CTL Temperature Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_ctl_state_t *state Parameters of the Light CTL state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition int32_t tt_delta_temperature Delta change value of temperature state transition int32_t tt_delta_delta_uv Delta change value of delta uv state transition Espressif Systems 473 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_light_hsl_state_t Parameters of Light HSL state Public Members uint16_t lightness The present value of Light HSL Lightness state uint16_t target_lightness The target value of Light HSL Lightness state uint16_t hue The present value of Light HSL Hue state uint16_t target_hue The target value of Light HSL Hue state uint16_t saturation The present value of Light HSL Saturation state uint16_t target_saturation The target value of Light HSL Saturation state uint16_t lightness_default The value of Light Lightness Default state uint16_t hue_default The value of Light HSL Hue Default state uint16_t saturation_default The value of Light HSL Saturation Default state uint8_t status_code The status code of setting Light HSL Hue & Saturation Range state uint16_t hue_range_min The minimum value of Light HSL Hue Range state uint16_t hue_range_max The maximum value of Light HSL Hue Range state uint16_t saturation_range_min The minimum value of Light HSL Saturation state uint16_t saturation_range_max The maximum value of Light HSL Saturation state struct esp_ble_mesh_light_hsl_srv_t User data of Light HSL Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting HSL Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_hsl_state_t *state Parameters of the Light HSL state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition Espressif Systems 474 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int32_t tt_delta_lightness Delta change value of lightness state transition int32_t tt_delta_hue Delta change value of hue state transition int32_t tt_delta_saturation Delta change value of saturation state transition struct esp_ble_mesh_light_hsl_setup_srv_t User data of Light HSL Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting HSL Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_hsl_state_t *state Parameters of the Light HSL state struct esp_ble_mesh_light_hsl_hue_srv_t User data of Light HSL Hue Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting HSL Hue Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_hsl_state_t *state Parameters of the Light HSL state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition int32_t tt_delta_hue Delta change value of hue state transition struct esp_ble_mesh_light_hsl_sat_srv_t User data of Light HSL Saturation Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting HSL Saturation Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_hsl_state_t *state Parameters of the Light HSL state esp_ble_mesh_last_msg_info_t last Parameters of the last received set message Espressif Systems 475 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_state_transition_t transition Parameters of state transition int32_t tt_delta_saturation Delta change value of saturation state transition struct esp_ble_mesh_light_xyl_state_t Parameters of Light xyL state Public Members uint16_t lightness The present value of Light xyL Lightness state uint16_t target_lightness The target value of Light xyL Lightness state uint16_t x The present value of Light xyL x state uint16_t target_x The target value of Light xyL x state uint16_t y The present value of Light xyL y state uint16_t target_y The target value of Light xyL y state uint16_t lightness_default The value of Light Lightness Default state uint16_t x_default The value of Light xyL x Default state uint16_t y_default The value of Light xyL y Default state uint8_t status_code The status code of setting Light xyL x & y Range state uint16_t x_range_min The minimum value of Light xyL x Range state uint16_t x_range_max The maximum value of Light xyL x Range state uint16_t y_range_min The minimum value of Light xyL y Range state uint16_t y_range_max The maximum value of Light xyL y Range state struct esp_ble_mesh_light_xyl_srv_t User data of Light xyL Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting xyL Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_xyl_state_t *state Parameters of the Light xyL state Espressif Systems 476 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition int32_t tt_delta_lightness Delta change value of lightness state transition int32_t tt_delta_x Delta change value of x state transition int32_t tt_delta_y Delta change value of y state transition struct esp_ble_mesh_light_xyl_setup_srv_t User data of Light xyL Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting xyL Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_xyl_state_t *state Parameters of the Light xyL state struct esp_ble_mesh_light_lc_state_t Parameters of Light LC states Public Members uint32_t mode : 1 0b0 The controller is turned off. · The binding with the Light Lightness state is disabled. 0b1 The controller is turned on. · The binding with the Light Lightness state is enabled. The value of Light LC Mode state uint32_t occupancy_mode : 1 The value of Light LC Occupancy Mode state uint32_t light_onoff : 1 The present value of Light LC Light OnOff state uint32_t target_light_onoff : 1 The target value of Light LC Light OnOff state uint32_t occupancy : 1 The value of Light LC Occupancy state uint32_t ambient_luxlevel : 24 The value of Light LC Ambient LuxLevel state uint16_t linear_output 1. Light LC Linear Output = max((Lightness Out)^2/65535, Regulator Output) 2. If the Light LC Mode state is set to 0b1, the binding is enabled and upon a change of the Light LC Linear Output state, the following operation shall be performed: Light Lightness Linear = Light LC Linear Output 3. If the Light LC Mode state is set to 0b0, the binding is disabled (i.e., upon a change of the Light LC Linear Output state, no operation on the Light Lightness Linear state is performed). The value of Light LC Linear Output state Espressif Systems 477 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_light_lc_property_state_t Parameters of Light Property states. The Light LC Property states are read / write states that determine the configuration of a Light Lightness Controller. Each state is represented by a device property and is controlled by Light LC Property messages. Public Members uint32_t time_occupancy_delay A timing state that determines the delay for changing the Light LC Occupancy state upon receiving a Sensor Status message from an occupancy sensor. The value of Light LC Time Occupancy Delay state uint32_t time_fade_on A timing state that determines the time the controlled lights fade to the level determined by the Light LC Lightness On state. The value of Light LC Time Fade On state uint32_t time_run_on A timing state that determines the time the controlled lights stay at the level determined by the Light LC Lightness On state. The value of Light LC Time Run On state uint32_t time_fade A timing state that determines the time the controlled lights fade from the level determined by the Light LC Lightness On state to the level determined by the Light Lightness Prolong state. The value of Light LC Time Fade state uint32_t time_prolong A timing state that determines the time the controlled lights stay at the level determined by the Light LC Lightness Prolong state. The value of Light LC Time Prolong state uint32_t time_fade_standby_auto A timing state that determines the time the controlled lights fade from the level determined by the Light LC Lightness Prolong state to the level determined by the Light LC Lightness Standby state when the transition is automatic. The value of Light LC Time Fade Standby Auto state uint32_t time_fade_standby_manual A timing state that determines the time the controlled lights fade from the level determined by the Light LC Lightness Prolong state to the level determined by the Light LC Lightness Standby state when the transition is triggered by a change in the Light LC Light OnOff state. The value of Light LC Time Fade Standby Manual state uint16_t lightness_on A lightness state that determines the perceptive light lightness at the Occupancy and Run internal 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 Espressif Systems 478 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference float regulator_kiu A float32 state representing the integral coefficient that determines the integral part of the equation 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 Public Members uint8_t fade_on The value of transition time of Light LC Time Fade On uint8_t fade The value of transition time of Light LC Time Fade uint8_t fade_standby_auto The value of transition time of Light LC Time Fade Standby Auto uint8_t fade_standby_manual The value of transition time of Light LC Time Fade Standby Manual struct esp_ble_mesh_light_lc_state_machine_t::[anonymous] trans_time The Fade On, Fade, Fade Standby Auto, and Fade Standby Manual states are transition states that define the transition of the Lightness Out and LuxLevel Out states. This transition can be started as a result of the Light LC State Machine change or as a result of receiving the Light LC Light OnOff Set or Light LC Light Set Unacknowledged message. The value of transition time esp_ble_mesh_lc_state_t state The value of Light LC state machine state struct k_delayed_work timer Timer of Light LC state machine Espressif Systems 479 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_light_control_t Parameters of Light Lightness controller Public Members esp_ble_mesh_light_lc_state_t state Parameters of Light LC state esp_ble_mesh_light_lc_property_state_t prop_state Parameters of Light LC Property state esp_ble_mesh_light_lc_state_machine_t state_machine Parameters of Light LC state machine struct esp_ble_mesh_light_lc_srv_t User data of Light LC Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting LC Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_control_t *lc Parameters of the Light controller esp_ble_mesh_last_msg_info_t last Parameters of the last received set message esp_ble_mesh_state_transition_t transition Parameters of state transition struct esp_ble_mesh_light_lc_setup_srv_t User data of Light LC Setup Server Model Public Members esp_ble_mesh_model_t *model Pointer to the Lighting LC Setup Server Model. Initialized internally. esp_ble_mesh_server_rsp_ctrl_t rsp_ctrl Response control of the server model received messages esp_ble_mesh_light_control_t *lc Parameters of the Light controller struct esp_ble_mesh_state_change_light_lightness_set_t Parameter of Light Lightness Actual state change event Public Members uint16_t lightness The value of Light Lightness Actual state struct esp_ble_mesh_state_change_light_lightness_linear_set_t Parameter of Light Lightness Linear state change event Espressif Systems 480 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t lightness The value of Light Lightness Linear state struct esp_ble_mesh_state_change_light_lightness_default_set_t Parameter of Light Lightness Default state change event Public Members uint16_t lightness The value of Light Lightness Default state struct esp_ble_mesh_state_change_light_lightness_range_set_t Parameters of Light Lightness Range state change event Public Members uint16_t range_min The minimum value of Light Lightness Range state uint16_t range_max The maximum value of Light Lightness Range state struct esp_ble_mesh_state_change_light_ctl_set_t Parameters of Light CTL state change event Public Members uint16_t lightness The value of Light CTL Lightness state uint16_t temperature The value of Light CTL Temperature state int16_t delta_uv The value of Light CTL Delta UV state struct esp_ble_mesh_state_change_light_ctl_temperature_set_t Parameters of Light CTL Temperature state change event Public Members uint16_t temperature The value of Light CTL Temperature state int16_t delta_uv The value of Light CTL Delta UV state struct esp_ble_mesh_state_change_light_ctl_temperature_range_set_t Parameters of Light CTL Temperature Range state change event Public Members uint16_t range_min The minimum value of Light CTL Temperature Range state uint16_t range_max The maximum value of Light CTL Temperature Range state Espressif Systems 481 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_state_change_light_ctl_default_set_t Parameters of Light CTL Default state change event Public Members uint16_t lightness The value of Light Lightness Default state uint16_t temperature The value of Light CTL Temperature Default state int16_t delta_uv The value of Light CTL Delta UV Default state struct esp_ble_mesh_state_change_light_hsl_set_t Parameters of Light HSL state change event Public Members uint16_t lightness The value of Light HSL Lightness state uint16_t hue The value of Light HSL Hue state uint16_t saturation The value of Light HSL Saturation state struct esp_ble_mesh_state_change_light_hsl_hue_set_t Parameter of Light HSL Hue state change event Public Members uint16_t hue The value of Light HSL Hue state struct esp_ble_mesh_state_change_light_hsl_saturation_set_t Parameter of Light HSL Saturation state change event Public Members uint16_t saturation The value of Light HSL Saturation state struct esp_ble_mesh_state_change_light_hsl_default_set_t Parameters of Light HSL Default state change event Public Members uint16_t lightness The value of Light HSL Lightness Default state uint16_t hue The value of Light HSL Hue Default state uint16_t saturation The value of Light HSL Saturation Default state struct esp_ble_mesh_state_change_light_hsl_range_set_t Parameters of Light HSL Range state change event Espressif Systems 482 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t hue_range_min The minimum hue value of Light HSL Range state uint16_t hue_range_max The maximum hue value of Light HSL Range state uint16_t saturation_range_min The minimum saturation value of Light HSL Range state uint16_t saturation_range_max The maximum saturation value of Light HSL Range state struct esp_ble_mesh_state_change_light_xyl_set_t Parameters of Light xyL state change event Public Members uint16_t lightness The value of Light xyL Lightness state uint16_t x The value of Light xyL x state uint16_t y The value of Light xyL y state struct esp_ble_mesh_state_change_light_xyl_default_set_t Parameters of Light xyL Default state change event Public Members uint16_t lightness The value of Light Lightness Default state uint16_t x The value of Light xyL x Default state uint16_t y The value of Light xyL y Default state struct esp_ble_mesh_state_change_light_xyl_range_set_t Parameters of Light xyL Range state change event Public Members uint16_t x_range_min The minimum value of Light xyL x Range state uint16_t x_range_max The maximum value of Light xyL x Range state uint16_t y_range_min The minimum value of Light xyL y Range state uint16_t y_range_max The maximum value of Light xyL y Range state struct esp_ble_mesh_state_change_light_lc_mode_set_t Parameter of Light LC Mode state change event Espressif Systems 483 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t mode The value of Light LC Mode state struct esp_ble_mesh_state_change_light_lc_om_set_t Parameter of Light LC Occupancy Mode state change event Public Members uint8_t mode The value of Light LC Occupancy Mode state struct esp_ble_mesh_state_change_light_lc_light_onoff_set_t Parameter of Light LC Light OnOff state change event Public Members uint8_t onoff The value of Light LC Light OnOff state struct esp_ble_mesh_state_change_light_lc_property_set_t Parameters of Light LC Property state change event Public Members uint16_t property_id The property id of Light LC Property state struct net_buf_simple *property_value The property value of Light LC Property state struct esp_ble_mesh_state_change_sensor_status_t Parameters of Sensor Status state change event Public Members uint16_t property_id The value of Sensor Property ID uint8_t occupancy The value of Light LC Occupancy state uint32_t set_occupancy_to_1_delay The value of Light LC Set Occupancy to 1 Delay state uint32_t ambient_luxlevel The value of Light LC Ambient Luxlevel state union esp_ble_mesh_state_change_sensor_status_t::[anonymous] state Parameters of Sensor Status related state struct esp_ble_mesh_server_recv_light_lc_property_get_t Context of the received Light LC Property Get message Espressif Systems 484 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint16_t property_id Property ID identifying a Light LC Property struct esp_ble_mesh_server_recv_light_lightness_set_t Context of the received Light Lightness Set message Public Members bool op_en Indicate if optional parameters are included uint16_t lightness Target value of light lightness actual state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_lightness_linear_set_t Context of the received Light Lightness Linear Set message Public Members bool op_en Indicate if optional parameters are included uint16_t lightness Target value of light lightness linear state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_lightness_default_set_t Context of the received Light Lightness Default Set message Public Members uint16_t lightness The value of the Light Lightness Default state struct esp_ble_mesh_server_recv_light_lightness_range_set_t Context of the received Light Lightness Range Set message Public Members uint16_t range_min Value of range min field of light lightness range state Espressif Systems 485 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t range_max Value of range max field of light lightness range state struct esp_ble_mesh_server_recv_light_ctl_set_t Context of the received Light CTL Set message Public Members bool op_en Indicate if optional parameters are included uint16_t lightness Target value of light ctl lightness state uint16_t temperature Target value of light ctl temperature state int16_t delta_uv Target value of light ctl delta UV state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_ctl_temperature_set_t Context of the received Light CTL Temperature Set message Public Members bool op_en Indicate if optional parameters are included uint16_t temperature Target value of light ctl temperature state int16_t delta_uv Target value of light ctl delta UV state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_ctl_temperature_range_set_t Context of the received Light CTL Temperature Range Set message Public Members uint16_t range_min Value of temperature range min field of light ctl temperature range state uint16_t range_max Value of temperature range max field of light ctl temperature range state Espressif Systems 486 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_ble_mesh_server_recv_light_ctl_default_set_t Context of the received Light CTL Default Set message Public Members uint16_t lightness Value of light lightness default state uint16_t temperature Value of light temperature default state int16_t delta_uv Value of light delta UV default state struct esp_ble_mesh_server_recv_light_hsl_set_t Context of the received Light HSL Set message Public Members bool op_en Indicate if optional parameters are included uint16_t lightness Target value of light hsl lightness state uint16_t hue Target value of light hsl hue state uint16_t saturation Target value of light hsl saturation state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_hsl_hue_set_t Context of the received Light HSL Hue Set message Public Members bool op_en Indicate if optional parameters are included uint16_t hue Target value of light hsl hue state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_hsl_saturation_set_t Context of the received Light HSL Saturation Set message Espressif Systems 487 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate if optional parameters are included uint16_t saturation Target value of light hsl hue state uint8_t tid Transaction ID uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_hsl_default_set_t Context of the received Light HSL Default Set message Public Members uint16_t lightness Value of light lightness default state uint16_t hue Value of light hue default state uint16_t saturation Value of light saturation default state struct esp_ble_mesh_server_recv_light_hsl_range_set_t Context of the received Light HSL Range Set message Public Members uint16_t hue_range_min Value of hue range min field of light hsl hue range state uint16_t hue_range_max Value of hue range max field of light hsl hue range state uint16_t saturation_range_min Value of saturation range min field of light hsl saturation range state uint16_t saturation_range_max Value of saturation range max field of light hsl saturation range state struct esp_ble_mesh_server_recv_light_xyl_set_t Context of the received Light xyL Set message Public Members bool op_en Indicate whether optional parameters included uint16_t lightness The target value of the Light xyL Lightness state uint16_t x The target value of the Light xyL x state Espressif Systems 488 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint16_t y The target value of the Light xyL y state uint8_t tid Transaction Identifier uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_xyl_default_set_t Context of the received Light xyL Default Set message Public Members uint16_t lightness The value of the Light Lightness Default state uint16_t x The value of the Light xyL x Default state uint16_t y The value of the Light xyL y Default state struct esp_ble_mesh_server_recv_light_xyl_range_set_t Context of the received Light xyl Range Set message Public Members uint16_t x_range_min The value of the xyL x Range Min field of the Light xyL x Range state uint16_t x_range_max The value of the xyL x Range Max field of the Light xyL x Range state uint16_t y_range_min The value of the xyL y Range Min field of the Light xyL y Range state uint16_t y_range_max The value of the xyL y Range Max field of the Light xyL y Range state struct esp_ble_mesh_server_recv_light_lc_mode_set_t Context of the received Light LC Mode Set message Public Members uint8_t mode The target value of the Light LC Mode state struct esp_ble_mesh_server_recv_light_lc_om_set_t Context of the received Light OM Set message Public Members uint8_t mode The target value of the Light LC Occupancy Mode state struct esp_ble_mesh_server_recv_light_lc_light_onoff_set_t Context of the received Light LC Light OnOff Set message Espressif Systems 489 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members bool op_en Indicate whether optional parameters included uint8_t light_onoff The target value of the Light LC Light OnOff state uint8_t tid Transaction Identifier uint8_t trans_time Time to complete state transition (optional) uint8_t delay Indicate message execution delay (C.1) struct esp_ble_mesh_server_recv_light_lc_property_set_t Context of the received Light LC Property Set message Public Members uint16_t property_id Property ID identifying a Light LC Property struct net_buf_simple *property_value Raw value for the Light LC Property struct esp_ble_mesh_server_recv_sensor_status_t Context of the received Sensor Status message Public Members struct net_buf_simple *data Value of sensor data state (optional) struct esp_ble_mesh_lighting_server_cb_param_t Lighting Server Model callback parameters Public Members esp_ble_mesh_model_t *model Pointer to Lighting Server Models esp_ble_mesh_msg_ctx_t ctx Context of the received messages esp_ble_mesh_lighting_server_cb_value_t value Value of the received Lighting Messages Macros ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_CLI(cli_pub, cli_data) Define a new Light Lightness Client Model. Note This API needs to be called for each element on which the application needs to have a Light Lightness Client Model. Return New Light Lightness Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. Espressif Systems 490 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_LIGHT_CTL_CLI(cli_pub, cli_data) Define a new Light CTL Client Model. Note This API needs to be called for each element on which the application needs to have a Light CTL Client Model. Return New Light CTL Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_LIGHT_HSL_CLI(cli_pub, cli_data) Define a new Light HSL Client Model. Note This API needs to be called for each element on which the application needs to have a Light HSL Client Model. Return New Light HSL Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_LIGHT_XYL_CLI(cli_pub, cli_data) Define a new Light xyL Client Model. Note This API needs to be called for each element on which the application needs to have a Light xyL Client Model. Return New Light xyL Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_LIGHT_LC_CLI(cli_pub, cli_data) Define a new Light LC Client Model. Note This API needs to be called for each element on which the application needs to have a Light LC Client Model. Return New Light LC Client Model instance. Parameters · cli_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · cli_data: Pointer to the unique struct esp_ble_mesh_client_t. ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_SRV(srv_pub, srv_data) Lighting Server Models related context. Define a new Light Lightness Server Model. Note 1. The Light Lightness Server model extends the Generic Power OnOff Server model and the Generic Level Server model. When this model is present on an Element, the corresponding Light Lightness Setup Server model shall also be present. 1. This model shall support model publication and model subscription. Return New Light Lightness Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_lightness_srv_t. ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_SETUP_SRV(srv_pub, srv_data) Define a new Light Lightness Setup Server Model. Note 1. The Light Lightness Setup Server model extends the Light Lightness Server model and the Generic Power OnOff Setup Server model. 1. This model shall support model subscription. Return New Light Lightness Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_lightness_setup_srv_t. Espressif Systems 491 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_BLE_MESH_MODEL_LIGHT_CTL_SRV(srv_pub, srv_data) Define a new Light CTL Server Model. Note 1. The Light CTL Server model extends the Light Lightness Server model. When this model is present on an Element, the corresponding Light CTL Temperature Server model and the corresponding Light CTL Setup Server model shall also be present. 1. This model shall support model publication and model subscription. 2. The model requires two elements: the main element and the Temperature element. The Temperature element contains the corresponding Light CTL Temperature Server model and an instance of a Generic Level state bound to the Light CTL Temperature state on the Temperature element. The Light CTL Temperature state on the Temperature element is bound to the Light CTL state on the main element. Return New Light CTL Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_ctl_srv_t. ESP_BLE_MESH_MODEL_LIGHT_CTL_SETUP_SRV(srv_pub, srv_data) Define a new Light CTL Setup Server Model. Note 1. The Light CTL Setup Server model extends the Light CTL Server and the Light Lightness Setup Server. 1. This model shall support model subscription. Return New Light CTL Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_ctl_setup_srv_t. ESP_BLE_MESH_MODEL_LIGHT_CTL_TEMP_SRV(srv_pub, srv_data) Define a new Light CTL Temperature Server Model. Note 1. The Light CTL Temperature Server model extends the Generic Level Server model. 1. This model shall support model publication and model subscription. Return New Light CTL Temperature Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_ctl_temp_srv_t. ESP_BLE_MESH_MODEL_LIGHT_HSL_SRV(srv_pub, srv_data) Define a new Light HSL Server Model. Note 1. The Light HSL Server model extends the Light Lightness Server model. When this model is present on an Element, the corresponding Light HSL Hue Server model and the corresponding Light HSL Saturation Server model and the corresponding Light HSL Setup Server model shall also be present. 1. This model shall support model publication and model subscription. 2. The model requires three elements: the main element and the Hue element and the Saturation 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. Espressif Systems 492 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return New Light HSL Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_hsl_setup_srv_t. ESP_BLE_MESH_MODEL_LIGHT_HSL_HUE_SRV(srv_pub, srv_data) Define a new Light HSL Hue Server Model. Note 1. The Light HSL Hue Server model extends the Generic Level Server model. This model is associated with the Light HSL Server model. 1. This model shall support model publication and model subscription. Return New Light HSL Hue Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_hsl_hue_srv_t. ESP_BLE_MESH_MODEL_LIGHT_HSL_SAT_SRV(srv_pub, srv_data) Define a new Light HSL Saturation Server Model. Note 1. The Light HSL Saturation Server model extends the Generic Level Server model. This model is associated with the Light HSL Server model. 1. This model shall support model publication and model subscription. Return New Light HSL Saturation Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_hsl_sat_srv_t. ESP_BLE_MESH_MODEL_LIGHT_XYL_SRV(srv_pub, srv_data) Define a new Light xyL Server Model. Note 1. The Light xyL Server model extends the Light Lightness Server model. When this model is present on an Element, the corresponding Light xyL Setup Server model shall also be present. 1. This model shall support model publication and model subscription. Return New Light xyL Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_xyl_srv_t. ESP_BLE_MESH_MODEL_LIGHT_XYL_SETUP_SRV(srv_pub, srv_data) Define a new Light xyL Setup Server Model. Note 1. The Light xyL Setup Server model extends the Light xyL Server and the Light Lightness Setup Server. 1. This model shall support model subscription. Return New Light xyL Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_xyl_setup_srv_t. ESP_BLE_MESH_MODEL_LIGHT_LC_SRV(srv_pub, srv_data) Define a new Light LC Server Model. Note 1. The Light LC (Lightness Control) Server model extends the Light Lightness Server model and the Generic OnOff Server model. When this model is present on an Element, the corresponding Light LC Setup Server model shall also be present. 1. This model shall support model publication and model subscription. 2. This model may be used to represent an element that is a client to a Sensor Server model and controls the Light Lightness Actual state via defined state bindings. Return New Light LC Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_lc_srv_t. ESP_BLE_MESH_MODEL_LIGHT_LC_SETUP_SRV(srv_pub, srv_data) Define a new Light LC Setup Server Model. Espressif Systems 493 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note 1. The Light LC (Lightness Control) Setup model extends the Light LC Server model. 1. This model shall support model publication and model subscription. 2. This model may be used to configure setup parameters for the Light LC Server model. Return New Light LC Setup Server Model instance. Parameters · srv_pub: Pointer to the unique struct esp_ble_mesh_model_pub_t. · srv_data: Pointer to the unique struct esp_ble_mesh_light_lc_setup_srv_t. Type Definitions typedef void (*esp_ble_mesh_light_client_cb_t)(esp_ble_mesh_light_client_cb_event_t event, esp_ble_mesh_light_client_cb_param_t *param) Bluetooth Mesh Light Client Model function. Lighting Client Model callback function type Parameters · event: Event type · param: Pointer to callback parameter typedef void (*esp_ble_mesh_lighting_server_cb_t)(esp_ble_mesh_lighting_server_cb_event_t event, esp_ble_mesh_lighting_server_cb_param_t 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 ESP_BLE_MESH_LIGHT_CLIENT_SET_STATE_EVT ESP_BLE_MESH_LIGHT_CLIENT_PUBLISH_EVT ESP_BLE_MESH_LIGHT_CLIENT_TIMEOUT_EVT ESP_BLE_MESH_LIGHT_CLIENT_EVT_MAX enum esp_ble_mesh_lc_state_t This enum value is the Light LC State Machine states Values: ESP_BLE_MESH_LC_OFF ESP_BLE_MESH_LC_STANDBY ESP_BLE_MESH_LC_FADE_ON ESP_BLE_MESH_LC_RUN ESP_BLE_MESH_LC_FADE ESP_BLE_MESH_LC_PROLONG ESP_BLE_MESH_LC_FADE_STANDBY_AUTO ESP_BLE_MESH_LC_FADE_STANDBY_MANUAL Espressif Systems 494 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference enum esp_ble_mesh_lighting_server_cb_event_t This enum value is the event of Lighting Server Model Values: ESP_BLE_MESH_LIGHTING_SERVER_STATE_CHANGE_EVT 1. When get_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, no event will be callback to the application layer when Lighting Get messages are received. 2. When set_auto_rsp is set to ESP_BLE_MESH_SERVER_AUTO_RSP, this event will be callback to the application layer when Lighting Set/Set Unack messages are received. ESP_BLE_MESH_LIGHTING_SERVER_RECV_GET_MSG_EVT When get_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Lighting Get messages are received. ESP_BLE_MESH_LIGHTING_SERVER_RECV_SET_MSG_EVT When set_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Lighting Set/Set Unack messages are received. ESP_BLE_MESH_LIGHTING_SERVER_RECV_STATUS_MSG_EVT When status_auto_rsp is set to ESP_BLE_MESH_SERVER_RSP_BY_APP, this event will be callback to the application layer when Sensor Status message is received. ESP_BLE_MESH_LIGHTING_SERVER_EVT_MAX 2.3.5 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. Espressif Systems Fig. 3: ESP NimBLE Stack 495 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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) { (continues on next page) Espressif Systems 496 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) ESP_LOGE(TAG, "esp_nimble_hci_and_controller_init() failed with error: %d ", ret); return; } nimble_port_init(); //Initialize the NimBLE Host configuration nimble_port_freertos_init(ble_host_task); nimble_port_freertos_init() is an optional call that creates a new task in which the NimBLE host will run. The task function should have a call to nimble_port_run(). If a separate task is not required, calling 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 Espressif Systems 497 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 2.4 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 Espressif Systems 498 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 499 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 500 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_ERR_ESPNOW_NOT_INIT (0x3065): ESPNOW is not initialized. ESP_ERR_ESPNOW_ARG (0x3066): Invalid argument ESP_ERR_ESPNOW_NO_MEM (0x3067): Out of memory ESP_ERR_ESPNOW_FULL (0x3068): ESPNOW peer list is full ESP_ERR_ESPNOW_NOT_FOUND (0x3069): ESPNOW peer is not found ESP_ERR_ESPNOW_INTERNAL (0x306a): Internal error ESP_ERR_ESPNOW_EXIST (0x306b): ESPNOW peer has existed ESP_ERR_ESPNOW_IF (0x306c): Interface error ESP_ERR_DPP_FAILURE (0x3097): Generic failure during DPP Operation ESP_ERR_DPP_TX_FAILURE (0x3098): DPP Frame Tx failed OR not Acked ESP_ERR_DPP_INVALID_ATTR (0x3099): Encountered invalid DPP Attribute ESP_ERR_MESH_BASE (0x4000): Starting number of MESH error codes ESP_ERR_MESH_WIFI_NOT_START (0x4001) ESP_ERR_MESH_NOT_INIT (0x4002) ESP_ERR_MESH_NOT_CONFIG (0x4003) ESP_ERR_MESH_NOT_START (0x4004) ESP_ERR_MESH_NOT_SUPPORT (0x4005) ESP_ERR_MESH_NOT_ALLOWED (0x4006) ESP_ERR_MESH_NO_MEMORY (0x4007) ESP_ERR_MESH_ARGUMENT (0x4008) ESP_ERR_MESH_EXCEED_MTU (0x4009) ESP_ERR_MESH_TIMEOUT (0x400a) ESP_ERR_MESH_DISCONNECTED (0x400b) ESP_ERR_MESH_QUEUE_FAIL (0x400c) ESP_ERR_MESH_QUEUE_FULL (0x400d) ESP_ERR_MESH_NO_PARENT_FOUND (0x400e) ESP_ERR_MESH_NO_ROUTE_FOUND (0x400f) ESP_ERR_MESH_OPTION_NULL (0x4010) ESP_ERR_MESH_OPTION_UNKNOWN (0x4011) ESP_ERR_MESH_XON_NO_WINDOW (0x4012) ESP_ERR_MESH_INTERFACE (0x4013) ESP_ERR_MESH_DISCARD_DUPLICATE (0x4014) ESP_ERR_MESH_DISCARD (0x4015) ESP_ERR_MESH_VOTING (0x4016) ESP_ERR_MESH_XMIT (0x4017) ESP_ERR_MESH_QUEUE_READ (0x4018) ESP_ERR_MESH_PS (0x4019) ESP_ERR_MESH_RECV_RELEASE (0x401a) ESP_ERR_ESP_NETIF_BASE (0x5000) Espressif Systems 501 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_ERR_ESP_NETIF_INVALID_PARAMS (0x5001) ESP_ERR_ESP_NETIF_IF_NOT_READY (0x5002) ESP_ERR_ESP_NETIF_DHCPC_START_FAILED (0x5003) ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED (0x5004) ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED (0x5005) ESP_ERR_ESP_NETIF_NO_MEM (0x5006) ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED (0x5007) ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED (0x5008) ESP_ERR_ESP_NETIF_INIT_FAILED (0x5009) ESP_ERR_ESP_NETIF_DNS_NOT_CONFIGURED (0x500a) ESP_ERR_ESP_NETIF_MLD6_FAILED (0x500b) ESP_ERR_ESP_NETIF_IP6_ADDR_FAILED (0x500c) ESP_ERR_FLASH_BASE (0x6000): Starting number of flash error codes ESP_ERR_FLASH_OP_FAIL (0x6001) ESP_ERR_FLASH_OP_TIMEOUT (0x6002) ESP_ERR_FLASH_NOT_INITIALISED (0x6003) ESP_ERR_FLASH_UNSUPPORTED_HOST (0x6004) ESP_ERR_FLASH_UNSUPPORTED_CHIP (0x6005) ESP_ERR_FLASH_PROTECTED (0x6006) ESP_ERR_HTTP_BASE (0x7000): Starting number of HTTP error codes ESP_ERR_HTTP_MAX_REDIRECT (0x7001): The error exceeds the number of HTTP redirects ESP_ERR_HTTP_CONNECT (0x7002): Error open the HTTP connection ESP_ERR_HTTP_WRITE_DATA (0x7003): Error write HTTP data ESP_ERR_HTTP_FETCH_HEADER (0x7004): Error read HTTP header from server ESP_ERR_HTTP_INVALID_TRANSPORT (0x7005): There are no transport support for the input scheme ESP_ERR_HTTP_CONNECTING (0x7006): HTTP connection 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 Espressif Systems 502 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_ERR_MBEDTLS_CTR_DRBG_SEED_FAILED (0x8011): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_SET_HOSTNAME_FAILED (0x8012): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED (0x8013): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_CONF_ALPN_PROTOCOLS_FAILED (0x8014): mbedtls api returned error ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED (0x8015): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILED (0x8016): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_SETUP_FAILED (0x8017): mbedtls api returned error ESP_ERR_MBEDTLS_SSL_WRITE_FAILED (0x8018): mbedtls api returned error ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED (0x8019): mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED (0x801a): mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_CONF_PSK_FAILED (0x801b): mbedtls api returned failed ESP_ERR_MBEDTLS_SSL_TICKET_SETUP_FAILED (0x801c): mbedtls api returned failed ESP_ERR_WOLFSSL_SSL_SET_HOSTNAME_FAILED (0x8031): wolfSSL api returned error ESP_ERR_WOLFSSL_SSL_CONF_ALPN_PROTOCOLS_FAILED (0x8032): wolfSSL api returned error ESP_ERR_WOLFSSL_CERT_VERIFY_SETUP_FAILED (0x8033): wolfSSL api returned error ESP_ERR_WOLFSSL_KEY_VERIFY_SETUP_FAILED (0x8034): wolfSSL api returned error ESP_ERR_WOLFSSL_SSL_HANDSHAKE_FAILED (0x8035): wolfSSL api returned failed ESP_ERR_WOLFSSL_CTX_SETUP_FAILED (0x8036): wolfSSL api returned failed ESP_ERR_WOLFSSL_SSL_SETUP_FAILED (0x8037): wolfSSL api returned failed ESP_ERR_WOLFSSL_SSL_WRITE_FAILED (0x8038): wolfSSL api returned failed ESP_ERR_HTTPS_OTA_BASE (0x9000) ESP_ERR_HTTPS_OTA_IN_PROGRESS (0x9001) ESP_ERR_PING_BASE (0xa000) ESP_ERR_PING_INVALID_PARAMS (0xa001) ESP_ERR_PING_NO_MEM (0xa002) ESP_ERR_HTTPD_BASE (0xb000): Starting number of HTTPD error codes ESP_ERR_HTTPD_HANDLERS_FULL (0xb001): All slots for registering URI handlers have been consumed ESP_ERR_HTTPD_HANDLER_EXISTS (0xb002): URI handler with same method and target URI already 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) Espressif Systems 503 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) ESP_ERR_MEMPROT_UNIMGMT_BLOCK_INVALID (0xd005) ESP_ERR_MEMPROT_WORLD_INVALID (0xd006) ESP_ERR_MEMPROT_AREA_INVALID (0xd007) 2.5 Networking APIs 2.5.1 Wi-Fi ESP-NOW Overview ESP-NOW is a kind of connectionless Wi-Fi communication protocol that is defined by Espressif. In ESP-NOW, application data is encapsulated in a vendor-specific action frame and then transmitted from one Wi-Fi device to another without connection. CTR with CBC-MAC Protocol(CCMP) is used to protect the action frame for security. ESP-NOW is widely used in smart light, remote controlling, sensor, etc. Frame Format ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The default 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. Espressif Systems 504 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 505 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. 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 · 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 Espressif Systems 506 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 507 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 508 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_now_peer_info ESPNOW peer information parameters. Public Members uint8_t peer_addr[ESP_NOW_ETH_ALEN] ESPNOW peer MAC address that is also the MAC address of station or softap uint8_t lmk[ESP_NOW_KEY_LEN] ESPNOW peer local master key that is used to encrypt data uint8_t channel Wi-Fi channel that peer uses to send/receive ESPNOW data. If the value is 0, use the current channel which station or softap is on. Otherwise, it must be set as the channel that station or softap is on. wifi_interface_t ifidx Wi-Fi interface that peer uses to send/receive ESPNOW data bool encrypt ESPNOW data that this peer sends/receives is encrypted or not void *priv ESPNOW peer private data struct esp_now_peer_num Number of ESPNOW peers which exist currently. Public Members int total_num Total number of ESPNOW peers, maximum value is ESP_NOW_MAX_TOTAL_PEER_NUM int encrypt_num Number of encrypted ESPNOW peers, maximum value is ESP_NOW_MAX_ENCRYPT_PEER_NUM Macros ESP_ERR_ESPNOW_BASE ESPNOW error number base. ESP_ERR_ESPNOW_NOT_INIT ESPNOW is not initialized. ESP_ERR_ESPNOW_ARG Invalid argument ESP_ERR_ESPNOW_NO_MEM Out of memory ESP_ERR_ESPNOW_FULL ESPNOW peer list is full ESP_ERR_ESPNOW_NOT_FOUND ESPNOW peer is not found ESP_ERR_ESPNOW_INTERNAL Internal error ESP_ERR_ESPNOW_EXIST ESPNOW peer has existed ESP_ERR_ESPNOW_IF Interface error ESP_NOW_ETH_ALEN Length of ESPNOW peer MAC address Espressif Systems 509 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_NOW_KEY_LEN Length of ESPNOW peer local master key ESP_NOW_MAX_TOTAL_PEER_NUM Maximum number of ESPNOW total peers ESP_NOW_MAX_ENCRYPT_PEER_NUM Maximum number of ESPNOW encrypted peers ESP_NOW_MAX_DATA_LEN Maximum length of ESPNOW data which is sent very time Type Definitions typedef struct esp_now_peer_info esp_now_peer_info_t ESPNOW peer information parameters. typedef struct esp_now_peer_num esp_now_peer_num_t Number of ESPNOW peers which exist currently. typedef void (*esp_now_recv_cb_t)(const uint8_t *mac_addr, const uint8_t *data, int data_len) Callback function of receiving ESPNOW data. Parameters · mac_addr: peer MAC address · data: received data · data_len: length of received data typedef void (*esp_now_send_cb_t)(const uint8_t *mac_addr, esp_now_send_status_t status) Callback function of sending ESPNOW data. Parameters · mac_addr: peer MAC address · status: status of sending ESPNOW data (succeed or fail) Enumerations enum esp_now_send_status_t Status of sending ESPNOW data . Values: ESP_NOW_SEND_SUCCESS = 0 Send ESPNOW data successfully ESP_NOW_SEND_FAIL Send ESPNOW data fail ESP-WIFI-MESH Programming Guide This is a programming guide for ESP-WIFI-MESH, including the API reference and coding examples. This guide is split into the following parts: 1. ESP-WIFI-MESH Programming Model 2. Writing an ESP-WIFI-MESH Application 3. Self Organized Networking 4. Application Examples 5. API Reference For documentation regarding the ESP-WIFI-MESH protocol, please see the ESP-WIFI-MESH API Guide. For more information about ESP-WIFI-MESH Development Framework, please see ESP-WIFI-MESH Development Framework. ESP-WIFI-MESH Programming Model Espressif Systems 510 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 4: 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. Fig. 5: 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, users should not call Wi-Fi APIs after esp_mesh_start() is called, and before esp_mesh_stop() is called. Espressif Systems 511 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 that could become root is required to initialize LwIP by calling esp_netif_init(). In order to prevent non-root node access to LwIP, the application should not create or register any network interfaces using esp_netif APIs. ESP-WIFI-MESH requires a root node to be connected with a router. Therefore, in the event that a node becomes the root, the corresponding handler must start the DHCP client service and immediately obtain an IP address. Doing so will allow other nodes to begin transmitting/receiving packets to/from the external IP network. However, this step is unnecessary if static IP settings are used. Writing an ESP-WIFI-MESH Application The prerequisites for starting ESP-WIFI-MESH is to initialize LwIP and Wi-Fi, The following code snippet demonstrates the necessary prerequisite steps before ESP-WIFI-MESH itself can be initialized. ESP_ERROR_CHECK(esp_netif_init()); /* 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 512 Release v5.0-dev-2349-g4350e6fef8 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 513 Release v5.0-dev-2349-g4350e6fef8 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 514 Release v5.0-dev-2349-g4350e6fef8 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 515 Release v5.0-dev-2349-g4350e6fef8 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 516 Release v5.0-dev-2349-g4350e6fef8 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 517 Release v5.0-dev-2349-g4350e6fef8 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 518 Release v5.0-dev-2349-g4350e6fef8 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 519 Release v5.0-dev-2349-g4350e6fef8 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 520 Release v5.0-dev-2349-g4350e6fef8 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 521 Release v5.0-dev-2349-g4350e6fef8 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 522 Release v5.0-dev-2349-g4350e6fef8 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 523 Release v5.0-dev-2349-g4350e6fef8 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 524 Release v5.0-dev-2349-g4350e6fef8 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 525 Release v5.0-dev-2349-g4350e6fef8 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 526 Release v5.0-dev-2349-g4350e6fef8 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 527 Release v5.0-dev-2349-g4350e6fef8 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 528 Release v5.0-dev-2349-g4350e6fef8 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 529 Release v5.0-dev-2349-g4350e6fef8 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 530 Release v5.0-dev-2349-g4350e6fef8 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 531 Release v5.0-dev-2349-g4350e6fef8 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 532 Release v5.0-dev-2349-g4350e6fef8 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 533 Release v5.0-dev-2349-g4350e6fef8 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 534 Release v5.0-dev-2349-g4350e6fef8 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 535 Release v5.0-dev-2349-g4350e6fef8 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 536 Release v5.0-dev-2349-g4350e6fef8 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 537 Release v5.0-dev-2349-g4350e6fef8 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 538 Release v5.0-dev-2349-g4350e6fef8 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 539 Release v5.0-dev-2349-g4350e6fef8 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 540 Release v5.0-dev-2349-g4350e6fef8 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 541 Release v5.0-dev-2349-g4350e6fef8 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 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. Espressif Systems 542 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 543 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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() Espressif Systems 544 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 545 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 546 Release v5.0-dev-2349-g4350e6fef8 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_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 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 Espressif Systems 547 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_wifi_scan_start(const wifi_scan_config_t *config, bool block) Scan all available APs. Attention If this API is called, the found APs are stored in WiFi driver dynamic allocated memory and the will be freed in esp_wifi_scan_get_ap_records, so generally, call esp_wifi_scan_get_ap_records to cause the memory to be freed once the scan is done Attention The values of maximum active scan time and passive scan time per channel are limited to 1500 milliseconds. Values above 1500ms may cause station to disconnect from AP and are not recommended. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start · ESP_ERR_WIFI_TIMEOUT: blocking scan is timeout · ESP_ERR_WIFI_STATE: wifi still connecting when invoke esp_wifi_scan_start · others: refer to error code in esp_err.h Parameters · config: configuration of scanning · block: if block is true, this API will block the caller until the scan is done, otherwise it will return immediately esp_err_t esp_wifi_scan_stop(void) Stop the scan in process. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start esp_err_t esp_wifi_scan_get_ap_num(uint16_t *number) Get number of APs found in last scan. Attention This API can only be called when the scan is completed, otherwise it may get wrong value. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start · ESP_ERR_INVALID_ARG: invalid argument Parameters · [out] number: store number of APIs found in last scan esp_err_t esp_wifi_scan_get_ap_records(uint16_t *number, wifi_ap_record_t *ap_records) Get AP list found in last scan. Return · 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 Espressif Systems 548 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 549 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Attention 1. API return false if try to get a interface that is not enable Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_IF: invalid interface · ESP_ERR_INVALID_ARG: invalid argument Parameters · ifx: interface to be configured · [out] bw: store bandwidth of interface ifx esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second) Set primary/secondary channel of ESP32. Attention 1. This API should be called after esp_wifi_start() Attention 2. When ESP32 is in STA mode, this API should not be called when STA is scanning or connecting to an external AP Attention 3. When ESP32 is in softAP mode, this API should not be called when softAP has connected to external STAs Attention 4. When ESP32 is in STA+softAP mode, this API should not be called when in the scenarios described above Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_IF: invalid interface · ESP_ERR_INVALID_ARG: invalid argument Parameters · primary: for HT20, primary is the channel number, for HT40, primary is the primary channel · second: for HT20, second is ignored, for HT40, second is the second channel esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second) Get the primary/secondary channel of ESP32. Attention 1. API return false if try to get a interface that is not enable Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_INVALID_ARG: invalid argument Parameters · primary: store current primary channel · [out] second: store current second channel 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. Espressif Systems 550 Release v5.0-dev-2349-g4350e6fef8 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: 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. 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 Espressif Systems 551 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init Parameters · en: false - disable, true - enable esp_err_t esp_wifi_get_promiscuous(bool *en) Get the promiscuous mode. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_INVALID_ARG: invalid argument Parameters · [out] en: store the current status of promiscuous mode esp_err_t esp_wifi_set_promiscuous_filter(const wifi_promiscuous_filter_t *filter) Enable the promiscuous mode packet type filter. Note The default filter is to filter all packets except WIFI_PKT_MISC Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init Parameters · filter: the packet type filtered in promiscuous mode. esp_err_t esp_wifi_get_promiscuous_filter(wifi_promiscuous_filter_t *filter) Get the promiscuous filter. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_INVALID_ARG: invalid argument Parameters · [out] filter: store the current status of promiscuous filter esp_err_t esp_wifi_set_promiscuous_ctrl_filter(const wifi_promiscuous_filter_t *filter) Enable subtype filter of the control packet in promiscuous mode. Note The default filter is to filter none control packet. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init Parameters · filter: the subtype of the control packet filtered in promiscuous mode. 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 Espressif Systems 552 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_INVALID_ARG: invalid argument · ESP_ERR_WIFI_IF: invalid interface · ESP_ERR_WIFI_MODE: invalid mode · ESP_ERR_WIFI_PASSWORD: invalid password · ESP_ERR_WIFI_NVS: WiFi internal NVS error · others: refer to the erro code in esp_err.h Parameters · interface: interface · conf: station or soft-AP configuration esp_err_t esp_wifi_get_config(wifi_interface_t interface, wifi_config_t *conf) Get configuration of specified interface. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_INVALID_ARG: invalid argument · ESP_ERR_WIFI_IF: invalid interface Parameters · interface: interface · [out] conf: station or soft-AP configuration esp_err_t esp_wifi_ap_get_sta_list(wifi_sta_list_t *sta) Get STAs associated with soft-AP. Attention SSC only API Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_INVALID_ARG: invalid argument · ESP_ERR_WIFI_MODE: WiFi mode is wrong · ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid Parameters · [out] sta: station list ap can get the connected 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 Espressif Systems 553 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · storage: : storage type esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, const void *vnd_ie) Set 802.11 Vendor-Specific Information Element. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init() · ESP_ERR_INVALID_ARG: Invalid argument, including if first byte of vnd_ie is not WIFI_VENDOR_IE_ELEMENT_ID (0xDD) or second byte is an invalid length. · ESP_ERR_NO_MEM: Out of memory Parameters · enable: If true, specified IE is enabled. If false, specified IE is removed. · type: Information Element type. Determines the frame type to associate with the IE. · idx: Index to set or clear. Each IE type can be associated with up to two elements (indices 0 & 1). · vnd_ie: Pointer to vendor specific element data. First 6 bytes should be a header with fields matching vendor_ie_data_t. If enable is false, this argument is ignored and can be NULL. Data does not need to remain valid after the function returns. esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx) Register Vendor-Specific Information Element monitoring callback. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init Parameters · cb: Callback function · ctx: Context argument, passed to callback function. esp_err_t esp_wifi_set_max_tx_power(int8_t power) Set maximum transmitting power after WiFi start. Attention 1. Maximum power before wifi startup is limited by PHY init data bin. Attention 2. The value set by this API will be mapped to the max_tx_power of the structure wifi_country_t variable. Attention 3. Mapping Table {Power, max_tx_power} = {{8, 2}, {20, 5}, {28, 7}, {34, 8}, {44, 11}, {52, 13}, {56, 14}, {60, 15}, {66, 16}, {72, 18}, {80, 20}}. Attention 4. Param power unit is 0.25dBm, range is [8, 84] corresponding to 2dBm - 20dBm. Attention 5. Relationship between set value and actual value. As follows: {set value range, actual value} = {{[8, 19],8}, {[20, 27],20}, {[28, 33],28}, {[34, 43],34}, {[44, 51],44}, {[52, 55],52}, {[56, 59],56}, {[60, 65],60}, {[66, 71],66}, {[72, 79],72}, {[80, 84],80}}. Return · 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. Espressif Systems 554 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 555 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start or promiscuous mode is not en- abled · ESP_ERR_INVALID_ARG: invalid argument Parameters · config: configuration esp_err_t esp_wifi_set_csi(bool en) Enable or disable CSI. return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start or promiscuous mode is not en- abled · ESP_ERR_INVALID_ARG: invalid argument Parameters · en: true - enable, false - disable esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config) Set antenna GPIO configuration. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc Parameters · config: Antenna GPIO configuration. esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config) Get current antenna GPIO configuration. Return · ESP_OK: succeed · ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init · ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL Parameters · config: Antenna GPIO configuration. esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config) Set antenna configuration. Return · 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 Espressif Systems 556 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 557 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · others: failed Parameters · cfg: FTM Initiator session configuration esp_err_t esp_wifi_ftm_end_session(void) End the ongoing FTM Initiator session. Attention This API works only on FTM Initiator Return · ESP_OK: succeed · others: failed esp_err_t esp_wifi_ftm_resp_set_offset(int16_t offset_cm) Set offset in cm for FTM Responder. An equivalent offset is calculated in picoseconds and added in TOD of FTM Measurement frame (T1). Attention Use this API only in AP mode before performing FTM as responder Return · ESP_OK: succeed · others: failed Parameters · offset_cm: T1 Offset to be added in centimeters esp_err_t esp_wifi_config_11b_rate(wifi_interface_t ifx, bool disable) Enable or disable 11b rate of specified interface. Attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start(). Attention 2. Only when really need to disable 11b rate call this API otherwise 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. Espressif Systems 558 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 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 Espressif Systems 559 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int tx_buf_type WiFi TX buffer type int static_tx_buf_num WiFi static TX buffer number int dynamic_tx_buf_num WiFi dynamic TX buffer number int cache_tx_buf_num WiFi TX cache buffer number int csi_enable WiFi channel state information enable flag int ampdu_rx_enable WiFi AMPDU RX feature enable flag int ampdu_tx_enable WiFi AMPDU TX feature enable flag int amsdu_tx_enable WiFi AMSDU TX feature enable flag int nvs_enable WiFi NVS flash enable flag int nano_enable Nano option for printf/scan family enable flag int rx_ba_win WiFi Block Ack RX window size int wifi_task_core_id WiFi Task Core ID int beacon_max_len WiFi softAP maximum length of the beacon int mgmt_sbuf_num WiFi management short buffer number, the minimum value is 6, the maximum value is 32 uint64_t feature_caps Enables additional WiFi features and capabilities bool sta_disconnected_pm WiFi Power Management for station at disconnected status int magic WiFi init magic number, it should be the last field Macros ESP_ERR_WIFI_NOT_INIT WiFi driver was not installed by esp_wifi_init ESP_ERR_WIFI_NOT_STARTED WiFi driver was not started by esp_wifi_start ESP_ERR_WIFI_NOT_STOPPED WiFi driver was not stopped by esp_wifi_stop ESP_ERR_WIFI_IF WiFi interface error ESP_ERR_WIFI_MODE WiFi mode error Espressif Systems 560 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_ERR_WIFI_STATE WiFi internal state error ESP_ERR_WIFI_CONN WiFi internal control block of station or soft-AP error ESP_ERR_WIFI_NVS WiFi internal NVS module error ESP_ERR_WIFI_MAC MAC address is invalid ESP_ERR_WIFI_SSID SSID is invalid ESP_ERR_WIFI_PASSWORD Password is invalid ESP_ERR_WIFI_TIMEOUT Timeout error ESP_ERR_WIFI_WAKE_FAIL WiFi is in sleep state(RF closed) and wakeup fail ESP_ERR_WIFI_WOULD_BLOCK The caller would block ESP_ERR_WIFI_NOT_CONNECT Station still in disconnect status ESP_ERR_WIFI_POST Failed to post the event to WiFi task ESP_ERR_WIFI_INIT_STATE Invalid WiFi state when init/deinit is called ESP_ERR_WIFI_STOP_STATE Returned when WiFi is stopping ESP_ERR_WIFI_NOT_ASSOC The WiFi connection is not associated ESP_ERR_WIFI_TX_DISALLOW The WiFi TX is disallowed WIFI_STATIC_TX_BUFFER_NUM WIFI_CACHE_TX_BUFFER_NUM WIFI_DYNAMIC_TX_BUFFER_NUM WIFI_CSI_ENABLED WIFI_AMPDU_RX_ENABLED WIFI_AMPDU_TX_ENABLED WIFI_AMSDU_TX_ENABLED WIFI_NVS_ENABLED WIFI_NANO_FORMAT_ENABLED WIFI_INIT_CONFIG_MAGIC WIFI_DEFAULT_RX_BA_WIN WIFI_TASK_CORE_ID WIFI_SOFTAP_BEACON_MAX_LEN WIFI_MGMT_SBUF_NUM Espressif Systems 561 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 562 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Structures struct wifi_country_t Structure describing WiFi country-based regional restrictions. Public Members char cc[3] country code string uint8_t schan start channel uint8_t nchan total channel number int8_t max_tx_power This field is used for getting WiFi maximum transmitting power, call esp_wifi_set_max_tx_power to set the maximum transmitting power. wifi_country_policy_t policy country policy struct wifi_active_scan_time_t Range of active scan times per channel. Public Members uint32_t min minimum active scan time per channel, units: millisecond uint32_t max maximum active scan time per channel, units: millisecond, values above 1500ms may cause station to disconnect from AP and are not recommended. struct wifi_scan_time_t Aggregate of active & passive scan time per channel. Public Members wifi_active_scan_time_t active active scan time per channel, units: millisecond. uint32_t passive passive scan time per channel, units: millisecond, values above 1500ms may cause station to disconnect from AP and are not recommended. struct wifi_scan_config_t Parameters for an SSID scan. Public Members uint8_t *ssid SSID of AP uint8_t *bssid MAC address of AP uint8_t channel channel, scan the specific channel bool show_hidden enable to scan AP whose SSID is hidden Espressif Systems 563 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference wifi_scan_type_t scan_type scan type, active or passive wifi_scan_time_t scan_time scan time per channel struct wifi_ap_record_t Description of a WiFi AP. Public Members uint8_t bssid[6] MAC address of AP uint8_t ssid[33] SSID of AP uint8_t primary channel of AP wifi_second_chan_t second secondary channel of AP int8_t rssi signal strength of AP wifi_auth_mode_t authmode authmode of AP wifi_cipher_type_t pairwise_cipher pairwise cipher of AP wifi_cipher_type_t group_cipher group cipher of AP wifi_ant_t ant antenna used to receive beacon from AP uint32_t phy_11b : 1 bit: 0 flag to identify if 11b mode is enabled or not uint32_t phy_11g : 1 bit: 1 flag to identify if 11g mode is enabled or not uint32_t phy_11n : 1 bit: 2 flag to identify if 11n mode is enabled or not uint32_t phy_lr : 1 bit: 3 flag to identify if low rate is enabled or not uint32_t wps : 1 bit: 4 flag to identify if WPS is supported or not uint32_t ftm_responder : 1 bit: 5 flag to identify if FTM is supported in responder mode uint32_t ftm_initiator : 1 bit: 6 flag to identify if FTM is supported in initiator mode uint32_t reserved : 25 bit: 7..31 reserved wifi_country_t country country information of AP struct wifi_scan_threshold_t Structure describing parameters for a WiFi fast scan. Espressif Systems 564 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members int8_t rssi The minimum rssi to accept in the fast scan mode wifi_auth_mode_t authmode The weakest authmode to accept in the fast scan mode struct wifi_pmf_config_t Configuration structure for Protected Management Frame Public Members bool capable Deprecated variable. Device will always 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 wifi_pmf_config_t pmf_cfg Configuration for Protected Management Frame Espressif Systems 565 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct wifi_sta_config_t STA configuration settings for the ESP32. Public Members uint8_t ssid[32] SSID of target AP. uint8_t password[64] Password of target AP. wifi_scan_method_t scan_method do all channel scan or fast scan bool bssid_set whether set MAC address of target AP or not. Generally, station_config.bssid_set needs to be 0; and it needs to be 1 only when users need to check the MAC address of the AP. uint8_t bssid[6] MAC address of target AP uint8_t channel channel of target AP. Set to 1~13 to scan starting from the specified channel before connecting to AP. If the channel of AP is unknown, set it to 0. uint16_t listen_interval Listen interval for ESP32 station to receive beacon when WIFI_PS_MAX_MODEM is set. Units: AP beacon intervals. Defaults to 3 if set to 0. wifi_sort_method_t sort_method sort the connect AP in the list by rssi or security mode wifi_scan_threshold_t threshold When sort_method is set, only APs which have an auth mode that is more secure than the selected auth mode and a signal stronger than the minimum RSSI will be used. wifi_pmf_config_t pmf_cfg Configuration for Protected Management Frame. Will be advertized in RSN Capabilities in RSN IE. uint32_t rm_enabled : 1 Whether Radio Measurements are enabled for the connection uint32_t btm_enabled : 1 Whether BSS Transition Management is enabled for the connection uint32_t mbo_enabled : 1 Whether MBO is enabled for the connection 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 Espressif Systems 566 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint32_t phy_11g : 1 bit: 1 flag to identify if 11g mode is enabled or not uint32_t phy_11n : 1 bit: 2 flag to identify if 11n mode is enabled or not uint32_t phy_lr : 1 bit: 3 flag to identify if low rate is enabled or not uint32_t is_mesh_child : 1 bit: 4 flag to identify mesh child uint32_t reserved : 27 bit: 5..31 reserved struct wifi_sta_list_t List of stations associated with the ESP32 Soft-AP. Public Members wifi_sta_info_t sta[ESP_WIFI_MAX_CONN_NUM] station list int num number of stations in the list (other entries are invalid) struct vendor_ie_data_t Vendor Information Element header. The first bytes of the Information Element will match this header. Payload follows. Public Members uint8_t element_id Should be set to WIFI_VENDOR_IE_ELEMENT_ID (0xDD) uint8_t length Length of all bytes in the element data following this field. Minimum 4. uint8_t vendor_oui[3] Vendor identifier (OUI). uint8_t vendor_oui_type Vendor-specific OUI type. uint8_t payload[0] Payload. Length is equal to value in 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 Espressif Systems 567 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference unsigned sig_mode : 2 0: non HT(11bg) packet; 1: HT(11n) packet; 3: VHT(11ac) packet unsigned __pad1__ : 16 reserved unsigned mcs : 7 Modulation Coding Scheme. If is HT(11n) packet, shows the modulation, range from 0 to 76(MSC0 ~ MCS76) unsigned cwb : 1 Channel Bandwidth of the packet. 0: 20MHz; 1: 40MHz unsigned __pad2__ : 16 reserved unsigned smoothing : 1 reserved unsigned not_sounding : 1 reserved unsigned __pad3__ : 1 reserved unsigned aggregation : 1 Aggregation. 0: MPDU packet; 1: AMPDU packet unsigned stbc : 2 Space Time Block Code(STBC). 0: non STBC packet; 1: STBC packet unsigned fec_coding : 1 Flag is set for 11n packets which are LDPC unsigned sgi : 1 Short Guide Interval(SGI). 0: Long GI; 1: Short GI 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 Espressif Systems 568 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 569 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference bool channel_filter_en enable to turn on channel filter to smooth adjacent sub-carrier. Disable it to keep independence of adjacent sub-carrier. Default enabled bool manu_scale manually scale the CSI data by left shifting or automatically scale the CSI data. If set true, please set the shift bits. false: automatically. true: manually. Default false uint8_t shift manually left shift bits of the scale of the CSI data. The range of the left shift bits is 0~15 struct wifi_csi_info_t CSI data type. Public Members wifi_pkt_rx_ctrl_t rx_ctrl received packet radio metadata header of the CSI data uint8_t mac[6] source MAC address of the CSI data bool first_word_invalid first four bytes of the CSI data is invalid or not int8_t *buf buffer of CSI data uint16_t len length of CSI data struct wifi_ant_gpio_t WiFi GPIO configuration for antenna selection. Public Members uint8_t gpio_select : 1 Whether this GPIO is connected to external antenna switch uint8_t gpio_num : 7 The GPIO number that connects to external antenna switch struct wifi_ant_gpio_config_t WiFi GPIOs configuration for antenna selection. Public Members wifi_ant_gpio_t gpio_cfg[4] The configurations of GPIOs that connect to external antenna switch struct wifi_ant_config_t WiFi antenna configuration. Public Members wifi_ant_mode_t rx_ant_mode WiFi antenna mode for receiving wifi_ant_t rx_ant_default Default antenna mode for receiving, itns ignored if rx_ant_mode is not WIFI_ANT_MODE_AUTO Espressif Systems 570 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference wifi_ant_mode_t tx_ant_mode WiFi antenna mode for transmission, it can be set to WIFI_ANT_MODE_AUTO only if rx_ant_mode is set to WIFI_ANT_MODE_AUTO uint8_t enabled_ant0 : 4 Index (in antenna GPIO configuration) of enabled WIFI_ANT_MODE_ANT0 uint8_t enabled_ant1 : 4 Index (in antenna GPIO configuration) of enabled WIFI_ANT_MODE_ANT1 struct wifi_action_tx_req_t Action Frame Tx Request. Public Members wifi_interface_t ifx WiFi interface to send request to uint8_t dest_mac[6] Destination MAC address bool no_ack Indicates no ack required wifi_action_rx_cb_t rx_cb Rx Callback to receive any response uint32_t data_len Length of the appended Data uint8_t data[0] Appended Data payload struct wifi_ftm_initiator_cfg_t FTM Initiator configuration. Public Members uint8_t resp_mac[6] MAC address of the FTM Responder uint8_t channel Primary channel of the FTM Responder uint8_t frm_count No. of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0(No pref), 16, 24, 32, 64) uint16_t burst_period Requested time period between consecutive FTM bursts in 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 Espressif Systems 571 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct wifi_event_sta_connected_t Argument structure for WIFI_EVENT_STA_CONNECTED event Public Members uint8_t ssid[32] SSID of connected AP uint8_t ssid_len SSID length of connected AP uint8_t bssid[6] BSSID of connected AP uint8_t channel channel of connected AP 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 Espressif Systems 572 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t ap_cred_cnt Number of AP credentials received uint8_t ssid[MAX_SSID_LEN] SSID of AP uint8_t passphrase[MAX_PASSPHRASE_LEN] Passphrase for the AP struct wifi_event_sta_wps_er_success_t::[anonymous] ap_cred[MAX_WPS_AP_CRED] All AP credentials received from WPS handshake struct wifi_event_ap_staconnected_t Argument structure for WIFI_EVENT_AP_STACONNECTED event Public Members uint8_t mac[6] MAC address of the station connected to ESP32 soft-AP uint8_t aid the aid that ESP32 soft-AP gives to the station connected to bool is_mesh_child flag to identify mesh child struct wifi_event_ap_stadisconnected_t Argument structure for WIFI_EVENT_AP_STADISCONNECTED event Public Members uint8_t mac[6] MAC address of the station disconnects to ESP32 soft-AP uint8_t aid the aid that ESP32 soft-AP gave to the station disconnects to bool is_mesh_child flag to identify mesh child struct wifi_event_ap_probe_req_rx_t Argument structure for WIFI_EVENT_AP_PROBEREQRECVED event Public Members int rssi Received probe request signal strength uint8_t mac[6] MAC address of the station which send probe request struct wifi_event_bss_rssi_low_t Argument structure for WIFI_EVENT_STA_BSS_RSSI_LOW event Public Members int32_t rssi RSSI value of bss Espressif Systems 573 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct wifi_ftm_report_entry_t Argument structure for Public Members uint8_t dlog_token Dialog Token of the FTM frame int8_t rssi RSSI of the FTM frame received uint32_t rtt Round Trip Time in pSec with a peer uint64_t t1 Time of departure of FTM frame from FTM Responder in pSec uint64_t t2 Time of arrival of FTM frame at FTM Initiator in pSec uint64_t t3 Time of departure of ACK from FTM Initiator in pSec uint64_t t4 Time of arrival of ACK at FTM Responder in pSec struct wifi_event_ftm_report_t Argument structure for WIFI_EVENT_FTM_REPORT event Public Members uint8_t peer_mac[6] MAC address of the FTM Peer wifi_ftm_status_t status Status of the FTM operation uint32_t rtt_raw Raw average Round-Trip-Time with peer in Nano-Seconds uint32_t rtt_est Estimated Round-Trip-Time with peer in Nano-Seconds uint32_t dist_est Estimated one-way distance in Centi-Meters wifi_ftm_report_entry_t *ftm_report_data Pointer to FTM Report with multiple entries, should be freed after use uint8_t ftm_report_num_entries Number of entries in the FTM Report data struct wifi_event_action_tx_status_t Argument structure for WIFI_EVENT_ACTION_TX_STATUS event Public Members wifi_interface_t ifx WiFi interface to send request to uint32_t context Context to identify the request Espressif Systems 574 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint8_t da[6] Destination MAC address uint8_t status Status of the operation struct wifi_event_roc_done_t Argument structure for WIFI_EVENT_ROC_DONE event Public Members uint32_t context Context to identify the request Macros WIFI_OFFCHAN_TX_REQ WIFI_OFFCHAN_TX_CANCEL WIFI_ROC_REQ WIFI_ROC_CANCEL WIFI_PROTOCOL_11B WIFI_PROTOCOL_11G WIFI_PROTOCOL_11N WIFI_PROTOCOL_LR ESP_WIFI_MAX_CONN_NUM max number of stations which can connect to ESP32 soft-AP WIFI_VENDOR_IE_ELEMENT_ID WIFI_PROMIS_FILTER_MASK_ALL filter all packets WIFI_PROMIS_FILTER_MASK_MGMT filter the packets with type of WIFI_PKT_MGMT WIFI_PROMIS_FILTER_MASK_CTRL filter the packets with type of WIFI_PKT_CTRL WIFI_PROMIS_FILTER_MASK_DATA filter the packets with type of WIFI_PKT_DATA WIFI_PROMIS_FILTER_MASK_MISC filter the packets with type of WIFI_PKT_MISC WIFI_PROMIS_FILTER_MASK_DATA_MPDU filter the MPDU which is a kind of WIFI_PKT_DATA WIFI_PROMIS_FILTER_MASK_DATA_AMPDU filter the AMPDU which is a kind of WIFI_PKT_DATA WIFI_PROMIS_FILTER_MASK_FCSFAIL filter the FCS failed packets, do not open it in general WIFI_PROMIS_CTRL_FILTER_MASK_ALL filter all control packets WIFI_PROMIS_CTRL_FILTER_MASK_WRAPPER filter the control packets with subtype of Control Wrapper WIFI_PROMIS_CTRL_FILTER_MASK_BAR filter the control packets with subtype of Block Ack Request Espressif Systems 575 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference WIFI_PROMIS_CTRL_FILTER_MASK_BA filter the control packets with subtype of Block Ack WIFI_PROMIS_CTRL_FILTER_MASK_PSPOLL filter the control packets with subtype of PS-Poll WIFI_PROMIS_CTRL_FILTER_MASK_RTS filter the control packets with subtype of RTS WIFI_PROMIS_CTRL_FILTER_MASK_CTS filter the control packets with subtype of CTS WIFI_PROMIS_CTRL_FILTER_MASK_ACK filter the control packets with subtype of ACK WIFI_PROMIS_CTRL_FILTER_MASK_CFEND filter the control packets with subtype of CF-END WIFI_PROMIS_CTRL_FILTER_MASK_CFENDACK filter the control packets with subtype of CF-END+CF-ACK WIFI_EVENT_MASK_ALL mask all WiFi events WIFI_EVENT_MASK_NONE mask none of the WiFi events WIFI_EVENT_MASK_AP_PROBEREQRECVED mask SYSTEM_EVENT_AP_PROBEREQRECVED event MAX_SSID_LEN MAX_PASSPHRASE_LEN MAX_WPS_AP_CRED WIFI_STATIS_BUFFER WIFI_STATIS_RXTX WIFI_STATIS_HW WIFI_STATIS_DIAG WIFI_STATIS_PS WIFI_STATIS_ALL Type Definitions typedef int (*wifi_action_rx_cb_t)(uint8_t *hdr, uint8_t *payload, size_t len, uint8_t channel) The Rx callback function of Action Tx operations. Parameters · hdr: pointer to the IEEE 802.11 Header structure · payload: pointer to the Payload following 802.11 Header · len: length of the Payload · channel: channel number the frame is received on Enumerations enum wifi_mode_t Values: WIFI_MODE_NULL = 0 null mode WIFI_MODE_STA WiFi station mode Espressif Systems 576 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference WIFI_MODE_AP WiFi soft-AP mode WIFI_MODE_APSTA WiFi station + soft-AP mode WIFI_MODE_MAX enum wifi_interface_t Values: WIFI_IF_STA = ESP_IF_WIFI_STA WIFI_IF_AP = ESP_IF_WIFI_AP enum wifi_country_policy_t Values: WIFI_COUNTRY_POLICY_AUTO Country policy is auto, use the country info of AP to which the station is connected WIFI_COUNTRY_POLICY_MANUAL Country policy is manual, always use the configured country info enum wifi_auth_mode_t Values: WIFI_AUTH_OPEN = 0 authenticate mode : open WIFI_AUTH_WEP authenticate mode : WEP WIFI_AUTH_WPA_PSK authenticate mode : WPA_PSK WIFI_AUTH_WPA2_PSK authenticate mode : WPA2_PSK WIFI_AUTH_WPA_WPA2_PSK authenticate mode : WPA_WPA2_PSK WIFI_AUTH_WPA2_ENTERPRISE authenticate mode : WPA2_ENTERPRISE WIFI_AUTH_WPA3_PSK authenticate mode : WPA3_PSK WIFI_AUTH_WPA2_WPA3_PSK authenticate mode : WPA2_WPA3_PSK WIFI_AUTH_WAPI_PSK authenticate mode : WAPI_PSK WIFI_AUTH_MAX enum wifi_err_reason_t Values: WIFI_REASON_UNSPECIFIED = 1 WIFI_REASON_AUTH_EXPIRE = 2 WIFI_REASON_AUTH_LEAVE = 3 WIFI_REASON_ASSOC_EXPIRE = 4 WIFI_REASON_ASSOC_TOOMANY = 5 WIFI_REASON_NOT_AUTHED = 6 WIFI_REASON_NOT_ASSOCED = 7 Espressif Systems 577 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference WIFI_REASON_ASSOC_LEAVE = 8 WIFI_REASON_ASSOC_NOT_AUTHED = 9 WIFI_REASON_DISASSOC_PWRCAP_BAD = 10 WIFI_REASON_DISASSOC_SUPCHAN_BAD = 11 WIFI_REASON_BSS_TRANSITION_DISASSOC = 12 WIFI_REASON_IE_INVALID = 13 WIFI_REASON_MIC_FAILURE = 14 WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT = 15 WIFI_REASON_GROUP_KEY_UPDATE_TIMEOUT = 16 WIFI_REASON_IE_IN_4WAY_DIFFERS = 17 WIFI_REASON_GROUP_CIPHER_INVALID = 18 WIFI_REASON_PAIRWISE_CIPHER_INVALID = 19 WIFI_REASON_AKMP_INVALID = 20 WIFI_REASON_UNSUPP_RSN_IE_VERSION = 21 WIFI_REASON_INVALID_RSN_IE_CAP = 22 WIFI_REASON_802_1X_AUTH_FAILED = 23 WIFI_REASON_CIPHER_SUITE_REJECTED = 24 WIFI_REASON_INVALID_PMKID = 53 WIFI_REASON_BEACON_TIMEOUT = 200 WIFI_REASON_NO_AP_FOUND = 201 WIFI_REASON_AUTH_FAIL = 202 WIFI_REASON_ASSOC_FAIL = 203 WIFI_REASON_HANDSHAKE_TIMEOUT = 204 WIFI_REASON_CONNECTION_FAIL = 205 WIFI_REASON_AP_TSF_RESET = 206 WIFI_REASON_ROAMING = 207 enum wifi_second_chan_t Values: WIFI_SECOND_CHAN_NONE = 0 the channel width is HT20 WIFI_SECOND_CHAN_ABOVE the channel width is HT40 and the secondary channel is above the primary channel WIFI_SECOND_CHAN_BELOW the channel width is HT40 and the secondary channel is below the primary channel enum wifi_scan_type_t Values: WIFI_SCAN_TYPE_ACTIVE = 0 active scan WIFI_SCAN_TYPE_PASSIVE passive scan enum wifi_cipher_type_t Values: Espressif Systems 578 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference WIFI_CIPHER_TYPE_NONE = 0 the cipher type is none WIFI_CIPHER_TYPE_WEP40 the cipher type is WEP40 WIFI_CIPHER_TYPE_WEP104 the cipher type is WEP104 WIFI_CIPHER_TYPE_TKIP the cipher type is TKIP WIFI_CIPHER_TYPE_CCMP the cipher type is CCMP WIFI_CIPHER_TYPE_TKIP_CCMP the cipher type is TKIP and CCMP WIFI_CIPHER_TYPE_AES_CMAC128 the cipher type is AES-CMAC-128 WIFI_CIPHER_TYPE_SMS4 the cipher type is SMS4 WIFI_CIPHER_TYPE_GCMP the cipher type is GCMP WIFI_CIPHER_TYPE_GCMP256 the cipher type is GCMP-256 WIFI_CIPHER_TYPE_AES_GMAC128 the cipher type is AES-GMAC-128 WIFI_CIPHER_TYPE_AES_GMAC256 the cipher type is AES-GMAC-256 WIFI_CIPHER_TYPE_UNKNOWN the cipher type is unknown enum wifi_ant_t WiFi antenna. Values: WIFI_ANT_ANT0 WiFi antenna 0 WIFI_ANT_ANT1 WiFi antenna 1 WIFI_ANT_MAX Invalid WiFi antenna enum wifi_scan_method_t Values: WIFI_FAST_SCAN = 0 Do fast scan, scan will end after find SSID match AP WIFI_ALL_CHANNEL_SCAN All channel scan, scan will end after scan all the channel enum wifi_sort_method_t Values: WIFI_CONNECT_AP_BY_SIGNAL = 0 Sort match AP in scan list by RSSI WIFI_CONNECT_AP_BY_SECURITY Sort match AP in scan list by security mode Espressif Systems 579 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 580 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 581 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 582 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference WIFI_EVENT_STA_STOP ESP32 station stop WIFI_EVENT_STA_CONNECTED ESP32 station connected to AP WIFI_EVENT_STA_DISCONNECTED ESP32 station disconnected from AP WIFI_EVENT_STA_AUTHMODE_CHANGE the auth mode of AP connected by ESP32 station changed WIFI_EVENT_STA_WPS_ER_SUCCESS ESP32 station wps succeeds in enrollee mode WIFI_EVENT_STA_WPS_ER_FAILED ESP32 station wps fails in enrollee mode WIFI_EVENT_STA_WPS_ER_TIMEOUT ESP32 station wps timeout in enrollee mode WIFI_EVENT_STA_WPS_ER_PIN ESP32 station wps pin code in enrollee mode WIFI_EVENT_STA_WPS_ER_PBC_OVERLAP ESP32 station wps overlap in enrollee mode WIFI_EVENT_AP_START ESP32 soft-AP start WIFI_EVENT_AP_STOP ESP32 soft-AP stop WIFI_EVENT_AP_STACONNECTED a station connected to ESP32 soft-AP WIFI_EVENT_AP_STADISCONNECTED a station disconnected from ESP32 soft-AP WIFI_EVENT_AP_PROBEREQRECVED Receive probe request packet in soft-AP interface WIFI_EVENT_FTM_REPORT Receive report of FTM procedure WIFI_EVENT_STA_BSS_RSSI_LOW 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 Espressif Systems 583 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference WPS_FAIL_REASON_MAX enum wifi_ftm_status_t FTM operation status types. Values: FTM_STATUS_SUCCESS = 0 FTM exchange is successful FTM_STATUS_UNSUPPORTED Peer does not support FTM FTM_STATUS_CONF_REJECTED Peer rejected FTM configuration in FTM Request FTM_STATUS_NO_RESPONSE Peer did not respond to FTM Requests FTM_STATUS_FAIL Unknown error during FTM exchange 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 · 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. Espressif Systems 584 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Starts DPP Supplicant and initializes related Data Structures. return · ESP_OK: Success · ESP_FAIL: Failure Parameters · evt_cb: Callback function to receive DPP related events void esp_supp_dpp_deinit(void) De-initalize DPP Supplicant. Frees memory from DPP Supplicant Data Structures. esp_err_t esp_supp_dpp_bootstrap_gen(const char *chan_list, esp_supp_dpp_bootstrap_t type, const char *key, const char *info) Generates Bootstrap Information as an Enrollee. Generates Out Of Band Bootstrap information as an Enrollee which can be used by a DPP Configurator to provision the Enrollee. Return · ESP_OK: Success · ESP_FAIL: Failure Parameters · chan_list: List of channels device will be available on for listening · type: Bootstrap method type, only QR Code method is supported for now. · key: (Optional) Private Key used to generate a Bootstrapping Public Key · info: (Optional) Ancilliary Device Information like Serial Number esp_err_t esp_supp_dpp_start_listen(void) Start listening on Channels provided during esp_supp_dpp_bootstrap_gen. Listens on every Channel from Channel List for a pre-defined wait time. Return · ESP_OK: Success · ESP_FAIL: Generic Failure · ESP_ERR_INVALID_STATE: ROC attempted before WiFi is started · ESP_ERR_NO_MEM: Memory allocation failed while posting ROC request void esp_supp_dpp_stop_listen(void) Stop listening on Channels. Stops listening on Channels and cancels ongoing listen operation. Macros ESP_ERR_DPP_FAILURE Generic failure during DPP Operation ESP_ERR_DPP_TX_FAILURE DPP Frame Tx failed OR not Acked ESP_ERR_DPP_INVALID_ATTR Encountered invalid DPP Attribute Type Definitions typedef enum dpp_bootstrap_type esp_supp_dpp_bootstrap_t Types of Bootstrap Methods for DPP. typedef void (*esp_supp_dpp_event_cb_t)(esp_supp_dpp_event_t evt, void *data) Callback function for receiving DPP Events from Supplicant. Espressif Systems 585 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Callback function will be called with DPP related information. Parameters · evt: DPP event ID · data: Event data payload Enumerations enum dpp_bootstrap_type Types of Bootstrap Methods for DPP. Values: DPP_BOOTSTRAP_QR_CODE QR Code Method DPP_BOOTSTRAP_PKEX Proof of Knowledge Method DPP_BOOTSTRAP_NFC_URI NFC URI record Method enum esp_supp_dpp_event_t Types of Callback Events received from DPP Supplicant. Values: ESP_SUPP_DPP_URI_READY URI is ready through Bootstrapping ESP_SUPP_DPP_CFG_RECVD Config received via DPP Authentication ESP_SUPP_DPP_FAIL DPP Authentication failure Code examples for the Wi-Fi API are provided in the wifi directory of ESP-IDF examples. Code examples for ESP-WIFI-MESH are provided in the mesh directory of ESP-IDF examples. 2.5.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. Espressif Systems 586 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Thus the traffic on the twist-pair cabling will appear as shown blow: Fig. 6: Ethernet Data Frame Format Preamble and Start-of-Frame Delimiter The preamble contains seven bytes of 55H, it allows the receiver to lock onto the stream of data before the actual frame arrives. The Start-of-Frame Delimiter (SFD) is a binary sequence 10101011 (as seen on the physical medium). It is sometimes considered to be part of the preamble. When transmitting and receiving data, the preamble and SFD bytes will automatically be generated or stripped from the packets. Destination Address The destination address field contains a 6-byte length MAC address of the device that the packet is directed to. If the Least Significant bit in the first byte of the MAC address is set, the address is a multi-cast destination. For example, 01-00-00-00-F0-00 and 33-45-67-89-AB-CD are multi-cast addresses, while 00-00-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. Espressif Systems 587 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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: · eth_mac_config_t::sw_reset_timeout_ms: software reset timeout value, in milliseconds, typically MAC reset should be finished within 100ms. · eth_mac_config_t::rx_task_stack_size and eth_mac_config_t::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. · eth_mac_config_t::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: · eth_phy_config_t::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 Espressif Systems 588 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · eth_phy_config_t::reset_timeout_ms: reset timeout value, in milliseconds, typically PHY reset should be finished within 100ms. · eth_phy_config_t::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. · eth_phy_config_t::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, .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. Espressif Systems 589 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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: · esp_eth_config_t::mac: instance that created from MAC generator (e.g. esp_eth_mac_new_esp32()). · esp_eth_config_t::phy: instance that created from PHY generator (e.g. esp_eth_phy_new_ip101()). · esp_eth_config_t::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. · esp_eth_config_t::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. · esp_eth_config_t::on_lowlevel_init_done and esp_eth_config_t::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, ð_handle); // install driver Ethernet driver also includes event-driven model, which will send useful and important event to user space. We need to initialize the event loop before installing the Ethernet driver. For more information about event-driven programming, please refer to ESP Event. /** Event handler for Ethernet events */ static void eth_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data) { uint8_t mac_addr[6] = {0}; /* we can get the ethernet driver handle from event data */ esp_eth_handle_t eth_handle = *(esp_eth_handle_t *)event_data; switch (event_id) { case ETHERNET_EVENT_CONNECTED: esp_eth_ioctl(eth_handle, ETH_CMD_G_MAC_ADDR, mac_addr); ESP_LOGI(TAG, "Ethernet Link Up"); ESP_LOGI(TAG, "Ethernet HW Addr %02x:%02x:%02x:%02x:%02x:%02x", mac_addr[0], mac_addr[1], mac_addr[2], mac_addr[3], mac_ addr[4], mac_addr[5]); break; case ETHERNET_EVENT_DISCONNECTED: ESP_LOGI(TAG, "Ethernet Link Down"); break; case ETHERNET_EVENT_START: ESP_LOGI(TAG, "Ethernet Started"); break; case ETHERNET_EVENT_STOP: ESP_LOGI(TAG, "Ethernet Stopped"); break; default: (continues on next page) Espressif Systems 590 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference break; } } (continued from previous page) esp_event_loop_create_default(); // create a default event loop that running in background esp_event_handler_register(ETH_EVENT, ESP_EVENT_ANY_ID, ð_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; 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. Espressif Systems 591 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 592 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 593 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 594 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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. Espressif Systems 595 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 596 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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 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 Espressif Systems 597 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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 Espressif Systems 598 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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. Espressif Systems 599 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 600 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 601 Release v5.0-dev-2349-g4350e6fef8 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 (*set_addr)(esp_eth_mac_t *mac, uint8_t *addr) Set MAC address. Return · ESP_OK: set MAC address successfully · ESP_ERR_INVALID_ARG: set MAC address failed because of invalid argument · ESP_FAIL: set MAC address failed because some other error occurred Parameters · [in] mac: Ethernet MAC instance · [in] addr: MAC address esp_err_t (*get_addr)(esp_eth_mac_t *mac, uint8_t *addr) Get MAC address. Return · ESP_OK: get MAC address successfully · ESP_ERR_INVALID_ARG: get MAC address failed because of invalid argument · ESP_FAIL: get MAC address failed because some other error occurred Parameters · [in] mac: Ethernet MAC instance · [out] addr: MAC address esp_err_t (*set_speed)(esp_eth_mac_t *mac, eth_speed_t speed) Set speed of MAC. Return · ESP_OK: set MAC speed successfully · ESP_ERR_INVALID_ARG: set MAC speed failed because of invalid argument · ESP_FAIL: set MAC speed failed because some other error occurred Parameters · [in] ma:c: Ethernet MAC instance · [in] speed: MAC speed esp_err_t (*set_duplex)(esp_eth_mac_t *mac, eth_duplex_t duplex) Set duplex mode of MAC. Return · ESP_OK: set MAC duplex mode successfully · ESP_ERR_INVALID_ARG: set MAC duplex failed because of invalid argument · ESP_FAIL: set MAC duplex failed because some other error occurred Parameters · [in] mac: Ethernet MAC instance · [in] duplex: MAC duplex esp_err_t (*set_link)(esp_eth_mac_t *mac, eth_link_t link) Set link status of MAC. Return · ESP_OK: set link status successfully · ESP_ERR_INVALID_ARG: set link status failed because of invalid argument · ESP_FAIL: set link status failed because some other error occurred 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 Espressif Systems 602 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_FAIL: set promiscuous mode failed because some error occurred Parameters · [in] mac: Ethernet MAC instance · [in] enable: set true to enable promiscuous mode; set false to disable promiscuous mode esp_err_t (*enable_flow_ctrl)(esp_eth_mac_t *mac, bool enable) Enable flow control on MAC layer or not. Return · ESP_OK: set flow control successfully · ESP_FAIL: set flow control failed because some error occurred Parameters · [in] mac: Ethernet MAC instance · [in] enable: set true to enable flow control; set false to disable flow control esp_err_t (*set_peer_pause_ability)(esp_eth_mac_t *mac, uint32_t ability) Set the PAUSE ability of peer node. Return · ESP_OK: set peer pause ability successfully · ESP_FAIL: set peer pause ability failed because some error occurred Parameters · [in] mac: Ethernet MAC instance · [in] ability: zero indicates that pause function is supported by link partner; non-zero indicates that pause function is not supported by link partner esp_err_t (*del)(esp_eth_mac_t *mac) Free memory of Ethernet MAC. Return · ESP_OK: free Ethernet MAC instance successfully · ESP_FAIL: free Ethernet MAC instance failed because some error occurred Parameters · [in] mac: Ethernet MAC instance struct eth_mac_config_t Configuration of Ethernet MAC object. Public Members uint32_t sw_reset_timeout_ms Software reset timeout value (Unit: ms) uint32_t rx_task_stack_size Stack size of the receive task uint32_t rx_task_prio Priority of the receive task uint32_t flags Flags that specify extra capability for mac driver 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. Espressif Systems 603 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 604 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 605 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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 Espressif Systems 606 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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 · 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 Espressif Systems 607 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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. 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 Espressif Systems 608 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.5.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. API Reference For manipulating the Thread network, the OpenThread api shall be used. The OpenThread api docs can be found at the OpenThread official website. ESP-IDF provides extra apis for launching and managing the OpenThread stack, binding to network interfaces and border routing features. Header File · components/openthread/include/esp_openthread.h Functions esp_err_t esp_openthread_init(const esp_openthread_platform_config_t *init_config) Initializes the full OpenThread stack. Note The OpenThread instance will also be initialized in this function. Return · ESP_OK on success · ESP_ERR_NO_MEM if allocation has failed · ESP_ERR_INVALID_ARG if radio or host connection mode not supported · ESP_ERR_INVALID_STATE if already initialized Parameters · [in] init_config: The initialization configuration. esp_err_t esp_openthread_launch_mainloop(void) Launches the OpenThread main loop. Espressif Systems 609 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note Thie function will not return unless error happens when running the OpenThread stack. Return · ESP_OK on success · ESP_ERR_NO_MEM if allocation has failed · ESP_FAIL on other failures esp_err_t esp_openthread_deinit(void) This function performs OpenThread stack and platform driver deinitialization. Return · ESP_OK on success · ESP_ERR_INVALID_STATE if not initialized otInstance *esp_openthread_get_instance(void) This function acquires the underlying OpenThread instance. Note This function can be called on other tasks without lock. Return The OpenThread instance pointer Header File · components/openthread/include/esp_openthread_types.h Structures struct esp_openthread_mainloop_context_t This structure represents a context for a select() based mainloop. Public Members fd_set read_fds The read file descriptors fd_set write_fds The write file descriptors fd_set error_fds The error file descriptors int max_fd The max file descriptor struct timeval timeout The timeout struct esp_openthread_uart_config_t The uart port config for OpenThread. Public Members uart_port_t port UART port number uart_config_t uart_config UART configuration, see uart_config_t docs int rx_pin UART RX pin int tx_pin UART TX pin struct esp_openthread_radio_config_t The OpenThread radio configuration. Espressif Systems 610 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_openthread_radio_mode_t radio_mode The radio mode esp_openthread_uart_config_t radio_uart_config The uart configuration to RCP struct esp_openthread_host_connection_config_t The OpenThread host connection configuration. Public Members esp_openthread_host_connection_mode_t host_connection_mode The host connection mode esp_openthread_uart_config_t host_uart_config The uart configuration to host struct esp_openthread_port_config_t The OpenThread port specific configuration. Public Members const char *storage_partition_name The partition for storing OpenThread dataset uint8_t netif_queue_size The packet queue size for the network interface uint8_t task_queue_size The task queue size struct esp_openthread_platform_config_t The OpenThread platform configuration. Public Members esp_openthread_radio_config_t radio_config The radio configuration esp_openthread_host_connection_config_t host_config The host connection configuration esp_openthread_port_config_t port_config The port configuration Enumerations enum esp_openthread_event_t OpenThread event declarations. Values: OPENTHREAD_EVENT_START OpenThread stack start OPENTHREAD_EVENT_STOP OpenThread stack stop OPENTHREAD_EVENT_IF_UP OpenThread network interface up Espressif Systems 611 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference OPENTHREAD_EVENT_IF_DOWN OpenThread network interface down OPENTHREAD_EVENT_GOT_IP6 OpenThread stack added IPv6 address OPENTHREAD_EVENT_LOST_IP6 OpenThread stack removed IPv6 address OPENTHREAD_EVENT_MULTICAST_GROUP_JOIN OpenThread stack joined IPv6 multicast group OPENTHREAD_EVENT_MULTICAST_GROUP_LEAVE OpenThread stack left IPv6 multicast group OPENTHREAD_EVENT_TREL_ADD_IP6 OpenThread stack added TREL IPv6 address OPENTHREAD_EVENT_TREL_REMOVE_IP6 OpenThread stack removed TREL IPv6 address OPENTHREAD_EVENT_TREL_MULTICAST_GROUP_JOIN OpenThread stack joined TREL IPv6 multicast group enum esp_openthread_radio_mode_t The radio mode of OpenThread. Values: RADIO_MODE_NATIVE = 0x0 Use the native 15.4 radio RADIO_MODE_UART_RCP = 0x1 UART connection to a 15.4 capable radio co-processor (RCP) RADIO_MODE_SPI_RCP = 0x2 SPI connection to a 15.4 capable radio co-processor (RCP) enum esp_openthread_host_connection_mode_t How OpenThread connects to the host. Values: HOST_CONNECTION_MODE_NONE = 0x0 Disable host connection HOST_CONNECTION_MODE_CLI_UART = 0x1 CLI UART connection to the host HOST_CONNECTION_MODE_RCP_UART = 0x2 RCP UART connection to the host Header File · components/openthread/include/esp_openthread_lock.h Functions esp_err_t esp_openthread_lock_init(void) This function initializes the OpenThread API lock. Return · ESP_OK on success · ESP_ERR_NO_MEM if allocation has failed · ESP_ERR_INVALID_STATE if already initialized void esp_openthread_lock_deinit(void) This function deinitializes the OpenThread API lock. Espressif Systems 612 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference bool esp_openthread_lock_acquire(TickType_t block_ticks) This functions acquires the OpenThread API lock. Note Every OT APIs that takes an otInstance argument MUST be protected with this API lock except that the call site is in OT callbacks. Return · True on lock acquired · False on failing to acquire the lock with the timeout. Parameters · [in] block_ticks: The maxinum number of RTOS ticks to wait for the lock. void esp_openthread_lock_release(void) This function releases the OpenThread API lock. Header File · components/openthread/include/esp_openthread_netif_glue.h Functions void *esp_openthread_netif_glue_init(const esp_openthread_platform_config_t *config) This function initializes the OpenThread network interface glue. Return · glue pointer on success · NULL on failure Parameters · [in] config: The platform configuration. void esp_openthread_netif_glue_deinit(void) This function deinitializes the OpenThread network interface glue. esp_netif_t *esp_openthread_get_netif(void) This function acquires the OpenThread netif. Return The OpenThread netif or NULL if not initialzied. Header File · components/openthread/include/esp_openthread_border_router.h Functions void esp_openthread_set_backbone_netif(esp_netif_t *backbone_netif) Sets the backbone interface used for border routing. Note This function must be called before esp_openthread_init Parameters · [in] backbone_netif: The backbone network interface (WiFi or ethernet) esp_err_t esp_openthread_border_router_init(void) Initializes the border router features of OpenThread. Note Calling this function will make the device behave as an OpenThread border router. Kconfig option CONFIG_OPENTHREAD_BORDER_ROUTER is required. Return · ESP_OK on success · ESP_ERR_NOT_SUPPORTED if feature not supported · ESP_ERR_INVALID_STATE if already initialized · ESP_FIAL on other failures esp_err_t esp_openthread_border_router_deinit(void) Deinitializes the border router features of OpenThread. Return Espressif Systems 613 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_OK on success · ESP_ERR_INVALID_STATE if not initialized · ESP_FIAL on other failures esp_netif_t *esp_openthread_get_backbone_netif(void) Gets the backbone interface of OpenThread border router. Return The backbone interface or NULL if border router not initialized. Thread is an IPv6-based mesh networking technology for IoT. Code examples for the Thread API are provided in the openthread directory of ESP-IDF examples. 2.5.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 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 || || +-----------------------+ || (continues on next page) Espressif Systems 614 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference | | || | l2tap_write |-------| | | | | | l2tap_eth_filter |----------| | | | (E) | +-----------------------+ ESP-NETIF L2 TAP (continued from previous page) Data and event flow in the diagram · ........ Initialization line from user code to ESP-NETIF and communication driver · --<--->-- Data packets going from communication media to TCP/IP stack and back · ******** Events aggregated in ESP-NETIF propagates to driver, user code and network stack · | User settings and runtime configuration ESP-NETIF interaction A) User code, boiler plate Overall application interaction with a specific IO driver for communication media and configured TCP/IP network stack is abstracted using ESP-NETIF APIs and outlined as below: A) Initialization code 1) Initializes IO driver 2) Creates a new instance of ESP-NETIF and configure with · ESP-NETIF specific options (flags, behaviour, name) · Network stack options (netif init and input functions, not publicly available) · IO driver specific options (transmit, free rx buffer functions, IO driver handle) 3) Attaches the IO driver handle to the ESP-NETIF instance created in the above steps 4) Configures event handlers · use default handlers for common interfaces defined in IO drivers; or define a specific handlers for customised behaviour/new interfaces · register handlers for app related events (such as IP lost/acquired) B) Interaction with network interfaces using ESP-NETIF API · Getting and setting TCP/IP related parameters (DHCP, IP, etc) · Receiving IP events (connect/disconnect) · Controlling application lifecycle (set interface up/down) B) Communication driver, IO driver, media driver Communication driver plays these two important roles in relation with ESP-NETIF: 1) Event handlers: Define behaviour patterns of interaction with ESP-NETIF (for example: ethernet link-up -> turn netif on) 2) Glue IO layer: Adapts the input/output functions to use ESP-NETIF transmit, receive and free receive buffer · Installs driver_transmit to appropriate ESP-NETIF object, so that outgoing packets from network stack are passed to the IO driver · Calls esp_netif_receive() to pass incoming data to network stack Espressif Systems 615 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference C) ESP-NETIF ESP-NETIF is an intermediary between an IO driver and a network stack, connecting packet data path between these two. As that it provides a set of interfaces for attaching a driver to ESP-NETIF object (runtime) and configuring a network stack (compile time). In addition to that a set of API is provided to control network interface lifecycle and its TCP/IP properties. As an overview, the ESP-NETIF public interface could be divided into these 6 groups: 1) Initialization APIs (to create and configure ESP-NETIF instance) 2) Input/Output API (for passing data between IO driver and network stack) 3) Event or Action API · Used for network interface lifecycle management · ESP-NETIF provides building blocks for designing event handlers 4) Setters and Getters for basic network interface properties 5) Network stack abstraction: enabling user interaction with TCP/IP stack · Set interface up or down · DHCP server and client API · DNS API 6) Driver conversion utilities D) Network stack Network stack has no public interaction with application code with regard to public interfaces and shall be fully abstracted by ESP-NETIF API. 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 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(). Espressif Systems 616 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 617 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference +-------------------+-------------------+-------------+---------------------------- --- --+ | 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. 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 · Ethernet: ethernet/basic/main/ethernet_example_main.c · WiFi Access Point: wifi/getting_started/softAP/main/softap_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 separate APIs to facilitate simple startup code for most applications: · esp_netif_create_default_wifi_sta() · esp_netif_create_default_wifi_ap() 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(). Espressif Systems 618 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · esp_netif_config: pointer esp-netif configuration void esp_netif_destroy(esp_netif_t *esp_netif) Destroys the esp_netif object. Parameters · [in] esp_netif: pointer to the object to be deleted esp_err_t esp_netif_set_driver_config(esp_netif_t *esp_netif, 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 Espressif Systems 619 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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 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 Espressif Systems 620 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · [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: Espressif Systems 621 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 Parameters · [in] esp_netif: Handle to esp-netif instance · base: · event_id: · data: esp_err_t esp_netif_set_default_netif(esp_netif_t *esp_netif) Manual configuration of the default netif. This API overrides the automatic configuration of the default interface based on the route_prio If the selected netif is set default using this API, no other interface could be set-default disregarding its route_prio number (unless the selected netif gets destroyed) Return ESP_OK on success Parameters · [in] esp_netif: Handle to esp-netif instance 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 Espressif Systems 622 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 623 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 624 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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) Espressif Systems 625 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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, Set DNS Server information. esp_netif_dns_info_t *dns) esp_netif_dns_type_t type, 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. Espressif Systems 626 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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, Get DNS Server information. esp_netif_dns_info_t *dns) esp_netif_dns_type_t type, 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 · [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. Espressif Systems 627 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 628 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 629 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Parameters · [in] netstack_buf: the net stack buffer Header File · components/esp_netif/include/esp_netif_types.h Structures struct esp_netif_dns_info_t DNS server info. Public Members esp_ip_addr_t ip IPV4 address of DNS server struct esp_netif_ip_info_t Event structure for IP_EVENT_STA_GOT_IP, IP_EVENT_ETH_GOT_IP events Public Members esp_ip4_addr_t ip Interface IPV4 address esp_ip4_addr_t netmask Interface IPV4 netmask esp_ip4_addr_t gw Interface IPV4 gateway address struct esp_netif_ip6_info_t IPV6 IP address information. Public Members esp_ip6_addr_t ip Interface IPV6 address struct ip_event_got_ip_t Public Members int if_index Interface index for which the event is received (left for legacy compilation) esp_netif_t *esp_netif Pointer to corresponding esp-netif object esp_netif_ip_info_t ip_info IP address, netmask, gatway IP address bool ip_changed Whether the assigned IP has changed or not struct ip_event_got_ip6_t Event structure for IP_EVENT_GOT_IP6 event Espressif Systems 630 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members int if_index Interface index for which the event is received (left for legacy compilation) esp_netif_t *esp_netif Pointer to corresponding esp-netif object esp_netif_ip6_info_t ip6_info IPv6 address of the interface int ip_index IPv6 address index struct ip_event_add_ip6_t Event structure for ADD_IP6 event Public Members esp_ip6_addr_t addr The address to be added to the interface bool preferred The default preference of the address struct ip_event_ap_staipassigned_t Event structure for IP_EVENT_AP_STAIPASSIGNED event Public Members esp_netif_t *esp_netif Pointer to the associated netif handle esp_ip4_addr_t ip IP address which was assigned to the station uint8_t mac[6] MAC address of the connected client struct esp_netif_inherent_config Public Members esp_netif_flags_t flags flags that define esp-netif behavior uint8_t mac[6] initial mac address for this interface const esp_netif_ip_info_t *ip_info initial ip address for this interface uint32_t get_ip_event event id to be raised when interface gets an IP uint32_t lost_ip_event event id to be raised when interface losts its IP const char *if_key string identifier of the interface const char *if_desc textual description of the interface Espressif Systems 631 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int route_prio numeric priority of this interface to become a default routing if (if other netifs are up). A higher value of route_prio indicates a higher priority struct esp_netif_driver_base_s struct esp_netif_driver_ifconfig Specific IO driver configuration. struct esp_netif_config Generic esp_netif configuration. Macros ESP_ERR_ESP_NETIF_BASE Definition of ESP-NETIF based errors. ESP_ERR_ESP_NETIF_INVALID_PARAMS ESP_ERR_ESP_NETIF_IF_NOT_READY ESP_ERR_ESP_NETIF_DHCPC_START_FAILED ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED ESP_ERR_ESP_NETIF_NO_MEM ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED ESP_ERR_ESP_NETIF_INIT_FAILED ESP_ERR_ESP_NETIF_DNS_NOT_CONFIGURED ESP_ERR_ESP_NETIF_MLD6_FAILED ESP_ERR_ESP_NETIF_IP6_ADDR_FAILED Type Definitions typedef struct esp_netif_obj esp_netif_t typedef enum esp_netif_flags esp_netif_flags_t typedef enum esp_netif_ip_event_type esp_netif_ip_event_type_t typedef struct esp_netif_inherent_config esp_netif_inherent_config_t typedef struct esp_netif_config esp_netif_config_t typedef void *esp_netif_iodriver_handle IO driver handle type. typedef struct esp_netif_driver_base_s esp_netif_driver_base_t typedef struct esp_netif_driver_ifconfig esp_netif_driver_ifconfig_t typedef struct esp_netif_netstack_config esp_netif_netstack_config_t Specific L3 network stack configuration. typedef esp_err_t (*esp_netif_receive_t)(esp_netif_t *esp_netif, void *buffer, size_t len, void ESP-NETIF Receive function type. *eb) Espressif Systems 632 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Enumerations enum esp_netif_dns_type_t Type of DNS server. Values: ESP_NETIF_DNS_MAIN = 0 DNS main server address ESP_NETIF_DNS_BACKUP DNS backup server address (Wi-Fi STA and Ethernet only) ESP_NETIF_DNS_FALLBACK DNS fallback server address (Wi-Fi STA and Ethernet only) ESP_NETIF_DNS_MAX enum esp_netif_dhcp_status_t Status of DHCP client or DHCP server. Values: ESP_NETIF_DHCP_INIT = 0 DHCP client/server is in initial state (not yet started) ESP_NETIF_DHCP_STARTED DHCP client/server has been started ESP_NETIF_DHCP_STOPPED DHCP client/server has been stopped ESP_NETIF_DHCP_STATUS_MAX enum esp_netif_dhcp_option_mode_t Mode for DHCP client or DHCP server option functions. Values: ESP_NETIF_OP_START = 0 ESP_NETIF_OP_SET Set option ESP_NETIF_OP_GET Get option ESP_NETIF_OP_MAX enum esp_netif_dhcp_option_id_t Supported options for DHCP client or DHCP server. Values: ESP_NETIF_SUBNET_MASK = 1 Network mask ESP_NETIF_DOMAIN_NAME_SERVER = 6 Domain name server ESP_NETIF_ROUTER_SOLICITATION_ADDRESS = 32 Solicitation router address ESP_NETIF_REQUESTED_IP_ADDRESS = 50 Request specific IP address ESP_NETIF_IP_ADDRESS_LEASE_TIME = 51 Request IP address lease time ESP_NETIF_IP_REQUEST_RETRY_TIME = 52 Request IP address retry counter Espressif Systems 633 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_NETIF_VENDOR_CLASS_IDENTIFIER = 60 Vendor Class Identifier of a DHCP client ESP_NETIF_VENDOR_SPECIFIC_INFO = 43 Vendor Specific Information of a DHCP server enum ip_event_t IP event declarations Values: IP_EVENT_STA_GOT_IP station got IP from connected AP IP_EVENT_STA_LOST_IP station lost IP and the IP is reset to 0 IP_EVENT_AP_STAIPASSIGNED soft-AP assign an IP to a connected station IP_EVENT_GOT_IP6 station or ap or ethernet interface v6IP addr is preferred IP_EVENT_ETH_GOT_IP ethernet got IP from connected AP IP_EVENT_ETH_LOST_IP ethernet lost IP and the IP is reset to 0 IP_EVENT_PPP_GOT_IP PPP interface got IP IP_EVENT_PPP_LOST_IP PPP interface lost IP enum esp_netif_flags Values: ESP_NETIF_DHCP_CLIENT = 1 << 0 ESP_NETIF_DHCP_SERVER = 1 << 1 ESP_NETIF_FLAG_AUTOUP = 1 << 2 ESP_NETIF_FLAG_GARP = 1 << 3 ESP_NETIF_FLAG_EVENT_IP_MODIFIED = 1 << 4 ESP_NETIF_FLAG_IS_PPP = 1 << 5 ESP_NETIF_FLAG_IS_SLIP = 1 << 6 enum esp_netif_ip_event_type Values: ESP_NETIF_IP_EVENT_GOT_IP = 1 ESP_NETIF_IP_EVENT_LOST_IP = 2 Header File · components/esp_netif/include/esp_netif_ip_addr.h Functions esp_ip6_addr_type_t esp_netif_ip6_get_addr_type(esp_ip6_addr_t *ip6_addr) Get the IPv6 address type. Return IPv6 type in form of enum esp_ip6_addr_type_t Parameters Espressif Systems 634 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [in] ip6_addr: IPv6 type static void esp_netif_ip_addr_copy(esp_ip_addr_t *dest, const esp_ip_addr_t *src) Copy IP addresses. Parameters · [out] dest: destination IP · [in] src: source IP Structures struct esp_ip6_addr struct esp_ip4_addr struct _ip_addr Macros esp_netif_htonl(x) esp_netif_ip4_makeu32(a, b, c, d) ESP_IP6_ADDR_BLOCK1(ip6addr) ESP_IP6_ADDR_BLOCK2(ip6addr) ESP_IP6_ADDR_BLOCK3(ip6addr) ESP_IP6_ADDR_BLOCK4(ip6addr) ESP_IP6_ADDR_BLOCK5(ip6addr) ESP_IP6_ADDR_BLOCK6(ip6addr) ESP_IP6_ADDR_BLOCK7(ip6addr) ESP_IP6_ADDR_BLOCK8(ip6addr) IPSTR esp_ip4_addr_get_byte(ipaddr, idx) esp_ip4_addr1(ipaddr) esp_ip4_addr2(ipaddr) esp_ip4_addr3(ipaddr) esp_ip4_addr4(ipaddr) esp_ip4_addr1_16(ipaddr) esp_ip4_addr2_16(ipaddr) esp_ip4_addr3_16(ipaddr) esp_ip4_addr4_16(ipaddr) IP2STR(ipaddr) IPV6STR IPV62STR(ipaddr) ESP_IPADDR_TYPE_V4 ESP_IPADDR_TYPE_V6 ESP_IPADDR_TYPE_ANY ESP_IP4TOUINT32(a, b, c, d) ESP_IP4TOADDR(a, b, c, d) ESP_IP4ADDR_INIT(a, b, c, d) Espressif Systems 635 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_IP6ADDR_INIT(a, b, c, d) Type Definitions typedef struct esp_ip4_addr esp_ip4_addr_t typedef struct esp_ip6_addr esp_ip6_addr_t typedef struct _ip_addr esp_ip_addr_t Enumerations enum esp_ip6_addr_type_t Values: ESP_IP6_ADDR_IS_UNKNOWN ESP_IP6_ADDR_IS_GLOBAL ESP_IP6_ADDR_IS_LINK_LOCAL ESP_IP6_ADDR_IS_SITE_LOCAL ESP_IP6_ADDR_IS_UNIQUE_LOCAL ESP_IP6_ADDR_IS_IPV4_MAPPED_IPV6 Header File · components/esp_netif/include/esp_vfs_l2tap.h Functions esp_err_t esp_vfs_l2tap_intf_register(l2tap_vfs_config_t *config) Add L2 TAP virtual filesystem driver. This function must be called prior usage of ESP-NETIF L2 TAP Interface Return esp_err_t · ESP_OK on success Parameters · config: L2 TAP virtual filesystem driver configuration. Default base path /dev/net/tap is used when this paramenter is NULL. esp_err_t esp_vfs_l2tap_intf_unregister(const char *base_path) Removes L2 TAP virtual filesystem driver. Return esp_err_t · ESP_OK on success Parameters · base_path: Base path to the L2 TAP virtual filesystem driver. Default path /dev/net/tap is used when this paramenter is NULL. Structures struct l2tap_vfs_config_t Macros L2TAP_VFS_DEFAULT_PATH L2TAP_VFS_CONFIG_DEFAULT() Espressif Systems 636 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Enumerations enum l2tap_ioctl_opt_t Values: L2TAP_S_RCV_FILTER L2TAP_G_RCV_FILTER L2TAP_S_INTF_DEVICE L2TAP_G_INTF_DEVICE 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 · 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 Espressif Systems 637 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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.5.5 IP Network Layer 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. 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. Espressif Systems 638 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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. Espressif Systems 639 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. 2.5.6 Application Layer Documentation for Application layer network protocols (above the IP Network layer) are provided in Application Protocols. Espressif Systems 640 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.6 Peripherals API 2.6.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: 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. Espressif Systems 641 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 642 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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(). 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. Espressif Systems 643 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Espressif Systems 644 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference API Reference This reference covers three components: · ADC driver · ADC Calibration · GPIO Lookup Macros ADC driver 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. 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 | | +-------------+-----------------+ (continues on next page) Espressif Systems 645 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference | | 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 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 · -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) Espressif Systems 646 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) | +==========+=============+=================+ | | 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 | +----------+-------------+-----------------+ Espressif Systems 647 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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) Espressif Systems 648 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 649 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 650 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 651 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 652 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 653 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 SAR ADC 1. ADC_UNIT_2 SAR ADC 2. 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 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. Espressif Systems 654 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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: Espressif Systems 655 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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. Espressif Systems 656 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 657 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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()) 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 unit 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 Espressif Systems 658 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint32_t vref Vref used by lookup table const uint32_t *low_curve Pointer to low Vref curve of lookup table (NULL if unused) const uint32_t *high_curve Pointer to high Vref curve of lookup table (NULL if unused) uint8_t version ADC Calibration Enumerations enum esp_adc_cal_value_t Type of calibration value used in characterization. Values: ESP_ADC_CAL_VAL_EFUSE_VREF = 0 Characterization based on reference voltage stored in eFuse ESP_ADC_CAL_VAL_EFUSE_TP = 1 Characterization based on Two Point values stored in eFuse ESP_ADC_CAL_VAL_DEFAULT_VREF = 2 Characterization based on default reference voltage ESP_ADC_CAL_VAL_EFUSE_TP_FIT = 3 Characterization based on Two Point values and fitting curve coefficients stored in eFuse ESP_ADC_CAL_VAL_MAX ESP_ADC_CAL_VAL_NOT_SUPPORTED = ESP_ADC_CAL_VAL_MAX GPIO Lookup Macros Header File · components/soc/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 Espressif Systems 659 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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.6.2 GPIO & RTC GPIO Overview The ESP32-S3 chip features 45 physical GPIO pads (GPIO0 ~ GPIO21 and GPIO26 ~ GPIO48). 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 Analog Function ADC1_CH0 ADC1_CH1 ADC1_CH2 RTC GPIO RTC_GPIO0 RTC_GPIO1 RTC_GPIO2 RTC_GPIO3 Comment Strapping pin Strapping pin Continued on next page Espressif Systems 660 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference GPIO 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 GPIO34 GPIO35 GPIO36 GPIO37 GPIO38 GPIO39 GPIO40 GPIO41 GPIO42 GPIO43 GPIO44 GPIO45 GPIO46 GPIO47 GPIO48 Table 7 continued from previous page Analog Function RTC GPIO Comment ADC1_CH3 RTC_GPIO4 ADC1_CH4 RTC_GPIO5 ADC1_CH5 RTC_GPIO6 ADC1_CH6 RTC_GPIO7 ADC1_CH7 RTC_GPIO8 ADC1_CH8 RTC_GPIO9 ADC1_CH9 RTC_GPIO10 ADC2_CH0 RTC_GPIO11 ADC2_CH1 RTC_GPIO12 ADC2_CH2 RTC_GPIO13 ADC2_CH3 RTC_GPIO14 ADC2_CH4 RTC_GPIO15 ADC2_CH5 RTC_GPIO16 ADC2_CH6 RTC_GPIO17 ADC2_CH7 RTC_GPIO18 ADC2_CH8 RTC_GPIO19 USB-JTAG ADC2_CH9 RTC_GPIO20 USB-JTAG RTC_GPIO21 SPI0/1 SPI0/1 SPI0/1 SPI0/1 SPI0/1 SPI0/1 SPI0/1 SPI0/1 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: Espressif Systems 661 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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); Espressif Systems 662 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t gpio_intr_disable(gpio_num_t gpio_num) Disable GPIO module interrupt signal. Note This function is allowed to be executed when Cache is disabled within ISR context, by enabling CONFIG_GPIO_CTRL_FUNC_IN_IRAM 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. Note This function is allowed to be executed when Cache is disabled within ISR context, by enabling CONFIG_GPIO_CTRL_FUNC_IN_IRAM 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 · 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. Espressif Systems 663 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 664 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 665 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 666 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 667 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · gpio_num: GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); · pull: GPIO pull up/down mode. Macros GPIO_PIN_COUNT GPIO_IS_VALID_GPIO(gpio_num) Check whether it is a valid GPIO number. GPIO_IS_VALID_OUTPUT_GPIO(gpio_num) Check whether it can be a valid GPIO number of output mode. Type Definitions typedef intr_handle_t gpio_isr_handle_t Header File · components/hal/include/hal/gpio_types.h Structures struct gpio_config_t Configuration parameters of GPIO pad for gpio_config function. Public Members uint64_t pin_bit_mask GPIO pin: set with bit mask, each bit maps to a GPIO gpio_mode_t mode GPIO mode: set input/output mode gpio_pullup_t pull_up_en GPIO pull-up gpio_pulldown_t pull_down_en GPIO pull-down gpio_int_type_t intr_type GPIO interrupt type Macros GPIO_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 Espressif Systems 668 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference GPIO_PIN_REG_11 GPIO_PIN_REG_12 GPIO_PIN_REG_13 GPIO_PIN_REG_14 GPIO_PIN_REG_15 GPIO_PIN_REG_16 GPIO_PIN_REG_17 GPIO_PIN_REG_18 GPIO_PIN_REG_19 GPIO_PIN_REG_20 GPIO_PIN_REG_21 GPIO_PIN_REG_22 GPIO_PIN_REG_23 GPIO_PIN_REG_24 GPIO_PIN_REG_25 GPIO_PIN_REG_26 GPIO_PIN_REG_27 GPIO_PIN_REG_28 GPIO_PIN_REG_29 GPIO_PIN_REG_30 GPIO_PIN_REG_31 GPIO_PIN_REG_32 GPIO_PIN_REG_33 GPIO_PIN_REG_34 GPIO_PIN_REG_35 GPIO_PIN_REG_36 GPIO_PIN_REG_37 GPIO_PIN_REG_38 GPIO_PIN_REG_39 GPIO_PIN_REG_40 GPIO_PIN_REG_41 GPIO_PIN_REG_42 GPIO_PIN_REG_43 GPIO_PIN_REG_44 GPIO_PIN_REG_45 GPIO_PIN_REG_46 GPIO_PIN_REG_47 GPIO_PIN_REG_48 Espressif Systems 669 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 670 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 671 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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 Espressif Systems 672 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 673 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 674 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 675 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 676 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 2.6.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. Espressif Systems 677 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. · Kconfig options - lists the supported Kconfig options that can be used to make a different effect on driver behavior. Resource Allocation Different ESP chip might have different number of independent timer groups, and within each group, there could also be several independent timers. Please refer to the [TRM] to find out how many hardware timers exist. 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: · 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. · gptimer_config_t::direction sets the counting direction of the timer, supported directions are listed in gptimer_count_direction_t, you can only pick one of them. · gptimer_config_t::resolution_hz sets the resolution of the internal counter. Each count step is equivalent to 1 / resolution_hz seconds. · Optional gptimer_config_t::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. 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. 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 678 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · gptimer_alarm_config_t::alarm_count sets the target count value that will trig- ger the alarm event. You should also take the counting direction into consideration when set- ting the alarm value. Specially, gptimer_alarm_config_t::alarm_count and gpti- mer_alarm_config_t::reload_count cannt be set to the same value when gpti- mer_alarm_config_t::auto_reload_on_alarm is true, as keeping reload with a target alarm count is meaningless. · gptimer_alarm_config_t::reload_count sets the count value to be reloaded when the alarm event happens. This configuration only takes effect when gpti- mer_alarm_config_t::auto_reload_on_alarm is set to true. · gptimer_alarm_config_t::auto_reload_on_alarm flag sets whether to enable the auto-reload feature. If enabled, the hardware timer will reload the value of gpti- mer_alarm_config_t::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: · 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. 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; (continues on next page) Espressif Systems 679 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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) { 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; } 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)); (continues on next page) Espressif Systems 680 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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 gptimer_alarm_event_data_t::alarm_value. 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 = { .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 appli- Espressif Systems 681 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference cation. 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. Kconfig Options · CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM controls where to place the GPTimer control functions (IRAM or Flash), see IRAM Safe for more information. · CONFIG_GPTIMER_ISR_IRAM_SAFE controls whether the default ISR handler can work when cache is disabled, see IRAM Safe for more information. · CONFIG_GPTIMER_ENABLE_DEBUG_LOG is used to enabled the debug log output. Enable this option will increase the firmware binary size. 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 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 gptimer_event_callbacks_t::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 682 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 gpti- Set callbacks for GPTimer. mer_event_callbacks_t *cbs, void *user_data) 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 Espressif Systems 683 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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. 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 Espressif Systems 684 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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 Espressif Systems 685 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.6.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. 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: Espressif Systems 686 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // 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: 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 Espressif Systems 687 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 688 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 unsigned int in_invert : 1 Invert input signal unsigned int out_en : 1 Enable output Espressif Systems 689 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.6.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: 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 Espressif Systems 690 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: #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, (continues on next page) Espressif Systems 691 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference key_data, sizeof(key_data)); if (ets_status == ESP_OK) { // written key } else { // writing key failed, maybe written already } (continued from previous page) 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. In downstream mode, HMAC calculations performed by peripheral are used internally and not provided back to user. Return Espressif Systems 692 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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.6.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 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. Espressif Systems 693 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. The APIs esp_ds_sign() and esp_ds_start_sign() calculate a plain RSA signature with help of the DS peripheral. This signature needs to be converted to appropriate format for further use. For example, MbedTLS SSL stack supports PKCS#1 format. The API esp_ds_rsa_sign() can be used to obtain the signature directly in the PKCS#1 v1.5 format. It internally uses esp_ds_start_sign() and converts the signature into PKCS#1 v1.5 format. 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_ds/main/app_main.c Espressif Systems 694 Release v5.0-dev-2349-g4350e6fef8 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. The function calculates a plain RSA signature with help of the DS peripheral. The RSA encryption operation is as follows: Z = XY mod M where, Z is the signature, X is the input message, Y and M are the RSA private key parameters. 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 should be (data->rsa_length + 1)*4 bytes · 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. The function calculates a plain RSA signature with help of the DS peripheral. The RSA encryption operation is as follows: Z = XY mod M where, Z is the signature, X is the input message, Y and M are the RSA private key parameters. Espressif Systems 695 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 should be (data->rsa_length +1 )*4 bytes · 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. Espressif Systems 696 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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). 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 Espressif Systems 697 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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.6.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 Espressif Systems 698 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 - master or slave 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 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 Espressif Systems 699 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (clk_flags) is 0 in the clockns capabilities. Table 8: 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. Espressif Systems 700 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 7: I2C command link - master write example 2. Trigger the execution of the command link by I2C controller by calling i2c_master_cmd_begin(). Once the execution is triggered, the command link cannot be modified. 3. After the commands are transmitted, release the resources used by the command link by calling i2c_cmd_link_delete(). Master Read The example below shows how to build a command link for an I2C master to read n bytes from a slave. Fig. 8: 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. Espressif Systems 701 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference For this reason, the command link sent by the master to write data to the slave contains the address (ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE and looks as follows: i2c_master_write_byte(cmd, (ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE, ACK_EN); Likewise, the command link to read from the slave looks as follows: i2c_master_write_byte(cmd, (ESP_SLAVE_ADDR << 1) | I2C_MASTER_READ, ACK_EN); Communication as Slave After installing the I2C driver, ESP32-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 9: 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. Espressif Systems 702 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference You can also select different pins for SDA and SCL signals and alter the configuration of pull-ups with the function i2c_set_pin(). If you want to modify already entered values, use the function i2c_param_config(). Note: ESP32-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 examples: 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 Not all Espressif chips can support slave mode (e.g. ESP32C2) 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. Espressif Systems 703 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · intr_alloc_flags: Flags used to allocate the interrupt. ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. esp_err_t i2c_driver_delete(i2c_port_t i2c_num) Delete I2C driver. One or multiple (ORred) 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 Espressif Systems 704 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 705 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference underneath may increase in the future, resulting in a possible stack overflow as the macro I2C_LINK_RECOMMENDED_SIZE would also return a bigger value. A better option is to use a buffer allocated statically or dynamically (with malloc). Return Handle to the I2C command link or NULL if the buffer provided is too small, please use I2C_LINK_RECOMMENDED_SIZE macro to get the recommended size for the buffer. Parameters · buffer: Buffer to use for commands allocations · size: Size in bytes of the buffer i2c_cmd_handle_t i2c_cmd_link_create(void) Create and initialize an I2C commands list with a given buffer. After finishing the I2C transactions, it is required to call i2c_cmd_link_delete() to release and return the resources. The required bytes will be dynamically allocated. Return Handle to the I2C command link 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 Espressif Systems 706 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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: 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 Espressif Systems 707 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 708 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t i2c_filter_enable(i2c_port_t i2c_num, uint8_t cyc_num) Enable hardware filter on I2C bus Sometimes the I2C bus is disturbed by high frequency noise(about 20ns), or the rising edge of the SCL clock is very slow, these may cause the master state machine to break. Enable hardware filter can filter out high frequency interference and make the master more stable. Note Enable filter will slow down the SCL clock. Return · ESP_OK Success · 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 Espressif Systems 709 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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_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) *tx_trans_mode, Espressif Systems 710 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference get I2C data transfer mode 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 711 Release v5.0-dev-2349-g4350e6fef8 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 712 Release v5.0-dev-2349-g4350e6fef8 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.6.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 713 Release v5.0-dev-2349-g4350e6fef8 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 i2s_driver_install() and passing the following arguments: · Port number · The initialized i2s_config_t struct defining the communication parameters · Event queue size and handle An ESP_OK return value from i2s_driver_install() indictes 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 the physical GPIO pins to which the I2S signals will be routed. This is accomplished by calling the function i2s_set_pin() with the following arguments: · Port number · The structure i2s_pin_config_t which defines the GPIO pin numbers for the MCK, BCK, WS, DATA out, and DATA in signals. To keep a current pin allocatopm pin for a specific signal, or to indicate an unused signal, 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 714 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Running I2S Communication To send data: · 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 the data will be transmitted automatically by the I2S peripheral. 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 peripheral. i2s_read(I2S_NUM, data_recv, ((bits+8)/16)*SAMPLE_PER_CYCLE*4, &i2s_bytes_read, 100); You can temporarily halt the I2S driver by calling i2s_stop(), which disables the I2S Tx/Rx units until i2s_start() is called. The driver automatically starts the I2S peripheral after i2s_driver_install() is called, eliminating the need to call i2s_start(). Deleting the Driver Once I2S communication is no longer required, the driver can be removed to free allocated resources by calling i2s_driver_uninstall(). Application Example Code examples for the I2S driver can be found in the directory peripherals/i2s. Additionally, 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' * (continues on next page) Espressif Systems 715 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * The low 16 bits are the valid data bits in one chan and the high 16 bits are * the total bits in one chan. If high 16 bits is smaller than low 16 bits, it will * be set to a same value as low 16 bits. */ uint32_t bits_cfg = (I2S_BITS_PER_CHAN_32BIT << 16) | I2S_BITS_PER_SAMPLE_16BIT; i2s_set_clk(i2s_num, 22050, bits_cfg, I2S_CHANNEL_STEREO); ... i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver 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. You can also 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 Espressif Systems 716 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Application Notes For the applications that need a high frequency sample rate, sometimes the massive throughput of receiving data may cause data lost. Users can receive data loss event by the event queue, it will trigger an I2S_EVENT_RX_Q_OVF event.: QueueHandle_t evt_que; i2s_driver_install(i2s_num, &i2s_config, 10, &evt_que); ... i2s_event_t evt; xQueueReceive(evt_que, &evt, portMAX_DELAY); if (evt.type == I2S_EVENT_RX_Q_OVF) { printf("RX data dropped\n"); } Please follow these steps to calculate the parameters that can prevent data lost: 1. Determine the interrupt interval. Generally, when data lost happened, the interval should be the bigger the better, it can help to reduce the interrupt times, i.e., dma_frame_num should be as big as possible while the DMA buffer size wonnt exceed its maximum value 4092. The relationships are: interrupt_interval(unit: sec) = dma_frame_num / sample_rate dma_buffer_size = dma_frame_num * channel_num * data_bit_width / 8 <= 4092 2. Determine the dma_desc_num. The dma_desc_num is decided by the max time of i2s_read polling cycle, all the data should be stored between two i2s_read. This cycle can be measured by a timer or an outputting gpio signal. The relationship should be: dma_desc_num > polling_cycle / interrupt_interval 3. Determine the receiving buffer size. The receiving buffer that offered by user in i2s_read should be able to take all the data in all dma buffers, that means it should be bigger than the total size of all the dma buffers: recv_buffer_size > dma_desc_num * dma_buffer_size For example, if there is a I2S application: sample_rate = 144000 Hz data_bit_width = 32 bits channel_num = 2 polling_cycle = 10ms Then we need to calculate dma_frame_num, dma_desc_num and recv_buf_size according to the known values: dma_frame_num * channel_num * data_bit_width / 8 = dma_buffer_size <= 4092 dma_frame_num <= 511 interrupt_interval = dma_frame_num / sample_rate = 511 / 144000 = 0.003549 s = 3. 549 ms dma_desc_num > polling_cycle / interrupt_interval = cell(10 / 3.549) = cell(2.818) = 3 recv_buffer_size > dma_desc_num * dma_buffer_size = 3 * 4092 = 12276 bytes 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. Espressif Systems 717 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 718 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. · 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 Espressif Systems 719 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 720 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 721 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 722 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 723 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Enumerations enum i2s_port_t I2S port number, the max port number is (I2S_NUM_MAX -1). Values: I2S_NUM_0 = 0 I2S port 0 I2S_NUM_1 = 1 I2S port 1 I2S_NUM_MAX I2S port max enum i2s_event_type_t I2S event queue types. Values: I2S_EVENT_DMA_ERROR I2S_EVENT_TX_DONE I2S DMA finish sent 1 buffer I2S_EVENT_RX_DONE I2S DMA finish received 1 buffer I2S_EVENT_TX_Q_OVF I2S DMA sent queue overflow I2S_EVENT_RX_Q_OVF I2S DMA receive queue overflow I2S_EVENT_MAX I2S event max index Header File · components/hal/include/hal/i2s_types.h Enumerations enum i2s_bits_per_sample_t I2S bit width per sample. Values: I2S_BITS_PER_SAMPLE_8BIT = 8 data bit-width: 8 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 Espressif Systems 724 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 = 1 I2S channel (mono), one channel activated. In this mode, you only need to send one channel data but the fifo will copy same data for the other unactivated channels automatically, then both channels will transmit same data. I2S_CHANNEL_STEREO = 2 I2S channel (stereo), two (or more) channels activated. In this mode, these channels will transmit different data. I2S_TDM_ACTIVE_CH0 = (0x1 << 16) I2S channel 0 activated I2S_TDM_ACTIVE_CH1 = (0x1 << 17) I2S channel 1 activated I2S_TDM_ACTIVE_CH2 = (0x1 << 18) I2S channel 2 activated I2S_TDM_ACTIVE_CH3 = (0x1 << 19) I2S channel 3 activated I2S_TDM_ACTIVE_CH4 = (0x1 << 20) I2S channel 4 activated I2S_TDM_ACTIVE_CH5 = (0x1 << 21) I2S channel 5 activated I2S_TDM_ACTIVE_CH6 = (0x1 << 22) I2S channel 6 activated I2S_TDM_ACTIVE_CH7 = (0x1 << 23) I2S channel 7 activated I2S_TDM_ACTIVE_CH8 = (0x1 << 24) I2S channel 8 activated I2S_TDM_ACTIVE_CH9 = (0x1 << 25) I2S channel 9 activated I2S_TDM_ACTIVE_CH10 = (0x1 << 26) I2S channel 10 activated I2S_TDM_ACTIVE_CH11 = (0x1 << 27) I2S channel 11 activated I2S_TDM_ACTIVE_CH12 = (0x1 << 28) I2S channel 12 activated I2S_TDM_ACTIVE_CH13 = (0x1 << 29) I2S channel 13 activated I2S_TDM_ACTIVE_CH14 = (0x1 << 30) I2S channel 14 activated Espressif Systems 725 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference I2S_TDM_ACTIVE_CH15 = (0x1 << 31) I2S channel 15 activated enum i2s_comm_format_t I2S communication standard format. Values: I2S_COMM_FORMAT_STAND_I2S = 0X01 I2S communication I2S Philips standard, data launch at second BCK I2S_COMM_FORMAT_STAND_MSB = 0X02 I2S communication MSB alignment standard, data launch at first BCK I2S_COMM_FORMAT_STAND_PCM_SHORT = 0x04 PCM Short standard, also known as DSP mode. The period of synchronization signal (WS) is 1 bck cycle. I2S_COMM_FORMAT_STAND_PCM_LONG = 0x0C PCM Long standard. The period of synchronization signal (WS) is channel_bit*bck cycles. I2S_COMM_FORMAT_STAND_MAX standard max I2S_COMM_FORMAT_I2S = 0x01 I2S communication format I2S, correspond to I2S_COMM_FORMAT_STAND_I2S I2S_COMM_FORMAT_I2S_MSB = 0x01 I2S format MSB, (I2S_COMM_FORMAT_I2S |I2S_COMM_FORMAT_I2S_MSB) correspond to I2S_COMM_FORMAT_STAND_I2S I2S_COMM_FORMAT_I2S_LSB = 0x02 I2S format LSB, (I2S_COMM_FORMAT_I2S |I2S_COMM_FORMAT_I2S_LSB) correspond to I2S_COMM_FORMAT_STAND_MSB I2S_COMM_FORMAT_PCM = 0x04 I2S communication format PCM, correspond to I2S_COMM_FORMAT_STAND_PCM_SHORT I2S_COMM_FORMAT_PCM_SHORT = 0x04 PCM Short, (I2S_COMM_FORMAT_PCM | I2S_COMM_FORMAT_PCM_SHORT) correspond to I2S_COMM_FORMAT_STAND_PCM_SHORT I2S_COMM_FORMAT_PCM_LONG = 0x08 PCM Long, (I2S_COMM_FORMAT_PCM | I2S_COMM_FORMAT_PCM_LONG) correspond to I2S_COMM_FORMAT_STAND_PCM_LONG enum i2s_channel_fmt_t I2S channel format type. Values: I2S_CHANNEL_FMT_RIGHT_LEFT Separated left and right channel I2S_CHANNEL_FMT_ALL_RIGHT Load right channel data in both two channels I2S_CHANNEL_FMT_ALL_LEFT Load left channel data in both two channels I2S_CHANNEL_FMT_ONLY_RIGHT Only load data in right channel (mono mode) I2S_CHANNEL_FMT_ONLY_LEFT Only load data in left channel (mono mode) I2S_CHANNEL_FMT_MULTIPLE More than two channels are used Espressif Systems 726 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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: Espressif Systems 727 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.6.9 LCD Introduction ESP chips can generate various kinds of timings that needed by common LCDs on the market, like SPI LCD, I80 LCD (a.k.a Intel 8080 parallel LCD), RGB LCD, I2C LCD, etc. The esp_lcd component is officially to support those LCDs with a group of universal APIs across chips. Functional Overview In esp_lcd, an LCD panel is represented by esp_lcd_panel_handle_t, which plays the role of an abstract frame buffer, regardless of the frame memory is allocated inside ESP chip or in external LCD controller. Based on the location of the frame buffer, the LCD panel allocation functions are mainly grouped into the following categories: · RGB LCD panel - is simply based on a group of specific synchronous signals indicating where to start and stop a frame. · Controller based LCD panel involves multiple steps to get a panel handle, like bus allocation, IO device registration and controller driver install. After we get the LCD handle, the remaining LCD operations are the same for different LCD interfaces and vendors. Application Example LCD examples are located under: peripherals/lcd: · Jpeg decoding and LCD display - peripherals/lcd/tjpgd · 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 Espressif Systems 728 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_PLL240M LCD_CLK_SRC_APLL LCD_CLK_SRC_XTAL Features High resolution High resolution Configurable resolution Medium resolution Power Management ESP_PM_APB_FREQ_MAX lock 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_PLL240M Select PLL240M as the source clock LCD_CLK_SRC_APLL Select APLL as the source clock LCD_CLK_SRC_XTAL Select XTAL as the source clock Header File · components/esp_lcd/include/esp_lcd_types.h Type Definitions typedef struct esp_lcd_panel_io_t *esp_lcd_panel_io_handle_t Type of LCD panel IO handle typedef struct esp_lcd_panel_t *esp_lcd_panel_handle_t Type of LCD panel handle Enumerations enum esp_lcd_color_space_t LCD color space type definition. Values: ESP_LCD_COLOR_SPACE_RGB Color space: RGB ESP_LCD_COLOR_SPACE_BGR Color space: BGR ESP_LCD_COLOR_SPACE_MONOCHROME Color space: monochrome Header File · components/esp_lcd/include/esp_lcd_panel_io.h Functions esp_err_t esp_lcd_panel_io_tx_param(esp_lcd_panel_io_handle_t io, int lcd_cmd, const void *param, size_t param_size) Transmit LCD command and corresponding parameters. Espressif Systems 729 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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, Espressif Systems 730 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 731 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 732 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 733 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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() Espressif Systems 734 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 x_end, int y_end, const void *color_data) Draw bitmap on 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() · [in] x_start: Start index on x-axis (x_start included) · [in] y_start: Start index on y-axis (y_start included) · [in] x_end: End index on x-axis (x_end not included) · [in] y_end: End index on y-axis (y_end not included) · [in] color_data: RGB color data that will be dumped to the specific window range esp_err_t esp_lcd_panel_mirror(esp_lcd_panel_handle_t panel, bool mirror_x, bool mirror_y) Mirror the LCD panel on specific axis. Note Combined with esp_lcd_panel_swap_xy(), one can realize screen rotation Return · ESP_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 Espressif Systems 735 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Width <------------------------------------------------ HSYNC width HBP Active Width <---><--><--------------------------------------> ____ ____|_______________________________________ |___| | | __| | /|\ /|\ | | (continues on next page) Espressif Systems 736 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference * | | * | | * | | * | | * | | * | | * | | * Total | | * Height | | * | | * | | * | | * | | * | | * | | * | | * | | * | * | * ____| * | VSYNC| | | (continued from previous page) |Width\|/ |__ | | /|\ | | | VBP | | | | \|/_____|_________|_______________________________________ | /|\ | | / / / / / / / / / / / / / / / / / / / | | | |/ / / / / / / / / / / / / / / / / / / / | | | |/ / / / / / / / / / / / / / / / / / / / | | | |/ / / / / / / / / / / / / / / / / / / / |Active| | |/ / / / / / / / / / / / / / / / / / / / |Heigh | | |/ / / / / / Active Display Area / / / / | | | |/ / / / / / / / / / / / / / / / / / / / | | | |/ / / / / / / / / / / / / / / / / / / / | | | |/ / / / / / / / / / / / / / / / / / / / | | | |/ / / / / / / / / / / / / / / / / / / / | | | |/ / / / / / / / / / / / / / / / / / / / | \|/_____|_________|_______________________________________ | /|\ | | 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 Espressif Systems 737 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 the 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 on 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. 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 Espressif Systems 738 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 739 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 unsigned int reset_active_high : 1 Setting this if the panel reset is high level active 2.6.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. Espressif Systems 740 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 9: 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 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 10: Characteristics of ESP32-S3 LEDC source clocks Clock freq Clock capabilities 80 MHz / ~20 MHz 40 MHz Dynamic Frequency Scaling compatible, Light sleep compatible 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 Espressif Systems 741 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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() · 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() Espressif Systems 742 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Return given channel/output Espressif Systems 743 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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. Note This function only routes the LEDC signal to GPIO through matrix, other LEDC resources initialization are not involved. Please use ledc_channel_config() instead to fully configure a LEDC channel. 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 Espressif Systems 744 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 745 Release v5.0-dev-2349-g4350e6fef8 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 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 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 Espressif Systems 746 Release v5.0-dev-2349-g4350e6fef8 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. · 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 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 Espressif Systems 747 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 748 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 ). Espressif Systems 749 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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 Espressif Systems 750 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 751 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members ledc_cb_t fade_cb LEDC fade_end callback function Macros LEDC_APB_CLK_HZ LEDC_REF_CLK_HZ LEDC_ERR_DUTY LEDC_ERR_VAL Type Definitions typedef intr_handle_t ledc_isr_handle_t typedef bool (*ledc_cb_t)(const ledc_cb_param_t *param, void *user_arg) Type of LEDC event callback. Parameters · param: LEDC callback parameter · user_arg: User registered data Enumerations enum ledc_cb_event_t LEDC callback event type. Values: LEDC_FADE_END_EVT LEDC fade end event Header File · components/hal/include/hal/ledc_types.h Enumerations enum ledc_mode_t Values: LEDC_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 Espressif Systems 752 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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: Espressif Systems 753 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 754 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.6.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. Fig. 10: MCPWM Overview 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 · 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. Espressif Systems 755 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 11: MCPWM Block Diagram 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. 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 Espressif Systems 756 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 12: Example of Brushed DC Motor Control with MCPWM Timer is automatically associated by the API to drive an Operator of the same index, e.g. Timer 0 is associated with Operator 0. There are the following basic ways to control the outputs: · We can drive particular signal steady high or steady low with function mcpwm_set_signal_high() or mcpwm_set_signal_low(). This will make the motor to turn with a maximum speed or stop. Depending on selected output A or B the motor will rotate either right or left. · Another option is to drive the outputs with the PWM signal by calling mcpwm_start() or mcpwm_stop(). The motor speed will be proportional to the PWM duty. · To vary 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. Espressif Systems 757 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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, }; (continues on next page) Espressif Systems 758 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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. Fig. 13: Example of Brushless DC Motor Control with MCPWM 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 If not required anymore, the capture functionality may be disabled with mcpwm_capture_disable_channel(). Espressif Systems 759 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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]. Espressif Systems 760 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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: Espressif Systems 761 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference MCPWM_TIMER_COUNT_MODE_PAUSE MCPWM timer paused MCPWM_TIMER_COUNT_MODE_UP MCPWM timer counting up MCPWM_TIMER_COUNT_MODE_DOWN MCPWM timer counting down MCPWM_TIMER_COUNT_MODE_UP_DOWN MCPWM timer counting up and down enum mcpwm_timer_execute_cmd_t Values: MCPWM_TIMER_STOP_AT_ZERO MCPWM timer stops when couting to zero MCPWM_TIMER_STOP_AT_PEAK MCPWM timer stops when counting to peak MCPWM_TIMER_START_NO_STOP MCPWM timer starts couting MCPWM_TIMER_START_STOP_AT_ZERO MCPWM timer starts counting and stops when couting to zero MCPWM_TIMER_START_STOP_AT_PEAK MCPWM timer starts counting and stops when counting to peak enum mcpwm_generator_action_t Values: MCPWM_GEN_ACTION_KEEP Generator action: Keep the same level MCPWM_GEN_ACTION_LOW Generator action: Force to low level MCPWM_GEN_ACTION_HIGH Generator action: Force to high level MCPWM_GEN_ACTION_TOGGLE Generator action: Toggle level enum mcpwm_trip_type_t Values: MCPWM_TRIP_TYPE_CBC CBC trip type, shut down the operator cycle by cycle MCPWM_TRIP_TYPE_OST OST trip type, shut down the operator in one shot Header File · components/driver/include/driver/mcpwm.h Functions esp_err_t mcpwm_gpio_init(mcpwm_unit_t mcpwm_num, mcpwm_io_signals_t io_signal, int gpio_num) This function initializes each gpio signal for MCPWM. Note This function initializes one gpio at a time. Return · ESP_OK Success Espressif Systems 762 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 763 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 764 Release v5.0-dev-2349-g4350e6fef8 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 · 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 · 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 Espressif Systems 765 Release v5.0-dev-2349-g4350e6fef8 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_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 · 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) Espressif Systems 766 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 767 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 768 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) · 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 Espressif Systems 769 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 770 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 771 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 772 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint32_t cap_prescale Prescale of capture signal, ranging from 1 to 256 cap_isr_cb_t capture_cb User defined capture event callback, running under interrupt context void *user_data User defined ISR callback function args struct mcpwm_sync_config_t MCPWM config sync structure. Public Members mcpwm_sync_signal_t sync_sig Set sync input signal that will cause timer to sync uint32_t timer_val Counter value to be set after sync, in 0 ~ 999, unit: 1 / 1000 * peak mcpwm_timer_direction_t count_direction Counting direction to be set after sync Macros MCPWM_OPR_A MCPWM_OPR_B MCPWM_OPR_MAX MCPWM_SELCT_SYNC0 MCPWM_SELCT_SYNC1 MCPWM_SELCT_SYNC2 MCPWM_NO_CHANGE_IN_MCPWMXA MCPWM_FORCE_MCPWMXA_LOW MCPWM_FORCE_MCPWMXA_HIGH MCPWM_TOG_MCPWMXA MCPWM_NO_CHANGE_IN_MCPWMXB MCPWM_FORCE_MCPWMXB_LOW MCPWM_FORCE_MCPWMXB_HIGH MCPWM_TOG_MCPWMXB Type Definitions typedef mcpwm_generator_t mcpwm_operator_t typedef mcpwm_output_action_t mcpwm_action_on_pwmxa_t typedef mcpwm_output_action_t mcpwm_action_on_pwmxb_t typedef mcpwm_capture_signal_t mcpwm_capture_channel_id_t MCPWM capture channel ID alias. typedef bool (*cap_isr_cb_t)(mcpwm_unit_t mcpwm, mcpwm_capture_channel_id_t cap_channel, const cap_event_data_t *edata, void *user_data) Type of capture event callback. Note Since this an ISR callback so do not do anything that may block and call APIs that is designed to be used within ISR(usually has m_ISRnpostfix) Espressif Systems 773 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return Whether a task switch is needed after the callback function returns, this is usually due to the callback wakes up some high priority task. Parameters · mcpwm: MCPWM unit(0-1) · cap_channel: capture channel ID · edata: Capture event data, contains capture edge and capture value, fed by the driver · user_data: User registered data, passed from mcpwm_capture_config_t Enumerations enum mcpwm_io_signals_t IO signals for the MCPWM. - 6 MCPWM output pins that generate PWM signals - 3 MCPWM fault input pins to detect faults like overcurrent, overvoltage, etc. - 3 MCPWM sync input pins to synchronize MCPWM outputs signals - 3 MCPWM capture input pins to gather feedback from controlled motors, using e.g. hall sensors Values: MCPWM0A = 0 PWM0A output pin MCPWM0B PWM0B output pin MCPWM1A PWM1A output pin MCPWM1B PWM1B output pin MCPWM2A PWM2A output pin MCPWM2B PWM2B output pin MCPWM_SYNC_0 SYNC0 input pin MCPWM_SYNC_1 SYNC1 input pin MCPWM_SYNC_2 SYNC2 input pin MCPWM_FAULT_0 FAULT0 input pin MCPWM_FAULT_1 FAULT1 input pin MCPWM_FAULT_2 FAULT2 input pin MCPWM_CAP_0 = 84 CAP0 input pin MCPWM_CAP_1 CAP1 input pin MCPWM_CAP_2 CAP2 input pin Espressif Systems 774 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference enum mcpwm_unit_t Select MCPWM unit. Values: MCPWM_UNIT_0 MCPWM unit0 selected MCPWM_UNIT_1 MCPWM unit1 selected MCPWM_UNIT_MAX Max number of MCPWM units enum mcpwm_timer_t Select MCPWM timer. Values: MCPWM_TIMER_0 Select MCPWM timer0 MCPWM_TIMER_1 Select MCPWM timer1 MCPWM_TIMER_2 Select MCPWM timer2 MCPWM_TIMER_MAX Max number of timers in a unit enum mcpwm_generator_t Select MCPWM operator. Values: MCPWM_GEN_A Select MCPWMXA, where 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: Espressif Systems 775 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 776 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 777 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 778 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.6.12 Pulse Counter (PCNT) Introduction The PCNT (Pulse Counter) module is designed to count the number of rising and/or falling edges of input signals. The ESP32-S3 contains multiple pulse counter units in the module.1 Each unit is in effect an independent counter with multiple channels, where each channel can increment/decrement the counter on a rising/falling edge. Furthermore, each channel can be configured separately. PCNT channels can react to signals of edge type and level type, however for simple applications, detecting the edge signal is usually sufficient. PCNT channels can be configured react to both pulse edges (i.e., rising and falling edge), and can be configured to increase, decrease or do nothing to the unitns counter on each edge. The level signal is the so-called control signal, which is used to control the counting mode of the edge signals that are attached to the same channel. By combining the usage of both edge and level signals, a PCNT unit can act as a quadrature decoder. Besides that, PCNT unit is equipped with a separate glitch filter, which is helpful to remove noise from the signal. Typically, a PCNT module can be used in scenarios like: · Calculate periodic signalns frequency by counting the pulse numbers within a time slice · Decode quadrature signals into speed and direction Functional Overview Description of the PCNT functionality is broken down into the following sections: · Resource Allocation - covers how to allocate PCNT units and channels with properly set of configurations. It also covers how to recycle the resources when they finished working. · Set Up Channel Actions - covers how to configure the PCNT channel to behave on different signal edges and levels. · Watch Points - describes how to configure PCNT watch points (i.e., tell PCNT unit to trigger an event when the count reaches a certain value). · Register Event Callbacks - describes how to hook user specific code to the watch point event callback function. · Unit IO Control - describes IO control functions of PCNT unit, like enable glitch filter, start and stop unit, get and clear count value. · Power Management - describes what functionality will prevent the chip from going into low power mode. · IRAM Safe - describes tips on how to make the PCNT 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. · Kconfig options - lists the supported Kconfig options that can be used to make a different effect on driver behavior. Resource Allocation The PCNT unit and channel are represented by pcnt_unit_handle_t and pcnt_channel_handle_t respectively. All available units and channels are maintained by the driver in a resource pool, so the user doesnnt need to know the exact underlying instance ID. Install PCNT Unit To install a PCNT unit, therens a configuration structure that needs to be given in advance: pcnt_unit_config_t: · pcnt_unit_config_t::low_limit and pcnt_unit_config_t::high_limit specify the range for the internal counter. Counter will back to zero when it crosses either limit value. Unit allocation and initialization is done by calling a function pcnt_new_unit() with pcnt_unit_config_t as an input parameter. The function will return a PCNT unit handle only when it runs correctly. Specifically, when there are no more free PCNT units in the pool (i.e. unit resources have been used up), then this Different ESP chip series might have different number of PCNT units and channels. Please refer to the [TRM] for details. The driver wonnt forbid you from applying for more PCNT units and channels, but it will return error when all available hardware resources are used up. Please always check the return value when doing resource allocation (e.g. pcnt_new_unit()). Espressif Systems 779 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference function will return ESP_ERR_NOT_FOUND error. The total number of available PCNT units is recorded by SOC_PCNT_UNITS_PER_GROUP for reference. If a previously created PCNT unit is no longer needed, itns recommended to recycle the resource by calling pcnt_del_unit(). Which in return allows the underlying unit hardware to be used for other purposes. Before deleting a PCNT unit, one should ensure the following prerequisites: · The unit is in a stop state, in other words, the unit either is stopped by pcnt_unit_stop() or not started yet. · The unit ought to stop watching any owatch pointp. See Watch Points for how to removing a watch point. #define EXAMPLE_PCNT_HIGH_LIMIT 100 #define EXAMPLE_PCNT_LOW_LIMIT -100 pcnt_unit_config_t unit_config = { .high_limit = EXAMPLE_PCNT_HIGH_LIMIT, .low_limit = EXAMPLE_PCNT_LOW_LIMIT, }; pcnt_unit_handle_t pcnt_unit = NULL; ESP_ERROR_CHECK(pcnt_new_unit(&unit_config, &pcnt_unit)); Install PCNT Channel To install a PCNT channel, therens a configuration structure that needs to be given in advance: pcnt_chan_config_t as well: · pcnt_chan_config_t::edge_gpio_num and pcnt_chan_config_t::level_gpio_num specify the GPIO numbers used by edge type signal and level type signal. pcnt_chan_config_t::level_gpio_num is optional and can be assigned with -1 if itns not used whereas the pcnt_chan_config_t::edge_gpio_num is mandatory. · pcnt_chan_config_t::invert_edge_input and pcnt_chan_config_t::invert_level_input are used to decide whether to invert the input signals before they going into PCNT hardware. The invert is done by GPIO matrix instead of PCNT hardware. · pcnt_chan_config_t::io_loop_back is for debug only, which enables both the GPIOns input and output paths. This can help to simulate the pulse signals by function gpio_set_level() on the same GPIO. Channel allocating and initialization is done by calling a function pcnt_new_channel() with the above pcnt_chan_config_t input parameter plus a PCNT unit handle returned from pcnt_new_unit(). This function will return a PCNT channel handle if it runs correctly. Specifically, when there are no more free PCNT channel within the unit (i.e. channel resources have been used up), then this function will return ESP_ERR_NOT_FOUND error. The total number of available PCNT channels within the unit is recorded by SOC_PCNT_CHANNELS_PER_UNIT for reference. If a previously created PCNT channel is no longer needed, itns recommended to recycle the resources by calling pcnt_del_channel(). Which in return allows the underlying channel hardware to be used for other purposes. #define EXAMPLE_CHAN_GPIO_A 0 #define EXAMPLE_CHAN_GPIO_B 2 pcnt_chan_config_t chan_config = { .edge_gpio_num = EXAMPLE_CHAN_GPIO_A, .level_gpio_num = EXAMPLE_CHAN_GPIO_B, }; pcnt_channel_handle_t pcnt_chan = NULL; ESP_ERROR_CHECK(pcnt_new_channel(pcnt_unit, &chan_config, &pcnt_chan)); Set Up Channel Actions The PCNT will increase/decrease/hold its internal count value when the input pulse signal toggles. User can set different actions for edge signal and/or level signal. · pcnt_channel_set_edge_action() function is to set specific actions for rising and falling edge of the signal attached to the pcnt_chan_config_t::edge_gpio_num. Supported actions are listed in pcnt_channel_edge_action_t. Espressif Systems 780 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · pcnt_channel_set_level_action() function is to set specific actions for high and low level of the signal attached to the pcnt_chan_config_t::level_gpio_num. Supported actions are listed in pcnt_channel_level_action_t. This function is not mandatory if the pcnt_chan_config_t::level_gpio_num is set to -1 when allocating PCNT channel by pcnt_new_channel(). // decrease the counter on rising edge, increase the counter on falling edge ESP_ERROR_CHECK(pcnt_channel_set_edge_action(pcnt_chan, PCNT_CHANNEL_EDGE_ACTION_ DECREASE, PCNT_CHANNEL_EDGE_ACTION_INCREASE)); // keep the counting mode when the control signal is high level, and reverse the counting mode when the control signal is low level ESP_ERROR_CHECK(pcnt_channel_set_level_action(pcnt_chan, PCNT_CHANNEL_LEVEL_ACTION_ KEEP, PCNT_CHANNEL_LEVEL_ACTION_INVERSE)); Watch Points Each PCNT unit can be configured to watch several different values that younre interested in. The value to be watched is also called Watch Point. The watch point itself cann t exceed the range set in pcnt_unit_config_t by pcnt_unit_config_t::low_limit and pcnt_unit_config_t::high_limit. When the counter reaches either watch point, a watch event will be triggered and notify user by interrupt if any watch event callback has ever registered in pcnt_unit_register_event_callbacks(). See Register Event Callbacks for how to register event callbacks. The watch point can be added and removed by pcnt_unit_add_watch_point() and pcnt_unit_remove_watch_point(). The commonly used watch points are: zero cross, maximum / minimum count and other threshold values. The number of available watch point is limited, pcnt_unit_add_watch_point() will return error ESP_ERR_NOT_FOUND if it cannt find any free hardware resource to save the watch point. User cannt add the same watch point for multiple times, otherwise it will return error ESP_ERR_INVALID_STATE. It is recommended to remove the unused watch point by pcnt_unit_remove_watch_point() to recycle the watch point resources. Be careful when you recycle the PCNT unit by pcnt_del_unit(), the using watch points must be removed from the unit in advance. // add zero across watch point ESP_ERROR_CHECK(pcnt_unit_add_watch_point(pcnt_unit, 0)); // add high limit watch point ESP_ERROR_CHECK(pcnt_unit_add_watch_point(pcnt_unit, EXAMPLE_PCNT_HIGH_LIMIT)); Register Event Callbacks When PCNT unit reaches any enabled watch point, specific event will be generated and notify the CPU by interrupt. If you have some function that want to get executed when event happens, you should hook your function to the interrupt service routine by calling pcnt_unit_register_event_callbacks(). All supported event callbacks are listed in the pcnt_event_callbacks_t: · pcnt_event_callbacks_t::on_reach sets a callback function for watch point 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 pcnt_watch_cb_t. User can save their own context to pcnt_unit_register_event_callbacks() as well, via the parameter user_ctx. This user data will be directly passed to the callback functions. In the callback function, the driver will fill in the event data of specific event. For example, the watch point event data is declared as pcnt_watch_event_data_t: · pcnt_watch_event_data_t::watch_point_value saves the watch point value that triggers the event. · pcnt_watch_event_data_t::zero_cross_mode saves how the PCNT unit crosses the zero point in the latest time. The possible zero cross modes are listed in the pcnt_unit_zero_cross_mode_t. Usually different zero cross mode means different counting direction and counting step size. Espressif Systems 781 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference static bool example_pcnt_on_reach(pcnt_unit_handle_t unit, pcnt_watch_event_data_t *edata, void *user_ctx) { BaseType_t high_task_wakeup; QueueHandle_t queue = (QueueHandle_t)user_ctx; // send watch point to queue, from this interrupt callback xQueueSendFromISR(queue, &(edata->watch_point_value), &high_task_wakeup); // return whether a high priority task has been waken up by this function return (high_task_wakeup == pdTRUE); } pcnt_event_callbacks_t cbs = { .on_reach = example_pcnt_on_reach, }; QueueHandle_t queue = xQueueCreate(10, sizeof(int)); ESP_ERROR_CHECK(pcnt_unit_register_event_callbacks(pcnt_unit, &cbs, queue)); Unit IO Control Set Glitch Filter The PCNT unit features filters to ignore possible short glitches in the signals. The parameters that can be configured for the glitch filter are listed in pcnt_glitch_filter_config_t: · pcnt_glitch_filter_config_t::max_glitch_ns sets the maximum glitch width, in nano seconds. If a signal pulsens width is smaller than this value, then it will be treated as noise and wonnt increase/decrease the internal counter. User can enable the glitch filter for PCNT unit by calling pcnt_unit_set_glitch_filter() with the filter configuration provided above. Particularly, user can disable the glitch filter later by calling pcnt_unit_set_glitch_filter() with a NULL filter configuration. Note: The glitch filter is clocked from APB. For the counter not to miss any pulses, the maximum glitch width should be longer than one APB_CLK cycle (usually 12.5 ns if APB equals 80MHz). As the APB frequency would be changed after DFS (Dynamic Frequency Scaling) enabled, which means the filter wonnt work as expect in that case. So the driver will install a PM lock for PCNT unit during the first time user enables the glitch filter. For more information related to power management strategy used in PCNT driver, please see Power Management. pcnt_glitch_filter_config_t filter_config = { .max_glitch_ns = 1000, }; ESP_ERROR_CHECK(pcnt_unit_set_glitch_filter(pcnt_unit, &filter_config)); Start/Stop and Clear Calling pcnt_unit_start() will make the PCNT unit start to work, increase or decrease counter according to pulse signals. On the contrary, calling pcnt_unit_stop() will stop the PCNT unit but retain current count value. Instead, clearing counter can only be done by calling pcnt_unit_clear_count(). Get Count Value User can check current count value at any time by calling pcnt_unit_get_count(). Note: The returned count value is a signed integer, where the sign can be used to reflect the direction. The internal counter will overflow when it reaches high or low limit, but this function doesnnt compensate for that loss. int pulse_count = 0; ESP_ERROR_CHECK(pcnt_unit_get_count(pcnt_unit, &pulse_count)); Espressif Systems 782 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 behavior of PCNT glitch filter and leading to valid signal being treated as noise. 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 user enables the glitch filter by pcnt_unit_set_glitch_filter(), the driver will guarantee that the power management lock is acquired after the PCNT unit is started by pcnt_unit_start(). Likewise, the driver releases the lock after pcnt_unit_stop() is called. This requires that the pcnt_unit_start() and pcnt_unit_stop() should appear in pairs, otherwise the power management will be out of action. IRAM Safe By default, the PCNT 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_PCNT_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_PCNT_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: · pcnt_unit_start() · pcnt_unit_stop() · pcnt_unit_clear_count() · pcnt_unit_get_count() Thread Safety The factory function pcnt_new_unit() and pcnt_new_channel() are guaranteed to be thread safe by the driver, which means, user can call them from different RTOS tasks without protection by extra locks. Other functions that take the pcnt_unit_handle_t and pcnt_channel_handle_t as the first positional parameter, are not thread safe. The lifecycle of the PCNT unit and channel handle is maintained by the user. So user should avoid calling them concurrently. If it has to, another mutex should be added to prevent them being accessed concurrently. Kconfig Options · CONFIG_PCNT_CTRL_FUNC_IN_IRAM controls where to place the PCNT control functions (IRAM or Flash), see IRAM Safe for more information. · CONFIG_PCNT_ISR_IRAM_SAFE controls whether the default ISR handler can work when cache is disabled, see IRAM Safe for more information. · CONFIG_PCNT_ENABLE_DEBUG_LOG is used to enabled the debug log output. Enable this option will increase the firmware binary size. Application Examples · Decode the quadrature signals from rotary encoder: peripherals/pcnt/rotary_encoder. pcnt_event_callbacks_t::on_reach callback and the functions invoked by itself should also be placed in IRAM, users need to take care of them by themselves. Espressif Systems 783 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference API Reference Header File · components/driver/include/driver/pulse_cnt.h Functions esp_err_t pcnt_new_unit(const pcnt_unit_config_t *config, pcnt_unit_handle_t *ret_unit) Create a new PCNT unit, and return the handle. Note The newly created PCNT unit is put into the stopped state. Return · ESP_OK: Create PCNT unit successfully · ESP_ERR_INVALID_ARG: Create PCNT unit failed because of invalid argument (e.g. high/low limit value out of the range) · ESP_ERR_NO_MEM: Create PCNT unit failed because out of memory · ESP_ERR_NOT_FOUND: Create PCNT unit failed because all PCNT units are used up and no more free one · ESP_FAIL: Create PCNT unit failed because of other error Parameters · [in] config: PCNT unit configuration · [out] ret_unit: Returned PCNT unit handle esp_err_t pcnt_del_unit(pcnt_unit_handle_t unit) Delete the PCNT unit handle. Note Users must ensure that the PCNT unit is stopped before deleting the unit. Users can force a working unit into the stopped state via pcnt_unit_stop(). Return · ESP_OK: Delete the PCNT unit successfully · ESP_ERR_INVALID_ARG: Delete the PCNT unit failed because of invalid argument · ESP_ERR_INVALID_STATE: Delete the PCNT unit failed because corresponding PCNT channels and/or watch points are still in working · ESP_FAIL: Delete the PCNT unit failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() esp_err_t pcnt_unit_set_glitch_filter(pcnt_unit_handle_t unit, Set glitch filter for PCNT unit. pcnt_glitch_filter_config_t *config) const Note The glitch filter module is clocked from APB, and APB frequency can be changed during DFS, which in return make the filter out of action. So this function will lazy-install a PM lock internally when the power management is enabled. With this lock, the APB frequency wonnt be changed. The PM lock can only be uninstalled in pcnt_del_unit(). Return · ESP_OK: Set glitch filter successfully · ESP_ERR_INVALID_ARG: Set glitch filter failed because of invalid argument (e.g. glitch width is too big) · ESP_FAIL: Set glitch filter failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() · [in] config: PCNT filter configuration, set config to NULL means disabling the filter function esp_err_t pcnt_unit_start(pcnt_unit_handle_t unit) Start the PCNT unit, the counter will start to count according to the edge and/or level input signals. Note This function will acquire the PM lock when power management is enabled. Also see pcnt_unit_set_glitch_filter() for the condition of PM lock installation. Note The number of calls to this function should be equal to the number of calls to pcnt_unit_stop(). Note This function will be placed into IRAM if CONFIG_PCNT_CTRL_FUNC_IN_IRAM, so that itns allowed to be executed when Cache is disabled Espressif Systems 784 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return · ESP_OK: Start PCNT unit successfully · ESP_ERR_INVALID_ARG: Start PCNT unit failed because of invalid argument · ESP_FAIL: Start PCNT unit failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() esp_err_t pcnt_unit_stop(pcnt_unit_handle_t unit) Stop PCNT from counting. Note If power management is enabled, this function will release the PM lock acquired in pcnt_unit_start(). Also see pcnt_unit_set_glitch_filter() for the condition of PM lock installation. Note The stop operation wonnt clear the counter. Also see pcnt_unit_clear_count() for how to clear pulse count value. Note The number of calls to this function should be equal to the number of calls to pcnt_unit_start(). Note This function will be placed into IRAM if CONFIG_PCNT_CTRL_FUNC_IN_IRAM, so that it is allowed to be executed when Cache is disabled Return · ESP_OK: Stop PCNT unit successfully · ESP_ERR_INVALID_ARG: Stop PCNT unit failed because of invalid argument · ESP_FAIL: Stop PCNT unit failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() esp_err_t pcnt_unit_clear_count(pcnt_unit_handle_t unit) Clear PCNT pulse count value to zero. Note Itns recommended to call this function after adding a watch point by pcnt_unit_add_watch_point(), so that the newly added watch point is effective immediately. Note This function will be placed into IRAM if CONFIG_PCNT_CTRL_FUNC_IN_IRAM, so that itns allowed to be executed when Cache is disabled Return · ESP_OK: Clear PCNT pulse count successfully · ESP_ERR_INVALID_ARG: Clear PCNT pulse count failed because of invalid argument · ESP_FAIL: Clear PCNT pulse count failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() esp_err_t pcnt_unit_get_count(pcnt_unit_handle_t unit, int *value) Get PCNT count value. Note This function will be placed into IRAM if CONFIG_PCNT_CTRL_FUNC_IN_IRAM, so that itns allowed to be executed when Cache is disabled Return · ESP_OK: Get PCNT pulse count successfully · ESP_ERR_INVALID_ARG: Get PCNT pulse count failed because of invalid argument · ESP_FAIL: Get PCNT pulse count failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() · [out] value: Returned count value esp_err_t pcnt_unit_register_event_callbacks(pcnt_unit_handle_t pcnt_event_callbacks_t Set event callbacks for PCNT unit. *user_data) unit, *cbs, const void Note User can deregister the previous callback by calling this function with an empty cbs. Return · ESP_OK: Set event callbacks successfully · ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument Espressif Systems 785 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_FAIL: Set event callbacks failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() · [in] cbs: Group of callback functions · [in] user_data: User data, which will be passed to callback functions directly esp_err_t pcnt_unit_add_watch_point(pcnt_unit_handle_t unit, int watch_point) Add a watch point for PCNT unit, PCNT will generate an event when the counter value reaches the watch point value. Note The number of calls to this function should be equal to the number of calls to pcnt_unit_remove_watch_point(), otherwise the unit cannt be deleted Return · ESP_OK: Add watch point successfully · ESP_ERR_INVALID_ARG: Add watch point failed because of invalid argument (e.g. the value to be watched is out of the limitation set in pcnt_unit_config_t) · ESP_ERR_INVALID_STATE: Add watch point failed because the same watch point has already been added · ESP_ERR_NOT_FOUND: Add watch point failed because no more hardware watch point can be configured · ESP_FAIL: Add watch point failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() · [in] watch_point: Value to be watched esp_err_t pcnt_unit_remove_watch_point(pcnt_unit_handle_t unit, int watch_point) Remove a watch point for PCNT unit. Note The number of calls to this function should be equal to the number of calls to pcnt_unit_add_watch_point(), otherwise the unit cannt be deleted Return · ESP_OK: Remove watch point successfully · ESP_ERR_INVALID_ARG: Remove watch point failed because of invalid argument · ESP_ERR_INVALID_STATE: Remove watch point failed because the watch point was not added by pcnt_unit_add_watch_point() yet · ESP_FAIL: Remove watch point failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() · [in] watch_point: Watch point value esp_err_t pcnt_new_channel(pcnt_unit_handle_t unit, const pcnt_chan_config_t *config, pcnt_channel_handle_t *ret_chan) Create PCNT channel for specific unit, each PCNT has several channels associated with it. Return · ESP_OK: Create PCNT channel successfully · ESP_ERR_INVALID_ARG: Create PCNT channel failed because of invalid argument · ESP_ERR_NO_MEM: Create PCNT channel failed because of insufficient memory · ESP_ERR_NOT_FOUND: Create PCNT channel failed because all PCNT channels are used up and no more free one · ESP_FAIL: Create PCNT channel failed because of other error Parameters · [in] unit: PCNT unit handle created by pcnt_new_unit() · [in] config: PCNT channel configuration · [out] ret_chan: Returned channel handle esp_err_t pcnt_del_channel(pcnt_channel_handle_t chan) Delete the PCNT channel. Return · ESP_OK: Delete the PCNT channel successfully · ESP_ERR_INVALID_ARG: Delete the PCNT channel failed because of invalid argument Espressif Systems 786 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_FAIL: Delete the PCNT channel failed because of other error Parameters · [in] chan: PCNT channel handle created by pcnt_new_channel() esp_err_t pcnt_channel_set_edge_action(pcnt_channel_handle_t chan, pcnt_channel_edge_action_t pos_act, pcnt_channel_edge_action_t neg_act) Set channel actions when edge signal changes (e.g. falling or rising edge occurred). The edge signal is input from the edge_gpio_num configured in pcnt_chan_config_t. We use these actions to control when and how to change the counter value. Return · ESP_OK: Set edge action for PCNT channel successfully · ESP_ERR_INVALID_ARG: Set edge action for PCNT channel failed because of invalid argument · ESP_FAIL: Set edge action for PCNT channel failed because of other error Parameters · [in] chan: PCNT channel handle created by pcnt_new_channel() · [in] pos_act: Action on posedge signal · [in] neg_act: Action on negedge signal esp_err_t pcnt_channel_set_level_action(pcnt_channel_handle_t chan, pcnt_channel_level_action_t high_act, pcnt_channel_level_action_t low_act) Set channel actions when level signal changes (e.g. signal level goes from high to low). The level signal is input from the level_gpio_num configured in pcnt_chan_config_t. We use these actions to control when and how to change the counting mode. Return · ESP_OK: Set level action for PCNT channel successfully · ESP_ERR_INVALID_ARG: Set level action for PCNT channel failed because of invalid argument · ESP_FAIL: Set level action for PCNT channel failed because of other error Parameters · [in] chan: PCNT channel handle created by pcnt_new_channel() · [in] high_act: Action on high level signal · [in] low_act: Action on low level signal Structures struct pcnt_watch_event_data_t PCNT watch event data. Public Members int watch_point_value Watch point value that triggered the event pcnt_unit_zero_cross_mode_t zero_cross_mode Zero cross mode struct pcnt_event_callbacks_t Group of supported PCNT callbacks. Note The callbacks are all running under ISR environment Note When CONFIG_PCNT_ISR_IRAM_SAFE is enabled, the callback itself and functions callbed by it should be placed in IRAM. Public Members pcnt_watch_cb_t on_reach Called when PCNT unit counter reaches any watch point Espressif Systems 787 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct pcnt_unit_config_t PCNT unit configuration. Public Members int low_limit Low limitation of the count unit, should be lower than 0 int high_limit High limitation of the count unit, should be higher than 0 struct pcnt_chan_config_t PCNT channel configuration. Public Members int edge_gpio_num GPIO number used by the edge signal, input mode with pull up enabled. Set to -1 if unused int level_gpio_num GPIO number used by the level signal, input mode with pull up enabled. Set to -1 if unused uint32_t invert_edge_input : 1 Invert the input edge signal uint32_t invert_level_input : 1 Invert the input level signal uint32_t io_loop_back : 1 For debug/test, the signal output from the GPIO will be fed to the input path as well struct pcnt_glitch_filter_config_t PCNT glitch filter configuration. Public Members uint32_t max_glitch_ns Pulse width smaller than this threshold will be treated as glitch and ignored, in the unit of ns Type Definitions typedef struct pcnt_unit_t *pcnt_unit_handle_t Type of PCNT unit handle. typedef struct pcnt_chan_t *pcnt_channel_handle_t Type of PCNT channel handle. typedef bool (*pcnt_watch_cb_t)(pcnt_unit_handle_t unit, pcnt_watch_event_data_t *edata, void *user_ctx) PCNT watch event callback prototype. Note The callback function is invoked from an ISR context, so it should meet the restrictions of not calling any blocking APIs when implementing the callback. e.g. must use ISR version of FreeRTOS APIs. Return Whether a high priority task has been woken up by this function Parameters · [in] unit: PCNT unit handle · [in] edata: PCNT event data, fed by the driver · [in] user_ctx: User data, passed from pcnt_unit_register_event_callbacks() Header File · components/hal/include/hal/pcnt_types.h Espressif Systems 788 Release v5.0-dev-2349-g4350e6fef8 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_zero_cross_mode_t PCNT unit zero cross mode. Values: PCNT_UNIT_ZERO_CROSS_POS_ZERO start from positive value, end to zero, i.e. +N->0 PCNT_UNIT_ZERO_CROSS_NEG_ZERO start from negative value, end to zero, i.e. -N->0 PCNT_UNIT_ZERO_CROSS_NEG_POS start from negative value, end to positive value, i.e. -N->+M PCNT_UNIT_ZERO_CROSS_POS_NEG start from positive value, end to negative value, i.e. +N->-M 2.6.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 789 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 14: RMT Transmitter Overview Fig. 15: RMT Receiver Overview Espressif Systems 790 Release v5.0-dev-2349-g4350e6fef8 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 791 Release v5.0-dev-2349-g4350e6fef8 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. 16: 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 792 Release v5.0-dev-2349-g4350e6fef8 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_AUTO_STOP. 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 793 Release v5.0-dev-2349-g4350e6fef8 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() 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 esp_err_t rmt_set_rx_idle_thresh(rmt_channel_t channel, uint16_t thresh) Set RMT RX idle threshold value. Espressif Systems 794 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · ESP_OK Success Parameters Espressif Systems 795 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success Espressif Systems 796 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. esp_err_t rmt_set_tx_loop_mode(rmt_channel_t channel, bool loop_en) Set RMT tx loop mode. Espressif Systems 797 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 798 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 799 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 800 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 801 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 esp_err_t rmt_translator_get_context(const size_t *item_num, void **context) Get the user context set by mrmt_translator_set_contextn. Espressif Systems 802 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · ESP_ERR_INVALID_ARG Parameter error · ESP_OK Success Parameters Espressif Systems 803 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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_AUTO_STOP 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 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_mem_t RMT hardware memory layout. 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 Espressif Systems 804 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 805 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 806 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 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 Espressif Systems 807 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference RMT_BASECLK_MAX enum rmt_data_mode_t RMT Data Mode. Note We highly recommended to use MEM mode not FIFO mode since there will be some gotcha in FIFO mode. Values: RMT_DATA_MODE_FIFO RMT_DATA_MODE_MEM RMT_DATA_MODE_MAX enum rmt_mode_t RMT Channel Working Mode (TX or RX) Values: RMT_MODE_TX RMT TX mode RMT_MODE_RX RMT RX mode RMT_MODE_MAX enum rmt_idle_level_t RMT Idle Level. Values: RMT_IDLE_LEVEL_LOW RMT TX idle level: low Level RMT_IDLE_LEVEL_HIGH RMT TX idle level: high Level RMT_IDLE_LEVEL_MAX enum rmt_carrier_level_t RMT Carrier Level. Values: RMT_CARRIER_LEVEL_LOW RMT carrier wave is modulated for low Level output RMT_CARRIER_LEVEL_HIGH RMT carrier wave is modulated for high Level output RMT_CARRIER_LEVEL_MAX enum rmt_channel_status_t RMT Channel Status. Values: RMT_CHANNEL_UNINIT RMT channel uninitialized RMT_CHANNEL_IDLE RMT channel status idle RMT_CHANNEL_BUSY RMT channel status busy Espressif Systems 808 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Header File · components/hal/include/hal/rmt_types.h Unions union rmt_symbol_word_t #include <rmt_types.h> The layout of RMT symbol stored in memory, which is decided by the hardware design. Public Members unsigned int duration0 : 15 Duration of level0 unsigned int level0 : 1 Level of the first part unsigned int duration1 : 15 Duration of level1 unsigned int level1 : 1 Level of the second part struct rmt_symbol_word_t::[anonymous] [anonymous] unsigned int val Equivelent unsigned value for the RMT symbol Enumerations enum rmt_clock_source_t RMT group clock source. Note User should select the clock source based on the power and resolution requirement Values: RMT_CLK_SRC_NONE No clock source is selected RMT_CLK_SRC_REFTICK Select REF_TICK as the source clock RMT_CLK_SRC_APB Select APB as the source clock RMT_CLK_SRC_FAST_RC Select internal fast RC oscillator as the source clock RMT_CLK_SRC_XTAL Select XTAL as the source clock 2.6.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: Espressif Systems 809 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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.6.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. Espressif Systems 810 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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; (continues on next page) Espressif Systems 811 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference slot.d0 = GPIO_NUM_3; slot.d1 = GPIO_NUM_4; slot.d2 = GPIO_NUM_5; slot.d3 = GPIO_NUM_6; (continued from previous page) 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(). 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 Espressif Systems 812 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 813 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 814 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 815 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.6.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). 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. Espressif Systems 816 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 817 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 818 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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). Espressif Systems 819 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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_DEFAULT_DMA 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 Espressif Systems 820 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Type Definitions typedef int sdspi_dev_handle_t Handle representing an SD SPI device. 2.6.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. 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. Application Example Sigma-delta Modulation example: peripherals/sigmadelta. API Reference Header File · components/driver/include/driver/sigmadelta.h Functions esp_err_t sigmadelta_config(const sigmadelta_config_t *config) Configure Sigma-delta channel. Return · ESP_OK Success · ESP_ERR_INVALID_STATE sigmadelta driver already initialized · ESP_ERR_INVALID_ARG Parameter error Parameters Espressif Systems 821 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 17: Sallen-Key Low Pass Filter · 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 Espressif Systems 822 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. gpio_num_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 Espressif Systems 823 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SIGMADELTA_CHANNEL_6 Sigma-delta channel 6 SIGMADELTA_CHANNEL_7 Sigma-delta channel 7 SIGMADELTA_CHANNEL_MAX Sigma-delta channel max 2.6.18 SPI Master Driver SPI Master driver is a program that controls ESP32-S3ns SPI peripherals while they function as masters. 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. Espressif Systems 824 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 825 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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). The SPI Master driver hasnnt supported SPI1 bus. Only SPI Flash driver can attach to the bus. · For other buses, the driver may register its ISR as the BG. The bus lock will block a device task when it requests for exclusive use of the bus, try to disable the ISR, and unblock the device task allowed to exclusively use the bus when the ISR is successfully disabled. When the task releases the lock, the lock will also try to resume the ISR if there are pending transactions to be done in the ISR. SPI Transactions An SPI bus transaction consists of five phases which can be found in the table below. Any of these phases can be skipped. Phase 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 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 spi_transaction_t::length and spi_transaction_t::rxlength 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 spi_device_interface_config_t::command_bits and/or spi_device_interface_config_t::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 spi_transaction_t::rx_buffer is NULL and SPI_TRANS_USE_RXDATA is not set, the read phase is skipped. If spi_transaction_t::tx_buffer is NULL and SPI_TRANS_USE_TXDATA is not set, the write phase is skipped. Espressif Systems 826 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Data Line Line Width Width 1 1 Transaction Flag 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 spi_transaction_t::cmd and spi_transaction_t::addr 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 Espressif Systems 827 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 spi_transaction_ext_t::command_bits and spi_transaction_ext_t::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 spi_transaction_t::rx_buffer and spi_transaction_t::tx_buffer. 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. 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(). Espressif Systems 828 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 spi_transaction_t::tx_data member and setting the SPI_TRANS_USE_TXDATA flag on the transmission. For received data, use spi_transaction_t::rx_data and set SPI_TRANS_USE_RXDATA. In both cases, do not touch the spi_transaction_t::tx_buffer or spi_transaction_t::rx_buffer members, because they use the same memory locations as spi_transaction_t::tx_data and spi_transaction_t::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 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. Espressif Systems 829 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 830 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · components/hal/include/hal/spi_types.h Structures struct spi_line_mode_t Line mode of SPI transaction phases: CMD, ADDR, DOUT/DIN. Public Members uint8_t cmd_lines The line width of command phase, e.g. 2-line-cmd-phase. uint8_t addr_lines The line width of address phase, e.g. 1-line-addr-phase. uint8_t data_lines The line width of data phase, e.g. 4-line-data-phase. Enumerations enum spi_host_device_t Enum with the three SPI peripherals that are software-accessible in it. Values: SPI1_HOST = 0 SPI1. SPI2_HOST = 1 SPI2. SPI3_HOST = 2 SPI3. SPI_HOST_MAX invalid host value enum spi_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). Espressif Systems 831 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 bus hasnnt been initialized before, or 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. Espressif Systems 832 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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); Espressif Systems 833 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Then points tx_buffer to &data. Parameters · DATA: Data to be sent, can be uint8_t, uint16_t or uint32_t. · LEN: Length of data to be sent, since the SPI peripheral sends from the MSB, this helps to shift the data to the MSB. SPI_SWAP_DATA_RX(DATA, LEN) Transform received data of length <= 32 bits to the format of an unsigned integer. E.g. to transform the data of 15 bits placed in a 4-byte array to integer: uint16_t data = SPI_SWAP_DATA_RX(*(uint32_t*)t->rx_data, 15); Parameters · DATA: Data to be rearranged, can be uint8_t, uint16_t or uint32_t. · LEN: Length of data received, since the SPI peripheral writes from the MSB, this helps to shift the data to the LSB. SPICOMMON_BUSFLAG_SLAVE Initialize I/O in slave mode. SPICOMMON_BUSFLAG_MASTER Initialize I/O in master mode. SPICOMMON_BUSFLAG_IOMUX_PINS Check using iomux pins. Or indicates the pins are configured through the IO mux rather than GPIO matrix. SPICOMMON_BUSFLAG_GPIO_PINS Force the signals to be routed through GPIO matrix. Or indicates the pins are routed through the GPIO matrix. SPICOMMON_BUSFLAG_SCLK Check existing of SCLK pin. Or indicates CLK line initialized. SPICOMMON_BUSFLAG_MISO Check existing of MISO pin. Or indicates MISO line initialized. SPICOMMON_BUSFLAG_MOSI Check existing of MOSI pin. Or indicates MOSI line initialized. SPICOMMON_BUSFLAG_DUAL Check MOSI and MISO pins can output. Or indicates bus able to work under DIO mode. SPICOMMON_BUSFLAG_WPHD Check existing of WP and HD pins. Or indicates WP & HD pins initialized. SPICOMMON_BUSFLAG_QUAD Check existing of MOSI/MISO/WP/HD pins as output. Or indicates bus able to work under QIO mode. SPICOMMON_BUSFLAG_IO4_IO7 Check existing of IO4~IO7 pins. Or indicates IO4~IO7 pins initialized. SPICOMMON_BUSFLAG_OCTAL Check existing of MOSI/MISO/WP/HD/SPIIO4/SPIIO5/SPIIO6/SPIIO7 pins as output. Or indicates bus able to work under octal mode. SPICOMMON_BUSFLAG_NATIVE_PINS Type Definitions typedef spi_common_dma_t spi_dma_chan_t Enumerations enum spi_common_dma_t SPI DMA channels. Values: Espressif Systems 834 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 835 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 836 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 837 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · duty_cycle: Duty cycle of the spi clock void spi_get_timing(bool gpio_is_used, int input_delay_ns, int eff_clk, int *dummy_o, int *cycles_remain_o) Calculate the timing settings of specified frequency and settings. Note If **dummy_o* is not zero, it means dummy bits should be applied in half duplex mode, and full duplex mode may not work. Parameters · gpio_is_used: True if using GPIO matrix, or False if iomux pins are used. · input_delay_ns: Input delay from SCLK launch edge to MISO data valid. · eff_clk: Effective clock frequency (in Hz) from spi_cal_clock. · dummy_o: Address of dummy bits used output. Set to NULL if not needed. · cycles_remain_o: Address of cycles remaining (after dummy bits are used) output. -1 If too many cycles remaining, suggest to compensate half a clock. 0 If no remaining cycles or dummy bits are not used. positive value: cycles suggest to compensate. int spi_get_freq_limit(bool gpio_is_used, int input_delay_ns) Get the frequency limit of current configurations. SPI master working at this limit is OK, while above the limit, full duplex mode and DMA will not work, and dummy bits will be aplied in the half duplex mode. Return Frequency limit of current configurations. Parameters · gpio_is_used: True if using GPIO matrix, or False if native pins are used. · input_delay_ns: Input delay from SCLK launch edge to MISO data valid. Structures struct spi_device_interface_config_t This is a configuration for a SPI slave device that is connected to one of the SPI buses. Public Members uint8_t command_bits Default amount of bits in command phase (0-16), used when SPI_TRANS_VARIABLE_CMD is not used, otherwise ignored. uint8_t address_bits Default amount of bits in address phase (0-64), used when SPI_TRANS_VARIABLE_ADDR is not used, otherwise ignored. uint8_t dummy_bits Amount of dummy bits to insert between address and data phase. uint8_t mode SPI mode, representing a pair of (CPOL, CPHA) configuration: · 0: (0, 0) · 1: (0, 1) · 2: (1, 0) · 3: (1, 1) uint16_t duty_cycle_pos Duty cycle of positive clock, in 1/256th increments (128 = 50%/50% duty). Setting this to 0 (=not setting it) is equivalent to setting this to 128. uint16_t cs_ena_pretrans Amount of SPI bit-cycles the cs should be activated before the transmission (0-16). This only works on half-duplex transactions. uint8_t cs_ena_posttrans Amount of SPI bit-cycles the cs should stay active after the transmission (0-16) Espressif Systems 838 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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). Espressif Systems 839 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference void *user User-defined variable. Can be used to store eg transaction ID. const void *tx_buffer Pointer to transmit buffer, or NULL for no MOSI phase. uint8_t tx_data[4] If SPI_TRANS_USE_TXDATA is set, data set here is sent directly from this variable. void *rx_buffer Pointer to receive buffer, or NULL for no MISO phase. Written by 4 bytes-unit if DMA is used. uint8_t rx_data[4] If SPI_TRANS_USE_RXDATA is set, data is received directly to this variable. struct spi_transaction_ext_t This struct is for SPI transactions which may change their address and command length. Please do set the flags in base to SPI_TRANS_VARIABLE_CMD_ADR to use the bit length here. Public Members struct spi_transaction_t base Transaction data, so that pointer to spi_transaction_t can be converted into spi_transaction_ext_t. uint8_t command_bits The command length in this transaction, in bits. uint8_t address_bits The address length in this transaction, in bits. uint8_t dummy_bits The dummy length in this transaction, in bits. Macros SPI_MASTER_FREQ_8M SPI master clock is divided by 80MHz apb clock. Below defines are example frequencies, and are accurate. Be free to specify a random frequency, it will be rounded to closest frequency (to macros below if above 8MHz). 8MHz SPI_MASTER_FREQ_9M 8.89MHz SPI_MASTER_FREQ_10M 10MHz SPI_MASTER_FREQ_11M 11.43MHz SPI_MASTER_FREQ_13M 13.33MHz SPI_MASTER_FREQ_16M 16MHz SPI_MASTER_FREQ_20M 20MHz SPI_MASTER_FREQ_26M 26.67MHz SPI_MASTER_FREQ_40M 40MHz SPI_MASTER_FREQ_80M 80MHz Espressif Systems 840 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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) Espressif Systems 841 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.6.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. Terminology The terms used in relation to the SPI slave driver are given in the table below. Espressif Systems 842 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Term Host Device Bus · MISO · MOSI · SCLK · CS · QUADWP · QUADHD · Assertion Transaction Launch edge Latch edge 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. 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. 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. Espressif Systems 843 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 spi_slave_transaction_t::rx_buffer and spi_slave_transaction_t::tx_buffer. 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 spi_slave_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 speci- fied in the spi_slave_transaction_t::length member will be sent and received. In this case, spi_slave_transaction_t::trans_len is set to spi_slave_transaction_t::length instead of the actual transaction length. To meet the actual transaction length require- ments, set spi_slave_transaction_t::length to a value greater than the maximum spi_slave_transaction_t::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. 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(). Espressif Systems 844 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. esp_err_t spi_slave_free(spi_host_device_t host) Free a SPI bus claimed as a SPI slave interface. Return Espressif Systems 845 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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. Espressif Systems 846 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 847 Release v5.0-dev-2349-g4350e6fef8 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.6.20 Temperature Sensor Introduction The ESP32-S3 has a built-in sensor used to measure the chipns internal temperature. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a DAC to compensate for the temperature offset. Due to restrictions of hardware, the sensor has predefined measurement ranges with specific measurement errors. See the table below for details. predefined range (°C) 50 ~ 125 20 ~ 100 -10 ~ 80 -30 ~ 50 -40 ~ 20 error (°C) <3 <2 <1 <2 <3 Note: The temperature sensor is designed primarily to measure the temperature changes inside the chip. The temperature value depends on factors like microcontroller clock frequency or I/O load. Generally, the chipns internal temperature might be higher than the ambient temperature. Functional Overview · Resource Allocation - covers which parameters should be set up to get a temperature sensor handle and how to recycle the resources when temperature sensor finishes working. · Start and Stop Temperature - covers how to start or stop the temperature sensor. · Get Temperature Value - covers how to get the real-time temperature value. · Power Management - covers how temperature sensor is affected when changing power mode (i.e. light sleep). · Thread Safety - covers how to make the driver to be thread safe. Resource Allocation The ESP32-S3 has just one built-in temperature sensor hardware. The temperature sensor instance is represented by temperature_sensor_handle_t, which is also the bond of the context. It would always be the parameter of the temperature APIs with the information of hardware and configurations, so user can just create a pointer of type temperature_sensor_handle_t and passing to APIs as needed. In order to install a built-in temperature sensor instance, the first thing is to evaluate the temperature range in your detection environment (For example: if the testing environment is in a room, the range you evaluate might be 10 °C ~ 30 °C; if the testing in a lamp bulb, the range you evaluate might be 60 °C ~ 110 °C). Based on that, the following configuration structure should be defined in advance: temperature_sensor_config_t: · range_min. The minimum value of testing range you have evaluated. Espressif Systems 848 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · range_max. The maximum value of testing range you have evaluated. After the ranges are set, the structure could be passed to temperature_sensor_install(), which will instantiate the temperature sensor instance and return a handle. As mentioned above, different measure ranges have different measurement errors. The user doesnnt need to care about the measurement error because we have an internal mechanism to choose the minimum error according to the given range. If the temperature sensor is no longer needed, you need to call temperature_sensor_uninstall() to free the temperature sensor resource. Creating a Temperature Sensor Handle · Step1: Evaluate the testing range. In this example, the range is 20 °C ~ 50 °C. · Step2: Configure the range and obtain a handle temperature_sensor_handle_t temp_handle = NULL; temperature_sensor_config_t temp_sensor = { .range_min = 20, .range_max = 50, }; ESP_ERROR_CHECK(temperature_sensor_install(&temp_sensor, &temp_handle)); Start and Stop Temperature 1. Start the temperature sensor by calling temperature_sensor_start(). The temperature sensor will now measure the temperature. 2. To stop the temperature sensor, please call temperature_sensor_stop(). Get Temperature Value After the temperature sensor has been installed, you can get the temperature value by following the steps below. 1. To get the current temperature, please call temperature_sensor_get_celsius(). ESP_ERROR_CHECK(temperature_sensor_start(temp_handle)); printf("Temperature sensor started\n"); float tsens_out; ESP_ERROR_CHECK(temperature_sensor_get_celsius(temp_handle, &tsens_out)); printf("Temperature in %f °C\n", tsens_out); ESP_ERROR_CHECK(temperature_sensor_stop(temp_handle)); Power Management When power management is enabled (i.e. CONFIG_PM_ENABLE is on), temperature sensor will still keep working because it uses XTAL clock (on ESP32-C3) or RTC clock (on ESP32-S2/S3). Thread Safety In temperature sensor we donnt add any protection to keep the thread safe. Because from the common usage, temperature sensor should only be called in one task. If you must use this driver in different tasks, please add extra locks to protect it. Unexpected Behaviors 1. The value user gets from the chip is usually different from the ambient temperature. It is because the temperature sensor is built inside the chip. To some extent, it measures the temperature of the chip. 2. When installing the temperature sensor, the driver gives a mthe boundary you gave cannot meet the range of internal temperature sensornerror feedback. It is because the built-in temperature sensor has testing limit. The error due to setting temperature_sensor_config_t: (1) Totally out of range, like 200 °C ~ 300 °C. Espressif Systems 849 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (2) Cross the boundary of each predefined measurement. like 40 °C ~ 110 °C. Application Example Temperature sensor reading example: peripherals/temp_sensor. API Reference Header File · components/driver/include/driver/temperature_sensor.h Functions esp_err_t temperature_sensor_install(const temperature_sensor_config_t *tsens_config, tem- perature_sensor_handle_t *ret_tsens) Install temperature sensor driver. Return · ESP_OK if succeed Parameters · tsens_config: Pointer to config structure. · ret_tsens: Return the pointer of temperature sensor handle. esp_err_t temperature_sensor_uninstall(temperature_sensor_handle_t tsens) Uninstall the temperature sensor driver. Return · ESP_OK if succeed. Parameters · tsens: The handle created by temperature_sensor_install(). esp_err_t temperature_sensor_start(temperature_sensor_handle_t tsens) Start temperature measurement. Return · ESP_OK Success · ESP_ERR_INVALID_STATE if temperature sensor is started already. Parameters · tsens: The handle created by temperature_sensor_install(). esp_err_t temperature_sensor_stop(temperature_sensor_handle_t tsens) Stop temperature sensor measure. Return · ESP_OK Success · ESP_ERR_INVALID_STATE if temperature sensor is stopped already. Parameters · tsens: The handle created by temperature_sensor_install(). esp_err_t temperature_sensor_get_celsius(temperature_sensor_handle_t tsens, float *out_celsius) Read temperature sensor data that is converted to degrees Celsius. Note Should not be called from interrupt. Return · ESP_OK Success · ESP_ERR_INVALID_ARG ARG is NULL. · ESP_ERR_INVALID_STATE The ambient temperature is out of range. Parameters · tsens: The handle created by temperature_sensor_install(). · out_celsius: The measure output value. Espressif Systems 850 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Structures struct temperature_sensor_config_t Configuration of measurement range for the temperature sensor. Note If you see the log the boundary you gave cannot meet the range of internal temperature sensor. You may need to refer to predefined range listed doc api-reference/ peripherals/Temperature sensor. Macros TEMPERAUTRE_SENSOR_CONFIG_DEFAULT(min, max) temperature_sensor_config_t default constructure Type Definitions typedef struct temperature_sensor_obj_t *temperature_sensor_handle_t Type of temperature sensor driver handle. 2.6.21 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(). Espressif Systems 851 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Configuration Enabling the touch sensor functionality for a particular GPIO is done with touch_pad_config(). Use the function touch_pad_set_fsm_mode() to select if touch pad measurement (operated by FSM) should be started automatically by a hardware timer, or by software. If software mode is selected, use touch_pad_sw_start() to start the FSM. Touch State Measurements The following 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. 18: 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. Espressif Systems 852 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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(). 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 Espressif Systems 853 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 854 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 855 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 856 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 857 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 858 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 859 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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; Espressif Systems 860 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 861 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 862 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 863 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 864 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TOUCH_PAD_GPIO4_CHANNEL TOUCH_PAD_NUM4_GPIO_NUM TOUCH_PAD_GPIO5_CHANNEL TOUCH_PAD_NUM5_GPIO_NUM TOUCH_PAD_GPIO6_CHANNEL 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 Espressif Systems 865 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 866 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TOUCH_PAD_THRESHOLD_MAX If set touch threshold max value, The touch sensor cannt be in touched status 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) Espressif Systems 867 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TOUCH_PAD_NUM8 Touch pad channel 8 is GPIO33(ESP32) / GPIO8(ESP32-S2) 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: Espressif Systems 868 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TOUCH_HVOLT_ATTEN_KEEP = -1 Touch sensor high reference voltage attenuation, no change TOUCH_HVOLT_ATTEN_1V5 = 0 Touch sensor high reference voltage attenuation, 1.5V attenuation TOUCH_HVOLT_ATTEN_1V Touch 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 Espressif Systems 869 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TOUCH_FSM_MODE_MAX enum touch_trigger_mode_t Values: TOUCH_TRIGGER_BELOW = 0 Touch interrupt will happen if counter value is less than threshold. TOUCH_TRIGGER_ABOVE = 1 Touch interrupt will happen if counter value is larger than threshold. TOUCH_TRIGGER_MAX enum touch_trigger_src_t Values: TOUCH_TRIGGER_SOURCE_BOTH = 0 wakeup interrupt is generated if both SET1 and SET2 are 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 Espressif Systems 870 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TOUCH_PAD_DENOISE_CAP_L1 = 1 Denoise channel internal reference capacitance is 6.4pf 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. Espressif Systems 871 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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.6.22 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. Espressif Systems 872 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: Sections · Two-Wire Automotive Interface (TWAI) Overview TWAI Protocol Summary Signals Lines and Transceiver Driver Configuration Driver Operation Examples API Reference 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. Espressif Systems 873 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Error Active: A node is Error Active when both TEC and REC are less than 128 and indicates that the node is operating normally. Error Active nodes are allowed to participate in bus communications, and will actively signal the detection of any errors by automatically transmitting an Active Error Flag over the bus. Error Passive: A node is Error Passive when either the TEC or REC becomes greater than or equal to 128. Error Passive nodes are still able to take part in bus communications, but will instead transmit a Passive Error Flag upon detection of an error. Bus-Off: A node becomes Bus-Off when the TEC becomes greater than or equal to 256. A Bus-Off node is unable influence the bus in any manner (essentially disconnected from the bus) thus eliminating itself from the bus. A node will remain in the Bus-Off state until it undergoes bus-off recovery. Signals Lines and Transceiver The TWAI controller does not contain a integrated transceiver. Therefore, to connect the TWAI controller to a TWAI bus, an external transceiver is required. The type of external transceiver used should depend on the 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. 19: 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. Espressif Systems 874 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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). 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 11: 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 Espressif Systems 875 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Fig. 20: 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. Espressif Systems 876 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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). Fig. 21: Bit layout of single filter mode (Right side MSBit) Dual Filter Mode will use the acceptance code and mask to define two separate filters allowing for increased flexibility of IDns to accept, but does not allow for all 29-bits of an extended ID to be filtered. The following diagram illustrates how the 32-bit acceptance code and mask will be interpreted under Dual Filter Mode (Note: The yellow and blue fields represent standard and extended frame formats respectively). Fig. 22: 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). Espressif Systems 877 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Label A B C D E F G H Fig. 23: State transition diagram of the TWAI driver (see table below) 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 878 Release v5.0-dev-2349-g4350e6fef8 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 879 Release v5.0-dev-2349-g4350e6fef8 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 880 Release v5.0-dev-2349-g4350e6fef8 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 881 Release v5.0-dev-2349-g4350e6fef8 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 882 Release v5.0-dev-2349-g4350e6fef8 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 883 Release v5.0-dev-2349-g4350e6fef8 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 884 Release v5.0-dev-2349-g4350e6fef8 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 885 Release v5.0-dev-2349-g4350e6fef8 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 886 Release v5.0-dev-2349-g4350e6fef8 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 887 Release v5.0-dev-2349-g4350e6fef8 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.6.23 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 (also referred to as port), 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 888 Release v5.0-dev-2349-g4350e6fef8 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 12: 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 889 Release v5.0-dev-2349-g4350e6fef8 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 890 Release v5.0-dev-2349-g4350e6fef8 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 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 891 Release v5.0-dev-2349-g4350e6fef8 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 892 Release v5.0-dev-2349-g4350e6fef8 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 893 Release v5.0-dev-2349-g4350e6fef8 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 894 Release v5.0-dev-2349-g4350e6fef8 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 895 Release v5.0-dev-2349-g4350e6fef8 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 896 Release v5.0-dev-2349-g4350e6fef8 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 897 Release v5.0-dev-2349-g4350e6fef8 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 898 Release v5.0-dev-2349-g4350e6fef8 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 899 Release v5.0-dev-2349-g4350e6fef8 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 900 Release v5.0-dev-2349-g4350e6fef8 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 901 Release v5.0-dev-2349-g4350e6fef8 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 902 Release v5.0-dev-2349-g4350e6fef8 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 903 Release v5.0-dev-2349-g4350e6fef8 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 904 Release v5.0-dev-2349-g4350e6fef8 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_WAKEUP UART wakeup event 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. Espressif Systems 905 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t cmd_char UART AT cmd char uint8_t char_num AT cmd char repeat number uint32_t gap_tout gap time(in baud-rate) between AT cmd char uint32_t pre_idle the idle time(in baud-rate) between the non AT char and first AT char uint32_t post_idle the idle time(in baud-rate) between the last AT char and the none AT char struct uart_sw_flowctrl_t UART software flow control configuration parameters. Public Members uint8_t xon_char Xon flow control char uint8_t xoff_char Xoff flow control char uint8_t xon_thrd If the software flow control is enabled and the data amount in rxfifo is less than xon_thrd, an xon_char will be sent uint8_t xoff_thrd If the software flow control is enabled and the data amount in rxfifo is more than xoff_thrd, an xoff_char will be sent struct uart_config_t UART configuration parameters for uart_param_config function. Public Members int baud_rate UART baud rate uart_word_length_t data_bits UART byte size uart_parity_t parity UART parity mode uart_stop_bits_t stop_bits UART stop bits uart_hw_flowcontrol_t flow_ctrl UART HW flow control mode (cts/rts) uint8_t rx_flow_ctrl_thresh UART HW RTS threshold uart_sclk_t source_clk UART source clock selection bool use_ref_tick Deprecated method to select ref tick clock source, set source_clk field instead Espressif Systems 906 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Type Definitions typedef int uart_port_t UART port number, can be UART_NUM_0 ~ (UART_NUM_MAX -1). Enumerations enum uart_mode_t UART mode selection. Values: UART_MODE_UART = 0x00 mode: regular UART mode UART_MODE_RS485_HALF_DUPLEX = 0x01 mode: half duplex RS485 UART mode control by RTS pin UART_MODE_IRDA = 0x02 mode: IRDA UART mode UART_MODE_RS485_COLLISION_DETECT = 0x03 mode: RS485 collision detection UART mode (used for test purposes) UART_MODE_RS485_APP_CTRL = 0x04 mode: application control RS485 UART mode (used for test purposes) enum uart_word_length_t UART word length constants. Values: UART_DATA_5_BITS = 0x0 word length: 5bits 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 Espressif Systems 907 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference UART_PARITY_EVEN = 0x2 Enable UART even parity UART_PARITY_ODD = 0x3 Enable UART odd parity enum uart_hw_flowcontrol_t UART hardware flow control modes. Values: UART_HW_FLOWCTRL_DISABLE = 0x0 disable hardware flow control UART_HW_FLOWCTRL_RTS = 0x1 enable RX hardware flow control (rts) UART_HW_FLOWCTRL_CTS = 0x2 enable TX hardware flow control (cts) UART_HW_FLOWCTRL_CTS_RTS = 0x3 enable hardware flow control UART_HW_FLOWCTRL_MAX = 0x4 enum uart_signal_inv_t UART signal bit map. Values: UART_SIGNAL_INV_DISABLE = 0 Disable UART signal inverse UART_SIGNAL_IRDA_TX_INV = (0x1 << 0) inverse the UART irda_tx signal UART_SIGNAL_IRDA_RX_INV = (0x1 << 1) inverse the UART irda_rx signal UART_SIGNAL_RXD_INV = (0x1 << 2) inverse the UART rxd signal UART_SIGNAL_CTS_INV = (0x1 << 3) inverse the UART cts signal UART_SIGNAL_DSR_INV = (0x1 << 4) inverse the UART dsr signal UART_SIGNAL_TXD_INV = (0x1 << 5) inverse the UART txd signal UART_SIGNAL_RTS_INV = (0x1 << 6) inverse the UART rts signal UART_SIGNAL_DTR_INV = (0x1 << 7) inverse the UART dtr signal enum uart_sclk_t UART source clock. Values: UART_SCLK_APB = 0x0 UART source clock from APB UART_SCLK_RTC = 0x1 UART source clock from RTC UART_SCLK_XTAL = 0x2 UART source clock from XTAL Espressif Systems 908 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference GPIO Lookup Macros The UART peripherals have dedicated IO_MUX pins to which they are connected directly. However, signals can also be routed to other pins using the less direct GPIO matrix. To use direct routes, you need to know which pin is a dedicated IO_MUX pin for a UART channel. GPIO Lookup Macros simplify the process of finding and assigning IO_MUX pins. You choose a macro based on either the IO_MUX pin number, or a required UART channel name, and the macro will return the matching counterpart for you. See some examples below. Note: These macros are useful if you need very high UART baud rates (over 40 MHz), which means you will have to use IO_MUX pins only. In other cases, these macros can be ignored, and you can use the GPIO Matrix as it allows you to configure any GPIO pin for any UART function. 1. UART_NUM_2_TXD_DIRECT_GPIO_NUM returns the IO_MUX pin number of UART channel 2 TXD pin (pin 17) 2. UART_GPIO19_DIRECT_CHANNEL returns the UART number of GPIO 19 when connected to the UART peripheral via IO_MUX (this is UART_NUM_0) 3. UART_CTS_GPIO19_DIRECT_CHANNEL returns the UART number of GPIO 19 when used as the UART CTS pin via IO_MUX (this is UART_NUM_0). Similar to the above macro but specifies the pin function which is also part of the IO_MUX assignment. Header File · components/soc/esp32s3/include/soc/uart_channel.h Macros UART_GPIO43_DIRECT_CHANNEL UART_NUM_0_TXD_DIRECT_GPIO_NUM UART_GPIO44_DIRECT_CHANNEL UART_NUM_0_RXD_DIRECT_GPIO_NUM UART_GPIO16_DIRECT_CHANNEL UART_NUM_0_CTS_DIRECT_GPIO_NUM UART_GPIO15_DIRECT_CHANNEL UART_NUM_0_RTS_DIRECT_GPIO_NUM UART_TXD_GPIO43_DIRECT_CHANNEL UART_RXD_GPIO44_DIRECT_CHANNEL UART_CTS_GPIO16_DIRECT_CHANNEL UART_RTS_GPIO15_DIRECT_CHANNEL UART_GPIO17_DIRECT_CHANNEL UART_NUM_1_TXD_DIRECT_GPIO_NUM UART_GPIO18_DIRECT_CHANNEL UART_NUM_1_RXD_DIRECT_GPIO_NUM UART_GPIO20_DIRECT_CHANNEL UART_NUM_1_CTS_DIRECT_GPIO_NUM UART_GPIO19_DIRECT_CHANNEL UART_NUM_1_RTS_DIRECT_GPIO_NUM UART_TXD_GPIO17_DIRECT_CHANNEL UART_RXD_GPIO18_DIRECT_CHANNEL UART_CTS_GPIO20_DIRECT_CHANNEL Espressif Systems 909 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference UART_RTS_GPIO19_DIRECT_CHANNEL 2.6.24 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: 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 Espressif Systems 910 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; } 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 (continues on next page) Espressif Systems 911 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference }; tusb_cdc_acm_init(&amc_cfg); (continued from previous page) 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 · 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. Espressif Systems 912 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members const tusb_desc_device_t *device_descriptor Pointer to a device descriptor. If set to NULL, the TinyUSB device will use a default device descriptor whose values are set in Kconfig const tusb_desc_device_t *descriptor Alias to device_descriptor for backward compatibility const char **string_descriptor Pointer to an array of string descriptors bool external_phy Should USB use an external PHY const uint8_t *configuration_descriptor Pointer to a configuration descriptor. If set to NULL, TinyUSB device will use a default configuration descriptor whose values are set in Kconfig 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- Unregister a callback invoking on CDC event. cacm_event_type_t event_type) Return esp_err_t - ESP_OK or ESP_ERR_INVALID_ARG Parameters Espressif Systems 913 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 914 Release v5.0-dev-2349-g4350e6fef8 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 915 Release v5.0-dev-2349-g4350e6fef8 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 916 Release v5.0-dev-2349-g4350e6fef8 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.6.25 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 917 Release v5.0-dev-2349-g4350e6fef8 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. 24: 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 918 Release v5.0-dev-2349-g4350e6fef8 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 919 Release v5.0-dev-2349-g4350e6fef8 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. 25: 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 920 Release v5.0-dev-2349-g4350e6fef8 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 921 Release v5.0-dev-2349-g4350e6fef8 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 922 Release v5.0-dev-2349-g4350e6fef8 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 923 Release v5.0-dev-2349-g4350e6fef8 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 924 Release v5.0-dev-2349-g4350e6fef8 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 925 Release v5.0-dev-2349-g4350e6fef8 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 926 Release v5.0-dev-2349-g4350e6fef8 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 927 Release v5.0-dev-2349-g4350e6fef8 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 928 Release v5.0-dev-2349-g4350e6fef8 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 929 Release v5.0-dev-2349-g4350e6fef8 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 930 Release v5.0-dev-2349-g4350e6fef8 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 931 Release v5.0-dev-2349-g4350e6fef8 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 932 Release v5.0-dev-2349-g4350e6fef8 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 933 Release v5.0-dev-2349-g4350e6fef8 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 934 Release v5.0-dev-2349-g4350e6fef8 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 935 Release v5.0-dev-2349-g4350e6fef8 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 936 Release v5.0-dev-2349-g4350e6fef8 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 937 Release v5.0-dev-2349-g4350e6fef8 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 938 Release v5.0-dev-2349-g4350e6fef8 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 939 Release v5.0-dev-2349-g4350e6fef8 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 940 Release v5.0-dev-2349-g4350e6fef8 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 941 Release v5.0-dev-2349-g4350e6fef8 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 942 Release v5.0-dev-2349-g4350e6fef8 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 943 Release v5.0-dev-2349-g4350e6fef8 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 944 Release v5.0-dev-2349-g4350e6fef8 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.7 Project Configuration 2.7.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.7.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. Espressif Systems 945 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.7.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.7.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. 2.7.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. Renames that should only appear for a single target can be placed in a target specific rename file: sdkconfig.rename.TARGET, where TARGET is the target name, e.g. sdkconfig.rename.esp32s2. 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. Espressif Systems 946 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.7.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_NO_BLOBS CONFIG_APP_BUILD_TYPE Application build type Found in: Build type Select the way the application is built. By default, the application is built as a binary file in a format compatible with the ESP-IDF bootloader. In addition to this application, 2nd stage bootloader is also built. Application and bootloader binaries can be written into flash and loaded/executed from there. Another option, useful for only very small and limited applications, is to only link the .elf file of the application, such that it can be loaded directly into RAM over JTAG. Note that since IRAM and DRAM sizes are very limited, it is not possible to build any complex application this way. However for kinds of testing and debugging, this option may provide faster iterations, since the application does not need to be written into flash. Note that at the moment, ESP-IDF does not contain all the startup code required to initialize the CPUs and ROM memory (data/bss). Therefore it is necessary to execute a bit of ROM code prior to executing the application. A gdbinit file may look as follows (for ESP32): # Connect to a running instance of OpenOCD target remote :3333 # Reset and halt the target mon reset halt # Run to a specific point in ROM code, # where most of initialization is complete. thb *0x40007d54 c # Load the application into RAM load # Run till app_main tb app_main c Execute this gdbinit file as follows: xtensa-esp32-elf-gdb build/app-name.elf -x gdbinit Example gdbinit files for other targets can be found in tools/test_apps/system/gdb_loadable_elf/ Recommended sdkconfig.defaults for building loadable ELF files is as follows. 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) Espressif Systems 947 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) CONFIG_APP_NO_BLOBS No Binary Blobs Found in: Build type 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) 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 948 Release v5.0-dev-2349-g4350e6fef8 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 949 Release v5.0-dev-2349-g4350e6fef8 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 950 Release v5.0-dev-2349-g4350e6fef8 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 951 Release v5.0-dev-2349-g4350e6fef8 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_APP_TEST_PIN_LEVEL App test GPIO level Found in: Bootloader config > CONFIG_BOOTLOADER_APP_TEST Pin level for app test, can be triggered on low or high. Available options: · Enter test app on GPIO low (BOOTLOADER_APP_TEST_PIN_LOW) · Enter test app on GPIO high (BOOTLOADER_APP_TEST_PIN_HIGH) 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). Espressif Systems 952 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 953 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 954 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 955 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE Size in bytes for custom purposes Found in: Bootloader config > CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC This option reserves in RTC FAST memory the area for custom purposes. If you want to create your own bootloader and save more information in this area of memory, you can increase it. It must be a multiple of 4 bytes. This area (rtc_retain_mem_t) is reserved and has access from the bootloader and an application. Range: · from 0 to 0x10 if CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC Default value: · 0 if CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC CONFIG_BOOTLOADER_FLASH_XMC_SUPPORT Enable the support for flash chips of XMC (READ HELP FIRST) 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_SIGNED_ON_BOOT_NO_SECURE_BOOT · CONFIG_SECURE_FLASH_CHECK_ENC_EN_IN_APP · CONFIG_SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE · CONFIG_SECURE_FLASH_ENC_ENABLED · CONFIG_SECURE_BOOT · CONFIG_SECURE_BOOTLOADER_KEY_ENCODING · Potentially insecure options · CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT · CONFIG_SECURE_BOOT_VERIFICATION_KEY · CONFIG_SECURE_BOOTLOADER_MODE · CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES · CONFIG_SECURE_UART_ROM_DL_MODE · CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT Require signed app images Found in: Security features Require apps to be signed to verify their integrity. This option uses the same app signature scheme as hardware secure boot, but unlike hardware secure boot it does not prevent the bootloader from being physically updated. This means that the device can be secured against remote network access, but not physical access. Compared to using hardware Secure Boot this option is much simpler to implement. Espressif Systems 956 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · ECDSA (SECURE_SIGNED_APPS_ECDSA_SCHEME) Embeds the ECDSA public key in the bootloader and signs the application with an ECDSA key. Refer to the documentation before enabling. · RSA (SECURE_SIGNED_APPS_RSA_SCHEME) Appends the RSA-3072 based Signature block to the application. Refer to <Secure Boot Version 2 documentation link> before enabling. CONFIG_SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT Bootloader verifies app signatures Found in: Security features If this option is set, the bootloader will be compiled with code to verify that an app is signed before booting it. If hardware secure boot is enabled, this option is always enabled and cannot be disabled. If hardware secure boot is not enabled, this option doesnnt add significant security by itself so most users will want to leave it disabled. Default value: · No (disabled) if CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT && SECURE_SIGNED_APPS_ECDSA_SCHEME 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. Espressif Systems 957 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. CONFIG_SECURE_BOOTLOADER_MODE Secure bootloader mode Found in: Security features Available options: · One-time flash (SECURE_BOOTLOADER_ONE_TIME_FLASH) On first boot, the bootloader will generate a key which is not readable externally or by software. A digest is generated from the bootloader image itself. This digest will be verified on each subsequent boot. Enabling this option means that the bootloader cannot be changed after the first time it is booted. · Reflashable (SECURE_BOOTLOADER_REFLASHABLE) Generate a reusable secure bootloader key, derived (via SHA-256) from the secure boot signing key. This allows the secure bootloader to be re-flashed by anyone with access to the secure boot signing key. This option is less secure than one-time flash, because a leak of the digest key from one device allows reflashing of any device that uses it. CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES Sign binaries during build 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.) Espressif Systems 958 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · No (disabled) if CONFIG_SECURE_BOOT CONFIG_SECURE_BOOTLOADER_KEY_ENCODING Hardware Key Encoding Found in: Security features In reflashable secure bootloader mode, a hardware key is derived from the signing key (with SHA-256) and can be written to eFuse with espefuse.py. Normally this is a 256-bit key, but if 3/4 Coding Scheme is used on the device then the eFuse key is truncated to 192 bits. Espressif Systems 959 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference This configuration item doesnnt change any firmware code, it only changes the size of key binary which is generated at build time. Available options: · No encoding (256 bit key) (SECURE_BOOTLOADER_KEY_ENCODING_256BIT) · 3/4 encoding (192 bit key) (SECURE_BOOTLOADER_KEY_ENCODING_192BIT) CONFIG_SECURE_BOOT_INSECURE Allow potentially insecure options 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. Espressif Systems 960 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 961 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 962 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 963 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Boot ROM Behavior Contains: · CONFIG_BOOT_ROM_LOG_SCHEME 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) Espressif Systems 964 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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) · 32 MB (ESPTOOLPY_FLASHSIZE_32MB) · 64 MB (ESPTOOLPY_FLASHSIZE_64MB) · 128 MB (ESPTOOLPY_FLASHSIZE_128MB) CONFIG_ESPTOOLPY_FLASHSIZE_DETECT Detect flash size when flashing bootloader Found in: Serial flasher config Espressif Systems 965 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference If this option is set, flashing the project will automatically detect the flash size of the target chip and update the bootloader image before it is flashed. Default value: · Yes (enabled) CONFIG_ESPTOOLPY_BEFORE Before flashing 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 Espressif Systems 966 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 compo- nents/partition_table/partitions_singleapp_large.csv This partition table is not suitable for an app that needs OTA (over the air update) capability. · Factory app, two OTA definitions (PARTITION_TABLE_TWO_OTA) This is a basic OTA-enabled partition table with a factory app partition plus two OTA app partitions. All are 1MB, so this partition table requires 4MB or larger flash size. 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. Espressif Systems 967 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 968 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · Optimize for performance (-O2) (COMPILER_OPTIMIZATION_PERF) · Debug without optimization (-O0) (COMPILER_OPTIMIZATION_NONE) 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 Espressif Systems 969 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Enabling this option compiles all IDF C++ files with exception support enabled. Disabling this option disables C++ exception support in all compiled files, and any libstdc++ code which throws an exception will abort instead. Enabling this option currently adds an additional ~500 bytes of heap overhead when an exception is thrown in user code for the first time. Default value: · No (disabled) Contains: · CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE Emergency Pool Size Found in: Compiler options > CONFIG_COMPILER_CXX_EXCEPTIONS Size (in bytes) of the emergency memory pool for C++ exceptions. This pool will be used to allocate memory for thrown exceptions when there is not enough memory on the heap. Default value: · 0 if CONFIG_COMPILER_CXX_EXCEPTIONS CONFIG_COMPILER_CXX_RTTI Enable C++ run-time type info (RTTI) 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) Espressif Systems 970 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · Normal (COMPILER_STACK_CHECK_MODE_NORM) · Strong (COMPILER_STACK_CHECK_MODE_STRONG) · Overall (COMPILER_STACK_CHECK_MODE_ALL) CONFIG_COMPILER_WARN_WRITE_STRINGS Enable -Wwrite-strings warning flag 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 · 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 Espressif Systems 971 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP32S3-Specific · Ethernet · Event Loop Library · FAT Filesystem support · FreeRTOS · GDB Stub · Hardware Abstraction Layer (HAL) and Low Level (LL) · Hardware Settings · Heap memory debugging · High resolution timer (esp_timer) · HTTP Server · IPC (Inter-Processor Call) · LCD and Touch Panel · Log output · LWIP · mbedTLS · mDNS · Modbus configuration · Newlib · NVS · 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_DESTINATION1 · CONFIG_APPTRACE_DESTINATION2 · 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_UART_BAUDRATE · CONFIG_APPTRACE_UART_RX_GPIO · CONFIG_APPTRACE_UART_RX_BUFF_SIZE · CONFIG_APPTRACE_UART_TASK_PRIO · CONFIG_APPTRACE_UART_TX_MSG_SIZE · CONFIG_APPTRACE_UART_TX_GPIO · CONFIG_APPTRACE_UART_TX_BUFF_SIZE CONFIG_APPTRACE_DESTINATION1 Data Destination 1 Espressif Systems 972 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_DESTINATION2 Data Destination 2 Found in: Component config > Application Level Tracing Select destination for application trace: UART(XX) or none (to disable). Available options: · UART0 (APPTRACE_DEST_UART0) · UART1 (APPTRACE_DEST_UART1) · UART2 (APPTRACE_DEST_UART2) · USB_CDC (APPTRACE_DEST_USB_CDC) · None (APPTRACE_DEST_UART_NONE) CONFIG_APPTRACE_UART_TX_GPIO UART TX on GPIO# Found in: Component config > Application Level Tracing This GPIO is used for UART TX pin. CONFIG_APPTRACE_UART_RX_GPIO UART RX on GPIO# Found in: Component config > Application Level Tracing This GPIO is used for UART RX pin. CONFIG_APPTRACE_UART_BAUDRATE UART baud rate Found in: Component config > Application Level Tracing This baud rate is used for UART. 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. CONFIG_APPTRACE_UART_RX_BUFF_SIZE UART RX ring buffer size Found in: Component config > Application Level Tracing Size of the UART input ring buffer. This size related to the baudrate, system tick frequency and amount of data to transfer. The data placed to this buffer before sent out to the interface. Espressif Systems 973 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_APPTRACE_UART_TX_BUFF_SIZE UART TX ring buffer size Found in: Component config > Application Level Tracing Size of the UART output ring buffer. This size related to the baudrate, system tick frequency and amount of data to transfer. CONFIG_APPTRACE_UART_TX_MSG_SIZE UART TX message size Found in: Component config > Application Level Tracing Maximum size of the single message to transfer. CONFIG_APPTRACE_UART_TASK_PRIO UART Task Priority Found in: Component config > Application Level Tracing UART task priority. In case of high events rate, this parameter could be changed up to (configMAX_PRIORITIES-1). Range: · from 1 to 32 Default value: ·1 CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO 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. Espressif Systems 974 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference FreeRTOS SystemView Tracing Contains: · CONFIG_APPTRACE_SV_CPU · CONFIG_APPTRACE_SV_EVT_ISR_ENTER_ENABLE · CONFIG_APPTRACE_SV_EVT_ISR_EXIT_ENABLE · CONFIG_APPTRACE_SV_EVT_ISR_TO_SCHED_ENABLE · CONFIG_APPTRACE_SV_MAX_TASKS · CONFIG_APPTRACE_SV_EVT_IDLE_ENABLE · CONFIG_APPTRACE_SV_ENABLE · CONFIG_APPTRACE_SV_EVT_TASK_CREATE_ENABLE · CONFIG_APPTRACE_SV_EVT_TASK_START_EXEC_ENABLE · CONFIG_APPTRACE_SV_EVT_TASK_START_READY_ENABLE · CONFIG_APPTRACE_SV_EVT_TASK_STOP_EXEC_ENABLE · CONFIG_APPTRACE_SV_EVT_TASK_STOP_READY_ENABLE · CONFIG_APPTRACE_SV_EVT_TASK_TERMINATE_ENABLE · CONFIG_APPTRACE_SV_EVT_TIMER_ENTER_ENABLE · CONFIG_APPTRACE_SV_EVT_TIMER_EXIT_ENABLE · CONFIG_APPTRACE_SV_TS_SOURCE · CONFIG_APPTRACE_SV_EVT_OVERFLOW_ENABLE · CONFIG_APPTRACE_SV_BUF_WAIT_TMO 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_DEST SystemView destination Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE SystemView witt transfer data trough defined interface. Available options: · Data destination JTAG (APPTRACE_SV_DEST_JTAG) Send SEGGER SystemView events through JTAG interface. · Data destination UART (APPTRACE_SV_DEST_UART) Send SEGGER SystemView events through UART interface. CONFIG_APPTRACE_SV_CPU CPU to trace Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing Define the CPU to trace by SystemView. Available options: · CPU0 (APPTRACE_SV_DEST_CPU_0) Send SEGGER SystemView events for Pro CPU. · CPU1 (APPTRACE_SV_DEST_CPU_1) Send SEGGER SystemView events for App CPU. CONFIG_APPTRACE_SV_TS_SOURCE Espressif Systems 975 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Timer to use as timestamp source Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing 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) CONFIG_APPTRACE_SV_MAX_TASKS Maximum supported tasks Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing 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 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 Enables oTrace Buffer Overflowpevent. CONFIG_APPTRACE_SV_EVT_ISR_ENTER_ENABLE ISR Enter Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing Enables oISR Enterpevent. CONFIG_APPTRACE_SV_EVT_ISR_EXIT_ENABLE ISR Exit Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing 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 Enables oISR to Schedulerpevent. Espressif Systems 976 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_APPTRACE_SV_EVT_TASK_START_EXEC_ENABLE Task Start Execution Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing Enables oTask Start Executionpevent. CONFIG_APPTRACE_SV_EVT_TASK_STOP_EXEC_ENABLE Task Stop Execution Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing 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 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 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 Enables oTask Createpevent. CONFIG_APPTRACE_SV_EVT_TASK_TERMINATE_ENABLE Task Terminate Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing Enables oTask Terminatepevent. CONFIG_APPTRACE_SV_EVT_IDLE_ENABLE System Idle Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing Enables oSystem Idlepevent. CONFIG_APPTRACE_SV_EVT_TIMER_ENTER_ENABLE Timer Enter Event Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing Enables oTimer Enterpevent. Espressif Systems 977 Release v5.0-dev-2349-g4350e6fef8 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 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 Bluetooth Contains: · Bluedroid Options · CONFIG_BT_ENABLED · NimBLE Options Espressif Systems 978 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 979 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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: Espressif Systems 980 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) 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. Espressif Systems 981 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 982 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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 Espressif Systems 983 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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. Espressif Systems 984 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 985 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 986 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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: Espressif Systems 987 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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: Espressif Systems 988 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) · 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 Espressif Systems 989 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) · 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) Espressif Systems 990 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 991 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) · 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 Espressif Systems 992 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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) Espressif Systems 993 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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) Espressif Systems 994 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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: Espressif Systems 995 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 996 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_LL_DUP_SCAN_LIST_COUNT · CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME · CONFIG_BT_NIMBLE_HS_STOP_TIMEOUT_MS · CONFIG_BT_NIMBLE_LL_RESOLV_LIST_SIZE · CONFIG_BT_NIMBLE_WHITELIST_SIZE · CONFIG_BT_NIMBLE_COEX_PHY_CODED_TX_RX_TLIM · CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_2M_PHY · 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_SLEEP_ENABLE · CONFIG_BT_NIMBLE_SECURITY_ENABLE · CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT · CONFIG_BT_NIMBLE_BLUFI_ENABLE · CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_CODED_PHY · CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT Espressif Systems 997 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · CONFIG_BT_NIMBLE_USE_ESP_TIMER · CONFIG_BT_NIMBLE_DEBUG · CONFIG_BT_NIMBLE_HOST_BASED_PRIVACY · CONFIG_BT_NIMBLE_HS_FLOW_CTRL · CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_ENCRYPTION · CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV · CONFIG_BT_NIMBLE_PERIODIC_ADV_SYNC_TRANSFER · CONFIG_BT_NIMBLE_SVC_GAP_APPEARANCE · CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE · CONFIG_BT_NIMBLE_HCI_UART_BAUD · CONFIG_BT_NIMBLE_HCI_UART_PORT · CONFIG_BT_NIMBLE_HCI_UART_RX_PIN · CONFIG_BT_NIMBLE_HCI_UART_TASK_STACK_SIZE · CONFIG_BT_NIMBLE_HCI_UART_TX_PIN · 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_EXT_ADV_DATA_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_MAX_EXT_ADV_INSTANCES · CONFIG_BT_NIMBLE_MAX_PERIODIC_SYNCS · CONFIG_BT_NIMBLE_MEM_ALLOC_MODE · CONFIG_BT_NIMBLE_CONTROLLER_TASK_PRIORITY · CONFIG_BT_NIMBLE_LOG_LEVEL · CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE · CONFIG_BT_NIMBLE_MEMORY_SETTINGS · 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_RUN_BQB_TEST · CONFIG_BT_NIMBLE_HARDWARE_BLE_ONLY · CONFIG_BT_NIMBLE_RUN_QA_TEST · CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE · CONFIG_BT_NIMBLE_TEST_THROUGHPUT_TEST · 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. Espressif Systems 998 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) · 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_HCI_UART_PORT HCI UART port Found in: Component config > Bluetooth > NimBLE Options Set the port number of HCI UART Default value: · 1 if BT_NIMBLE_USE_UART_HCI && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_HCI_UART_TX_PIN HCI uart Tx gpio Found in: Component config > Bluetooth > NimBLE Options Default value: · 19 if BT_NIMBLE_USE_UART_HCI && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_HCI_UART_RX_PIN HCI uart Rx gpio Found in: Component config > Bluetooth > NimBLE Options Default value: · 10 if BT_NIMBLE_USE_UART_HCI && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_HCI_UART_TASK_STACK_SIZE HCI uart task stack size Found in: Component config > Bluetooth > NimBLE Options Set the size of uart task stack Default value: · 1000 if BT_NIMBLE_USE_UART_HCI && BT_NIMBLE_ENABLED Espressif Systems 999 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_BT_NIMBLE_HCI_UART_BAUD HCI uart baudrate Found in: Component config > Bluetooth > NimBLE Options HCI uart baud rate 115200 ~ 1000000 Default value: · 921600 if BT_NIMBLE_USE_UART_HCI && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_RUN_QA_TEST Run QA test Found in: Component config > Bluetooth > NimBLE Options Enable this option to run QA test. Default value: · Yes (enabled) if BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_RUN_BQB_TEST Run BQB test Found in: Component config > Bluetooth > NimBLE Options Enable this option to run BQB test. Default value: · No (disabled) if BT_NIMBLE_ENABLED 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 Espressif Systems 1000 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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_HOST_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 Enables central role 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 Enable peripheral role Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED Espressif Systems 1001 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_BT_NIMBLE_ROLE_BROADCASTER Enable BLE Broadcaster role Found in: Component config > Bluetooth > NimBLE Options Enables broadcaster role 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 Enables observer role Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_CONTROLLER_TASK_PRIORITY NimBLE Controller task priority Found in: Component config > Bluetooth > NimBLE Options This configures priority of NimBLE controller task Default value: · 23 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: · No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_SECURITY_ENABLE Enable BLE SM feature Found in: Component config > Bluetooth > NimBLE Options Enable BLE sm feature Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED Contains: · CONFIG_BT_NIMBLE_SM_LEGACY · CONFIG_BT_NIMBLE_SM_SC Espressif Systems 1002 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_BT_NIMBLE_SM_LEGACY Security manager legacy pairing Found in: Component config FIG_BT_NIMBLE_SECURITY_ENABLE Enable security manager legacy pairing Default value: · Yes (enabled) if BT_NIMBLE_ENABLED > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_SECURITY_ENABLE CON&& CONFIG_BT_NIMBLE_SM_SC Security manager secure connections (4.2) Found in: Component config > Bluetooth > NimBLE Options > FIG_BT_NIMBLE_SECURITY_ENABLE Enable security manager secure connections Default value: · Yes (enabled) if BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_SECURITY_ENABLE CON&& 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_LL_CFG_FEAT_LE_ENCRYPTION Enable LE encryption Found in: Component config > Bluetooth > NimBLE Options Enable encryption connection Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_SECURITY_ENABLE && 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 Espressif Systems 1003 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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: · 512 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: · 24 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: Espressif Systems 1004 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 251 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 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_MEMORY_SETTINGS OS Memory Settings Found in: Component config > Bluetooth > NimBLE Options Settings memory blocks Default value: · Yes (enabled) if BT_NIMBLE_ENABLED Contains: · CONFIG_BT_NIMBLE_MSYS_1_BLOCK_COUNT · CONFIG_BT_NIMBLE_MSYS_1_BLOCK_SIZE · CONFIG_BT_NIMBLE_MSYS_2_BLOCK_COUNT · CONFIG_BT_NIMBLE_MSYS_2_BLOCK_SIZE Espressif Systems 1005 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_BT_NIMBLE_MSYS_1_BLOCK_COUNT MSYS_1 Block Count Found in: Component config > Bluetooth > NimBLE Options > CON- FIG_BT_NIMBLE_MEMORY_SETTINGS 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 CONFIG_BT_NIMBLE_MEMORY_SETTINGS && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_MSYS_1_BLOCK_SIZE MSYS_1 Block Size Found in: Component config > Bluetooth > NimBLE Options > CON- FIG_BT_NIMBLE_MEMORY_SETTINGS Dynamic memory size of block 1 Default value: · 256 if CONFIG_BT_NIMBLE_MEMORY_SETTINGS && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_MSYS_2_BLOCK_COUNT MSYS_2 Block Count Found in: Component config > Bluetooth > NimBLE Options > CON- FIG_BT_NIMBLE_MEMORY_SETTINGS Dynamic memory count Default value: · 24 if CONFIG_BT_NIMBLE_MEMORY_SETTINGS && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_MSYS_2_BLOCK_SIZE MSYS_2 Block Size Found in: Component config > Bluetooth > NimBLE Options > CON- FIG_BT_NIMBLE_MEMORY_SETTINGS Dynamic memory size of block 2 Default value: · 320 if CONFIG_BT_NIMBLE_MEMORY_SETTINGS && 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 Espressif Systems 1006 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_BT_NIMBLE_HS_FLOW_CTRL_ITVL Host Flow control interval Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_HS_FLOW_CTRL Host flow control interval in msecs Default value: · 1000 if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_HS_FLOW_CTRL_THRESH Host Flow control threshold 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 Espressif Systems 1007 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · CONFIG_BT_NIMBLE_MESH_RELAY · CONFIG_BT_NIMBLE_MESH_DEVICE_NAME · CONFIG_BT_NIMBLE_MESH_NODE_COUNT CONFIG_BT_NIMBLE_MESH_PROXY Enable mesh proxy functionality Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH Enable proxy. This is automatically set whenever NIMBLE_MESH_PB_GATT or 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 Espressif Systems 1008 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1009 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1010 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT Enable BLE v5.0 feature Found in: Component config > Bluetooth > NimBLE Options Enable BLE v5.0 feature Default value: · Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED Contains: · CONFIG_BT_NIMBLE_EXT_ADV CONFIG_BT_NIMBLE_EXT_ADV Enable extended advertising Found in: Component config > Bluetooth > NimBLE Options > CON- FIG_BT_NIMBLE_50_FEATURE_SUPPORT Enable this option to do extended advertising. Extended advertising will be supported from BLE 5.0 onwards. Default value: · No (disabled) if BT_NIMBLE_ENABLED && FIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED CON- CONFIG_BT_NIMBLE_EXT_ADV_MAX_SIZE set ext adv maximum paket size Found in: Component config > Bluetooth > NimBLE Options > FIG_BT_NIMBLE_50_FEATURE_SUPPORT > CONFIG_BT_NIMBLE_EXT_ADV Ext ADV packet size Default value: · 1650 if CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && FIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED CONCON- CONFIG_BT_NIMBLE_COEX_PHY_CODED_TX_RX_TLIM Coexistence: limit on MAX Tx/Rx time for coded-PHY connection Found in: Component config > Bluetooth > NimBLE Options 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_NIMBLE_COEX_PHY_CODED_TX_RX_TLIM_EN) Always enable the limitation on max tx/rx time for Coded-PHY connection · Force Disable (BT_NIMBLE_COEX_PHY_CODED_TX_RX_TLIM_DIS) Disable the limitation on max tx/rx time for Coded-PHY connection CONFIG_BT_NIMBLE_WHITELIST_SIZE BLE white list size Found in: Component config > Bluetooth > NimBLE Options BLE list size Range: Espressif Systems 1011 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · from 1 to 15 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED Default value: · 12 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_MAX_EXT_ADV_INSTANCES Maximum number of extended advertising instances. Found in: Component config > Bluetooth > NimBLE Options 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 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 Enable this option to start periodic advertisement. Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_PERIODIC_ADV_SYNC_TRANSFER Enable Transer Sync Events Found in: Component config > Bluetooth > NimBLE Options This enables controller transfer periodic sync events to host 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 Espressif Systems 1012 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_2M_PHY Enable 2M Phy Found in: Component config > Bluetooth > NimBLE Options Enable 2M-PHY Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_CODED_PHY Enable coded Phy Found in: Component config > Bluetooth > NimBLE Options Enable coded-PHY Default value: · Yes (enabled) if CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_HARDWARE_BLE_ONLY Run example on Ble Only Hardware Found in: Component config > Bluetooth > NimBLE Options Run example on Ble Only Hardware Default value: · Yes (enabled) if BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_TEST_THROUGHPUT_TEST Throughput Test Mode enable Found in: Component config > Bluetooth > NimBLE Options Enable the throughput test mode Default value: · No (disabled) if BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_LL_RESOLV_LIST_SIZE BLE LL Resolving list size Found in: Component config > Bluetooth > NimBLE Options Configure the size of resolving list used in link layer. Espressif Systems 1013 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Default value: · 4 if BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_LL_DUP_SCAN_LIST_COUNT BLE duplicate scan list count Found in: Component config > Bluetooth > NimBLE Options config the max count of duplicate scan list Range: · from 1 to 100 if BT_NIMBLE_ENABLED Default value: · 8 if BT_NIMBLE_ENABLED CONFIG_BT_NIMBLE_SLEEP_ENABLE Enable BLE sleep Found in: Component config > Bluetooth > NimBLE Options Enable BLE sleep Default value: · No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED 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 Espressif Systems 1014 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · CONFIG_BLE_MESH_PROV · CONFIG_BLE_MESH_PROXY · BLE Mesh specific test option · BLE Mesh STACK DEBUG LOG LEVEL · CONFIG_BLE_MESH_NO_LOG · CONFIG_BLE_MESH_IVU_DIVIDER · CONFIG_BLE_MESH_FAST_PROV · CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC · CONFIG_BLE_MESH_CRPL · CONFIG_BLE_MESH_RX_SDU_MAX · CONFIG_BLE_MESH_MODEL_KEY_COUNT · CONFIG_BLE_MESH_APP_KEY_COUNT · CONFIG_BLE_MESH_MODEL_GROUP_COUNT · CONFIG_BLE_MESH_LABEL_COUNT · CONFIG_BLE_MESH_SUBNET_COUNT · CONFIG_BLE_MESH_TX_SEG_MAX · CONFIG_BLE_MESH_RX_SEG_MSG_COUNT · CONFIG_BLE_MESH_TX_SEG_MSG_COUNT · CONFIG_BLE_MESH_MEM_ALLOC_MODE · CONFIG_BLE_MESH_MSG_CACHE_SIZE · CONFIG_BLE_MESH_ADV_BUF_COUNT · CONFIG_BLE_MESH_PB_GATT · CONFIG_BLE_MESH_PB_ADV · CONFIG_BLE_MESH_RELAY · CONFIG_BLE_MESH_SETTINGS · CONFIG_BLE_MESH_DEINIT · CONFIG_BLE_MESH_USE_DUPLICATE_SCAN · Support for BLE Mesh Client/Server models · Support for BLE Mesh Foundation models · CONFIG_BLE_MESH_NODE · CONFIG_BLE_MESH_PROVISIONER · CONFIG_BLE_MESH_FRIEND · CONFIG_BLE_MESH_LOW_POWER · CONFIG_BLE_MESH_HCI_5_0 · CONFIG_BLE_MESH_IV_UPDATE_TEST · CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT CONFIG_BLE_MESH_HCI_5_0 Support sending 20ms non-connectable adv packets Found in: Component config > CONFIG_BLE_MESH It is a temporary solution and needs further modifications. Default value: · Yes (enabled) if CONFIG_BLE_MESH CONFIG_BLE_MESH_USE_DUPLICATE_SCAN Support Duplicate Scan in BLE Mesh 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 Espressif Systems 1015 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · 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. Espressif Systems 1016 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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 Espressif Systems 1017 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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: Espressif Systems 1018 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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: · 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 Espressif Systems 1019 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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- 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. Espressif Systems 1020 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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 Espressif Systems 1021 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1022 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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 Espressif Systems 1023 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1024 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1025 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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 Espressif Systems 1026 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1027 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1028 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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: Espressif Systems 1029 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 1030 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1031 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1032 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1033 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 1034 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · CONFIG_BLE_MESH_LIGHT_CTL_CLI · CONFIG_BLE_MESH_LIGHT_HSL_CLI · CONFIG_BLE_MESH_LIGHT_LC_CLI · CONFIG_BLE_MESH_LIGHT_LIGHTNESS_CLI · CONFIG_BLE_MESH_LIGHT_XYL_CLI · CONFIG_BLE_MESH_LIGHTING_SERVER · CONFIG_BLE_MESH_SCENE_CLI · CONFIG_BLE_MESH_SCHEDULER_CLI · CONFIG_BLE_MESH_SENSOR_CLI · CONFIG_BLE_MESH_SENSOR_SERVER · CONFIG_BLE_MESH_TIME_SCENE_SERVER · CONFIG_BLE_MESH_TIME_CLI CONFIG_BLE_MESH_GENERIC_ONOFF_CLI Generic OnOff Client model Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models Enable support for Generic OnOff Client model. CONFIG_BLE_MESH_GENERIC_LEVEL_CLI Generic Level Client model 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. Espressif Systems 1035 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1036 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1037 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1038 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1039 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Driver configurations Contains: · ADC configuration · GDMA Configuration · GPIO Configuration · GPTimer Configuration · MCPWM configuration · PCNT Configuration · SPI configuration · Temperature sensor Configuration · TWAI configuration · UART configuration ADC configuration Contains: · CONFIG_ADC_DISABLE_DAC · CONFIG_ADC_FORCE_XPD_FSM Espressif Systems 1040 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_ADC_FORCE_XPD_FSM Use the FSM to control ADC power Found in: Component config > Driver configurations > ADC configuration ADC power can be controlled by the FSM instead of software. This allows the ADC to be shut off when it is not working leading to lower power consumption. However using the FSM control ADC power will increase the noise of ADC. Default value: · No (disabled) CONFIG_ADC_DISABLE_DAC Disable DAC when ADC2 is used on GPIO 25 and 26 Found in: Component config > Driver configurations > ADC configuration If this is set, the ADC2 driver will disable the output of the DAC corresponding to the specified channel. This is the default value. For testing, disable this option so that we can measure the output of DAC by internal ADC. Default value: · Yes (enabled) MCPWM configuration Contains: · CONFIG_MCPWM_ISR_IN_IRAM CONFIG_MCPWM_ISR_IN_IRAM Place MCPWM ISR function into IRAM Found in: Component config > Driver configurations > MCPWM configuration If this option is not selected, the MCPWM interrupt will be deferred when the Cache is in a disabled state (e.g. Flash write/erase operation). Note that if this option is selected, all user registered ISR callbacks should never try to use cache as well. (with IRAM_ATTR) Default value: · No (disabled) SPI configuration Contains: · CONFIG_SPI_MASTER_ISR_IN_IRAM · CONFIG_SPI_SLAVE_ISR_IN_IRAM · CONFIG_SPI_MASTER_IN_IRAM · CONFIG_SPI_SLAVE_IN_IRAM CONFIG_SPI_MASTER_IN_IRAM Place transmitting functions of SPI master into IRAM Found in: Component config > Driver configurations > SPI configuration Normally only the ISR of SPI master is placed in the IRAM, so that it can work without the flash when interrupt is triggered. For other functions, 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. Espressif Systems 1041 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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: Espressif Systems 1042 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · No (disabled) Temperature sensor Configuration Contains: · CONFIG_TEMP_SENSOR_ENABLE_DEBUG_LOG · CONFIG_TEMP_SENSOR_SUPPRESS_DEPRECATE_WARN CONFIG_TEMP_SENSOR_SUPPRESS_DEPRECATE_WARN Suppress legacy driver deprecated warning Found in: Component config > Driver configurations > Temperature sensor Configuration Wether to suppress the deprecation warnings when using legacy temperature sensor driver (driver/temp_sensor.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) CONFIG_TEMP_SENSOR_ENABLE_DEBUG_LOG Enable debug log Found in: Component config > Driver configurations > Temperature sensor Configuration Wether to enable the debug log message for temperature sensor driver. Note that, this option only controls the temperature sensor driver log, wonnt affect other drivers. Default value: · No (disabled) UART configuration Contains: · CONFIG_UART_ISR_IN_IRAM CONFIG_UART_ISR_IN_IRAM Place UART ISR function into IRAM Found in: Component config > Driver configurations > UART configuration If this option is not selected, UART interrupt will be disabled for a long time and may cause data lost when doing spi flash operation. Default value: · No (disabled) GPIO Configuration Contains: · CONFIG_GPIO_CTRL_FUNC_IN_IRAM CONFIG_GPIO_CTRL_FUNC_IN_IRAM Place GPIO control functions into IRAM Found in: Component config > Driver configurations > GPIO Configuration Place GPIO control functions (like intr_disable/set_level) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Default value: · No (disabled) Espressif Systems 1043 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_ENABLE_DEBUG_LOG · 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) CONFIG_GPTIMER_ISR_IRAM_SAFE GPTimer ISR IRAM-Safe Found in: Component config > Driver configurations > GPTimer Configuration Ensure the GPTimer interrupt is IRAM-Safe by allowing the interrupt handler to be executable when the cache is disabled (e.g. SPI Flash write). Default value: · No (disabled) Espressif Systems 1044 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN Suppress legacy 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) CONFIG_GPTIMER_ENABLE_DEBUG_LOG Enable debug log Found in: Component config > Driver configurations > GPTimer Configuration Wether to enable the debug log message for GPTimer driver. Note that, this option only controls the GPTimer driver log, wonnt affect other drivers. Default value: · No (disabled) PCNT Configuration Contains: · CONFIG_PCNT_ENABLE_DEBUG_LOG · CONFIG_PCNT_ISR_IRAM_SAFE · CONFIG_PCNT_CTRL_FUNC_IN_IRAM · CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN CONFIG_PCNT_CTRL_FUNC_IN_IRAM Place PCNT control functions into IRAM Found in: Component config > Driver configurations > PCNT Configuration Place PCNT 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) CONFIG_PCNT_ISR_IRAM_SAFE PCNT ISR IRAM-Safe Found in: Component config > Driver configurations > PCNT Configuration Ensure the PCNT interrupt is IRAM-Safe by allowing the interrupt handler to be executable when the cache is disabled (e.g. SPI Flash write). Default value: · No (disabled) CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN Suppress legacy driver deprecated warning Found in: Component config > Driver configurations > PCNT Configuration Espressif Systems 1045 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Wether to suppress the deprecation warnings when using legacy PCNT driver (driver/pcnt.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) CONFIG_PCNT_ENABLE_DEBUG_LOG Enable debug log Found in: Component config > Driver configurations > PCNT Configuration Wether to enable the debug log message for PCNT driver. Note that, this option only controls the PCNT driver log, wonnt affect other drivers. 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: · No (disabled) Espressif Systems 1046 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_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_CLIENT_SESSION_TICKETS Enable client session tickets Found in: Component config > ESP-TLS Enable session ticket support as specified in RFC5077. Espressif Systems 1047 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. CONFIG_ESP_TLS_SERVER_SESSION_TICKETS Enable server session tickets Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER Enable session ticket support as specified in RFC5077 CONFIG_ESP_TLS_SERVER_SESSION_TICKET_TIMEOUT Server session ticket timeout in seconds Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER > 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_SERVER_MIN_AUTH_MODE_OPTIONAL ESP-TLS Server: Set minimum Certificate Verification mode to Optional Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER When this option is enabled, the peer (here, the client) certificate is checked by the server, however the handshake continues even if verification failed. By default, the peer certificate is not checked and ignored by the server. mbedtls_ssl_get_verify_result() can be called after the handshake is complete to retrieve status of verification. 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. 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 1048 Release v5.0-dev-2349-g4350e6fef8 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. ESP32S3-Specific Contains: · Cache config · CONFIG_ESP32S3_DEFAULT_CPU_FREQ_MHZ · CONFIG_ESP32S3_DEEP_SLEEP_WAKEUP_DELAY · 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. 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) Espressif Systems 1049 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) · 32KB (ESP32S3_DATA_CACHE_32KB) · 64KB (ESP32S3_DATA_CACHE_64KB) Espressif Systems 1050 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · Quad Mode PSRAM (SPIRAM_MODE_QUAD) · Octal Mode PSRAM (SPIRAM_MODE_OCT) Espressif Systems 1051 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 1052 Release v5.0-dev-2349-g4350e6fef8 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 1053 Release v5.0-dev-2349-g4350e6fef8 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 1054 Release v5.0-dev-2349-g4350e6fef8 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_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. Espressif Systems 1055 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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_SYSTIMER) · RTC (ESP32S3_TIME_SYSCALL_USE_RTC) · High-resolution timer (ESP32S3_TIME_SYSCALL_USE_SYSTIMER) · 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. 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) Espressif Systems 1056 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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). Espressif Systems 1057 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1058 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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 Espressif Systems 1059 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Event Loop Library Contains: · CONFIG_ESP_EVENT_LOOP_PROFILING · CONFIG_ESP_EVENT_POST_FROM_ISR CONFIG_ESP_EVENT_LOOP_PROFILING Enable event loop profiling Found in: Component config > Event Loop Library Enables collections of statistics in the event loop library such as the number of events posted to/recieved by an event loop, number of callbacks involved, number of events dropped to to a full event loop queue, run time of event handlers, and number of times/run time of each event handler. Default value: · No (disabled) CONFIG_ESP_EVENT_POST_FROM_ISR Support posting events from ISRs Found in: Component config > Event Loop Library Enable posting events from interrupt handlers. Default value: · Yes (enabled) CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR Support posting events from ISRs placed in IRAM Found in: Component config > Event Loop Library > CONFIG_ESP_EVENT_POST_FROM_ISR Enable posting events from interrupt handlers placed in IRAM. Enabling this option places API functions esp_event_post and esp_event_post_to in IRAM. Default value: · Yes (enabled) GDB Stub Contains: · CONFIG_ESP_GDBSTUB_SUPPORT_TASKS CONFIG_ESP_GDBSTUB_SUPPORT_TASKS Enable listing FreeRTOS tasks through GDB Stub Found in: Component config > GDB Stub If enabled, GDBStub can supply the list of FreeRTOS tasks to GDB. Thread list can be queried from GDB using 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 Espressif Systems 1060 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 1061 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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_ESP_HTTPS_OTA_ALLOW_HTTP · CONFIG_ESP_HTTPS_OTA_DECRYPT_CB Espressif Systems 1062 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_ESP_HTTPS_OTA_DECRYPT_CB Provide decryption callback Found in: Component config > ESP HTTPS OTA Exposes an additional callback whereby firmware data could be decrypted before being processed by OTA update component. This can help to integrate external encryption related format and removal of such encapsulation layer from firmware image. Default value: · No (disabled) CONFIG_ESP_HTTPS_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 · Peripheral Control · RTC Clock Config · Sleep Config 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 Espressif Systems 1063 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1064 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) Peripheral Control Contains: · CONFIG_PERIPH_CTRL_FUNC_IN_IRAM CONFIG_PERIPH_CTRL_FUNC_IN_IRAM Place peripheral control functions into IRAM Found in: Component config > Hardware Settings > Peripheral Control Place peripheral control functions (e.g. periph_module_reset) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Default value: · No (disabled) LCD and Touch Panel Contains: · LCD Peripheral Configuration LCD Peripheral Configuration Contains: · CONFIG_LCD_ENABLE_DEBUG_LOG · CONFIG_LCD_PANEL_IO_FORMAT_BUF_SIZE · CONFIG_LCD_RGB_ISR_IRAM_SAFE Espressif Systems 1065 Release v5.0-dev-2349-g4350e6fef8 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 CONFIG_LCD_ENABLE_DEBUG_LOG Enable debug log Found in: Component config > LCD and Touch Panel > LCD Peripheral Configuration Wether to enable the debug log message for LCD driver. Note that, this option only controls the LCD driver log, wonnt affect other drivers. Default value: · No (disabled) CONFIG_LCD_RGB_ISR_IRAM_SAFE RGB LCD ISR IRAM-Safe Found in: Component config > LCD and Touch Panel > LCD Peripheral Configuration Ensure the LCD interrupt is IRAM-Safe by allowing the interrupt handler to be executable when the cache is disabled (e.g. SPI Flash write). If you want the LCD driver to keep flushing the screen even when cache ops disabled, you can enable this option. Note, this will also increase the IRAM usage. Default value: · No (disabled) ESP NETIF Adapter Contains: · 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 Espressif Systems 1066 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_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 Espressif Systems 1067 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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. Espressif Systems 1068 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1069 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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. 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 Espressif Systems 1070 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1071 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · Yes (enabled) ESP System Settings Contains: · CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES · Brownout Detector · 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 · CONFIG_ESP_DEBUG_OCDAWARE · 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 Espressif Systems 1072 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES Bootstrap cycles for external 32kHz crystal Found in: Component config > ESP System Settings 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. Espressif Systems 1073 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1074 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1075 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1076 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 1077 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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: Espressif Systems 1078 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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: Espressif Systems 1079 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ·oCOMPILER_OPTIMIZATION_LEVEL_DEBUGpif ESP32_TRAX && ESP32S2_TRAX && CONFIG_ESP32S3_TRAX CONFIG_ESP_DEBUG_OCDAWARE Make exception and panic handlers JTAG/OCD aware Found in: Component config > ESP System Settings The FreeRTOS panic and unhandled exception handers can detect a JTAG OCD debugger and instead of panicking, have the debugger stop on the offending instruction. Default value: · Yes (enabled) CONFIG_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. Brownout Detector Contains: · CONFIG_ESP_BROWNOUT_DET CONFIG_ESP_BROWNOUT_DET Hardware brownout detect & reset Found in: Component config > ESP System Settings > Brownout Detector 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_ESP_BROWNOUT_DET_LVL_SEL Brownout voltage level Found in: Component config > ESP System Settings > Brownout Detector > CONFIG_ESP_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 (ESP_BROWNOUT_DET_LVL_SEL_7) · 2.56V (ESP_BROWNOUT_DET_LVL_SEL_6) · 2.67V (ESP_BROWNOUT_DET_LVL_SEL_5) · 2.84V (ESP_BROWNOUT_DET_LVL_SEL_4) · 2.98V (ESP_BROWNOUT_DET_LVL_SEL_3) Espressif Systems 1080 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 3.19V (ESP_BROWNOUT_DET_LVL_SEL_2) · 3.30V (ESP_BROWNOUT_DET_LVL_SEL_1) IPC (Inter-Processor Call) Contains: · CONFIG_ESP_IPC_TASK_STACK_SIZE · CONFIG_ESP_IPC_USES_CALLERS_PRIORITY CONFIG_ESP_IPC_TASK_STACK_SIZE Inter-Processor Call (IPC) task stack size Found in: Component config > IPC (Inter-Processor Call) Configure the IPC tasks stack size. An IPC task runs on each core (in dual core mode), and allows for cross-core function calls. See IPC documentation for more details. The default IPC stack size should be enough for most common simple use cases. However, users can increase/decrease the stack size to their needs. Range: · from 512 to 65536 Default value: · 1024 CONFIG_ESP_IPC_USES_CALLERS_PRIORITY IPC runs at 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_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) Espressif Systems 1081 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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) Wi-Fi Contains: · CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE · CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN · CONFIG_ESP32_WIFI_CACHE_TX_BUFFER_NUM · CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM · CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM · CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM · CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM · CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE · CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE · CONFIG_ESP32_WIFI_TX_BUFFER · CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED · CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED · CONFIG_ESP32_WIFI_AMSDU_TX_ENABLED · CONFIG_ESP32_WIFI_CSI_ENABLED · CONFIG_ESP_WIFI_FTM_ENABLE Espressif Systems 1082 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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: Espressif Systems 1083 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. Range: · from 16 to 128 if ESP32_SPIRAM_SUPPORT || ESP32S2_SPIRAM_SUPPORT || CONFIG_ESP32S3_SPIRAM_SUPPORT Default value: Espressif Systems 1084 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 1085 Release v5.0-dev-2349-g4350e6fef8 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 1086 Release v5.0-dev-2349-g4350e6fef8 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 1087 Release v5.0-dev-2349-g4350e6fef8 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 1088 Release v5.0-dev-2349-g4350e6fef8 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 1089 Release v5.0-dev-2349-g4350e6fef8 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 1090 Release v5.0-dev-2349-g4350e6fef8 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_CHOOSE_TYPE · 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_SECTOR_SIZE · CONFIG_FATFS_SECTORS_PER_CLUSTER · 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 Espressif Systems 1091 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_FATFS_SECTOR_SIZE Sector size Found in: Component config > FAT Filesystem support Specify the size of the sector in bytes for FATFS partition generator. Available options: · 512 (FATFS_SECTOR_512) · 1024 (FATFS_SECTOR_1024) · 2048 (FATFS_SECTOR_2048) · 4096 (FATFS_SECTOR_4096) CONFIG_FATFS_SECTORS_PER_CLUSTER Sectors per cluster Found in: Component config > FAT Filesystem support This value specifies how many sectors there are in one cluster. Available options: · 1 (FATFS_SECTORS_PER_CLUSTER_1) · 2 (FATFS_SECTORS_PER_CLUSTER_2) · 4 (FATFS_SECTORS_PER_CLUSTER_4) · 8 (FATFS_SECTORS_PER_CLUSTER_8) · 16 (FATFS_SECTORS_PER_CLUSTER_16) · 32 (FATFS_SECTORS_PER_CLUSTER_32) · 64 (FATFS_SECTORS_PER_CLUSTER_64) · 128 (FATFS_SECTORS_PER_CLUSTER_128) CONFIG_FATFS_CHOOSE_CODEPAGE OEM Code Page Found in: Component config > FAT Filesystem support OEM code page used for file name encodings. 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) Espressif Systems 1092 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · Simplified Chinese (DBCS) (CP936) (FATFS_CODEPAGE_936) · Korean (DBCS) (CP949) (FATFS_CODEPAGE_949) · Traditional Chinese (DBCS) (CP950) (FATFS_CODEPAGE_950) CONFIG_FATFS_CHOOSE_TYPE FAT type Found in: Component config > FAT Filesystem support If user specifies automatic detection of the FAT type, the FATFS generator will determine the type by the size. Available options: · Select a suitable FATFS type automatically. (FATFS_AUTO_TYPE) · FAT12 (FATFS_FAT12) · FAT16 (FATFS_FAT16) 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 (Currently not supported by FATFS partition generator). 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. 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) Espressif Systems 1093 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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: Espressif Systems 1094 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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) Espressif Systems 1095 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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) Espressif Systems 1096 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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. Espressif Systems 1097 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1098 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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: Espressif Systems 1099 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 1100 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS · CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH · CONFIG_FREERTOS_UNICORE · CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK · CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY · CONFIG_FREERTOS_CHECK_PORT_CRITICAL_COMPLIANCE · CONFIG_FREERTOS_HZ · CONFIG_FREERTOS_USE_TICKLESS_IDLE · CONFIG_FREERTOS_USE_IDLE_HOOK · CONFIG_FREERTOS_USE_TICK_HOOK · 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 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 Espressif Systems 1101 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1102 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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 Espressif Systems 1103 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · from 1536 to 32768 Default value: · 2096 if ESP_COREDUMP_DATA_FORMAT_ELF · 1536 CONFIG_FREERTOS_USE_IDLE_HOOK Use FreeRTOS idle hook Found in: Component config > FreeRTOS · If enabled, configUSE_IDLE_HOOK will be defined as 1 in FreeRTOS. · The application must provide the hook function void vApplicationIdleHook( void ); · vApplicationIdleHook() is called from FreeRTOS idle task(s) · The FreeRTOS idle hook is NOT the same as the ESP-IDF Idle Hook, but both can be enabled simultaneously. Default value: · No (disabled) CONFIG_FREERTOS_USE_TICK_HOOK Use FreeRTOS tick hook Found in: Component config > FreeRTOS · If enabled, configUSE_TICK_HOOK will be defined as 1 in FreeRTOS. · The application must provide the hook function void vApplicationTickHook( void ); · vApplicationTickHook() is called from FreeRTOSns tick handling function xTaskIn- crementTick() · The FreeRTOS tick hook is NOT the same as the ESP-IDF Tick Interrupt Hook, but both can be enabled simultaneously. 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_BACKWARD_COMPATIBILITY Support legacy FreeRTOS API Found in: Component config > FreeRTOS This option enables the configENABLE_BACKWARD_COMPATIBILITY option, thus allowing the usage of legacy function names and types present in versions prior to FreeRTOS v8.0.0. Default value: Espressif Systems 1104 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · No (disabled) 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: · 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: Espressif Systems 1105 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 1106 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1107 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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: Espressif Systems 1108 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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) Espressif Systems 1109 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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. Espressif Systems 1110 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 chipns RTC and high resoultion 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) Espressif Systems 1111 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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 Espressif Systems 1112 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · TCP · CONFIG_LWIP_TCPIP_TASK_AFFINITY · CONFIG_LWIP_TCPIP_TASK_STACK_SIZE · CONFIG_LWIP_TCPIP_RECVMBOX_SIZE · UDP · CONFIG_LWIP_IPV6_RDNSS_MAX_DNS_SERVERS CONFIG_LWIP_LOCAL_HOSTNAME Local netif hostname Found in: Component config > LWIP The default name this device will report to other devices on the network. Could be updated at runtime with esp_netif_set_hostname() Default value: ·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) Espressif Systems 1113 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 1114 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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) Espressif Systems 1115 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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) Espressif Systems 1116 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 1117 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 1118 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference DHCP server Contains: · CONFIG_LWIP_DHCPS CONFIG_LWIP_DHCPS DHCPS: Enable IPv4 Dynamic Host Configuration Protocol Server (DHCPS) Found in: Component config > LWIP > DHCP server Enabling this option allows the device to run the DHCP server (to dynamically assign IPv4 addresses to clients). Default value: · Yes (enabled) CONFIG_LWIP_DHCPS_LEASE_UNIT Multiplier for lease time, in seconds Found in: Component config > LWIP > DHCP server > CONFIG_LWIP_DHCPS The DHCP server is calculating lease time multiplying the sent and received times by this number of seconds per unit. The default is 60, that equals one minute. Range: · from 1 to 3600 Default value: · 60 CONFIG_LWIP_DHCPS_MAX_STATION_NUM Maximum number of stations Found in: Component config > LWIP > DHCP server > CONFIG_LWIP_DHCPS The maximum number of DHCP clients that are connected to the server. After this number is exceeded, DHCP server removes of the oldest device from 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 Espressif Systems 1119 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1120 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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) Espressif Systems 1121 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1122 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1123 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1124 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1125 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1126 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1127 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1128 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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 Espressif Systems 1129 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1130 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1131 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference LWIP RAW API Contains: · CONFIG_LWIP_MAX_RAW_PCBS CONFIG_LWIP_MAX_RAW_PCBS Maximum LWIP RAW PCBs Found in: Component config > LWIP > LWIP RAW API The maximum number of simultaneously active LWIP RAW protocol control blocks. The practical maximum limit is determined by available heap memory at runtime. Range: · from 1 to 1024 Default value: · 16 SNTP Contains: · CONFIG_LWIP_SNTP_MAX_SERVERS · CONFIG_LWIP_SNTP_UPDATE_DELAY · CONFIG_LWIP_DHCP_GET_NTP_SRV CONFIG_LWIP_SNTP_MAX_SERVERS Maximum number of NTP servers Found in: Component config > LWIP > SNTP Set maximum number of NTP servers used by LwIP SNTP module. 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 Espressif Systems 1132 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1133 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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: Espressif Systems 1134 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · CONFIG_LWIP_API_LIB_DEBUG · CONFIG_LWIP_DHCP_DEBUG · CONFIG_LWIP_DHCP_STATE_DEBUG · CONFIG_LWIP_ETHARP_DEBUG · CONFIG_LWIP_ICMP_DEBUG · CONFIG_LWIP_ICMP6_DEBUG · CONFIG_LWIP_IP_DEBUG · CONFIG_LWIP_IP6_DEBUG · CONFIG_LWIP_NETIF_DEBUG · CONFIG_LWIP_PBUF_DEBUG · CONFIG_LWIP_SNTP_DEBUG · CONFIG_LWIP_SOCKETS_DEBUG · CONFIG_LWIP_TCP_DEBUG CONFIG_LWIP_NETIF_DEBUG Enable netif debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG CONFIG_LWIP_PBUF_DEBUG Enable pbuf debug messages 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 Espressif Systems 1135 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_LWIP_IP_DEBUG Enable IP debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG 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 Espressif Systems 1136 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_LWIP_SNTP_DEBUG Enable SNTP debug messages Found in: Component config > LWIP > CONFIG_LWIP_DEBUG Default value: · No (disabled) if CONFIG_LWIP_DEBUG 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_HARDWARE_ECC · 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_LARGE_KEY_SOFTWARE_MPI · CONFIG_MBEDTLS_HKDF_C · mbedTLS v3.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_2 · CONFIG_MBEDTLS_SSL_RENEGOTIATION · Symmetric Ciphers · TLS Key Exchange Methods Espressif Systems 1137 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN · CONFIG_MBEDTLS_TLS_MODE · CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS · CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS · CONFIG_MBEDTLS_ROM_MD5 · CONFIG_MBEDTLS_DYNAMIC_BUFFER CONFIG_MBEDTLS_MEM_ALLOC_MODE 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 Espressif Systems 1138 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN Asymmetric in/out fragment length Found in: Component config > mbedTLS 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_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. Espressif Systems 1139 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 v3.x related Contains: · DTLS-based configurations · CONFIG_MBEDTLS_SSL_CONTEXT_SERIALIZATION · CONFIG_MBEDTLS_X509_TRUSTED_CERT_CALLBACK · CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE · CONFIG_MBEDTLS_SSL_PROTO_TLS1_3 · CONFIG_MBEDTLS_ECDH_LEGACY_CONTEXT · CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH Espressif Systems 1140 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_MBEDTLS_SSL_PROTO_TLS1_3 Support TLS 1.3 protocol Found in: Component config > mbedTLS > mbedTLS v3.x related Default value: · No (disabled) if CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE && CONFIG_MBEDTLS_DYNAMIC_BUFFER CONFIG_MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE Enable TLS 1.3 middlebox compatibility mode Found in: Component config > mbedTLS > mbedTLS v3.x related > CONFIG_MBEDTLS_SSL_PROTO_TLS1_3 Default value: · Yes (enabled) if CONFIG_MBEDTLS_SSL_PROTO_TLS1_3 CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH Variable SSL buffer length Found in: Component config > mbedTLS > mbedTLS v3.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 v3.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: · No (disabled) 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 v3.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 v3.x related Enable serialization of the TLS context structures This is a local optimization in handling a single, potentially long-lived connection. Espressif Systems 1141 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 v3.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. Default value: · Yes (enabled) if 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 v3.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 v3.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 v3.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: Espressif Systems 1142 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 v3.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: · 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 v3.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) Espressif Systems 1143 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) 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_CERTIFICATE_BUNDLE_MAX_CERTS Maximum no of certificates allowed in certificate bundle Found in: Component config > mbedTLS > Certificate Bundle > CON- FIG_MBEDTLS_CERTIFICATE_BUNDLE Default value: · 200 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) Espressif Systems 1144 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) CONFIG_MBEDTLS_HARDWARE_GCM Enable partially hardware accelerated GCM Found in: Component config > mbedTLS > CONFIG_MBEDTLS_HARDWARE_AES Enable partially hardware accelerated GCM. GHASH calculation is still done in software. If MBEDTLS_HARDWARE_GCM is disabled and MBEDTLS_HARDWARE_AES is enabled then mbedTLS will still use the hardware accelerated AES block operation, but on a single block at a time. Default value: · Yes (enabled) if SOC_AES_SUPPORT_GCM && CONFIG_MBEDTLS_HARDWARE_AES 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. Espressif Systems 1145 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_HARDWARE_ECC Enable hardware ECC acceleration Found in: Component config > mbedTLS Enable hardware accelerated ECC point multiplication and point verification for points on curve SECP192R1 and SECP256R1 in mbedTLS Default value: · Yes (enabled) if SOC_ECC_SUPPORTED CONFIG_MBEDTLS_ECC_OTHER_CURVES_SOFT_FALLBACK Fallback to software implementation for curves not supported in hardware Found in: Component config > mbedTLS > CONFIG_MBEDTLS_HARDWARE_ECC Fallback to software implementation of ECC point multiplication and point verification for curves not supported in hardware. Default value: · Yes (enabled) if CONFIG_MBEDTLS_HARDWARE_ECC 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 This option enables hardware acceleration for ECDSA sign function, only when using ATECC608A cryptoauth chip (integrated with ESP32-WROOM-32SE) Espressif Systems 1146 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_PLATFORM_TIME_ALT Enable mbedtls time support: platform-specific Found in: Component config > mbedTLS > CONFIG_MBEDTLS_HAVE_TIME Enabling this config will provide users with a function ombedtls_platform_set_time()pthat allows to set an alternative time function pointer. Default value: · No (disabled) 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 Espressif Systems 1147 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference certificates expire while the device is offline and a TLS connection is required to update. Or if an issue with the SNTP server means that the system time is invalid for an extended period after a reset. Default value: · No (disabled) CONFIG_MBEDTLS_ECDSA_DETERMINISTIC Enable deterministic ECDSA 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: Espressif Systems 1148 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · No (disabled) 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) Espressif Systems 1149 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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-WITHDefault 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) Espressif Systems 1150 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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-WITH- Default value: · Yes (enabled) 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_TLS1_2 Support TLS 1.2 protocol Found in: Component config > mbedTLS Default value: · Yes (enabled) 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.2 to be enabled for DTLS 1.2 Default value: Espressif Systems 1151 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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_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) Espressif Systems 1152 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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) Espressif Systems 1153 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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) Espressif Systems 1154 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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: Espressif Systems 1155 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) 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) Espressif Systems 1156 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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- Espressif Systems 1157 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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- 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) Espressif Systems 1158 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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: Espressif Systems 1159 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) 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_INTERFACES · CONFIG_MDNS_MAX_SERVICES · CONFIG_MDNS_SERVICE_ADD_TIMEOUT_MS · MDNS Predefined interfaces · 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 Espressif Systems 1160 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_MDNS_MAX_INTERFACES Max number of interfaces Found in: Component config > mDNS Number of network interfaces to be served by the mDNS library. Lowering this number helps to reduce some static RAM usage. Range: · from 1 to 9 Default value: ·3 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: · 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) Espressif Systems 1161 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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. Espressif Systems 1162 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Default value: · Yes (enabled) MDNS Predefined interfaces Contains: · CONFIG_MDNS_PREDEF_NETIF_ETH · CONFIG_MDNS_PREDEF_NETIF_AP · CONFIG_MDNS_PREDEF_NETIF_STA CONFIG_MDNS_PREDEF_NETIF_STA Use predefined interface for WiFi Station Found in: Component config > mDNS > MDNS Predefined interfaces Set up mDNS for the default WiFi station. Disable this option if you do not need mDNS on default WiFi STA. Default value: · Yes (enabled) CONFIG_MDNS_PREDEF_NETIF_AP Use predefined interface for WiFi Access Point Found in: Component config > mDNS > MDNS Predefined interfaces Set up mDNS for the default WiFi Access Point. Disable this option if you do not need mDNS on default WiFi AP. Default value: · Yes (enabled) CONFIG_MDNS_PREDEF_NETIF_ETH Use predefined interface for Ethernet Found in: Component config > mDNS > MDNS Predefined interfaces Set up mDNS for the default Ethernet interface. Disable this option if you do not need mDNS on default Ethernet. 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 Espressif Systems 1163 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 1164 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 1165 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1166 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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) Espressif Systems 1167 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 1168 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 1169 Release v5.0-dev-2349-g4350e6fef8 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 1170 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1171 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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: Espressif Systems 1172 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) 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: Espressif Systems 1173 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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: Espressif Systems 1174 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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: Espressif Systems 1175 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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: · 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) Espressif Systems 1176 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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) Espressif Systems 1177 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1178 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1179 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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: Espressif Systems 1180 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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) Espressif Systems 1181 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) TCP Transport Contains: · Websocket Websocket Contains: · CONFIG_WS_TRANSPORT Espressif Systems 1182 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1183 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1184 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1185 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1186 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1187 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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) Espressif Systems 1188 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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) Espressif Systems 1189 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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. Espressif Systems 1190 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1191 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Host File System I/O (Semihosting) Contains: · CONFIG_VFS_SEMIHOSTFS_MAX_MOUNT_POINTS · CONFIG_VFS_SEMIHOSTFS_HOST_PATH_MAX_LEN CONFIG_VFS_SEMIHOSTFS_MAX_MOUNT_POINTS Host FS: Maximum number of the host filesystem mount points Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO > Host File System I/O (Semihosting) Define maximum number of host filesystem mount points. Default value: ·1 CONFIG_VFS_SEMIHOSTFS_HOST_PATH_MAX_LEN Host FS: Maximum path length for the host base directory Found in: Component config > Virtual file system > CONFIG_VFS_SUPPORT_IO > Host File System I/O (Semihosting) Define maximum path length for the host base directory which is to be mounted. If host path passed to esp_vfs_semihost_register() is longer than this value it will be truncated. Default value: · 128 Wear Levelling Contains: · CONFIG_WL_SECTOR_MODE · CONFIG_WL_SECTOR_SIZE CONFIG_WL_SECTOR_SIZE Wear Levelling library sector size Found in: Component config > Wear Levelling Sector size used by wear levelling library. You can set default sector size or size that will fit to the flash device sector size. With sector size set to 4096 bytes, wear levelling library is more efficient. However if FAT filesystem is used on top of wear levelling library, it will need more temporary storage: 4096 bytes for each mounted filesystem and 4096 bytes for each opened file. With sector size set to 512 bytes, wear levelling library will perform more operations with flash memory, but less RAM will be used by FAT filesystem library (512 bytes for the filesystem and 512 bytes for each file opened). Available options: · 512 (WL_SECTOR_SIZE_512) · 4096 (WL_SECTOR_SIZE_4096) CONFIG_WL_SECTOR_MODE Sector store mode Found in: Component config > Wear Levelling Specify the mode to store data into flash: Espressif Systems 1192 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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_BLE_SEC_CONN · CONFIG_WIFI_PROV_BLE_FORCE_ENCRYPTION · CONFIG_WIFI_PROV_SCAN_MAX_ENTRIES · CONFIG_WIFI_PROV_AUTOSTOP_TIMEOUT CONFIG_WIFI_PROV_SCAN_MAX_ENTRIES Max Wi-Fi Scan Result Entries Found in: Component config > Wi-Fi Provisioning Manager This sets the maximum number of entries of Wi-Fi scan results that will be kept by the provisioning manager Range: · from 1 to 255 Default value: · 16 CONFIG_WIFI_PROV_AUTOSTOP_TIMEOUT Provisioning auto-stop timeout 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: · Yes (enabled) if CONFIG_BT_ENABLED Espressif Systems 1193 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_WIFI_PROV_BLE_SEC_CONN Enable BLE Secure connection flag Found in: Component config > Wi-Fi Provisioning Manager Used to enable Secure connection support when provisioning transport is BLE. Default value: · Yes (enabled) if BT_NIMBLE_ENABLED CONFIG_WIFI_PROV_BLE_FORCE_ENCRYPTION Force Link Encryption during characteristic Read / Write Found in: Component config > Wi-Fi Provisioning Manager Used to enforce link encryption when attempting to read / write characteristic Default value: · Yes (enabled) if BT_NIMBLE_ENABLED Supplicant Contains: · CONFIG_WPA_TESTING_OPTIONS · CONFIG_WPA_11KV_SUPPORT · CONFIG_WPA_DPP_SUPPORT · CONFIG_WPA_MBO_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 1194 Release v5.0-dev-2349-g4350e6fef8 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 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) 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. Espressif Systems 1195 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Default value: · No (disabled) if CONFIG_WPA_11KV_SUPPORT CONFIG_WPA_MBO_SUPPORT Enable MBO support Found in: Component config > Supplicant Select this option to enable WiFi Multiband operation certification support. Default value: · No (disabled) CONFIG_WPA_DPP_SUPPORT Enable DPP support Found in: Component config > Supplicant Select this option to enable WiFi Easy Connect Support. Default value: · No (disabled) 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 Espressif Systems 1196 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_AVDT_TRACE_LEVEL_API CONFIG_AVDT_TRACE_LEVEL_EVENT CONFIG_AVDT_TRACE_LEVEL_DEBUG CONFIG_AVDT_TRACE_LEVEL_VERBOSE · CONFIG_AVRC_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_AVRC_TRACE_LEVEL) CONFIG_AVRC_TRACE_LEVEL_NONE CONFIG_AVRC_TRACE_LEVEL_ERROR CONFIG_AVRC_TRACE_LEVEL_WARNING CONFIG_AVRC_TRACE_LEVEL_API CONFIG_AVRC_TRACE_LEVEL_EVENT CONFIG_AVRC_TRACE_LEVEL_DEBUG CONFIG_AVRC_TRACE_LEVEL_VERBOSE · CONFIG_BLE_ACTIVE_SCAN_REPORT_ADV_SCAN_RSP_INDIVIDUALLY (CON- FIG_BT_BLE_ACT_SCAN_REP_ADV_SCAN ) · CONFIG_BLE_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_BROWNOUT_DET (CONFIG_ESP_BROWNOUT_DET) · CONFIG_BROWNOUT_DET_LVL_SEL (CONFIG_ESP_BROWNOUT_DET_LVL_SEL) CONFIG_BROWNOUT_DET_LVL_SEL_7 CONFIG_BROWNOUT_DET_LVL_SEL_6 CONFIG_BROWNOUT_DET_LVL_SEL_5 CONFIG_BROWNOUT_DET_LVL_SEL_4 CONFIG_BROWNOUT_DET_LVL_SEL_3 CONFIG_BROWNOUT_DET_LVL_SEL_2 CONFIG_BROWNOUT_DET_LVL_SEL_1 · 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 Espressif Systems 1197 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CONFIG_SDP_TRACE_LEVEL_VERBOSE · CONFIG_BTIF_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BTIF_TRACE_LEVEL) CONFIG_BTIF_TRACE_LEVEL_NONE CONFIG_BTIF_TRACE_LEVEL_ERROR CONFIG_BTIF_TRACE_LEVEL_WARNING CONFIG_BTIF_TRACE_LEVEL_API CONFIG_BTIF_TRACE_LEVEL_EVENT CONFIG_BTIF_TRACE_LEVEL_DEBUG CONFIG_BTIF_TRACE_LEVEL_VERBOSE · CONFIG_BTM_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_BTM_TRACE_LEVEL) CONFIG_BTM_TRACE_LEVEL_NONE CONFIG_BTM_TRACE_LEVEL_ERROR CONFIG_BTM_TRACE_LEVEL_WARNING CONFIG_BTM_TRACE_LEVEL_API CONFIG_BTM_TRACE_LEVEL_EVENT CONFIG_BTM_TRACE_LEVEL_DEBUG CONFIG_BTM_TRACE_LEVEL_VERBOSE · CONFIG_BTU_TASK_STACK_SIZE (CONFIG_BT_BTU_TASK_STACK_SIZE) · CONFIG_BT_NIMBLE_MSYS1_BLOCK_COUNT (CONFIG_BT_NIMBLE_MSYS_1_BLOCK_COUNT) · CONFIG_BT_NIMBLE_TASK_STACK_SIZE (CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE) · CONFIG_CONSOLE_UART (CONFIG_ESP_CONSOLE_UART) CONFIG_CONSOLE_UART_DEFAULT CONFIG_CONSOLE_UART_CUSTOM CONFIG_CONSOLE_UART_NONE, 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_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_PHY_CALIBRATION_AND_DATA_STORAGE (CON- FIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE) · CONFIG_ESP32_PHY_DEFAULT_INIT_IF_INVALID (CONFIG_ESP_PHY_DEFAULT_INIT_IF_INVALID) · CONFIG_ESP32_PHY_INIT_DATA_ERROR (CONFIG_ESP_PHY_INIT_DATA_ERROR) · CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION (CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION) · CONFIG_ESP32_PHY_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 Espressif Systems 1198 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1199 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) · 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- Espressif Systems 1200 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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_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_HOST_TASK_STACK_SIZE) · CONFIG_NO_BLOBS (CONFIG_APP_NO_BLOBS) · 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_OPTIMIZATION_LEVEL_DEBUG, CONFIG_COMPILER_OPTIMIZATION_LEVEL_DEBUG CONFIG_OPTIMIZATION_LEVEL_RELEASE, CONFIG_COMPILER_OPTIMIZATION_LEVEL_RELEASE · CONFIG_OSI_INITIAL_TRACE_LEVEL (CONFIG_BT_LOG_OSI_TRACE_LEVEL) CONFIG_OSI_TRACE_LEVEL_NONE CONFIG_OSI_TRACE_LEVEL_ERROR CONFIG_OSI_TRACE_LEVEL_WARNING CONFIG_OSI_TRACE_LEVEL_API CONFIG_OSI_TRACE_LEVEL_EVENT CONFIG_OSI_TRACE_LEVEL_DEBUG CONFIG_OSI_TRACE_LEVEL_VERBOSE · CONFIG_OTA_ALLOW_HTTP (CONFIG_ESP_HTTPS_OTA_ALLOW_HTTP) · 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 Espressif Systems 1201 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) · 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) Espressif Systems 1202 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) · 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) Espressif Systems 1203 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.8 Provisioning API 2.8.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 */ protocomm_t *start_pc(const char *pop_string) { protocomm_t *pc = protocomm_new(); /* Config for protocomm_httpd_start() */ protocomm_httpd_config_t pc_config = { (continues on next page) Espressif Systems 1204 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference .data = { .config = PROTOCOMM_HTTPD_DEFAULT_CONFIG() } }; (continued from previous page) /* Start protocomm server on top of HTTP */ protocomm_httpd_start(pc, &pc_config); /* Create Proof of Possession object from pop_string. It must be valid * throughout the scope of protocomm endpoint. This need not be static, * ie. could be dynamically allocated and freed at the time of endpoint * removal */ const static protocomm_security_pop_t pop_obj = { .data = (const uint8_t *) strdup(pop_string), .len = strlen(pop_string) }; /* Set security for communication at application level. Just like for * request handlers, setting security creates an endpoint and registers * the handler provided by protocomm_security1. One can similarly use * protocomm_security0. Only one type of security can be set for a * protocomm instance at a time. */ protocomm_set_security(pc, "security_endpoint", &protocomm_security1, &pop_obj); /* Private data passed to the endpoint must be valid throughout the scope * of protocomm endpoint. This need not be static, ie. could be dynamically * allocated and freed at the time of endpoint removal */ static uint32_t priv_data = 1234; /* Add a new endpoint for the protocomm instance, identified by a unique name * and register a handler function along with private data to be passed at the * time of handler execution. Multiple endpoints can be added as long as they * are identified by unique names */ protocomm_add_endpoint(pc, "echo_req_endpoint", echo_req_handler, (void *) &priv_data); return pc; } /* Example function for stopping a protocomm instance */ void stop_pc(protocomm_t *pc) { /* Remove endpoint identified by it's unique name */ protocomm_remove_endpoint(pc, "echo_req_endpoint"); /* Remove security endpoint identified by it's name */ protocomm_unset_security(pc, "security_endpoint"); /* Stop HTTP server */ protocomm_httpd_stop(pc); /* Delete (deallocate) the protocomm instance */ protocomm_delete(pc); (continues on next page) Espressif Systems 1205 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) } 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); } API Reference Header File · components/protocomm/include/common/protocomm.h Espressif Systems 1206 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1207 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 protocomm_security0 and protocomm_security1 are readily available. 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 Espressif Systems 1208 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · [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. 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 Espressif Systems 1209 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1210 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 Public Members void *handle HTTP Server Handle, if ext_handle_provided is set to true Espressif Systems 1211 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1212 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 1213 Release v5.0-dev-2349-g4350e6fef8 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.8.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 1214 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Espressif Systems Fig. 26: Typical Provisioning Process 1215 Release v5.0-dev-2349-g4350e6fef8 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 1216 Release v5.0-dev-2349-g4350e6fef8 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.8.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 1217 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Espressif Systems Fig. 28: Security1 1218 Release v5.0-dev-2349-g4350e6fef8 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 1219 Release v5.0-dev-2349-g4350e6fef8 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 1220 Release v5.0-dev-2349-g4350e6fef8 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 1221 Release v5.0-dev-2349-g4350e6fef8 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 1222 Release v5.0-dev-2349-g4350e6fef8 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 1223 Release v5.0-dev-2349-g4350e6fef8 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 1224 Release v5.0-dev-2349-g4350e6fef8 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 1225 Release v5.0-dev-2349-g4350e6fef8 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 1226 Release v5.0-dev-2349-g4350e6fef8 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_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 Espressif Systems 1227 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Parameters · [out] state: Pointer to wifi_prov_sta_state_t variable to be filled esp_err_t wifi_prov_mgr_get_wifi_disconnect_reason(wifi_prov_sta_fail_reason_t *reason) Get reason code in case of Wi-Fi station disconnection during provisioning. Return · ESP_OK : Successfully retrieved Wi-Fi disconnect reason · ESP_FAIL : Provisioning app not running Parameters · [out] reason: Pointer to wifi_prov_sta_fail_reason_t variable to be filled esp_err_t wifi_prov_mgr_configure_sta(wifi_config_t *wifi_cfg) Runs Wi-Fi as Station with the supplied configuration. Configures the Wi-Fi station mode to connect to the AP with SSID and password specified in config structure and sets Wi-Fi to run as station. This is automatically called by provisioning service upon receiving new credentials. If credentials are to be supplied to the manager via a different mode other than through protocomm, then this API needs to be called. Event WIFI_PROV_CRED_RECV is emitted after credentials have been applied and Wi-Fi station started Return · ESP_OK : Wi-Fi configured and started successfully · ESP_FAIL : Failed to set configuration Parameters · [in] wifi_cfg: Pointer to Wi-Fi configuration structure esp_err_t wifi_prov_mgr_reset_provisioning(void) Reset Wi-Fi provisioning config. Calling this API will restore WiFi stack persistent settings to default values. Return · ESP_OK : Reset provisioning config successfully · ESP_FAIL : Failed to reset provisioning config esp_err_t wifi_prov_mgr_reset_sm_state_on_failure(void) Reset internal state machine and clear provisioned credentials. This API can be used to restart provisioning in case invalid credentials are entered. Return · ESP_OK : Reset provisioning state machine successfully · ESP_FAIL : Failed to reset provisioning state machine · ESP_ERR_INVALID_STATE : Manager not initialized Structures struct wifi_prov_event_handler_t Event handler that is used by the manager while provisioning service is active. Public Members wifi_prov_cb_func_t event_cb Callback function to be executed on provisioning events void *user_data User context data to pass as parameter to callback function struct wifi_prov_scheme Structure for specifying the provisioning scheme to be followed by the manager. Espressif Systems 1228 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · wifi_prov_scheme_softap : for provisioning over SoftAP transport + HTTP server + mDNS (op- tional) · 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. Espressif Systems 1229 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1230 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 1231 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1232 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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: Espressif Systems 1233 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.9 Storage API 2.9.1 FAT Filesystem Support ESP-IDF uses the FatFs library to work with FAT filesystems. FatFs resides in the fatfs component. Although the library can be used directly, many of its features can be accessed via VFS, using the C standard library and POSIX API functions. Additionally, FatFs has been modified to support the runtime pluggable disk I/O layer. This allows mapping of FatFs drives to physical disks at runtime. Using FatFs with VFS The header file fatfs/vfs/esp_vfs_fat.h defines the functions for connecting FatFs and VFS. The function esp_vfs_fat_register() allocates a FATFS structure and registers a given path prefix in VFS. Subsequent operations on files starting with this prefix are forwarded to FatFs APIs. The function esp_vfs_fat_unregister_path() deletes the registration with VFS, and frees the FATFS structure. Most applications use the following workflow when working with esp_vfs_fat_ functions: 1. Call esp_vfs_fat_register() to specify: · Path prefix where to mount the filesystem (e.g. "/sdcard", "/spiflash") · FatFs drive number · A variable which will receive the pointer to the FATFS structure 2. Call ff_diskio_register() to register the disk I/O driver for the drive number used in Step 1. 3. Call the FatFs function f_mount, and optionally f_fdisk, f_mkfs, to mount the filesystem using the same drive number which was passed to esp_vfs_fat_register(). For more information, see FatFs documentation. 4. Call the C standard library and POSIX API functions to perform such actions on files as open, read, write, erase, copy, etc. Use paths starting with the path prefix passed to esp_vfs_register() (for example, "/sdcard/hello.txt"). The filesystem uses 8.3 filenames format (SFN) by default. If you need to use long filenames (LFN), enable the CONFIG_FATFS_LONG_FILENAMES option. More details on the FatFs filenames are available here. 5. Optionally, by enabling the option CONFIG_FATFS_USE_FASTSEEK, use the POSIX lseek function to perform it faster, the fast seek will not work for files in write mode, so to take advantage of fast seek, you should open (or close and then reopen) the file in read-only mode. 6. Optionally, call the FatFs library functions directly. In this case, use paths without a VFS prefix (for example, "/hello.txt"). 7. Close all open files. Espressif Systems 1234 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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: Espressif Systems 1235 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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_sdmmc_unmount(void) Unmount FAT filesystem and release resources acquired using esp_vfs_fat_sdmmc_mount. Return · ESP_OK on success · ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount hasnnt been called 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. · 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 Espressif Systems 1236 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 1237 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1238 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. The latest version supports both short and long file names, FAT12 and FAT16. The long file names are limited to 255 characters, and can contain multiple period (o.p) characters within the filename and additional characterso+p , o,p, o;p, o=p, o[pand also o]p. The long files name characters are encoded using utf-16, on the contrary to short file names encoded using utf-8. 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: 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. Espressif Systems 1239 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.9.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. Workflow Espressif Systems 1240 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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: Espressif Systems 1241 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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) Espressif Systems 1242 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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 Espressif Systems 1243 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.9.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) 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. Espressif Systems 1244 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1245 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1246 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (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. 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. Espressif Systems 1247 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. +-----------+--------------+-------------+-------------------------+ | State (4) | Seq. no. (4) | version (1) | Unused (19) | CRC32 (4) | +-----------+--------------+-------------+-------------------------+ | Entry state bitmap (32) | +------------------------------------------------------------------+ | Entry 0 (32) | +------------------------------------------------------------------+ Header (32) (continues on next page) Espressif Systems 1248 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) | Entry 1 (32) | +------------------------------------------------------------------+ / / / / +------------------------------------------------------------------+ | Entry 125 (32) | +------------------------------------------------------------------+ Page header and entry state bitmap are always written to flash unencrypted. Entries are encrypted if flash encryption feature of ESP32-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 -| ----------+-------+ | ChunkStart(1) | Rsv(2)| Data format ---+ ----------+-------+ | | Primitive +------------------------------ +--------> | Data (8) | Types +------------------------------ | +---------+--------------+----- +--------> | Size(4) | ChunkCount(1)| Blob Index +---------+--------------+----- +----------+---------+-----------+ (continues on next page) Espressif Systems 1249 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference +-> Variable length --> (Strings, Blob Data) (continued from previous page) | Size (2) | Rsv (2) | CRC32 (4) | +----------+---------+-----------+ 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 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. Espressif Systems 1250 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · one of the error codes from the underlying flash storage driver Parameters · [in] partition: pointer to a partition obtained by the ESP partition API. Espressif Systems 1251 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. This API initialises the default NVS partition. The default NVS partition is the one that is labeled onvspin the partition table. Espressif Systems 1252 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Public Members uint8_t eky[NVS_KEY_SIZE] XTS encryption and decryption key Espressif Systems 1253 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1254 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · 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 Espressif Systems 1255 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 1256 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · [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 Espressif Systems 1257 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1258 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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); ... 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; } Espressif Systems 1259 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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. Espressif Systems 1260 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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[NVS_KEY_NAME_MAX_SIZE] 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 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 Espressif Systems 1261 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) 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 Espressif Systems 1262 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference typedef struct nvs_opaque_iterator_t *nvs_iterator_t Opaque pointer type representing iterator to nvs entries Enumerations enum nvs_open_mode_t Mode of opening the non-volatile storage. Values: NVS_READONLY Read only NVS_READWRITE Read and write enum nvs_type_t Types of variables. Values: NVS_TYPE_U8 = 0x01 Type uint8_t NVS_TYPE_I8 = 0x11 Type int8_t NVS_TYPE_U16 = 0x02 Type uint16_t NVS_TYPE_I16 = 0x12 Type int16_t NVS_TYPE_U32 = 0x04 Type uint32_t NVS_TYPE_I32 = 0x14 Type int32_t NVS_TYPE_U64 = 0x08 Type uint64_t NVS_TYPE_I64 = 0x18 Type int64_t NVS_TYPE_STR = 0x21 Type string NVS_TYPE_BLOB = 0x42 Type blob NVS_TYPE_ANY = 0xff Must be last 2.9.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. Espressif Systems 1263 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Prerequisites To use this utility in encryption mode, install the following packages: · cryptography package All the required packages are included in requirements.txt in the root of the esp-idf directory. CSV file format Each line of a .csv file should contain 4 parameters, separated by a comma. The table below provides the description for each of these parameters. No. Pa- Description Notes ram- e- ter 1 Key Key of the data. The data can be accessed later from an appli- cation using this key. 2 Type Supported values are file, data and namespace. 3 En- Supported values are: u8, i8, u16, i16, u32, i32, u64, As of now, for the file cod- i64, string, hex2bin, base64 and binary. This type, only hex2bin, base64, ing specifies how actual data values are encoded in the resulting bi- string, and binary encoding nary file. The difference between the string and binary is supported. encoding is that string data is terminated with a NULL character, whereas binary data is not. 4 Value Data value. Encoding and Value cells for the namespace field type should be empty. Encoding and Value of namespace is fixed and is not configurable. Any values in these cells are ignored. Note: The first line of the CSV file should be the column header and it is not configurable. Comments (if provided) are allowed only as the first line of the CSV file, the following line then should always be the column header. Comments should always start with the # symbol. Below is an example dump of such a CSV file: key,type,encoding,value <-- column header namespace_name,namespace,, <-- First entry should be of type "namespace" key1,data,u8,1 key2,file,string,/path/to/file Note: Make sure there are no spaces: · before and after 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. Espressif Systems 1264 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 | +-----+--------------+------------------------------------------------------------- -------+ | 2 | generate-key | Generate keys for encryption | +-----+--------------+------------------------------------------------------------- -------+ | 3 | encrypt | Generate NVS encrypted partition | +-----+--------------+------------------------------------------------------------- -------+ (continues on next page) Espressif Systems 1265 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) | 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 | | | | +-----------------+------------------------------------------------------- -------------+ | --outdir OUTDIR | Output directory to store files created | | | (Default: current directory) | +-----------------+------------------------------------------------------- -------------+ Espressif Systems 1266 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: +--------------+---------------------------------------------------------- ------------+ | Parameter | Description | +==============+======================================================================+ | input | Path to CSV file to parse | +--------------+---------------------------------------------------------- ------------+ | output | Path to output NVS binary file | +--------------+---------------------------------------------------------- ------------+ (continues on next page) Espressif Systems 1267 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) | 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: · 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: Espressif Systems 1268 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 | +---------------------+--------------------------------------------------- -----------------+ | --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: Espressif Systems 1269 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.9.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: · 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. Espressif Systems 1270 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1271 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 1272 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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_erase_sectors(sdmmc_card_t *card, size_t start_sector, size_t sector_count, sdmmc_erase_arg_t arg) Erase given number of sectors from the SD/MMC card Note When sdmmc_erase_sectors used with cards in SDSPI mode, it was observed that card requires re-init after erase operation. 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 · start_sector: sector where to start erase · sector_count: number of sectors to erase · arg: erase command (CMD38) argument esp_err_t sdmmc_can_discard(sdmmc_card_t *card) Check if SD/MMC card supports discard Return · ESP_OK if supported by the card/device · ESP_FAIL if not supported by the card/device Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init esp_err_t sdmmc_can_trim(sdmmc_card_t *card) Check if SD/MMC card supports trim Return · ESP_OK if supported by the card/device · ESP_FAIL if not supported by the card/device Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init esp_err_t sdmmc_mmc_can_sanitize(sdmmc_card_t *card) Check if SD/MMC card supports sanitize Return · ESP_OK if supported by the card/device · ESP_FAIL if not supported by the card/device Parameters · card: pointer to card information structure previously initialized using sdmmc_card_init esp_err_t sdmmc_mmc_sanitize(sdmmc_card_t *card, uint32_t timeout_ms) Sanitize the data that was unmapped by a Discard command Espressif Systems 1273 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note Discard command has to precede sanitize operation. To discard, use MMC_DICARD_ARG with sdmmc_erase_sectors argument 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 · timeout_ms: timeout value in milliseconds required to sanitize the selected range of sectors. esp_err_t sdmmc_full_erase(sdmmc_card_t *card) Erase complete 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 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) 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 Espressif Systems 1274 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 1275 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 1276 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 Note: When new member is added, update reserved bits accordingly Public Members uint32_t sd_spec : 4 SD Physical layer specification version, reported by card uint32_t erase_mem_state : 1 data state on card after erase whether 0 or 1 (card vendor dependent) uint32_t bus_width : 4 bus widths supported by card: BIT(0) i1-bit bus, BIT(2) i4-bit bus uint32_t reserved : 23 reserved for future expansion uint32_t rsvd_mnf reserved for manufacturer usage Espressif Systems 1277 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct sdmmc_ssr_t Decoded values from SD Status Register Note: When new member is added, update reserved bits accordingly Public Members uint32_t cur_bus_width : 2 SD current bus width uint32_t discard_support : 1 SD discard feature support uint32_t fule_support : 1 SD FULE (Full User Area Logical Erase) feature support uint32_t reserved : 28 reserved for future expansion struct sdmmc_ext_csd_t Decoded values of Extended Card Specific Data Public Members uint8_t rev Extended CSD Revision uint8_t power_class Power class used by the card uint8_t erase_mem_state data state on card after erase whether 0 or 1 (card vendor dependent) uint8_t sec_feature secure data management features supported 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 Espressif Systems 1278 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference size_t blklen block length int flags see below esp_err_t error error returned from transfer uint32_t timeout_ms response timeout, in milliseconds struct sdmmc_host_t SD/MMC Host description This structure defines properties of SD/MMC host and functions of SD/MMC host which can be used by upper layers. Public Members uint32_t flags flags defining host properties int slot slot number, to be passed to host functions int max_freq_khz max frequency supported by the host float io_voltage I/O voltage used by the controller (voltage switching is not supported) esp_err_t (*init)(void) Host function to initialize the driver esp_err_t (*set_bus_width)(int slot, size_t width) host function to set bus width size_t (*get_bus_width)(int slot) host function to get bus width esp_err_t (*set_bus_ddr_mode)(int slot, bool ddr_enable) host function to set DDR mode esp_err_t (*set_card_clk)(int slot, uint32_t freq_khz) host function to set card clock frequency esp_err_t (*do_transaction)(int slot, sdmmc_command_t *cmdinfo) host function to do a transaction esp_err_t (*deinit)(void) host function to deinitialize the driver esp_err_t (*deinit_p)(int slot) host function to deinitialize the driver, called with the slot esp_err_t (*io_int_enable)(int slot) Host function to enable SDIO interrupt line esp_err_t (*io_int_wait)(int slot, TickType_t timeout_ticks) Host function to wait for SDIO interrupt line to be active int command_timeout_ms timeout, in milliseconds, of a single command. Set to 0 to use the default value. struct sdmmc_card_t SD/MMC card information structure Espressif Systems 1279 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members sdmmc_host_t host Host with which the card is associated uint32_t ocr OCR (Operation Conditions Register) value sdmmc_cid_t cid decoded CID (Card IDentification) register value sdmmc_response_t raw_cid raw CID of MMC card to be decoded after the CSD is fetched in the data transfer mode sdmmc_csd_t csd decoded CSD (Card-Specific Data) register value sdmmc_scr_t scr decoded SCR (SD card Configuration Register) value sdmmc_ssr_t ssr decoded SSR (SD Status 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 Espressif Systems 1280 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SDMMC_HOST_FLAG_DEINIT_ARG host deinit function called with the slot argument SDMMC_FREQ_DEFAULT SD/MMC Default speed (limited by clock divider) SDMMC_FREQ_HIGHSPEED SD High speed (limited by clock divider) SDMMC_FREQ_PROBING SD/MMC probing speed SDMMC_FREQ_52M MMC 52MHz speed SDMMC_FREQ_26M MMC 26MHz speed Type Definitions typedef uint32_t sdmmc_response_t[4] SD/MMC command response buffer Enumerations enum sdmmc_erase_arg_t SD/MMC erase command(38) arguments SD: ERASE: Erase the write blocks, physical/hard erase. DISCARD: Card may deallocate the discarded blocks partially or completely. After discard operation the previously written data may be partially or fully read by the host depending on card implementation. MMC: ERASE: Does TRIM, applies erase operation to write blocks instead of Erase Group. DISCARD: The Discard function allows the host to identify data that is no longer required so that the device can erase the data if necessary during background erase events. Applies to write blocks instead of Erase Group After discard operation, the original data may be remained partially or fully accessible to the host dependent on device. Values: SDMMC_ERASE_ARG = 0 Erase operation on SD, Trim operation on MMC SDMMC_DISCARD_ARG = 1 Discard operation for SD/MMC 2.9.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 Espressif Systems 1281 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 Quad/Dual mode 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 Optional Features Optional features for flash Some features are not supported on all ESP chips and Flash chips. You can check the list below for more information. · Auto Suspend & Resume · Flash unique ID · High performance mode · OPI flash support · 32-bit Address Flash Chips Note: · The features listed above needs to be supported by both esp chips and flash chips. · If you are using an official Espressif modules/SiP. Some of the modules/SiPs always support the feature, in this case you can see these features listed in the datasheet. Otherwise please contact Espressifns business team to know if we can supply such products for you. · If you are making your own modules with your own bought flash chips, and you need features listed above. Please contact your vendor if they support the those features, and make sure that the chips can be supplied continuously. Espressif Systems 1282 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Attention: This document only shows that IDF code has supported the features of those flash chips. Itns not a list of stable flash chips certified by Espressif. If you build your own hardware from flash chips with your own brought flash chips (even with flash listed in this page), you need to validate the reliability of flash chips yourself. Auto Suspend & Resume ESP Chips List: 1. ESP32C3 Flash Chips List: 1. XM25QxxC series. Flash unique ID Unique ID is not flash id, which means flash has 64-Bit unique ID for each device. The instruction to read the unique ID (4Bh) accesses a factory-set read-only 64-bit number that is unique to each flash device. This ID number helps you to recognize each single device. Not all flash vendors support this feature. If you try to read the unique ID on a chip which does not have this feature, the behavior is not determined. The support list is as follows. ESP Chips Lists: ALL Flash Chips List: 1. ISSI 2. GD 3. TH 4. FM 5. Winbond 6. XMC 7. BOYA High performance mode Note: This section is provided for Dual mode (DOUT/DIO) and Quad mode (QIO/QOUT) flash chips. Octal flash used on ESP-chips support High performance mode by default so far, you can refer to the octal flash support list below. High performance mode (HPM) means that the SPI1 and flash chip works under high frequency. Usually, when the operating frequency of the flash is greater than 80MHz, it is considered that the flash works under HPM. As far as we acknowledged, flash chips have more than two different coping strategies when flash work under HPM. For some flash chips, HPM is controlled by high performance flag (HPF) in status register and for some flash chips, HPM is controlled by dummy cycle bit. For following conditionsIDF start code deals with HPM internally. ESP Chips List: 1. ESP32S3 Flash Chips (name & ID) List: 1. GD25Q64C (ID: 0xC84017) 2. GD25Q32C (ID: 0xC84016) Attention: It is hard to create several strategies to cover all situations, so all flash chips using HPM need to be supported explicitly. Therefore, if you try to use a flash not listed as supported under high performance mode, it might cause some error. So, when you try to use the flash chip beyond supported list, please test properly. Espressif Systems 1283 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference OPI flash support OPI flash means that the flash chip supports octal peripheral interface, which has octal I/O pins. Different octal flash has different configurations and different commands. Hence, it is necessary to carefully check the support list. Note: 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 ESP Chips List: 1. ESP32S3 Flash Chips List: 1. MX25UM25645G 32-bit Address Flash Chips Most NOR flash chips used by Espressif chips use 24-bits address, which can cover 16 MBytes memory. However, for larger memory (usually equal to or larger than 16 MBytes), flash uses a 32-bits address to address larger memory. Regretfully, 32-bits address chips have vendor-specific commands, so we need to support the chips one by one. ESP Chips List: ALL ESP Chips support this. Flash Chips List: 1. W25Q256 2. GD25Q256 There are some features that are not supported by all flash models, or not supported by all Espressif chips. These features include: · OPI flash - means that flash supports octal mode. · 32-bit address flash - usually means that the flash has higher capacity (equal to or larger than 16MB) that needs longer address to access. · High performance mode (HPM) - means that flash works under high frequency which is higher than 80MHz. · Flash unique ID - means that flash supports its unique 64-bits ID. If you want to use these features, you need to ensure ESP32-S3 supports this feature, and ALL the flash chips in your product have this feature. For more details, refer Optional features for flash. 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. Espressif Systems 1284 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 caps_flags |= SPI_FLAHS_CHIP_CAP_SUSPEND; // flash read unique id. caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID; return caps_flags; } const spi_flash_chip_t esp_flash_chip_eon = { // Other function pointers .get_chip_caps = spi_flash_chip_eon_get_caps, }; · You also can see how to implement this in the example storage/custom_flash_driver. 4. Add linking dependency from spi_flash component to the new custom_chip_driver component, by adding the following lines after the idf_component_register, in the CMakeLists.txt file of the custom_chip_driver compo- nent: idf_component_get_property(spi_flash_lib spi_flash COMPONENT_LIB) set_property(TARGET ${spi_flash_lib} APPEND PROPERTY INTER- FACE_LINK_LIBRARIES $<LINK_ONLY:${COMPONENT_LIB}>) 5. The linker.lf is used to put every chip driver that you are going to use whilst cache is disabled into internal RAM. See Linker Script Generation for more details. Make sure this file covers all the source files that you add. 6. Build your project, and you will see the new flash driver is used. Example See also storage/custom_flash_driver. Espressif Systems 1285 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · spi_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. 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. Espressif Systems 1286 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1287 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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, provide support of some OS functions (e.g. lock, delay) in different stages (1st/2nd 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. Espressif Systems 1288 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1289 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Implementation Details In order to perform some flash operations, it is necessary to make sure that both CPUs are not running any code from flash for the duration of the flash operation: - In a single-core setup, the SDK does it by disabling interrupts/scheduler before performing the flash operation. - In a dual-core setup, this is slightly more complicated as the SDK needs to make sure that the other CPU is not running any code from flash. When SPI flash API is called on CPU A (can be PRO or APP), start the spi_flash_op_block_func function on CPU B using the esp_ipc_call API. This API wakes up a high priority task on CPU B and tells it to execute a given function, in this case, spi_flash_op_block_func. This function disables cache on CPU B and signals that the cache is disabled by setting the s_flash_op_can_start flag. Then the task on CPU A disables cache as well and proceeds to execute flash operation. While a flash operation is running, interrupts can still run on CPUs A and B. It is assumed that all interrupt code is placed into RAM. Once the interrupt allocation API is added, a flag should be added to request the interrupt to be disabled for the duration of a flash operations. Once the flash operation is complete, the function on CPU A sets another flag, s_flash_op_complete, to let the task on CPU B know that it can re-enable cache and release the CPU. Then the function on CPU A re-enables the cache on CPU A as well and returns control to the calling code. Additionally, all API functions are protected with a mutex (s_flash_op_mutex). In a single core environment (CONFIG_FREERTOS_UNICORE enabled), you need to disable both caches, so that no inter-CPU communication can take place. API Reference - SPI Flash Header File · components/spi_flash/include/esp_flash_spi_init.h Functions esp_err_t spi_bus_add_flash_device(esp_flash_t **out_chip, 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. Espressif Systems 1290 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1291 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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). Espressif Systems 1292 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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() · 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. Espressif Systems 1293 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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, en- crypted write is not supported. · address: Address on flash to write to. 16 byte aligned. Must be previously erased (SPI NOR flash can only write bits 1->0). · buffer: Pointer to a buffer with the data to write. · length: Length (in bytes) of data to write. 16 byte aligned. esp_err_t esp_flash_read_encrypted(esp_flash_t *chip, uint32_t address, void *out_buffer, uint32_t length) Read and decrypt data from the SPI flash chip using on-chip hardware flash encryption. Return · ESP_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. Espressif Systems 1294 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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). 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. Espressif Systems 1295 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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/spi_flash/include/esp_spi_flash.h Functions esp_err_t spi_flash_wrap_set(spi_flash_wrap_mode_t mode) set wrap mode of flash Return esp_err_t : ESP_OK for successful. Parameters · mode: wrap mode support disable, 16 32, 64 byte void spi_flash_init(void) Initialize SPI flash access driver. This function must be called exactly once, before any other spi_flash_* functions are called. Currently this function is called from startup code. There is no need to call it from application code. size_t spi_flash_get_chip_size(void) Get flash chip size, as set in binary image header. Espressif Systems 1296 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note This value does not necessarily match real flash size. Return size of flash chip, in bytes esp_err_t spi_flash_erase_sector(size_t sector) Erase the Flash sector. Return esp_err_t Parameters · sector: Sector number, the count starts at sector 0, 4KB per sector. esp_err_t spi_flash_erase_range(size_t start_address, size_t size) Erase a range of flash sectors. Return esp_err_t Parameters · start_address: Address where erase operation has to start. Must be 4kB-aligned · size: Size of erased range, in bytes. Must be divisible by 4kB. esp_err_t spi_flash_write(size_t dest_addr, const void *src, size_t size) Write data to Flash. Note For fastest write performance, write a 4 byte aligned size at a 4 byte aligned offset in flash from a source buffer in DRAM. Varying any of these parameters will still work, but will be slower due to buffering. Note Writing more than 8KB at a time will be split into multiple write operations to avoid disrupting other tasks in the system. Return esp_err_t Parameters · dest_addr: Destination address in Flash. · src: Pointer to the source buffer. · size: Length of data, in bytes. esp_err_t spi_flash_write_encrypted(size_t dest_addr, const void *src, size_t size) Write data encrypted to Flash. Note Flash encryption must be enabled for this function to work. Note Flash encryption must be enabled when calling this function. If flash encryption is disabled, the func- tion returns ESP_ERR_INVALID_STATE. Use esp_flash_encryption_enabled() function to determine if flash encryption is enabled. Note Both dest_addr and size must be multiples of 16 bytes. For absolute best performance, both dest_addr and size arguments should be multiples of 32 bytes. Return esp_err_t Parameters · dest_addr: Destination address in Flash. Must be a multiple of 16 bytes. · src: Pointer to the source buffer. · size: Length of data, in bytes. Must be a multiple of 16 bytes. esp_err_t spi_flash_read(size_t src_addr, void *dest, size_t size) Read data from Flash. Note For fastest read performance, all parameters should be 4 byte aligned. If source address and read size are not 4 byte aligned, read may be split into multiple flash operations. If destination buffer is not 4 byte aligned, a temporary buffer will be allocated on the stack. Note Reading more than 16KB of data at a time will be split into multiple reads to avoid disruption to other tasks in the system. Consider using spi_flash_mmap() to read large amounts of data. Return esp_err_t Parameters · src_addr: source address of the data in Flash. · dest: pointer to the destination buffer · size: length of data esp_err_t spi_flash_read_encrypted(size_t src, void *dest, size_t size) Read data from Encrypted Flash. Espressif Systems 1297 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference If flash encryption is enabled, this function will transparently decrypt data as it is read. If flash encryption is not enabled, this function behaves the same as spi_flash_read(). See esp_flash_encryption_enabled() for a function to check if flash encryption is enabled. Return esp_err_t Parameters · src: source address of the data in Flash. · dest: pointer to the destination buffer · size: length of data esp_err_t spi_flash_mmap(size_t src_addr, size_t size, spi_flash_mmap_memory_t memory, const void **out_ptr, spi_flash_mmap_handle_t *out_handle) Map region of flash memory into data or instruction address space. This function allocates sufficient number of 64kB MMU pages and configures them to map the requested region of flash memory into the address space. It may reuse MMU pages which already provide the required mapping. As with any allocator, if mmap/munmap are heavily used then the address space may become fragmented. To troubleshoot issues with page allocation, use spi_flash_mmap_dump() function. Return ESP_OK on success, ESP_ERR_NO_MEM if pages can not be allocated Parameters · src_addr: Physical address in flash where requested region starts. This address must be aligned to 64kB boundary (SPI_FLASH_MMU_PAGE_SIZE) · size: Size of region to be mapped. This size will be rounded up to a 64kB boundary · memory: Address space where the region should be mapped (data or instruction) · [out] out_ptr: Output, pointer to the mapped memory region · [out] out_handle: Output, handle which should be used for spi_flash_munmap call esp_err_t spi_flash_mmap_pages(const int *pages, size_t page_count, spi_flash_mmap_memory_t memory, const void **out_ptr, spi_flash_mmap_handle_t *out_handle) Map sequences of pages of flash memory into data or instruction address space. This function allocates sufficient number of 64kB MMU pages and configures them to map the indicated pages of flash memory contiguously into address space. In this respect, it works in a similar way as spi_flash_mmap() but it allows mapping a (maybe non-contiguous) set of pages into a contiguous region of memory. Return · ESP_OK on success · ESP_ERR_NO_MEM if pages can not be allocated · ESP_ERR_INVALID_ARG if pagecount is zero or pages array is not in internal memory Parameters · pages: An array of numbers indicating the 64kB pages in flash to be mapped contiguously into memory. These indicate the indexes of the 64kB pages, not the byte-size addresses as used in other functions. Array must be located in internal memory. · page_count: Number of entries in the pages array · memory: Address space where the region should be mapped (instruction or data) · [out] out_ptr: Output, pointer to the mapped memory region · [out] out_handle: Output, handle which should be used for spi_flash_munmap call void spi_flash_munmap(spi_flash_mmap_handle_t handle) Release region previously obtained using spi_flash_mmap. Note Calling this function will not necessarily unmap memory region. Region will only be unmapped when there are no other handles which reference this region. In case of partially overlapping regions it is possible that memory will be unmapped partially. Parameters · handle: Handle obtained from spi_flash_mmap void spi_flash_mmap_dump(void) Display information about mapped regions. Espressif Systems 1298 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference This function lists handles obtained using spi_flash_mmap, along with range of pages allocated to each handle. It also lists all non-zero entries of MMU table and corresponding reference counts. uint32_t spi_flash_mmap_get_free_pages(spi_flash_mmap_memory_t memory) get free pages number which can be mmap This function will return number of free pages available in mmu table. This could be useful before calling actual spi_flash_mmap (maps flash range to DCache or ICache memory) to check if there is sufficient space available for mapping. Return number of free pages which can be mmaped Parameters · memory: memory type of MMU table free page size_t spi_flash_cache2phys(const void *cached) Given a memory address where flash is mapped, return the corresponding physical flash offset. Cache address does not have have been assigned via spi_flash_mmap(), any address in memory mapped flash space can be looked up. Return · SPI_FLASH_CACHE2PHYS_FAIL If cache address is outside flash cache region, or the address is not mapped. · Otherwise, returns physical offset in flash Parameters · cached: Pointer to flashed cached memory. const void *spi_flash_phys2cache(size_t phys_offs, spi_flash_mmap_memory_t memory) Given a physical offset in flash, return the address where it is mapped in the memory space. Physical address does not have to have been assigned via spi_flash_mmap(), any address in flash can be looked up. Note Only the first matching cache address is returned. If MMU flash cache table is configured so multiple entries point to the same physical address, there may be more than one cache address corresponding to that physical address. It is also possible for a single physical address to be mapped to both the IROM and DROM regions. Note This function doesnnt impose any alignment constraints, but if memory argument is SPI_FLASH_MMAP_INST and phys_offs is not 4-byte aligned, then reading from the returned pointer will result in a crash. Return · NULL if the physical address is invalid or not mapped to flash cache of the specified memory type. · Cached memory address (in IROM or DROM space) corresponding to phys_offs. Parameters · phys_offs: Physical offset in flash memory to look up. · memory: Address space type to look up a flash cache address mapping for (instruction or data) bool spi_flash_cache_enabled(void) Check at runtime if flash cache is enabled on both CPUs. Return true if both CPUs have flash cache enabled, false otherwise. void spi_flash_enable_cache(uint32_t cpuid) Re-enable cache for the core defined as cpuid parameter. Parameters · cpuid: the core number to enable instruction cache for void spi_flash_guard_set(const spi_flash_guard_funcs_t *funcs) Sets guard functions to access flash. Note Pointed structure and corresponding guard functions should not reside in flash. For example structure can be placed in DRAM and functions in IRAM sections. Parameters · funcs: pointer to structure holding flash access guard functions. Espressif Systems 1299 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference const spi_flash_guard_funcs_t *spi_flash_guard_get(void) Get the guard functions used for flash access. Return The guard functions that were set via spi_flash_guard_set(). These functions can be called if implementing custom low-level SPI flash operations. Structures struct spi_flash_guard_funcs_t Structure holding SPI flash access critical sections management functions. Flash API uses two types of flash access management functions: 1) Functions which prepare/restore flash cache and interrupts before calling appropriate ROM functions (SPIWrite, SPIRead and SPIEraseBlock): · nstartnfunction should disables flash cache and non-IRAM interrupts and is invoked before the call to one of ROM function above. · nendnfunction should restore state of flash cache and non-IRAM interrupts and is invoked after the call to one of ROM function above. These two functions are not recursive. 2) Functions which synchronizes access to internal data used by flash API. This functions are mostly intended to synchronize access to flash API internal data in multithreaded environment and use OS primitives: · nop_locknlocks access to flash API internal data. · nop_unlocknunlocks access to flash API internal data. These two functions are recursive and can be used around the outside of multiple calls tomstartn&mendn, in order to create atomic multi-part flash operations. 3) When CONFIG_SPI_FLASH_DANGEROUS_WRITE_ALLOWED is disabled, flash writing/erasing API checks for addresses provided by user to avoid corruption of critical flash regions (bootloader, partition table, running application etc.). Different versions of the guarding functions should be used depending on the context of execution (with or without functional OS). In normal conditions when flash API is called from task the functions use OS primitives. When there is no OS at all or when it is not guaranteed that OS is functional (accessing flash from exception handler) these functions cannot use OS primitives or even does not need them (multithreaded access is not possible). Note Structure and corresponding guard functions should not reside in flash. For example structure can be placed in DRAM and functions in IRAM sections. Public Members spi_flash_guard_start_func_t start critical section start function. spi_flash_guard_end_func_t end critical section end function. spi_flash_op_lock_func_t op_lock flash access API lock function. spi_flash_op_unlock_func_t op_unlock flash access API unlock function. spi_flash_is_safe_write_address_t is_safe_write_address checks flash write addresses. spi_flash_os_yield_t yield yield to the OS during flash erase Macros ESP_ERR_FLASH_OP_FAIL ESP_ERR_FLASH_OP_TIMEOUT SPI_FLASH_SEC_SIZE SPI Flash sector size Espressif Systems 1300 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SPI_FLASH_MMU_PAGE_SIZE Flash cache MMU mapping page size SPI_FLASH_CACHE2PHYS_FAIL Type Definitions typedef uint32_t spi_flash_mmap_handle_t Opaque handle for memory region obtained from spi_flash_mmap. typedef void (*spi_flash_guard_start_func_t)(void) SPI flash critical section enter function. typedef void (*spi_flash_guard_end_func_t)(void) SPI flash critical section exit function. typedef void (*spi_flash_op_lock_func_t)(void) SPI flash operation lock function. typedef void (*spi_flash_op_unlock_func_t)(void) SPI flash operation unlock function. typedef bool (*spi_flash_is_safe_write_address_t)(size_t addr, size_t size) Function to protect SPI flash critical regions corruption. typedef void (*spi_flash_os_yield_t)(void) Function to yield to the OS during erase operation. Enumerations enum spi_flash_wrap_mode_t Values: FLASH_WRAP_MODE_8B = 0 FLASH_WRAP_MODE_16B = 2 FLASH_WRAP_MODE_32B = 4 FLASH_WRAP_MODE_64B = 6 FLASH_WRAP_MODE_DISABLE = 1 enum spi_flash_mmap_memory_t Enumeration which specifies memory space requested in an mmap call. Values: SPI_FLASH_MMAP_DATA map to data memory (Vaddr0), allows byte-aligned access, 4 MB total SPI_FLASH_MMAP_INST map to instruction memory (Vaddr1-3), allows only 4-byte-aligned access, 11 MB total 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. Espressif Systems 1301 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t reserved Reserved, must be 0. uint8_t mosi_len Output data length, in bytes. uint8_t miso_len Input data length, in bytes. uint8_t address_bitlen Length of address in bits, set to 0 if command does not need an address. uint32_t address Address to perform operation on. const uint8_t *mosi_data Output data to salve. uint8_t *miso_data [out] Input data from slave, little endian uint32_t flags Flags for this transaction. Set to 0 for now. uint16_t command Command to send. uint8_t dummy_bitlen Basic dummy bits to use. uint32_t io_mode Flash working mode when SPI_FLASH_IGNORE_BASEIO is specified. struct spi_flash_sus_cmd_conf Configuration structure for the flash chip suspend feature. Public Members uint32_t sus_mask SUS/SUS1/SUS2 bit in flash register. uint32_t cmd_rdsr : 8 Read flash status register(2) command. uint32_t sus_cmd : 8 Flash suspend command. uint32_t res_cmd : 8 Flash resume command. 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. Espressif Systems 1302 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1303 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference bool (*supports_direct_write)(spi_flash_host_inst_t *host, const void *p) Check whether given buffer can be directly used to write int (*write_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size) Slicer for write data. The program_page should be called iteratively with the return value of this function. Return Length that can be actually written in one program_page call Parameters · address: Beginning flash address to write · len: Length request to write · align_addr: Output of the aligned address to write to · page_size: Physical page size of the flash chip esp_err_t (*read)(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len) Read data from the flash. Check max_read_bytes for the maximum allowed reading length. bool (*supports_direct_read)(spi_flash_host_inst_t *host, const void *p) Check whether given buffer can be directly used to read int (*read_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size) Slicer for read data. The read should be called iteratively with the return value of this function. Return Length that can be actually read in one read call Parameters · address: Beginning flash address to read · len: Length request to read · align_addr: Output of the aligned address to read · page_size: Physical page size of the flash chip uint32_t (*host_status)(spi_flash_host_inst_t *host) Check the host status, 0:busy, 1:idle, 2:suspended. esp_err_t (*configure_host_io_mode)(spi_flash_host_inst_t *host, uint32_t command, uint32_t addr_bitlen, int dummy_bitlen_base, esp_flash_io_mode_t io_mode) Configure the host to work at different read mode. Responsible to compensate the timing and set IO mode. void (*poll_cmd_done)(spi_flash_host_inst_t *host) Internal use, poll the HW until the last operation is done. esp_err_t (*flush_cache)(spi_flash_host_inst_t *host, uint32_t addr, uint32_t size) For some host (SPI1), they are shared with a cache. When the data is modified, the cache needs to be flushed. Left NULL if not supported. void (*check_suspend)(spi_flash_host_inst_t *host) Suspend check erase/program operation, reserved for ESP32-C3 and ESP32-S3 spi flash ROM IMPL. void (*resume)(spi_flash_host_inst_t *host) Resume flash from suspend manually void (*suspend)(spi_flash_host_inst_t *host) Set flash in suspend status manually esp_err_t (*sus_setup)(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf) Suspend feature setup for setting cmd and status register mask. Macros SPI_FLASH_TRANS_FLAG_CMD16 Send command of 16 bits. SPI_FLASH_TRANS_FLAG_IGNORE_BASEIO Not applying the basic io mode configuration for this transaction. Espressif Systems 1304 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1305 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Header File · components/hal/include/hal/esp_flash_err.h Macros ESP_ERR_FLASH_NOT_INITIALISED esp_flash_chip_t structure not correctly initialised by esp_flash_init(). ESP_ERR_FLASH_UNSUPPORTED_HOST Requested operation isnnt supported via this host SPI bus (chip->spi field). ESP_ERR_FLASH_UNSUPPORTED_CHIP Requested operation isnnt supported by this model of SPI flash chip. ESP_ERR_FLASH_PROTECTED Write operation failed due to chipns write protection being enabled. Enumerations enum [anonymous] Values: ESP_ERR_FLASH_SIZE_NOT_MATCH = ESP_ERR_INVALID_SIZE The chip doesnnt have enough space for the current partition table. ESP_ERR_FLASH_NO_RESPONSE = ESP_ERR_INVALID_RESPONSE Chip did not respond to the command, or timed out. 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. Espressif Systems 1306 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Parameters · type: Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY. · subtype: Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer. To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY. · label: (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise. const esp_partition_t *esp_partition_find_first(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label) Find first partition based on one or more parameters. Return pointer to esp_partition_t structure, or NULL if no partition is found. This pointer is valid for the lifetime of the application. Parameters · type: Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY. · subtype: Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY. · label: (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise. const esp_partition_t *esp_partition_get(esp_partition_iterator_t iterator) Get esp_partition_t structure for given partition. Return pointer to esp_partition_t structure. This pointer is valid for the lifetime of the application. Parameters · iterator: Iterator obtained using esp_partition_find. Must be non-NULL. esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator) Move partition iterator to the next partition found. Any copies of the iterator will be invalid after this call. Return NULL if no partition was found, valid esp_partition_iterator_t otherwise. Parameters · iterator: Iterator obtained using esp_partition_find. Must be non-NULL. void esp_partition_iterator_release(esp_partition_iterator_t iterator) Release partition iterator. Parameters · iterator: Iterator obtained using esp_partition_find. The iterator is allowed to be NULL, so it is not necessary to check its value before calling this function. const esp_partition_t *esp_partition_verify(const esp_partition_t *partition) Verify partition data. Given a pointer to partition data, verify this partition exists in the partition table (all fields match.) This function is also useful to take partition data which may be in a RAM buffer and convert it to a pointer to the permanent partition data stored in flash. Pointers returned from this function can be compared directly to the address of any pointer returned from esp_partition_get(), as a test for equality. Return · If partition not found, returns NULL. · If found, returns a pointer to the esp_partition_t structure in flash. This pointer is always valid for the lifetime of the application. Parameters · partition: Pointer to partition data to verify. Must be non-NULL. All fields of this structure must match the partition table entry in flash for this function to return a successful match. Espressif Systems 1307 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_partition_read(const esp_partition_t *partition, size_t src_offset, void *dst, size_t size) Read data from the partition. Partitions marked with an encryption flag will automatically be be read and decrypted via a cache mapping. Return ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes from lower-level flash driver. Parameters · partition: Pointer to partition structure obtained using esp_partition_find_first or 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. Espressif Systems 1308 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note This function is essentially the same as esp_partition_write() above. It just never encrypts data but writes it as is. Note Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call. Return ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds parti- tion size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; or one of the error codes from lower-level flash driver. Parameters · 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. Espressif Systems 1309 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_ERR_IMAGE_INVALID: App partition doesnnt contain a valid app image. · ESP_FAIL: An allocation error occurred. Parameters · [in] partition: Pointer to info for partition containing app or data. (fields: address, size and type, are required to be filled). · [out] sha_256: Returned SHA-256 digest for a given partition. bool esp_partition_check_identity(const esp_partition_t *partition_1, const esp_partition_t *partition_2) Check for the identity of two partitions by SHA-256 digest. Return · True: In case of the two firmware is equal. · False: Otherwise Parameters · [in] partition_1: Pointer to info for partition 1 containing app or data. (fields: address, size and type, are required to be filled). · [in] partition_2: Pointer to info for partition 2 containing app or data. (fields: address, size and type, are required to be filled). esp_err_t esp_partition_register_external(esp_flash_t *flash_chip, size_t offset, size_t size, const char *label, esp_partition_type_t type, esp_partition_subtype_t subtype, const 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 Espressif Systems 1310 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct esp_partition_t partition information structure This is not the format in flash, that format is esp_partition_info_t. However, this is the format used by this API. Public Members esp_flash_t *flash_chip SPI flash chip on which the partition resides esp_partition_type_t type partition type (app/data) esp_partition_subtype_t subtype partition subtype uint32_t address starting address of the partition in flash uint32_t size size of the partition, in bytes char label[17] partition label, zero-terminated ASCII string bool encrypted flag is set to true if partition is encrypted Macros ESP_PARTITION_SUBTYPE_OTA(i) Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition. Type Definitions typedef struct esp_partition_iterator_opaque_ *esp_partition_iterator_t Opaque partition iterator type. Enumerations enum esp_partition_type_t Partition type. Note Partition types with integer value 0x00-0x3F are reserved for partition types defined by ESP-IDF. Any other integer value 0x40-0xFE can be used by individual applications, without restriction. Values: ESP_PARTITION_TYPE_APP = 0x00 Application partition type. ESP_PARTITION_TYPE_DATA = 0x01 Data partition type. ESP_PARTITION_TYPE_ANY = 0xff Used to search for partitions with any type. enum esp_partition_subtype_t Partition subtype. Application-defined partition types (0x40-0xFE) can set any numeric subtype value. Note These ESP-IDF-defined partition subtypes apply to partitions of type ESP_PARTITION_TYPE_APP and ESP_PARTITION_TYPE_DATA. Espressif Systems 1311 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Values: ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00 Factory application partition. ESP_PARTITION_SUBTYPE_APP_OTA_MIN = 0x10 Base for OTA partition subtypes. ESP_PARTITION_SUBTYPE_APP_OTA_0 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 0 OTA partition 0. 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. Espressif Systems 1312 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_PARTITION_SUBTYPE_DATA_COREDUMP = 0x03 COREDUMP partition. ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS = 0x04 Partition for NVS keys. ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM = 0x05 Partition for emulate eFuse bits. ESP_PARTITION_SUBTYPE_DATA_UNDEFINED = 0x06 Undefined (or unspecified) data partition. ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD = 0x80 ESPHTTPD partition. ESP_PARTITION_SUBTYPE_DATA_FAT = 0x81 FAT partition. ESP_PARTITION_SUBTYPE_DATA_SPIFFS = 0x82 SPIFFS partition. ESP_PARTITION_SUBTYPE_ANY = 0xff Used to search for partitions with any subtype. API Reference - Flash Encrypt Header File · components/bootloader_support/include/esp_flash_encrypt.h Functions 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 Espressif Systems 1313 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return void esp_flash_encryption_init_checks(void) Check the flash encryption mode during startup. Verifies the flash encryption config during startup: Note This function is called automatically during app startup, it 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.9.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. Espressif Systems 1314 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Tools spiffsgen.py spiffsgen.py is a write-only Python SPIFFS implementation used to create filesystem images from the contents of a host folder. To use spiffsgen.py, open Terminal and run: python spiffsgen.py <image_size> <base_dir> <output_file> The required arguments are as follows: · image_size: size of the partition onto which the created SPIFFS image will be flashed. · base_dir: directory for which the SPIFFS image needs to be created. · output_file: SPIFFS image output file. There are also other arguments that control image generation. Documentation on these arguments can be found in the 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) Espressif Systems 1315 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · Image Size: Size of the partition in bytes (can be obtained from a partition table) · Partition Offset: Starting address of the partition (can be obtained from a partition table) To pack a folder into a 1-Megabyte image, run: mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin To flash the image onto ESP32-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 Espressif Systems 1316 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · conf: Pointer to esp_vfs_spiffs_conf_t configuration structure esp_err_t esp_vfs_spiffs_unregister(const char *partition_label) Unregister and unmount SPIFFS from VFS Return · ESP_OK if successful · ESP_ERR_INVALID_STATE already unregistered Parameters · partition_label: Same label as passed to esp_vfs_spiffs_register. bool esp_spiffs_mounted(const char *partition_label) Check if SPIFFS is mounted Return · true if mounted · false if not mounted Parameters · partition_label: Optional, label of the partition to check. If not specified, first partition with subtype=spiffs is used. esp_err_t esp_spiffs_format(const char *partition_label) Format the SPIFFS partition Return · ESP_OK if successful · ESP_FAIL on error Parameters · partition_label: Same label as passed to esp_vfs_spiffs_register. esp_err_t esp_spiffs_info(const char *partition_label, size_t *total_bytes, size_t *used_bytes) Get information for SPIFFS Return · ESP_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. Espressif Systems 1317 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.9.8 Virtual filesystem component Overview Virtual filesystem (VFS) component provides a unified interface for drivers which can perform operations on file-like objects. These can be real filesystems (FAT, SPIFFS, etc.) or device drivers which provide a file-like interface. This component allows C library functions, such as fopen and fprintf, to work with FS drivers. At a high level, each FS driver is associated with some path prefix. When one of C library functions needs to open a file, the VFS component searches for the FS driver associated with the file path and forwards the call to that driver. VFS also forwards read, write, and other calls for the given file to the same FS driver. For example, one can register a FAT filesystem driver with the /fat prefix and call fopen("/fat/file.txt", "w"). The VFS component will then call the function open of the FAT driver and pass the argument /file.txt to it together with appropriate mode flags. All subsequent calls to C library functions for the returned FILE* stream will also be forwarded to the FAT driver. FS registration To register an FS driver, an application needs to define an instance of the esp_vfs_t structure and populate it with function pointers to FS APIs: esp_vfs_t myfs = { .flags = ESP_VFS_FLAG_DEFAULT, .write = &myfs_write, .open = &myfs_open, .fstat = &myfs_fstat, .close = &myfs_close, .read = &myfs_read, }; ESP_ERROR_CHECK(esp_vfs_register("/data", &myfs, NULL)); Depending on the way how the FS driver declares its API functions, either read, write, etc., or read_p, write_p, etc., should be used. Case 1: API functions are declared without an extra context pointer (the FS driver is a singleton): ssize_t myfs_write(int fd, const void * data, size_t size); // In definition of esp_vfs_t: .flags = ESP_VFS_FLAG_DEFAULT, .write = &myfs_write, // ... other members initialized // When registering FS, context pointer (third argument) is NULL: ESP_ERROR_CHECK(esp_vfs_register("/data", &myfs, NULL)); Case 2: API functions are declared with an extra context pointer (the FS driver supports multiple instances): ssize_t myfs_write(myfs_t* fs, int fd, const void * data, size_t size); // 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)); (continues on next page) Espressif Systems 1318 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // Can register another instance: myfs_t* myfs_inst2 = myfs_mount(partition2->offset, partition2->size); ESP_ERROR_CHECK(esp_vfs_register("/data2", &myfs, myfs_inst2)); Synchronous input/output multiplexing Synchronous input/output multiplexing by select() is supported in the VFS component. The implementation works in the following way. 1. select() is called with file descriptors which could belong to various VFS drivers. 2. The file descriptors are divided into groups each belonging to one VFS driver. 3. The file descriptors belonging to non-socket VFS drivers are handed over to the given VFS drivers by start_select(), described later on this page. This function represents the driver-specific 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, (continues on next page) Espressif Systems 1319 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference .stop_socket_select = &lwip_stop_socket_select, .stop_socket_select_isr = &lwip_stop_socket_select_isr, // ... other members initialized (continued from previous page) 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. Espressif Systems 1320 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1321 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 · 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). Espressif Systems 1322 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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(). · 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 Espressif Systems 1323 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · nfds: Specifies the range of descriptors which should be checked. The first nfds descriptors will be checked in each set. · readfds: If not NULL, then points to a descriptor set that on input specifies which descriptors should be checked for being ready to read, and on output indicates which descriptors are ready to read. · writefds: If not NULL, then points to a descriptor set that on input specifies which descriptors should be checked for being ready to write, and on output indicates which descriptors are ready to write. · errorfds: If not NULL, then points to a descriptor set that on input specifies which 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() Espressif Systems 1324 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1325 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int (*close)(int fd) close without context pointer int (*fstat_p)(void *ctx, int fd, struct stat *st) fstat with context pointer int (*fstat)(int fd, struct stat *st) fstat without context pointer int (*stat_p)(void *ctx, const char *path, struct stat *st) stat with context pointer int (*stat)(const char *path, struct stat *st) stat without context pointer int (*link_p)(void *ctx, const char *n1, const char *n2) link with context pointer int (*link)(const char *n1, const char *n2) link without context pointer int (*unlink_p)(void *ctx, const char *path) unlink with context pointer int (*unlink)(const char *path) unlink without context pointer int (*rename_p)(void *ctx, const char *src, const char *dst) rename with context pointer int (*rename)(const char *src, const char *dst) rename without context pointer DIR *(*opendir_p)(void *ctx, const char *name) opendir with context pointer DIR *(*opendir)(const char *name) opendir without context pointer struct dirent *(*readdir_p)(void *ctx, DIR *pdir) readdir with context pointer struct dirent *(*readdir)(DIR *pdir) readdir without context pointer int (*readdir_r_p)(void *ctx, DIR *pdir, struct dirent *entry, struct dirent **out_dirent) readdir_r with context pointer int (*readdir_r)(DIR *pdir, struct dirent *entry, struct dirent **out_dirent) readdir_r without context pointer long (*telldir_p)(void *ctx, DIR *pdir) telldir with context pointer long (*telldir)(DIR *pdir) telldir without context pointer void (*seekdir_p)(void *ctx, DIR *pdir, long offset) seekdir with context pointer void (*seekdir)(DIR *pdir, long offset) seekdir without context pointer int (*closedir_p)(void *ctx, DIR *pdir) closedir with context pointer int (*closedir)(DIR *pdir) closedir without context pointer Espressif Systems 1326 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int (*mkdir_p)(void *ctx, const char *name, mode_t mode) mkdir with context pointer int (*mkdir)(const char *name, mode_t mode) mkdir without context pointer int (*rmdir_p)(void *ctx, const char *name) rmdir with context pointer int (*rmdir)(const char *name) rmdir without context pointer int (*fcntl_p)(void *ctx, int fd, int cmd, int arg) fcntl with context pointer int (*fcntl)(int fd, int cmd, int arg) fcntl without context pointer int (*ioctl_p)(void *ctx, int fd, int cmd, va_list args) ioctl with context pointer int (*ioctl)(int fd, int cmd, va_list args) ioctl without context pointer int (*fsync_p)(void *ctx, int fd) fsync with context pointer int (*fsync)(int fd) fsync without context pointer int (*access_p)(void *ctx, const char *path, int amode) access with context pointer int (*access)(const char *path, int amode) access without context pointer int (*truncate_p)(void *ctx, const char *path, off_t length) truncate with context pointer int (*truncate)(const char *path, off_t length) truncate without context pointer int (*ftruncate_p)(void *ctx, int fd, off_t length) ftruncate with context pointer int (*ftruncate)(int fd, off_t length) ftruncate 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 Espressif Systems 1327 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference int (*tcdrain)(int fd) tcdrain without context pointer int (*tcflush_p)(void *ctx, int fd, int select) tcflush with context pointer int (*tcflush)(int fd, int select) tcflush without context pointer int (*tcflow_p)(void *ctx, int fd, int action) tcflow with context pointer int (*tcflow)(int fd, int action) tcflow without context pointer pid_t (*tcgetsid_p)(void *ctx, int fd) tcgetsid with context pointer pid_t (*tcgetsid)(int fd) tcgetsid without context pointer int (*tcsendbreak_p)(void *ctx, int fd, int duration) tcsendbreak with context pointer int (*tcsendbreak)(int fd, int duration) tcsendbreak without context pointer esp_err_t (*start_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, esp_vfs_select_sem_t sem, void **end_select_args) start_select is called for setting up synchronous I/O multiplexing of the desired file descriptors in the given VFS int (*socket_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout) socket select function for socket FDs with the functionality of POSIX select(); this should be set only for the socket VFS void (*stop_socket_select)(void *sem) called by VFS to interrupt the socket_select call when select is activated from a non-socket VFS driver; set only for the socket driver void (*stop_socket_select_isr)(void *sem, BaseType_t *woken) stop_socket_select which can be called from ISR; set only for the socket driver void *(*get_socket_select_semaphore)(void) end_select is called to stop the I/O multiplexing and deinitialize the environment created by start_select for the given VFS esp_err_t (*end_select)(void *end_select_args) get_socket_select_semaphore returns semaphore allocated in the socket driver; set only for the socket driver Macros MAX_FDS Maximum number of (global) file descriptors. ESP_VFS_PATH_MAX Maximum length of path prefix (not including zero terminator) ESP_VFS_FLAG_DEFAULT Default value of flags member in esp_vfs_t structure. ESP_VFS_FLAG_CONTEXT_PTR Flag which indicates that FS needs extra context pointer in syscalls. Espressif Systems 1328 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: · 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 Espressif Systems 1329 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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() Espressif Systems 1330 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.9.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. · 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 Espressif Systems 1331 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1332 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; 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; Espressif Systems 1333 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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.10 System API 2.10.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). Espressif Systems 1334 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 1335 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference > 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. * · 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. Espressif Systems 1336 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members uint8_t magic Magic word ESP_IMAGE_HEADER_MAGIC uint8_t segment_count Count of memory segments uint8_t spi_mode flash read mode (esp_image_spi_mode_t as uint8_t) uint8_t spi_speed : 4 flash frequency (esp_image_spi_freq_t as uint8_t) uint8_t spi_size : 4 flash chip size (esp_image_flash_size_t as uint8_t) uint32_t entry_addr Entry address uint8_t wp_pin WP pin when SPI pins set via efuse (read by ROM bootloader, the IDF bootloader uses software to configure the WP pin and sets this field to 0xEE=disabled) uint8_t spi_pin_drv[3] Drive settings for the SPI flash pins (read by ROM bootloader) esp_chip_id_t chip_id Chip identification number uint8_t min_chip_rev Minimum chip revision supported by image uint8_t reserved[8] Reserved bytes in additional header space, currently unused uint8_t hash_appended If 1, a SHA256 digest 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 Espressif Systems 1337 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint32_t reserv1[2] reserv1 char version[32] Application version char project_name[32] Project name char time[16] Compile time char date[16] Compile date char idf_ver[32] Version IDF uint8_t app_elf_sha256[32] sha256 of elf file uint32_t reserv2[20] reserv2 Macros ESP_IMAGE_HEADER_MAGIC The magic word for the esp_image_header_t structure. ESP_IMAGE_MAX_SEGMENTS Max count of segments in the image. ESP_APP_DESC_MAGIC_WORD The magic word for the esp_app_desc structure that is in DROM. Enumerations enum esp_chip_id_t ESP chip ID. Values: ESP_CHIP_ID_ESP32 = 0x0000 chip ID: ESP32 ESP_CHIP_ID_ESP32S2 = 0x0002 chip ID: ESP32-S2 ESP_CHIP_ID_ESP32C3 = 0x0005 chip ID: ESP32-C3 ESP_CHIP_ID_ESP32S3 = 0x0009 chip ID: ESP32-S3 ESP_CHIP_ID_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 Espressif Systems 1338 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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_32MB SPI flash size 32 MB ESP_IMAGE_FLASH_SIZE_64MB SPI flash size 64 MB ESP_IMAGE_FLASH_SIZE_128MB SPI flash size 128 MB ESP_IMAGE_FLASH_SIZE_MAX SPI flash size MAX 2.10.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 Espressif Systems 1339 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 attempting to receive any data using esp_apptrace_down_buffer_get and esp_apptrace_read. This function does not protect internal data by lock. Parameters · buf: Address of buffer to use for down channel (host to target) data. · size: Size of the buffer. uint8_t *esp_apptrace_buffer_get(esp_apptrace_dest_t dest, uint32_t size, uint32_t tmo) Allocates buffer for trace data. 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. Espressif Systems 1340 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1341 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 1342 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. ESP_APPTRACE_DEST_TRAX = ESP_APPTRACE_DEST_JTAG xxx_TRAX name is obsolete, use more common xxx_JTAG ESP_APPTRACE_DEST_UART UART destination. ESP_APPTRACE_DEST_MAX = ESP_APPTRACE_DEST_UART + 1 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 Espressif Systems 1343 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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.10.3 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: (continues on next page) Espressif Systems 1344 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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); } (continued from previous page) 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 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.10.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. · 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. Espressif Systems 1345 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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() Espressif Systems 1346 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · 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" ] Espressif Systems 1347 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1348 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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. Espressif Systems 1349 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference * - 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 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 Espressif Systems 1350 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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) Espressif Systems 1351 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1352 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.10.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. 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. Espressif Systems 1353 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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. Espressif Systems 1354 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1355 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Note: If there is already pre-written data in the eFuse block using the Reed-Solomon encoding scheme, then it is not possible to write anything extra (even if the required bits are empty) without breaking the previous encoding data. This encoding data will be overwritten with new encoding data and completely destroyed (however, the payload eFuses are not damaged). It can be related to: CUSTOM_MAC, SPI_PAD_CONFIG_HD, SPI_PAD_CONFIG_CS, etc. Please contact Espressif to order the required pre-burnt eFuses. FOR TESTING ONLY (NOT RECOMMENDED): You can ignore or suppress errors that violate encoding scheme data in order to burn the necessary bits in the eFuse block. Espressif Systems 1356 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference eFuse API Access to the fields is via a pointer to the description structure. API functions have some basic operation: · esp_efuse_read_field_blob() - returns an array of read eFuse bits. · esp_efuse_read_field_cnt() - returns the number of bits programmed as 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. Espressif Systems 1357 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · esp_efuse_set_write_protect_of_digest_revoke() - Sets a write protection of the Secure Boot public key digest revocation bit. 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] (continues on next page) Espressif Systems 1358 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) EFUSE_BLK2 [0 255] EFUSE_BLK3 [0 55] [96 159] [184 191] Note: Not printed ranges are free for using. (bits in EFUSE_BLK0 are reserved for Espressif) Parsing eFuse CSV input file $IDF_PATH/components/efuse/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) (continues on next page) Espressif Systems 1359 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) ADC2_MODE2_D2 (BLOCK2) ADC2 calibration 7 = 12 R/W (0x03) ADC2_MODE3_D2 (BLOCK2) ADC2 calibration 8 = 16 R/W (0x04) 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 Disables programming of = 0 R/W (0x00000000) (continues on next page) Espressif Systems 1360 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference RD_DIS (BLOCK0) BLOCK4-10 (continued from previous page) Disables software reading from = 0 R/W (0b0000000) 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) (continues on next page) Espressif Systems 1361 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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) 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) = 0 R/W (0b000000) SPI_PAD_CONFIG_Q (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_D (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_CS (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_HD (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_WP (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_DQS (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_D4 (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_D5 (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_D6 (BLOCK1) = 0 R/W (0b000000) SPI_PAD_CONFIG_D7 (BLOCK1) = 0 R/W (0b000000) SPI CLK pad SPI Q (D1) pad SPI D (D0) pad SPI CS pad SPI HD (D3) pad SPI WP (D2) pad SPI DQS pad SPI D4 pad SPI D5 pad SPI D6 pad SPI D7 pad (continues on next page) Espressif Systems 1362 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) Usb Config fuses: DIS_USB (BLOCK0) = False R/W (0b0) USB_EXCHG_PINS (BLOCK0) = False R/W (0b0) EXT_PHY_ENABLE (BLOCK0) = False R/W (0b0) USB_FORCE_NOPERSIST (BLOCK0) = False R/W (0b0) Disables the USB OTG hardware 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 Espressif Systems 1363 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Header File · components/efuse/esp32s3/include/esp_efuse.h Enumerations enum esp_efuse_block_t Type of eFuse blocks ESP32S3. Values: EFUSE_BLK0 = 0 Number of eFuse BLOCK0. REPEAT_DATA EFUSE_BLK1 = 1 Number of eFuse BLOCK1. MAC_SPI_8M_SYS EFUSE_BLK2 = 2 Number of eFuse BLOCK2. SYS_DATA_PART1 EFUSE_BLK_SYS_DATA_PART1 = 2 Number of eFuse BLOCK2. SYS_DATA_PART1 EFUSE_BLK3 = 3 Number of eFuse BLOCK3. USER_DATA EFUSE_BLK_USER_DATA = 3 Number of eFuse BLOCK3. USER_DATA EFUSE_BLK4 = 4 Number of eFuse BLOCK4. KEY0 EFUSE_BLK_KEY0 = 4 Number of eFuse BLOCK4. KEY0 EFUSE_BLK5 = 5 Number of eFuse BLOCK5. KEY1 EFUSE_BLK_KEY1 = 5 Number of eFuse BLOCK5. KEY1 EFUSE_BLK6 = 6 Number of eFuse BLOCK6. KEY2 EFUSE_BLK_KEY2 = 6 Number of eFuse BLOCK6. KEY2 EFUSE_BLK7 = 7 Number of eFuse BLOCK7. KEY3 EFUSE_BLK_KEY3 = 7 Number of eFuse BLOCK7. KEY3 EFUSE_BLK8 = 8 Number of eFuse BLOCK8. KEY4 EFUSE_BLK_KEY4 = 8 Number of eFuse BLOCK8. KEY4 EFUSE_BLK9 = 9 Number of eFuse BLOCK9. KEY5 EFUSE_BLK_KEY5 = 9 Number of eFuse BLOCK9. KEY5 EFUSE_BLK_KEY_MAX = 10 EFUSE_BLK10 = 10 Number of eFuse BLOCK10. SYS_DATA_PART2 Espressif Systems 1364 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference EFUSE_BLK_SYS_DATA_PART2 = 10 Number of eFuse BLOCK10. SYS_DATA_PART2 EFUSE_BLK_MAX enum esp_efuse_coding_scheme_t Type of coding scheme. Values: EFUSE_CODING_SCHEME_NONE = 0 None EFUSE_CODING_SCHEME_RS = 3 Reed-Solomon coding enum esp_efuse_purpose_t Type of key purpose. Values: ESP_EFUSE_KEY_PURPOSE_USER = 0 User purposes (software-only use) ESP_EFUSE_KEY_PURPOSE_RESERVED = 1 Reserved ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_1 = 2 XTS_AES_256_KEY_1 (flash/PSRAM encryption) ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_2 = 3 XTS_AES_256_KEY_2 (flash/PSRAM encryption) ESP_EFUSE_KEY_PURPOSE_XTS_AES_128_KEY = 4 XTS_AES_128_KEY (flash/PSRAM encryption) ESP_EFUSE_KEY_PURPOSE_HMAC_DOWN_ALL = 5 HMAC Downstream mode ESP_EFUSE_KEY_PURPOSE_HMAC_DOWN_JTAG = 6 JTAG soft enable key (uses HMAC Downstream mode) ESP_EFUSE_KEY_PURPOSE_HMAC_DOWN_DIGITAL_SIGNATURE = 7 Digital Signature peripheral key (uses HMAC Downstream mode) ESP_EFUSE_KEY_PURPOSE_HMAC_UP = 8 HMAC Upstream mode ESP_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST0 = 9 SECURE_BOOT_DIGEST0 (Secure Boot key digest) ESP_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST1 = 10 SECURE_BOOT_DIGEST1 (Secure Boot key digest) ESP_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST2 = 11 SECURE_BOOT_DIGEST2 (Secure Boot key digest) ESP_EFUSE_KEY_PURPOSE_MAX MAX PURPOSE Header File · components/efuse/include/esp_efuse.h Functions Espressif Systems 1365 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1366 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. This is a thread-safe implementation. Example: EFUSE_BLK2_RDATA3_REG where (blk=2, num_reg=3) Espressif Systems 1367 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Return chip version Espressif Systems 1368 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · secure_version: Secure version from app. Espressif Systems 1369 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. It will reset the batch writing mode and any written changes. Espressif Systems 1370 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) Return Espressif Systems 1371 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 1372 Release v5.0-dev-2349-g4350e6fef8 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 1373 Release v5.0-dev-2349-g4350e6fef8 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 1374 Release v5.0-dev-2349-g4350e6fef8 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.10.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_check.h Macros ESP_RETURN_ON_ERROR(x, log_tag, format, ...) Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message and returns. 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. 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__. Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message and returns. Espressif Systems 1375 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_RETURN_ON_ERROR_ISR(x, log_tag, format, ...) A version of ESP_RETURN_ON_ERROR() macro that can be called from ISR. ESP_GOTO_ON_ERROR(x, goto_tag, log_tag, format, ...) Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message, sets the local variable mretnto the code, and then exits by jumping to mgoto_tagn. ESP_GOTO_ON_ERROR_ISR(x, goto_tag, log_tag, format, ...) A version of ESP_GOTO_ON_ERROR() macro that can be called from ISR. ESP_RETURN_ON_FALSE(a, err_code, log_tag, format, ...) Macro which can be used to check the condition. If the condition is not mtruen, it prints the message and returns with the supplied merr_coden. ESP_RETURN_ON_FALSE_ISR(a, err_code, log_tag, format, ...) A version of ESP_RETURN_ON_FALSE() macro that can be called from ISR. ESP_GOTO_ON_FALSE(a, err_code, goto_tag, log_tag, format, ...) Macro which can be used to check the condition. If the condition is not mtruen, it prints the message, sets the local variable mretnto the supplied merr_coden, and then exits by jumping to mgoto_tagn. ESP_GOTO_ON_FALSE_ISR(a, err_code, goto_tag, log_tag, format, ...) A version of ESP_GOTO_ON_FALSE() macro that can be called from ISR. Header File · components/esp_common/include/esp_err.h Functions const char *esp_err_to_name(esp_err_t code) Returns string for esp_err_t error codes. This function finds the error code in a pre-generated lookup-table and returns its string representation. The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project. Return string error message Parameters · code: esp_err_t error code const char *esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen) Returns string for esp_err_t and system error codes. This function finds the error code in a pre-generated lookup-table of esp_err_t errors and returns its string representation. If the error code is not found then it is attempted to be found among system errors. The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project. Return buf containing the string error message Parameters · code: esp_err_t error code · [out] buf: buffer where the error message should be written · buflen: Size of buffer buf. At most buflen bytes are written into the buf buffer (including the terminating null byte). Macros ESP_OK esp_err_t value indicating success (no error) ESP_FAIL Generic esp_err_t code indicating failure Espressif Systems 1376 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_ERR_NO_MEM Out of memory ESP_ERR_INVALID_ARG Invalid argument ESP_ERR_INVALID_STATE Invalid state ESP_ERR_INVALID_SIZE Invalid size ESP_ERR_NOT_FOUND Requested resource not found ESP_ERR_NOT_SUPPORTED Operation or feature not supported ESP_ERR_TIMEOUT Operation timed out ESP_ERR_INVALID_RESPONSE Received response was invalid ESP_ERR_INVALID_CRC CRC or checksum was invalid ESP_ERR_INVALID_VERSION Version was invalid ESP_ERR_INVALID_MAC MAC address was invalid ESP_ERR_NOT_FINISHED There are items remained to retrieve ESP_ERR_WIFI_BASE Starting number of WiFi error codes ESP_ERR_MESH_BASE Starting number of MESH error codes ESP_ERR_FLASH_BASE Starting number of flash error codes ESP_ERR_HW_CRYPTO_BASE Starting number of HW cryptography module error codes ESP_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 Espressif Systems 1377 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.10.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_https_ota_config_t ota_config = { .http_config = &config, }; esp_err_t ret = esp_https_ota(&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. Signature Verification For additional security, signature of OTA firmware images can be verified. For that, refer Secure OTA Updates Without Secure boot Advanced APIs esp_https_ota also provides advanced APIs which can be used if more information and control is needed during the OTA process. Example that uses advanced ESP_HTTPS_OTA APIs: system/ota/advanced_https_ota. Espressif Systems 1378 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference OTA Upgrades with Pre-Encrypted Firmware To perform OTA upgrades with Pre-Encrypted Firmware, please enable CONFIG_ESP_HTTPS_OTA_DECRYPT_CB in component menuconfig. Example that performs OTA upgrade with Pre-Encrypted Firmware: system/ota/pre_encrypted_ota. API Reference Header File · components/esp_https_ota/include/esp_https_ota.h Functions esp_err_t esp_https_ota(const esp_https_ota_config_t *ota_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 ota_config->http_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] ota_config: pointer to esp_https_ota_config_t structure. esp_err_t esp_https_ota_begin(const 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 Espressif Systems 1379 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_https_ota_perform(esp_https_ota_handle_t https_ota_handle) Read image data from HTTP stream and write it to OTA partition. This function reads image data from HTTP stream and writes it to OTA partition. This function must be called only if esp_https_ota_begin() returns successfully. This function must be called in a loop since it returns after every HTTP read operation thus giving you the flexibility to stop OTA operation midway. Return · ESP_ERR_HTTPS_OTA_IN_PROGRESS: OTA update is in progress, call this API again to continue. · ESP_OK: OTA update was successful · ESP_FAIL: OTA update failed · ESP_ERR_INVALID_ARG: Invalid argument · ESP_ERR_INVALID_VERSION: Invalid chip revision in image header · 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 Espressif Systems 1380 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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_ERR_INVALID_STATE: Invalid state to call this API. esp_https_ota_begin() not called yet. · 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 Espressif Systems 1381 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Macros ESP_ERR_HTTPS_OTA_BASE ESP_ERR_HTTPS_OTA_IN_PROGRESS Type Definitions typedef void *esp_https_ota_handle_t typedef esp_err_t (*http_client_init_cb_t)(esp_http_client_handle_t) 2.10.8 Event Loop Library Overview The event loop library allows components to declare events to which other components can register handlers code which will execute when those events occur. This allows loosely coupled components to attach desired behavior to changes in state of other components without application involvement. For instance, a high level connection handling library may subscribe to events produced by the 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 = { (continues on next page) Espressif Systems 1382 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference .queue_size = ..., .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 1383 Release v5.0-dev-2349-g4350e6fef8 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 1384 Release v5.0-dev-2349-g4350e6fef8 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 1385 Release v5.0-dev-2349-g4350e6fef8 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 1386 Release v5.0-dev-2349-g4350e6fef8 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 1387 Release v5.0-dev-2349-g4350e6fef8 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 1388 Release v5.0-dev-2349-g4350e6fef8 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 1389 Release v5.0-dev-2349-g4350e6fef8 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, const 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, const 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 1390 Release v5.0-dev-2349-g4350e6fef8 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, const 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, const 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 1391 Release v5.0-dev-2349-g4350e6fef8 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 1392 Release v5.0-dev-2349-g4350e6fef8 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 2.10.9 FreeRTOS Overview This section contains documentation of FreeRTOS types, functions, and macros. It is automatically generated from FreeRTOS header files. Note: ESP-IDF FreeRTOS is based on 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 Supplemental Features. 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. Espressif Systems 1393 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. · 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. Espressif Systems 1394 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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. Espressif Systems 1395 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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: Espressif Systems 1396 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // Dimensions the buffer that the task being created will use as its stack. // NOTE: This is the number of bytes the stack will hold, not the number of // words as found in vanilla FreeRTOS. #define STACK_SIZE 200 // Structure that will hold the TCB of the task being created. StaticTask_t xTaskBuffer; // Buffer that the task being created will use as its stack. Note this is // an array of StackType_t variables. The size of StackType_t is dependent on // the RTOS port. StackType_t xStack[ STACK_SIZE ]; // Function that implements the task being created. 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. Espressif Systems 1397 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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 ); (continues on next page) Espressif Systems 1398 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // Start the scheduler. vTaskStartScheduler(); (continued from previous page) // 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 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 } } (continues on next page) Espressif Systems 1399 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference &xTaskBuffer; // Holds the task's data structure. }; (continued from previous page) 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( ;; ); } 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 Espressif Systems 1400 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; // 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. Espressif Systems 1401 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1402 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 ) { TaskHandle_t xHandle; // 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 ) { (continues on next page) Espressif Systems 1403 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TaskHandle_t xHandle; TaskStatus_t xTaskDetails; (continued from previous page) // Obtain the handle of a task from its name. xHandle = xTaskGetHandle( "Task_Name" ); // Check the handle is not NULL. configASSERT( xHandle ); // Use the handle to obtain further information about the task. vTaskGetInfo( xHandle, &xTaskDetails, pdTRUE, // Include the high water mark in xTaskDetails. eInvalid ); // Include the task state in xTaskDetails. } Parameters · xTask: Handle of the task being queried. If xTask is NULL then information will be returned about the calling task. · pxTaskStatus: A pointer to the TaskStatus_t structure that will be filled with information about the task referenced by the handle passed using the xTask parameter. · xGetFreeStackSpace: The TaskStatus_t structure contains a member to report the stack high water mark of the task being queried. Calculating the stack high water mark takes a relatively long time, and can make the system temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to allow the high water mark checking to be skipped. The high watermark value will only be written to the TaskStatus_t structure if xGetFreeStackSpace is not set to pdFALSE; · eState: The TaskStatus_t structure contains a member to report the state of the task being queried. Obtaining the task state is not as fast as a simple assignment - so the eState parameter is provided to allow the state information to be omitted from the TaskStatus_t structure. To obtain state information then set eState to eInvalid - otherwise the value passed in eState will be reported as the task state in the TaskStatus_t structure. void vTaskPrioritySet(TaskHandle_t xTask, UBaseType_t uxNewPriority) INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. See the configuration 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 ); } Espressif Systems 1404 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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; (continues on next page) Espressif Systems 1405 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // 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 ). //... // 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 (); (continues on next page) Espressif Systems 1406 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // 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 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( ;; ) (continues on next page) Espressif Systems 1407 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference { // Task code goes here. (continued from previous page) // ... // At some point the task wants to perform a long operation during // which it does not want to get swapped out. It cannot use // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the // operation may cause interrupts to be missed - including the // ticks. // Prevent the real time kernel swapping out the task. vTaskSuspendAll (); // Perform the operation here. There is no need to use critical // sections as we have all the microcontroller processing time. // During this time interrupts will still operate and the kernel // tick count will be maintained. // ... // The operation is complete. Restart the kernel. xTaskResumeAll (); } } BaseType_t xTaskResumeAll(void) Resumes scheduler activity after it was suspended by a call to vTaskSuspendAll(). xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks that were previously suspended by a call to vTaskSuspend(). Example usage: void vTask1( void * pvParameters ) { for( ;; ) { // 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 () ) (continues on next page) Espressif Systems 1408 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference { } } } taskYIELD (); (continued from previous page) Return If resuming the scheduler caused a context switch then pdTRUE is returned, otherwise pdFALSE is returned. TickType_t xTaskGetTickCount(void) Return The count of ticks since vTaskStartScheduler was called. TickType_t xTaskGetTickCountFromISR(void) This is a version of xTaskGetTickCount() that is safe to be called from an ISR - provided that TickType_t is the natural word size of the microcontroller being used or interrupt nesting is either not supported or not being used. Return The count of ticks since vTaskStartScheduler was called. UBaseType_t uxTaskGetNumberOfTasks(void) Return The number of tasks that the real time kernel is currently managing. This includes all ready, blocked and suspended tasks. A task that has been deleted but not yet freed by the idle task will also be included in the count. char *pcTaskGetName(TaskHandle_t xTaskToQuery) Return The text (human readable) name of the task referenced by the handle xTaskToQuery. A task can query its own name by either passing in its own handle, or by setting xTaskToQuery to NULL. TaskHandle_t xTaskGetHandle(const char *pcNameToQuery) NOTE: This function takes a relatively long time to complete and should be used sparingly. Return The handle of the task that has the human readable name pcNameToQuery. NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available. UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask) Returns the high water mark of the stack associated with xTask. INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for this function to be available. Returns the high water mark of the stack associated with xTask. That is, the minimum free stack space there has been (in bytes not words, unlike vanilla FreeRTOS) since the task started. The smaller the returned number the closer the task has come to overflowing its stack. uxTaskGetStackHighWaterMark() and uxTaskGetStackHighWaterMark2() are the same except for their 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. Espressif Systems 1409 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1410 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 1411 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference NOTE: This function is intended for debugging use only as its use results in the scheduler remaining suspended for an extended period. Example usage: // This example demonstrates how a human readable table of run time stats // information is generated from raw data provided by uxTaskGetSystemState(). // The human readable table is written to pcWriteBuffer void vTaskGetRunTimeStats( char *pcWriteBuffer ) { TaskStatus_t *pxTaskStatusArray; volatile UBaseType_t uxArraySize, x; uint32_t ulTotalRunTime, ulStatsAsPercentage; // Make sure the write buffer does not contain a string. *pcWriteBuffer = 0x00; // Take a snapshot of the number of tasks in case it changes while this // function is executing. uxArraySize = uxTaskGetNumberOfTasks(); // Allocate a TaskStatus_t structure for each task. An array could be // allocated statically at compile time. pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) ); if( pxTaskStatusArray != NULL ) { // Generate raw status information about each task. uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, & ulTotalRunTime ); // For percentage calculations. ulTotalRunTime /= 100UL; // Avoid divide by zero errors. if( ulTotalRunTime > 0 ) { // For each populated position in the pxTaskStatusArray array, // format the raw data as human readable ASCII data for( x = 0; x < uxArraySize; x++ ) { // What percentage of the total run time has the task used? // This will always be rounded down to the nearest integer. // ulTotalRunTimeDiv100 has already been divided by 100. ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime; if( ulStatsAsPercentage > 0UL ) { sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage ); } else { // If the percentage is zero here then the task has // consumed less than 1% of the total run time. sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter ); } pcWriteBuffer += strlen( ( char * ) pcWriteBuffer ); } (continues on next page) Espressif Systems 1412 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) } // The array is no longer needed, free the memory it consumes. vPortFree( pxTaskStatusArray ); } } Return The number of TaskStatus_t structures that were populated by uxTaskGetSystemState(). This should equal the number returned by the uxTaskGetNumberOfTasks() API function, but will be zero if the value passed in the uxArraySize parameter was too small. Parameters · pxTaskStatusArray: A pointer to an array of TaskStatus_t structures. The array must contain at least one TaskStatus_t structure for each task that is under the control of the RTOS. The number of tasks under the control of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function. · uxArraySize: The size of the array pointed to by the pxTaskStatusArray parameter. The size is specified as the number of indexes in the array, or the number of TaskStatus_t structures contained in the array, not by the number of bytes in the array. · pulTotalRunTime: If configGENERATE_RUN_TIME_STATS is set to 1 in 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() Espressif Systems 1413 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1414 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1415 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1416 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1417 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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). · 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. Espressif Systems 1418 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1419 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1420 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 ) { (continues on next page) Espressif Systems 1421 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // The buffer didn't contain enough data so this task is going to // enter the Blocked state. Adjusting xTicksToWait to account for // any time that has been spent in the Blocked state within this // function so far to ensure the total amount of time spent in the // Blocked state does not exceed MAX_TIME_TO_WAIT. if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE ) { //Timed out before the wanted number of bytes were available, // exit the loop. break; } // Wait for a maximum of xTicksToWait ticks to be notified that the // receive interrupt has placed more data into the buffer. ulTaskNotifyTake( pdTRUE, xTicksToWait ); } // Attempt to read uxWantedBytes from the receive buffer into pucBuffer. // The actual number of bytes read (which might be less than // uxWantedBytes) is returned. uxReceived = UART_read_from_receive_buffer( pxUARTInstance, pucBuffer, uxWantedBytes ); return uxReceived; } Return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is returned and pxTicksToWait is updated to reflect the number of remaining ticks. See https://www.FreeRTOS.org/xTaskCheckForTimeOut.html Parameters · pxTimeOut: The time status as captured previously using vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated to reflect the current time status. · pxTicksToWait: The number of ticks to check for timeout i.e. if pxTicksToWait ticks have passed since pxTimeOut was last updated (either by vTaskSetTimeOutState() or 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. Espressif Systems 1422 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference taskYIELD() Macro for forcing a context switch. taskENTER_CRITICAL() Macro to mark the start of a critical code region. Preemptive context switches cannot occur when in a critical region. Note This may alter the stack (depending on the portable implementation) so must be used with care! taskENTER_CRITICAL_FROM_ISR() taskENTER_CRITICAL_ISR() taskEXIT_CRITICAL() Macro to mark the end of a critical code region. Preemptive context switches cannot occur when in a critical region. Note This may alter the stack (depending on the portable implementation) so must be used with care! taskEXIT_CRITICAL_FROM_ISR(x) taskEXIT_CRITICAL_ISR() taskDISABLE_INTERRUPTS() Macro to disable all maskable interrupts. taskENABLE_INTERRUPTS() Macro to enable microcontroller interrupts. taskSCHEDULER_SUSPENDED taskSCHEDULER_NOT_STARTED taskSCHEDULER_RUNNING vTaskDelayUntil(pxPreviousWakeTime, xTimeIncrement) xTaskNotify(xTaskToNotify, ulValue, eAction) xTaskNotifyIndexed(xTaskToNotify, uxIndexToNotify, ulValue, eAction) xTaskNotifyAndQuery(xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue) 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. Espressif Systems 1423 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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) Espressif Systems 1424 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 *) 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 Espressif Systems 1425 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Functions BaseType_t xQueueGenericSend(QueueHandle_t xQueue, const void *const pvItemToQueue, Tick- Type_t xTicksToWait, const BaseType_t xCopyPosition) It is preferred that the macros xQueueSend(), xQueueSendToFront() and xQueueSendToBack() are used in place of calling this function directly. Post an item on a queue. The item is queued by copy, not by reference. This function must not be called from an interrupt service routine. See xQueueSendFromISR () for an alternative which may be used in an ISR. Example usage: struct AMessage { char ucMessageID; char ucData[ 20 ]; } xMessage; uint32_t ulVar = 10UL; 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 Espressif Systems 1426 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference available on the queue, should it already be full. The call will return immediately if this is set to 0 and the queue is full. The time is defined in tick periods so the constant portTICK_PERIOD_MS should be used to convert to real time if this is required. · xCopyPosition: Can take the value queueSEND_TO_BACK to place the item at the back of the queue, or queueSEND_TO_FRONT to place the item at the front of the queue (for high priority messages). BaseType_t xQueuePeek(QueueHandle_t xQueue, void *const pvBuffer, TickType_t xTicksToWait) Receive an item from a queue without removing the item from the queue. The item is received by copy so a buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the queue was created. Successfully received items remain on the queue so will be returned again by the next call, or a call to xQueueReceive(). This macro must not be used in an interrupt service routine. See xQueuePeekFromISR() for an alternative that can be called from an interrupt service routine. Example usage: struct AMessage { char ucMessageID; char ucData[ 20 ]; } xMessage; QueueHandle_t xQueue; // Task to create a queue and post a value. 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. (continues on next page) Espressif Systems 1427 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference } } // ... Rest of task code. } (continued from previous page) Return pdTRUE if an item was successfully received from the queue, otherwise pdFALSE. Parameters · xQueue: The handle to the queue from which the item is to be received. · pvBuffer: Pointer to the buffer into which the received item will be copied. · xTicksToWait: The maximum amount of time the task should block waiting for an item to receive should the queue be empty at the time of the call. The time is defined in tick periods so the constant portTICK_PERIOD_MS should be used to convert to real time if this is required. xQueuePeek() will return immediately if xTicksToWait is 0 and the queue is empty. BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue, void *const pvBuffer) A version of xQueuePeek() that can be called from an interrupt service routine (ISR). Receive an item from a queue without removing the item from the queue. The item is received by copy so a buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the queue was created. Successfully received items remain on the queue so will be returned again by the next call, or a call to xQueueReceive(). 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. } (continues on next page) Espressif Systems 1428 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // ... (continued from previous page) // 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 ) { // 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 xQueueSendTo- Espressif Systems 1429 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference BackFromISR() 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; // 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. (continues on next page) Espressif Systems 1430 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference void vAFunction( void *pvParameters ) { char cValueToPost; const TickType_t xTicksToWait = ( TickType_t )0xff; (continued from previous page) // Create a queue capable of containing 10 characters. xQueue = xQueueCreate( 10, sizeof( char ) ); if( xQueue == 0 ) { // Failed to create the queue. } // ... // 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) Espressif Systems 1431 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1432 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note 1: See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html for reasons why queue sets are very rarely needed in practice as there are simpler methods of blocking on multiple objects. Note 2: Blocking on a queue set that contains a mutex will not cause the mutex holder to inherit the priority of the blocked task. Note 3: An additional 4 bytes of RAM is required for each space in a every queue added to a queue set. Therefore counting semaphores that have a high maximum count value should not be added to a queue set. Note 4: A receive (in the case of a queue) or take (in the case of a semaphore) operation must not be performed on a member of a queue set unless a call to xQueueSelectFromSet() has first returned a handle to that set member. Return If the queue set is created successfully then a handle to the created queue set is returned. Otherwise NULL is returned. Parameters · uxEventQueueLength: Queue sets store events that occur on the queues and semaphores 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() Espressif Systems 1433 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 * ) ); (continues on next page) Espressif Systems 1434 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference if( xQueue2 == 0 ) { // Queue was not created and must not be used. } // ... Rest of task code. } (continued from previous page) Return If the queue is successfully create then a handle to the newly created queue is returned. If the queue cannot be created then 0 is returned. Parameters · uxQueueLength: The maximum number of items that the queue can contain. · uxItemSize: The number of bytes each item in the queue will require. Items are queued by copy, not by reference, so this is the number of bytes that will be copied for each posted item. Each item on the queue must be the same size. xQueueCreateStatic(uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer) Creates a new queue instance, and returns a handle by which the new queue can be referenced. Internally, within the FreeRTOS implementation, queues use two blocks of memory. The first block is used to hold the 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. (continues on next page) Espressif Systems 1435 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // ... Rest of task code. } (continued from previous page) 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. 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 (continues on next page) Espressif Systems 1436 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // 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) 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. } } (continues on next page) Espressif Systems 1437 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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. 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 ) { (continues on next page) Espressif Systems 1438 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // 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 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. (continues on next page) Espressif Systems 1439 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) } // 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 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 ) { (continues on next page) Espressif Systems 1440 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference portYIELD_FROM_ISR (); } } (continued from previous page) 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; // 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. Espressif Systems 1441 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; 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 Espressif Systems 1442 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); // 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. Espressif Systems 1443 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference typedef struct QueueDefinition *QueueSetMemberHandle_t Queue sets can contain both queues and semaphores, so the QueueSetMemberHandle_t is defined as a type to be used where a parameter or return value can be either an QueueHandle_t or an SemaphoreHandle_t. Semaphore API Header File · components/freertos/FreeRTOS-Kernel/include/freertos/semphr.h Macros semBINARY_SEMAPHORE_QUEUE_LENGTH semSEMAPHORE_QUEUE_ITEM_LENGTH semGIVE_BLOCK_TIME vSemaphoreCreateBinary(xSemaphore) xSemaphoreCreateBinary() Creates a new binary semaphore instance, and returns a handle by which the new semaphore can be referenced. In many usage scenarios it is faster and more memory efficient to use a direct to task notification in place of a binary semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html Internally, within the FreeRTOS implementation, binary semaphores use a block of memory, in which the semaphore structure is stored. If a binary semaphore is created using xSemaphoreCreateBinary() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateBinary() function. (see https://www.FreeRTOS.org/a00111.html). If a binary semaphore is created using 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. Espressif Systems 1444 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; 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 ) { (continues on next page) Espressif Systems 1445 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // Create the semaphore to guard a shared resource. vSemaphoreCreateBinary( xSemaphore ); } (continued from previous page) // 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. Release the // semaphore. xSemaphoreGive( xSemaphore ); } else { // We could not obtain the semaphore and can therefore not access // the shared resource safely. } } } Return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime expired without the semaphore becoming available. xSemaphoreTakeRecursive(xMutex, xBlockTime) Macro to recursively obtain, or 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 ) { (continues on next page) Espressif Systems 1446 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // ... Do other things. (continued from previous page) 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 // 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: Espressif Systems 1447 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. // ... // 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(); (continues on next page) Espressif Systems 1448 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) } // 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. 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: Espressif Systems 1449 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference #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. } } } // 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 *pxHigherPriority- Espressif Systems 1450 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TaskWoken to pdTRUE if giving the semaphore caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If xSemaphoreGiveFromISR() sets this value to pdTRUE then a context switch should be requested before the interrupt is exited. xSemaphoreTakeFromISR(xSemaphore, pxHigherPriorityTaskWoken) Macro to take a semaphore from an ISR. The semaphore must have previously been created with a call to xSemaphoreCreateBinary() or xSemaphoreCreateCounting(). Mutex type semaphores (those created using a call to xSemaphoreCreateMutex()) must not be used with this macro. This macro can be used from an ISR, however taking a semaphore from an ISR is not a common operation. It is likely to only be useful when taking a counting semaphore when an interrupt is obtaining an object from a resource pool (when the semaphore count indicates the number of resources available). Return pdTRUE if the semaphore was successfully taken, otherwise pdFALSE Parameters · xSemaphore: A handle to the semaphore being taken. This is the handle returned when the 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. 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. Espressif Systems 1451 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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. Espressif Systems 1452 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. } } 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(). (continues on next page) Espressif Systems 1453 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // 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 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 ) (continues on next page) Espressif Systems 1454 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference { // The semaphore was created successfully. // The semaphore can now be used. } } (continued from previous page) 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 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 ); (continues on next page) Espressif Systems 1455 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) // 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. 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. Espressif Systems 1456 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; * 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. (continues on next page) Espressif Systems 1457 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * vTimerCallback // Each timer calls the same callback when it expires. * ); * * if( xTimers[ x ] == NULL ) * { * // The timer was not created. * } * else * { * // Start the timer. No block time is specified, and even if one was * // it would be ignored because the scheduler has not yet been * // started. * if( xTimerStart( xTimers[ x ], 0 ) != pdPASS ) * { * // The timer could not be set into the Active state. * } * } * } * * // ... * // Create tasks here. * // ... * * // Starting the scheduler will start the timers running as they have already * // been set into the active state. * vTaskStartScheduler(); * * // Should not reach here. * for( ;; ); *} * Return If the timer is successfully created then a handle to the newly created timer is returned. If the timer cannot be created (because either there is insufficient FreeRTOS heap remaining to allocate the timer structures, or the timer period was set to 0) then NULL is returned. Parameters · pcTimerName: A text name that is assigned to the timer. This is done purely to assist debugging. The kernel itself only ever references a timer by its handle, and never by its name. · xTimerPeriodInTicks: The timer period. The time is defined in tick periods so the 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) Espressif Systems 1458 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; * * // 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. (continues on next page) Espressif Systems 1459 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * 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 * // been set into the active state. * vTaskStartScheduler(); * * // Should not reach here. * for( ;; ); *} * Return If the timer is created then a handle to the created timer is returned. If pxTimerBuffer was NULL then NULL is returned. Parameters · pcTimerName: A text name that is assigned to the timer. This is done purely to assist debugging. The kernel itself only ever references a timer by its handle, and never by its name. · xTimerPeriodInTicks: The timer period. The time is defined in tick periods so the 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 Espressif Systems 1460 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference local) storage. Example usage: Return The ID assigned to the timer being queried. Parameters · xTimer: The timer being queried. See the xTimerCreate() API function example usage scenario. void vTimerSetTimerID(TimerHandle_t xTimer, void *pvNewID) void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ); Sets the ID assigned to the timer. IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to create the timer. If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer local) storage. Example usage: Parameters · xTimer: The timer being updated. · pvNewID: The ID to assign to the timer. 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) TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ); Simply returns the handle of the timer service/daemon task. It it not valid to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started. Espressif Systems 1461 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: * * // 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 Espressif Systems 1462 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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. Espressif Systems 1463 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1464 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: 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. Espressif Systems 1465 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: * // 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. Espressif Systems 1466 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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; * (continues on next page) Espressif Systems 1467 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * // The callback function assigned to the one-shot timer. In this case the * // parameter is not used. * void vBacklightTimerCallback( TimerHandle_t pxTimer ) *{ * // The timer expired, therefore 5 seconds must have passed since a key * // was pressed. Switch off the LCD back-light. * vSetBacklightState( BACKLIGHT_OFF ); *} * * // The key press event handler. * void vKeyPressEventHandler( char cKey ) *{ * // Ensure the LCD back-light is on, then reset the timer that is * // responsible for turning the back-light off after 5 seconds of * // key inactivity. Wait 10 ticks for the command to be successfully sent * // if it cannot be sent immediately. * vSetBacklightState( BACKLIGHT_ON ); * if( xTimerReset( xBacklightTimer, 100 ) != pdPASS ) * { * // The reset command was not executed successfully. Take appropriate * // action here. * } * * // Perform the rest of the key processing here. *} * * void main( void ) *{ * int32_t x; * * // Create then start the one-shot timer that is responsible for turning * // the back-light off if no keys are pressed within a 5 second period. * xBacklightTimer = xTimerCreate( "BacklightTimer", // Just a text name, not used by the kernel. * ( 5000 / portTICK_PERIOD_MS), // The timer period in ticks. * pdFALSE, // The timer is a one-shot timer. * 0, // The id is not used by the callback so can take any value. * vBacklightTimerCallback // The callback function that switches the LCD back-light off. * ); * * if( xBacklightTimer == NULL ) * { * // The timer was not created. * } * else * { * // Start the timer. No block time is specified, and even if one was * // it would be ignored because the scheduler has not yet been * // started. * if( xTimerStart( xBacklightTimer, 0 ) != pdPASS ) * { * // The timer could not be set into the Active state. * } * } * * // ... * // Create tasks here. (continues on next page) Espressif Systems 1468 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * // ... * * // 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 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 (continues on next page) Espressif Systems 1469 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * // 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 * // depends on the FreeRTOS port being used). * } *} * Return pdFAIL will be returned if the start command could not be sent to the timer command queue. pdPASS will be returned if the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when xTimerStartFromISR() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant. Parameters · xTimer: The handle of the timer being started/restarted. · pxHigherPriorityTaskWoken: The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling 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 ) (continues on next page) Espressif Systems 1470 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * { * // 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). * } *} * 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. * } (continues on next page) Espressif Systems 1471 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * * // 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. 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. (continues on next page) Espressif Systems 1472 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) * 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. * } * * // 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) Espressif Systems 1473 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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: Espressif Systems 1474 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // 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. 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. } (continues on next page) Espressif Systems 1475 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) else { // xEventGroupWaitBits() returned because xTicksToWait ticks passed // without either BIT_0 or BIT_4 becoming set. } } Return The value of the event group at the time either the bits being waited for became set, or the block time expired. Test the return value to know which bits were set. If xEventGroupWaitBits() returned because its timeout expired then not all the bits being waited for will be set. If xEventGroupWaitBits() returned because the bits it was waiting for were set then the returned value is the event group value before any bits were automatically cleared in the case that xClearOnExit parameter was set to pdTRUE. Parameters · xEventGroup: The event group in which the bits are being tested. The event group must have previously been created using a call to xEventGroupCreate(). · uxBitsToWaitFor: A bitwise value that indicates the bit or bits to test inside the event group. For example, to wait for bit 0 and/or bit 2 set uxBitsToWaitFor to 0x05. To wait for bits 0 and/or bit 1 and/or bit 2 set uxBitsToWaitFor to 0x07. Etc. · xClearOnExit: If xClearOnExit is set to pdTRUE then any bits within uxBitsToWaitFor that are set within the event group will be cleared before xEventGroupWaitBits() returns if the wait condition was met (if the function returns for a reason other than a timeout). If xClearOnExit is set to pdFALSE then the bits set in the event group are not altered when the call to xEventGroupWaitBits() returns. · xWaitForAllBits: If xWaitForAllBits is set to pdTRUE then xEventGroupWaitBits() will 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 ) (continues on next page) Espressif Systems 1476 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) { // 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: #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. } } Espressif Systems 1477 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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: // 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 ) (continues on next page) Espressif Systems 1478 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference { for( ;; ) { // Perform task functionality here. (continued from previous page) // 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 // 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) Espressif Systems 1479 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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(). EventGroupHandle_t xEventGroup; 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; (continues on next page) Espressif Systems 1480 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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 ); } } 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 Espressif Systems 1481 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 ); // 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 xTick- Espressif Systems 1482 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference sToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out before it can write all xDataLengthBytes into the buffer it will still write as many bytes as possible. A task does not use any CPU time when it is in the blocked state. size_t xStreamBufferSendFromISR(StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *const 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: // 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. Espressif Systems 1483 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 1484 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 ]; size_t xReceivedBytes; BaseType_t xHigherPriorityTaskWoken = pdFALSE; // 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 Espressif Systems 1485 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1486 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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, Base- Type_t *pxHigherPriorityTaskWoken) For advanced users only. The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when data is sent to a message buffer or stream buffer. If there was a task that was blocked on the message or stream buffer waiting for data to arrive then the sbSEND_COMPLETED() macro sends a notification to the task to remove it from the Blocked state. xStreamBufferSendCompletedFromISR() does the same thing. It is provided to enable application writers to implement their own version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME. See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for additional information. Return If a task was removed from the Blocked state then pdTRUE is returned. Otherwise pdFALSE is returned. Parameters · xStreamBuffer: The handle of the stream buffer to which data was written. · pxHigherPriorityTaskWoken: *pxHigherPriorityTaskWoken should be initialised to pdFALSE before it is passed into xStreamBufferSendCompletedFromISR(). If calling 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. Espressif Systems 1487 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 { // 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 ) (continues on next page) Espressif Systems 1488 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference { StreamBufferHandle_t xStreamBuffer; const size_t xTriggerLevel = 1; (continued from previous page) xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucBufferStorage ), xTriggerLevel, ucBufferStorage, &xStreamBufferStruct ); // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer // parameters were NULL, xStreamBuffer will not be NULL, and can be used to // reference the created stream buffer in other stream buffer API calls. // Other code that uses the stream buffer can go here. } Return If the stream buffer is created successfully then a handle to the created stream buffer is returned. If either pucStreamBufferStorageArea or pxStaticstreamBuffer are NULL then NULL is returned. Parameters · xBufferSizeBytes: The size, in bytes, of the buffer pointed to by the 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: Espressif Systems 1489 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. } 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. (continues on next page) Espressif Systems 1490 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference // Other code that uses the message buffer can go here. } (continued from previous page) 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. : 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 ); (continues on next page) Espressif Systems 1491 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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 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, (continues on next page) Espressif Systems 1492 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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 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: Espressif Systems 1493 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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; (continues on next page) Espressif Systems 1494 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference (continued from previous page) 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 ); } 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. Espressif Systems 1495 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1496 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 2.10.10 FreeRTOS Supplemental Features ESP-IDF uses a modified version of FreeRTOS v10.4.3 that contains significant changes for SMP compatibility (see ESP-IDF FreeRTOS SMP Changes). However, in addition to ESP-IDF FreeRTOS, various features are also provided by ESP-IDF to supplement the features offered by FreeRTOS. This document describes these supplemental features added to ESP-IDF. This document is split into the following sections: Contents · FreeRTOS Supplemental Features Overview Ring Buffers ESP-IDF Tick and Idle 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. Espressif Systems 1497 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP-IDF Tick and Idle Hooks: ESP-IDF provides multiple custom tick interrupt hooks and idle task hooks that are more numerous and more flexible when compared to FreeRTOS tick and idle hooks. · 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. 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)); (continues on next page) Espressif Systems 1498 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference if (res != pdTRUE) { printf("Failed to send item\n"); } (continued from previous page) 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, }; //Actually send to the ring buffer for consumer to use res = xRingbufferSendComplete(buf_handle, &item); if (res != pdTRUE) { printf("Failed to send item\n"); } 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 (continues on next page) Espressif Systems 1499 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference vRingbufferReturnItem(buf_handle, (void *)item); } else { //Failed to receive item printf("Failed to receive item\n"); } (continued from previous page) 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() ... //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(), xRingbufferReceive- Espressif Systems 1500 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference UpToFromISR(), and vRingbufferReturnItemFromISR() Note: Two calls to RingbufferReceive[UpTo][FromISR]() are required if the bytes wraps around the end of the ring buffer. Sending to Ring Buffer The following diagrams illustrate the differences between No-Split 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. Fig. 30: Sending items to byte buffers Byte buffers treat data as a sequence of bytes and does not incur any overhead (no headers). As a result, all data sent to a byte buffer is merged into a single item. Referring to the diagram above, the 18, 3, and 27 byte items are sequentially written to the byte buffer and merged into a single item of 48 bytes. Using SendAcquire and SendComplete Items in No-Split buffers are acquired (by SendAcquire) in strict FIFO order and must be sent to the buffer by SendComplete for the data to be accessible by the consumer. Multiple items can be sent or acquired without calling SendComplete, and the items do not necessarily need to be completed in the order they were acquired. However, the receiving of data items must occur in FIFO order, therefore not calling SendComplete 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. 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 Espressif Systems 1501 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 31: SendAcquire/SendComplete items in No-Split ring buffers 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. Fig. 32: Wrap around in No-Split buffers No-Split buffers will only store an item in continuous free space and will not split an item under any 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. Espressif Systems Fig. 33: Wrap around in Allow-Split buffers 1502 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Fig. 35: Retrieving/Returning items in No-Split and Allow-Split ring buffers 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. 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. Espressif Systems 1503 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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); QueueSetHandle_t queue_set = xQueueCreateSet(3); //Add ring buffer to queue set if (xRingbufferAddToQueueSetRead(buf_handle, queue_set) != pdTRUE) { printf("Failed to add to queue set\n"); } ... //Block on queue set QueueSetMemberHandle_t 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 ... (continues on next page) Espressif Systems 1504 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference } else { ... } (continued from previous page) 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); //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. Espressif Systems 1505 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. ESP-IDF Tick and Idle Hooks FreeRTOS allows applications to provide a tick hook and an idle hook at compile time: · FreeRTOS tick hook can be enabled via the CONFIG_FREERTOS_USE_TICK_HOOK option. The application must provide the void vApplicationTickHook( void ) callback. · FreeRTOS idle hook can be enabled via the CONFIG_FREERTOS_USE_IDLE_HOOK option. The application must provide the void vApplicationIdleHook( void ) callback. However, the FreeRTOS tick hook and idle hook have the following draw backs: · The FreeRTOS hooks are registered at compile time · Only one of each hook can be registered · On multi-core targets, the FreeRTOS hooks are symmetric, meaning each CPUns tick interrupt and idle tasks ends up calling the same hook. Therefore, ESP-IDF tick and idle hooks are provided to supplement the features of FreeRTOS tick and idle hooks. The ESP-IDF hooks have the following features: · The hooks can be registered and deregistered at run-time · Multiple hooks can be registered (with a maximum of 8 hooks of each type per CPU) · On multi-core targets, the hooks can be asymmetric, meaning different hooks can be registered to each CPU ESP-IDF hooks can be registered and deregistered using the following API: · For tick hooks: Register using esp_register_freertos_tick_hook() or esp_register_freertos_tick_hook_for_cpu() Deregister using esp_deregister_freertos_tick_hook() or esp_deregister_freertos_tick_hook_for_cpu() · For idle hooks: Register using esp_register_freertos_idle_hook() or esp_register_freertos_idle_hook_for_cpu() Deregister using esp_deregister_freertos_idle_hook() or esp_deregister_freertos_idle_hook_for_cpu() Note: The tick interrupt stays active while the cache is disabled, therefore any tick hook (FreeRTOS or ESP-IDF) functions 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. Espressif Systems 1506 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1507 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1508 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1509 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 1510 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1511 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 1512 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1513 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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.10.11 Heap Memory Allocation Espressif Systems 1514 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1515 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1516 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 1517 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 Espressif Systems 1518 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1519 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1520 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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.) Espressif Systems 1521 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Note Please refer to following example for memory regions allowed for addition to heap based on an existing region (address range for demonstration purpose only): Existing region: 0x1000 <-> 0x3000 New region: 0x1000 <-> 0x3000 (Allowed) New region: 0x1000 <-> 0x2000 (Allowed) New region: 0x0000 <-> 0x1000 (Allowed) New region: 0x3000 <-> 0x4000 (Allowed) New region: 0x0000 <-> 0x2000 (NOT Allowed) New region: 0x0000 <-> 0x4000 (NOT Allowed) New region: 0x1000 <-> 0x4000 (NOT Allowed) New region: 0x2000 <-> 0x4000 (NOT Allowed) 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. Note Please refer to following example for memory regions allowed for addition to heap based on an existing region (address range for demonstration purpose only): Espressif Systems 1522 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Existing region: 0x1000 <-> 0x3000 New region: 0x1000 <-> 0x3000 (Allowed) New region: 0x1000 <-> 0x2000 (Allowed) New region: 0x0000 <-> 0x1000 (Allowed) New region: 0x3000 <-> 0x4000 (Allowed) New region: 0x0000 <-> 0x2000 (NOT Allowed) New region: 0x0000 <-> 0x4000 (NOT Allowed) New region: 0x1000 <-> 0x4000 (NOT Allowed) New region: 0x2000 <-> 0x4000 (NOT Allowed) 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() for the heap situated in that particular region. Calling free() involves finding the particular heap corresponding to the freed address, and then calling multi_heap_free() on that particular multi_heap instance. API Reference - Multi Heap API (Note: The multi heap API is used internally by the heap capabilities allocator. Most IDF programs will never need to call this API directly.) Header File · components/heap/include/multi_heap.h Functions void *multi_heap_aligned_alloc(multi_heap_handle_t heap, size_t size, size_t alignment) allocate a chunk of memory with specific alignment Return pointer to the memory allocated, NULL on failure Parameters · heap: Handle to a registered heap. · size: size in bytes of memory chunk · alignment: how the memory must be aligned Espressif Systems 1523 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. void multi_heap_set_lock(multi_heap_handle_t heap, void *lock) Associate a private lock pointer with a heap. Espressif Systems 1524 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 1525 Release v5.0-dev-2349-g4350e6fef8 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.10.12 Heap Memory Debugging Overview ESP-IDF integrates tools for requesting heap information, detecting heap corruption, and tracing memory leaks. These can help track down memory-related bugs. For general information about the heap memory allocator, see the Heap Memory Allocation page. Heap Information To obtain information about the state of the heap: · xPortGetFreeHeapSize() is a FreeRTOS function which returns the number of free bytes in the (data memory) heap. This is equivalent to calling heap_caps_get_free_size(MALLOC_CAP_8BIT). · heap_caps_get_free_size() can also be used to return the current free memory for different memory capabilities. · heap_caps_get_largest_free_block() can be used to return the largest free block in the heap. This is the largest single allocation which is currently possible. Tracking this value and comparing to total free heap allows you to detect heap fragmentation. · xPortGetMinimumEverFreeHeapSize() and the related heap_caps_get_minimum_free_size() can be used to track the heap 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 1526 Release v5.0-dev-2349-g4350e6fef8 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 1527 Release v5.0-dev-2349-g4350e6fef8 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 1528 Release v5.0-dev-2349-g4350e6fef8 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 1529 Release v5.0-dev-2349-g4350e6fef8 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 1530 Release v5.0-dev-2349-g4350e6fef8 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_DESTINATION1 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 1531 Release v5.0-dev-2349-g4350e6fef8 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 1532 Release v5.0-dev-2349-g4350e6fef8 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 1533 Release v5.0-dev-2349-g4350e6fef8 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 1534 Release v5.0-dev-2349-g4350e6fef8 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 1535 Release v5.0-dev-2349-g4350e6fef8 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.10.13 High Resolution Timer Overview Although FreeRTOS provides software timers, these timers have a few limitations: Espressif Systems 1536 Release v5.0-dev-2349-g4350e6fef8 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 the target. SYSTIMER is used for ESP32-S3. 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 1537 Release v5.0-dev-2349-g4350e6fef8 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 1538 Release v5.0-dev-2349-g4350e6fef8 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 1539 Release v5.0-dev-2349-g4350e6fef8 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 1540 Release v5.0-dev-2349-g4350e6fef8 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 void esp_timer_isr_dispatch_need_yield(void) Requests a context switch from a timer callback function. This only works for a timer that has an ISR dispatch method. The context switch will be called after all ISR dispatch timers have been processed. 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. Espressif Systems 1541 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Public Members esp_timer_cb_t callback Function to call when timer expires. void *arg Argument to pass to the callback. esp_timer_dispatch_t dispatch_method Call the callback from task or from ISR. const char *name Timer name, used in esp_timer_dump function. bool skip_unhandled_events Skip unhandled events for periodic timers. Type Definitions typedef struct esp_timer *esp_timer_handle_t Opaque type representing a single esp_timer. typedef void (*esp_timer_cb_t)(void *arg) Timer callback function type. Parameters · arg: pointer to opaque user-specific data Enumerations enum esp_timer_dispatch_t Method for dispatching timer callback. Values: ESP_TIMER_TASK Callback is called from timer task. ESP_TIMER_MAX Count of the methods for dispatching timer callback. 2.10.14 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. Espressif Systems 1542 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Parameters · us: Number of microseconds to pause void esp_rom_install_channel_putc(int channel, void (*putc))char c esp_rom_printf can print message to different channels simultaneously. This function can help install the low level putc function for esp_rom_printf. Parameters · channel: Channel number (startting from 1) · putc: Function pointer to the putc implementation. Set NULL can disconnect esp_rom_printf with putc. void esp_rom_install_uart_printf(void) Install UART1 as the default console channel, equivalent to esp_rom_install_channel_putc(1, esp_rom_uart_putc) soc_reset_reason_t esp_rom_get_reset_reason(int cpu_no) Get reset reason of CPU. Return Reset reason code (see in soc/reset_reasons.h) Parameters · cpu_no: CPU number void esp_rom_route_intr_matrix(int cpu_core, uint32_t periph_intr_id, uint32_t cpu_intr_num) Route peripheral interrupt sources to CPUns interrupt port by matrix. Usually therenre 4 steps to use an interrupt: 1. Route peripheral interrupt source to CPU. e.g. ETS_WIFI_MAC_INTR_SOURCE, ETS_WMAC_INUM) 2. Set interrupt handler for CPU 3. Enable CPU interupt 4. Enable peripheral interrupt esp_rom_route_intr_matrix(0, Parameters · cpu_core: The CPU number, which the peripheral interupt will inform to · periph_intr_id: The peripheral interrupt source number · cpu_intr_num: The CPU interrupt number uint32_t esp_rom_get_cpu_ticks_per_us(void) Get the real CPU ticks per us. Return CPU ticks per us 2.10.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. Espressif Systems 1543 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference The IPC (Inter-Processor Call) feature allows a particular CPU (the calling CPU) to trigger the execution of a callback function on another CPU (the target CPU). The IPC feature allows execution of a callback function on the target CPU in either a task context, or a High Priority Interrupt context (see High-Level Interrupts for more details). Depending on the context that the callback function is executed in, different restrictions apply to the implementation of the callback function. IPC in Task Context The IPC feature implements callback execution in a task context by creating an IPC task for each CPU during application startup. When the calling CPU needs to execute a callback on the target CPU, the callback will execute in the context of the target 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 Espressif Systems 1544 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · 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 Espressif Systems 1545 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference will busy-wait until esp_ipc_isr_release_other_cpu() is called. · esp_ipc_isr_release_other_cpu() resumes the target CPU. API Reference Header File · components/esp_system/include/esp_ipc.h Functions esp_err_t esp_ipc_call(uint32_t cpu_id, esp_ipc_func_t func, void *arg) Execute a callback on a given CPU. Execute a given callback on a particular CPU. The callback must be of type 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 Espressif Systems 1546 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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. Espressif Systems 1547 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference This function will resume the CPU stall feature that was previously paused by calling esp_ipc_isr_stall_pause(). Once resumed, calls to esp_ipc_isr_stall_other_cpu() and esp_ipc_isr_release_other_cpu() will have effect again. Type Definitions typedef void (*esp_ipc_isr_func_t)(void *arg) IPC ISR Callback. A callback of this type should be provided as an argument when calling esp_ipc_isr_asm_call() or esp_ipc_isr_asm_call_blocking(). 2.10.16 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. Internal peripheral interrupts Each Xtensa CPU core has its own set of six internal peripherals: · Three timer comparators · A performance monitor · Two software interrupts. Espressif Systems 1548 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 disabling the handlers for them, will cause the interrupt(s) to be triggered indefinitely, resulting therefore in a system crash. Espressif Systems 1549 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1550 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1551 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. ESP_INTR_FLAG_LEVEL4 Accept a Level 4 interrupt vector. ESP_INTR_FLAG_LEVEL5 Accept a Level 5 interrupt vector. Espressif Systems 1552 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1553 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.10.17 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. 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. Espressif Systems 1554 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1555 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1556 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 ESP_EARLY_LOGE(tag, format, ...) 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 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__. Espressif Systems 1557 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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 Espressif Systems 1558 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.10.18 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. 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. Espressif Systems 1559 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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). 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. Espressif Systems 1560 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. · 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 Espressif Systems 1561 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1562 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) ESP_RST_SDIO Reset over SDIO. Header File · components/esp_common/include/esp_idf_version.h Espressif Systems 1563 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1564 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Macros MAC2STR(a) MACSTR Enumerations enum esp_mac_type_t Values: ESP_MAC_WIFI_STA ESP_MAC_WIFI_SOFTAP ESP_MAC_BT Espressif Systems 1565 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_MAC_ETH ESP_MAC_IEEE802154 Header File · components/esp_hw_support/include/esp_chip_info.h Functions void esp_chip_info(esp_chip_info_t *out_info) Fill an esp_chip_info_t structure with information about the chip. Parameters · [out] out_info: structure to be filled Structures struct esp_chip_info_t The structure represents information about the chip. Public Members esp_chip_model_t model chip model, one of esp_chip_model_t uint32_t features bit mask of CHIP_FEATURE_x feature flags uint8_t cores number of CPU cores uint8_t revision chip revision number Macros CHIP_FEATURE_EMB_FLASH Chip has embedded flash memory. CHIP_FEATURE_WIFI_BGN Chip has 2.4GHz WiFi. CHIP_FEATURE_BLE Chip has Bluetooth LE. CHIP_FEATURE_BT Chip has Bluetooth Classic. CHIP_FEATURE_IEEE802154 Chip has IEEE 802.15.4. CHIP_FEATURE_EMB_PSRAM Chip has embedded psram. Enumerations enum esp_chip_model_t Chip models. Values: CHIP_ESP32 = 1 ESP32. Espressif Systems 1566 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference CHIP_ESP32S2 = 2 ESP32-S2. CHIP_ESP32S3 = 9 ESP32-S3. CHIP_ESP32C3 = 5 ESP32-C3. CHIP_ESP32H2 = 6 ESP32-H2. CHIP_ESP32C2 = 12 ESP32-C2. Header File · components/esp_hw_support/include/esp_cpu.h Functions static void *esp_cpu_get_sp(void) Read current stack pointer address. void esp_cpu_stall(int cpu_id) Stall CPU using RTC controller. Parameters · cpu_id: ID of the CPU to stall (0 = PRO, 1 = APP) void esp_cpu_unstall(int cpu_id) Un-stall CPU using RTC controller. Parameters · cpu_id: ID of the CPU to un-stall (0 = PRO, 1 = APP) void esp_cpu_reset(int cpu_id) Reset CPU using RTC controller. Parameters · cpu_id: ID of the CPU to reset (0 = PRO, 1 = APP) bool esp_cpu_in_ocd_debug_mode(void) Returns true if a JTAG debugger is attached to CPU OCD (on chip debug) port. Note If oMake exception and panic handlers JTAG/OCD awarepis disabled, this function always returns false. static esp_cpu_ccount_t esp_cpu_get_ccount(void) static void esp_cpu_set_ccount(esp_cpu_ccount_t val) void esp_cpu_configure_region_protection(void) Configure CPU to disable access to invalid memory regions. esp_err_t esp_cpu_set_watchpoint(int no, void *adr, int size, int flags) Set a watchpoint to break/panic when a certain memory range is accessed. Return ESP_ERR_INVALID_ARG on invalid arg, ESP_OK otherwise Warning The ESP32 watchpoint hardware watches a region of bytes by effectively masking away the lower n bits for a region with size 2^n. If adr does not have zero for these lower n bits, you may not be watching the region you intended. Parameters · no: Watchpoint number. On the ESP32, this can be 0 or 1. · adr: Base address to watch · size: Size of the region, starting at the base address, to watch. Must be one of 2^n, with n in [0..6]. · flags: One of ESP_CPU_WATCHPOINT_* flags Espressif Systems 1567 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference void esp_cpu_clear_watchpoint(int no) Clear a watchpoint. Parameters · no: Watchpoint to clear Macros ESP_CPU_WATCHPOINT_LOAD ESP_CPU_WATCHPOINT_STORE ESP_CPU_WATCHPOINT_ACCESS Type Definitions typedef uint32_t esp_cpu_ccount_t 2.10.19 SoC Capabilities This section lists definitions of the ESP32-S3ns SoC hardware capabilities. These definitions are commonly used in IDF to control which hardware dependent features are supported and thus compiled into the binary. Note: These defines are currently not considered to be part of the public API, and may be changed at any time. API Reference Header File · components/soc/esp32s3/include/soc/soc_caps.h Macros SOC_ADC_SUPPORTED SOC_PCNT_SUPPORTED SOC_WIFI_SUPPORTED SOC_TWAI_SUPPORTED SOC_GDMA_SUPPORTED SOC_LCDCAM_SUPPORTED SOC_MCPWM_SUPPORTED SOC_DEDICATED_GPIO_SUPPORTED SOC_CPU_CORES_NUM SOC_CACHE_SUPPORT_WRAP SOC_ULP_SUPPORTED SOC_RISCV_COPROC_SUPPORTED SOC_BT_SUPPORTED SOC_BLUEDROID_SUPPORTED SOC_USB_OTG_SUPPORTED SOC_USB_SERIAL_JTAG_SUPPORTED SOC_CCOMP_TIMER_SUPPORTED Espressif Systems 1568 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SOC_ASYNC_MEMCPY_SUPPORTED SOC_SUPPORTS_SECURE_DL_MODE SOC_EFUSE_KEY_PURPOSE_FIELD SOC_SDMMC_HOST_SUPPORTED SOC_RTC_FAST_MEM_SUPPORTED SOC_RTC_SLOW_MEM_SUPPORTED SOC_PSRAM_DMA_CAPABLE SOC_XT_WDT_SUPPORTED SOC_I2S_SUPPORTED SOC_RMT_SUPPORTED SOC_SIGMADELTA_SUPPORTED SOC_SUPPORT_COEXISTENCE SOC_TEMP_SENSOR_SUPPORTED SOC_AES_SUPPORTED SOC_MPI_SUPPORTED SOC_SHA_SUPPORTED SOC_HMAC_SUPPORTED SOC_DIG_SIGN_SUPPORTED SOC_FLASH_ENC_SUPPORTED SOC_SECURE_BOOT_SUPPORTED SOC_APPCPU_HAS_CLOCK_GATING_BUG SOC_ADC_RTC_CTRL_SUPPORTED < SAR ADC Module SOC_ADC_DIG_CTRL_SUPPORTED SOC_ADC_ARBITER_SUPPORTED SOC_ADC_FILTER_SUPPORTED SOC_ADC_MONITOR_SUPPORTED SOC_ADC_PERIPH_NUM SOC_ADC_CHANNEL_NUM(PERIPH_NUM) SOC_ADC_MAX_CHANNEL_NUM Digital SOC_ADC_DIGI_CONTROLLER_NUM SOC_ADC_PATT_LEN_MAX SOC_ADC_DIGI_MAX_BITWIDTH F_sample = F_digi_con / 2 / interval. F_digi_con = 5M for now. 30 <= interva <= 4095 SOC_ADC_SAMPLE_FREQ_THRES_HIGH SOC_ADC_SAMPLE_FREQ_THRES_LOW RTC SOC_ADC_MAX_BITWIDTH Calibration Espressif Systems 1569 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SOC_ADC_CALIBRATION_V1_SUPPORTED support HW offset calibration version 1 SOC_APB_BACKUP_DMA SOC_DS_SIGNATURE_MAX_BIT_LEN The maximum length of a Digital Signature in bits. SOC_DS_KEY_PARAM_MD_IV_LENGTH Initialization vector (IV) length for the RSA key parameter message digest (MD) in bytes. SOC_DS_KEY_CHECK_MAX_WAIT_US Maximum wait time for DS parameter decryption key. If overdue, then key error. See TRM DS chapter for more details SOC_GDMA_GROUPS SOC_GDMA_PAIRS_PER_GROUP SOC_GDMA_SUPPORT_PSRAM SOC_GDMA_PSRAM_MIN_ALIGN SOC_GPIO_PORT SOC_GPIO_PIN_COUNT SOC_GPIO_SUPPORT_RTC_INDEPENDENT SOC_GPIO_SUPPORT_FORCE_HOLD SOC_GPIO_VALID_GPIO_MASK SOC_GPIO_VALID_OUTPUT_GPIO_MASK SOC_GPIO_SUPPORT_SLP_SWITCH SOC_DEDIC_GPIO_OUT_CHANNELS_NUM 8 outward channels on each CPU core SOC_DEDIC_GPIO_IN_CHANNELS_NUM 8 inward channels on each CPU core SOC_DEDIC_GPIO_OUT_AUTO_ENABLE Dedicated GPIO output attribution is enabled automatically SOC_I2C_NUM SOC_I2C_FIFO_LEN I2C hardware FIFO depth SOC_I2C_SUPPORT_SLAVE SOC_I2C_SUPPORT_HW_FSM_RST SOC_I2C_SUPPORT_HW_CLR_BUS SOC_I2C_SUPPORT_XTAL SOC_I2C_SUPPORT_RTC SOC_I2S_NUM SOC_I2S_HW_VERSION_2 SOC_I2S_SUPPORTS_PCM SOC_I2S_SUPPORTS_PDM SOC_I2S_SUPPORTS_PDM_TX SOC_I2S_SUPPORTS_PDM_RX SOC_I2S_SUPPORTS_PDM_CODEC Espressif Systems 1570 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SOC_I2S_SUPPORTS_TDM SOC_MCPWM_GROUPS 2 MCPWM groups on the chip (i.e., the number of independent MCPWM peripherals) SOC_MCPWM_TIMERS_PER_GROUP The number of timers that each group has. SOC_MCPWM_OPERATORS_PER_GROUP The number of operators that each group has. SOC_MCPWM_COMPARATORS_PER_OPERATOR The number of comparators that each operator has. SOC_MCPWM_GENERATORS_PER_OPERATOR The number of generators that each operator has. SOC_MCPWM_TRIGGERS_PER_OPERATOR The number of triggers that each operator has. SOC_MCPWM_GPIO_FAULTS_PER_GROUP The number of fault signal detectors that each group has. SOC_MCPWM_CAPTURE_TIMERS_PER_GROUP The number of capture timers that each group has. SOC_MCPWM_CAPTURE_CHANNELS_PER_TIMER The number of capture channels that each capture timer has. SOC_MCPWM_GPIO_SYNCHROS_PER_GROUP The number of GPIO synchros that each group has. SOC_MCPWM_SWSYNC_CAN_PROPAGATE Software sync event can be routed to its output. SOC_MCPWM_BASE_CLK_HZ Base Clock frequency of 160MHz. SOC_PCNT_GROUPS SOC_PCNT_UNITS_PER_GROUP SOC_PCNT_CHANNELS_PER_UNIT SOC_PCNT_THRES_POINT_PER_UNIT SOC_RMT_GROUPS One RMT group SOC_RMT_TX_CANDIDATES_PER_GROUP Number of channels that capable of Transmit in each group SOC_RMT_RX_CANDIDATES_PER_GROUP Number of channels that capable of Receive in each group SOC_RMT_CHANNELS_PER_GROUP Total 8 channels SOC_RMT_MEM_WORDS_PER_CHANNEL Each channel owns 48 words memory (1 word = 4 Bytes) SOC_RMT_SUPPORT_RX_PINGPONG Support Ping-Pong mode on RX path SOC_RMT_SUPPORT_RX_DEMODULATION Support signal demodulation on RX path (i.e. remove carrier) SOC_RMT_SUPPORT_TX_ASYNC_STOP Support stop transmission asynchronously Espressif Systems 1571 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SOC_RMT_SUPPORT_TX_LOOP_COUNT Support transmit specified number of cycles in loop mode SOC_RMT_SUPPORT_TX_LOOP_AUTO_STOP Hardware support of auto-stop in loop mode SOC_RMT_SUPPORT_TX_SYNCHRO Support coordinate a group of TX channels to start simultaneously SOC_RMT_SUPPORT_TX_CARRIER_ALWAYS_ON TX carrier can be modulated all the time SOC_RMT_SUPPORT_XTAL Support set XTAL clock as the RMT clock source SOC_RMT_SUPPORT_DMA RMT peripheral can connect to DMA channel SOC_LCD_I80_SUPPORTED Intel 8080 LCD is supported SOC_LCD_RGB_SUPPORTED RGB LCD is supported SOC_LCD_I80_BUSES Has one LCD Intel 8080 bus SOC_LCD_RGB_PANELS Support one RGB LCD panel SOC_LCD_I80_BUS_WIDTH Intel 8080 bus width SOC_LCD_RGB_DATA_WIDTH Number of LCD data lines SOC_RTC_CNTL_CPU_PD_DMA_BUS_WIDTH SOC_RTC_CNTL_CPU_PD_REG_FILE_NUM SOC_RTC_CNTL_CPU_PD_DMA_ADDR_ALIGN SOC_RTC_CNTL_CPU_PD_DMA_BLOCK_SIZE SOC_RTC_CNTL_CPU_PD_RETENTION_MEM_SIZE SOC_RTC_CNTL_TAGMEM_PD_DMA_BUS_WIDTH SOC_RTC_CNTL_TAGMEM_PD_DMA_ADDR_ALIGN SOC_RTCIO_PIN_COUNT SOC_RTCIO_INPUT_OUTPUT_SUPPORTED SOC_RTCIO_HOLD_SUPPORTED SOC_RTCIO_WAKE_SUPPORTED SOC_SIGMADELTA_NUM SOC_SIGMADELTA_CHANNEL_NUM SOC_SPI_PERIPH_NUM SOC_SPI_PERIPH_CS_NUM(i) SOC_SPI_MAXIMUM_BUFFER_SIZE SOC_SPI_SUPPORT_DDRCLK SOC_SPI_SLAVE_SUPPORT_SEG_TRANS SOC_SPI_SUPPORT_CD_SIG Espressif Systems 1572 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SOC_SPI_SUPPORT_CONTINUOUS_TRANS SOC_SPI_SUPPORT_SLAVE_HD_VER2 SOC_SPI_PERIPH_SUPPORT_MULTILINE_MODE(host_id) SOC_SPI_PERIPH_SUPPORT_CONTROL_DUMMY_OUT SOC_MEMSPI_IS_INDEPENDENT SOC_SPI_MAX_PRE_DIVIDER SOC_SPI_SUPPORT_OCT SOC_SPIRAM_SUPPORTED SOC_TOUCH_VERSION_2 SOC_SYSTIMER_COUNTER_NUM SOC_SYSTIMER_ALARM_NUM SOC_SYSTIMER_BIT_WIDTH_LO SOC_SYSTIMER_BIT_WIDTH_HI SOC_SYSTIMER_FIXED_TICKS_US SOC_SYSTIMER_INT_LEVEL SOC_SYSTIMER_ALARM_MISS_COMPENSATE SOC_TIMER_GROUPS SOC_TIMER_GROUP_TIMERS_PER_GROUP SOC_TIMER_GROUP_COUNTER_BIT_WIDTH SOC_TIMER_GROUP_SUPPORT_XTAL SOC_TIMER_GROUP_TOTAL_TIMERS SOC_TOUCH_SENSOR_NUM SOC_TOUCH_PROXIMITY_CHANNEL_NUM SOC_TOUCH_PROXIMITY_MEAS_DONE_SUPPORTED SOC_TOUCH_PAD_THRESHOLD_MAX If set touch threshold max value, The touch sensor cannt be in touched status SOC_TOUCH_PAD_MEASURE_WAIT_MAX The timer frequency is 8Mhz, the max value is 0xff SOC_UART_NUM SOC_UART_FIFO_LEN The UART hardware FIFO length SOC_UART_BITRATE_MAX Max bit rate supported by UART SOC_UART_SUPPORT_FSM_TX_WAIT_SEND SOC_UART_SUPPORT_WAKEUP_INT Support UART wakeup interrupt SOC_UART_SUPPORT_RTC_CLK Support RTC clock as the clock source SOC_UART_SUPPORT_XTAL_CLK Support XTAL clock as the clock source SOC_UART_REQUIRE_CORE_RESET Espressif Systems 1573 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SOC_USB_PERIPH_NUM SOC_SHA_DMA_MAX_BUFFER_SIZE SOC_SHA_SUPPORT_DMA SOC_SHA_SUPPORT_RESUME SOC_SHA_GDMA SOC_SHA_SUPPORT_SHA1 SOC_SHA_SUPPORT_SHA224 SOC_SHA_SUPPORT_SHA256 SOC_SHA_SUPPORT_SHA384 SOC_SHA_SUPPORT_SHA512 SOC_SHA_SUPPORT_SHA512_224 SOC_SHA_SUPPORT_SHA512_256 SOC_SHA_SUPPORT_SHA512_T SOC_RSA_MAX_BIT_LEN SOC_AES_SUPPORT_DMA SOC_AES_GDMA SOC_AES_SUPPORT_AES_128 SOC_AES_SUPPORT_AES_256 SOC_PM_SUPPORT_EXT_WAKEUP SOC_PM_SUPPORT_WIFI_WAKEUP SOC_PM_SUPPORT_BT_WAKEUP SOC_PM_SUPPORT_CPU_PD SOC_PM_SUPPORT_TAGMEM_PD SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP Supports waking up from touch pad trigger SOC_PM_SUPPORT_DEEPSLEEP_CHECK_STUB_ONLY SOC_SECURE_BOOT_V2_RSA SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS SOC_SUPPORT_SECURE_BOOT_REVOKE_KEY SOC_FLASH_ENCRYPTED_XTS_AES_BLOCK_MAX SOC_FLASH_ENCRYPTION_XTS_AES SOC_FLASH_ENCRYPTION_XTS_AES_128 SOC_FLASH_ENCRYPTION_XTS_AES_256 SOC_WIFI_HW_TSF SOC_PHY_DIG_REGS_MEM_SIZE SOC_MAC_BB_PD_MEM_SIZE SOC_WIFI_LIGHT_SLEEP_CLK_WIDTH SOC_SPI_MEM_SUPPORT_AUTO_WAIT_IDLE Espressif Systems 1574 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND SOC_SPI_MEM_SUPPORT_AUTO_RESUME SOC_SPI_MEM_SUPPORT_SW_SUSPEND SOC_SPI_MEM_SUPPORT_OPI_MODE SOC_SPI_MEM_SUPPORT_TIME_TUNING SOC_COEX_HW_PTI SOC_SDMMC_USE_GPIO_MATRIX SOC_SDMMC_NUM_SLOTS SOC_SDMMC_SUPPORT_XTAL_CLOCK SOC_TEMPERATURE_SENSOR_SUPPORT_FAST_RC 2.10.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. Espressif Systems 1575 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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. Espressif Systems 1576 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · If the application has not been confirmed, the state remains ESP_OTA_IMG_PENDING_VERIFY, and the next boot it will be changed to ESP_OTA_IMG_ABORTED. That will prevent re-boot of this application. There will be a rollback to the previous working application. Unexpected Reset If a power loss or an unexpected crash occurs at the time of the first boot of a new application, it will roll back the application. Recommendation: Perform the self-test procedure as quickly as possible, to prevent rollback due to power loss. Only OTA partitions can be rolled back. Factory partition is not rolled back. Booting invalid/aborted apps Booting an application which was previously set to ESP_OTA_IMG_INVALID or ESP_OTA_IMG_ABORTED is possible: · Get the last invalid application partition esp_ota_get_last_invalid_partition(). · Pass the received partition to esp_ota_set_boot_partition(), this will update the otadata. · Restart esp_restart(). The bootloader will boot the specified application. To determine if self-tests should be run during startup of an application, call the esp_ota_get_state_partition() function. If result is ESP_OTA_IMG_PENDING_VERIFY then self-testing and subsequent confirmation of operability is required. Where the states are set A brief description of where the states are set: · ESP_OTA_IMG_VALID state is set by esp_ota_mark_app_valid_cancel_rollback() 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. Espressif Systems 1577 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. 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- Espressif Systems 1578 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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) · 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: Espressif Systems 1579 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference otatool.py [command-args] [subcommand] [subcommand-args] - command-args - these are arguments that are needed for executing the main command (parttool.py), mostly pertaining to the target device - subcommand - this is the operation to be performed - subcommand-args - these are arguments that are specific to the chosen operation # Erase otadata, resetting the device to factory app otatool.py --port "/dev/ttyUSB1" erase_otadata # Erase contents of OTA app slot 0 otatool.py --port "/dev/ttyUSB1" erase_ota_partition --slot 0 # Switch boot partition to that of app slot 1 otatool.py --port "/dev/ttyUSB1" switch_ota_partition --slot 1 # Read OTA partition 'ota_3' and save contents to a file named 'ota_3.bin' otatool.py --port "/dev/ttyUSB1" read_ota_partition --name=ota_3 --output=ota_3.bin More information can be obtained by specifying help as argument: # Display possible subcommands and show main command argument descriptions otatool.py --help # Show descriptions for specific subcommand arguments otatool.py [subcommand] --help See also · 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 Espressif Systems 1580 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · size: Size of the buffer esp_err_t esp_ota_begin(const esp_partition_t *partition, size_t image_size, esp_ota_handle_t *out_handle) Commence an OTA update writing to the specified partition. The specified partition is erased to the specified image size. If image size is not yet known, pass OTA_SIZE_UNKNOWN which will cause the entire partition to be erased. On success, this function allocates memory that remains in use until esp_ota_end() is called with the returned handle. Note: If the rollback option is enabled and the running application has the ESP_OTA_IMG_PENDING_VERIFY state then it will lead to the ESP_ERR_OTA_ROLLBACK_INVALID_STATE error. Confirm the running app before to run download a new app, use esp_ota_mark_app_valid_cancel_rollback() function for it (this should be done as early as possible when you first download a new application). Return · ESP_OK: OTA operation commenced successfully. · ESP_ERR_INVALID_ARG: partition or out_handle arguments were NULL, or partition 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 Espressif Systems 1581 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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). Espressif Systems 1582 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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. Espressif Systems 1583 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference esp_err_t esp_ota_mark_app_invalid_rollback_and_reboot(void) This function is called to roll back to the previously workable app with reboot. If rollback is successful then device will reset else API will return with error code. Checks applications on a flash drive that can be booted in case of rollback. If the flash does not have at least one app (except the running app) then rollback is not possible. Return · ESP_FAIL: if not successful. · ESP_ERR_OTA_ROLLBACK_FAILED: The rollback is not possible due to flash does not have any apps. const esp_partition_t *esp_ota_get_last_invalid_partition(void) Returns last partition with invalid state (ESP_OTA_IMG_INVALID or ESP_OTA_IMG_ABORTED). Return partition. esp_err_t esp_ota_get_state_partition(const esp_partition_t *partition, esp_ota_img_states_t 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 Espressif Systems 1584 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Macros OTA_SIZE_UNKNOWN Used for esp_ota_begin() if new image size is unknown OTA_WITH_SEQUENTIAL_WRITES Used for esp_ota_begin() if new image size is unknown and erase can be done in incremental manner (assuming write operation is in continuous sequence) ESP_ERR_OTA_BASE Base error code for ota_ops api ESP_ERR_OTA_PARTITION_CONFLICT Error if request was to write or erase the current running partition ESP_ERR_OTA_SELECT_INFO_INVALID Error if OTA data partition contains invalid content ESP_ERR_OTA_VALIDATE_FAILED Error if OTA app image is invalid ESP_ERR_OTA_SMALL_SEC_VER Error if the firmware has a secure version less than the running firmware. ESP_ERR_OTA_ROLLBACK_FAILED Error if flash does not have valid firmware in passive partition and hence rollback is not possible ESP_ERR_OTA_ROLLBACK_INVALID_STATE Error if current active firmware is still marked in pending validation state (ESP_OTA_IMG_PENDING_VERIFY), essentially first boot of firmware image post upgrade and hence firmware upgrade is not possible Type Definitions typedef uint32_t esp_ota_handle_t Opaque handle for an application OTA update. esp_ota_begin() returns a handle which is then used for subsequent calls to esp_ota_write() and esp_ota_end(). 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.10.21 Performance Monitor The Performance Monitor component provides APIs to use ESP32-S3 internal performance counters to profile functions and applications. Espressif Systems 1585 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Fig. 37: How to Debug When OTA Fails (click to enlarge) Espressif Systems 1586 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Application Example An example which combines performance monitor is provided in examples/system/perfmon directory. This example initializes the performance monitor structure and execute them with printing the statistics. High level API Reference Header Files · perfmon/include/perfmon.h API Reference Header File · components/perfmon/include/xtensa_perfmon_access.h Functions esp_err_t xtensa_perfmon_init(int id, uint16_t select, uint16_t mask, int kernelcnt, int tracelevel) Init Performance Monitoor. Initialize performance monitor register with define values Return · ESP_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 Espressif Systems 1587 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1588 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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.10.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: Espressif Systems 1589 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 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 1590 Release v5.0-dev-2349-g4350e6fef8 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 cpp:member:uart_config_t::use_ref_tick. · 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 rmt_config_t::flags and macro RMT_CHANNEL_FLAGS_AWARE_DFS. Espressif Systems 1591 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · GPTimer: if APB is used as the clock source. See gptimer_config_t::clk_src. · TSENS: XTAL or RTC_8M is used as a clock source. So, APB frequency changing will not influence it. 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 · 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 1592 Release v5.0-dev-2349-g4350e6fef8 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 1593 Release v5.0-dev-2349-g4350e6fef8 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 1594 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.10.23 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() 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()). Espressif Systems 1595 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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() · pthread_rwlock_rdlock() · pthread_rwlock_wrlock() · pthread_rwlock_unlock() Espressif Systems 1596 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 1597 Release v5.0-dev-2349-g4350e6fef8 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 1598 Release v5.0-dev-2349-g4350e6fef8 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.10.24 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. Espressif Systems 1599 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference API Reference Header File · components/esp_hw_support/include/esp_random.h Functions uint32_t esp_random(void) Get one random 32-bit word from hardware RNG. If Wi-Fi or Bluetooth are enabled, this function returns true random numbers. In other situations, if true random numbers are required then consult the ESP-IDF Programming 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: Espressif Systems 1600 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference #include <sys/random.h> ssize_t getrandom(void *buf, size_t buflen, unsigned int flags); This function is implemented by calling esp_fill_random() internally. The flags argument is ignored, this function is always non-blocking but the strength of any random numbers is dependent on the same conditions described above. Return value is -1 (with errno set to EFAULT) if the buf argument is NULL, and equal to buflen otherwise. 2.10.25 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]. Espressif Systems 1601 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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_deep_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 Espressif Systems 1602 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference EXT0 and EXT1 wakeup sources, which can only be used with RTC IOs, this wakeup source can be used with any IO (RTC or digital). esp_sleep_enable_gpio_wakeup() function can be used to enable this wakeup source. Warning: Before entering light sleep mode, check if any GPIO pin to be driven is part of the VDD_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. Espressif Systems 1603 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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); 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 · protocols/sntp: the implementation of basic functionality of deep sleep, where ESP module is periodically waken up to retrieve time from NTP server. · wifi/power_save: the implementation of modem sleep example. · system/deep_sleep: the 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_deep_sleep_start/esp_light_sleep_start function. Return · ESP_OK on success Espressif Systems 1604 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · ESP_ERR_INVALID_STATE if trigger was not active Parameters · source: - number of source to disable of type esp_sleep_source_t esp_err_t esp_sleep_enable_ulp_wakeup(void) Enable wakeup by ULP coprocessor. Note In revisions 0 and 1 of the ESP32, ULP wakeup source cannot be used when RTC_PERIPH power domain is forced to be powered on (ESP_PD_OPTION_ON) or when ext0 wakeup source is used. Return · ESP_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_deep_sleep_start/esp_light_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 Espressif Systems 1605 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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) 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_deep_sleep_start/esp_light_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 func- tionality can be used in this bit map: 0,2,4,12-15,25-27,32-39. · mode: select logic function used to determine wakeup condition: ESP_EXT1_WAKEUP_ALL_LOW: wake up when all selected GPIOs are low ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high esp_err_t esp_sleep_enable_gpio_wakeup(void) Enable wakeup from light sleep using GPIOs. Each GPIO supports wakeup function, which can be triggered on either low level or high level. Unlike EXT0 and EXT1 wakeup sources, this method can be used both for all IOs: RTC IOs and digital IOs. It can only be used to wakeup from light sleep though. To enable wakeup, first call gpio_wakeup_enable, specifying gpio number and wakeup level, for each GPIO which is used for wakeup. Then call this function to enable wakeup feature. Note In revisions 0 and 1 of the ESP32, GPIO wakeup source can not be used together with touch or ULP wakeup sources. Return · ESP_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. Espressif Systems 1606 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return · ESP_OK on success esp_err_t esp_sleep_disable_wifi_wakeup(void) Disable wakeup by WiFi MAC. Return · ESP_OK on success 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) Espressif Systems 1607 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference void esp_wake_deep_sleep(void) Default stub to run on wake from deep sleep. Allows for executing code immediately on wake from sleep, before the software bootloader or ESP-IDF app has started up. This function is weak-linked, so you can implement your own version to run code immediately when the chip wakes from sleep. See docs/deep-sleep-stub.rst for details. void esp_set_deep_sleep_wake_stub(esp_deep_sleep_wake_stub_fn_t new_stub) Install a new stub at runtime to run on wake from deep sleep. If implementing esp_wake_deep_sleep() then it is not necessary to call this function. However, it is possible to call this function to substitute a different deep sleep stub. Any function used as a deep sleep stub must be marked RTC_IRAM_ATTR, and must obey the same rules given for esp_wake_deep_sleep(). esp_deep_sleep_wake_stub_fn_t esp_get_deep_sleep_wake_stub(void) Get current wake from deep sleep stub. Return Return current wake from deep sleep stub, or NULL if no stub is installed. void esp_default_wake_deep_sleep(void) The default esp-idf-provided esp_wake_deep_sleep() stub. See docs/deep-sleep-stub.rst for details. void esp_deep_sleep_disable_rom_logging(void) Disable logging from the ROM code after deep sleep. Using LSB of RTC_STORE4. 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. Espressif Systems 1608 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_EXT1_WAKEUP_ANY_HIGH = 1 Wake the chip when any of the selected GPIOs go high. enum esp_sleep_pd_domain_t Power domains which can be powered down in sleep mode. Values: ESP_PD_DOMAIN_RTC_PERIPH RTC IO, sensors and ULP co-processor. ESP_PD_DOMAIN_RTC_SLOW_MEM RTC slow memory. ESP_PD_DOMAIN_RTC_FAST_MEM RTC fast memory. ESP_PD_DOMAIN_XTAL XTAL oscillator. ESP_PD_DOMAIN_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. Espressif Systems 1609 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ESP_SLEEP_WAKEUP_ULP Wakeup caused by ULP program. ESP_SLEEP_WAKEUP_GPIO Wakeup caused by GPIO (light sleep only) ESP_SLEEP_WAKEUP_UART Wakeup caused by UART (light sleep only) ESP_SLEEP_WAKEUP_WIFI Wakeup caused by WIFI (light sleep only) ESP_SLEEP_WAKEUP_COCPU Wakeup caused by COCPU int. ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG Wakeup caused by COCPU crash. ESP_SLEEP_WAKEUP_BT Wakeup caused by BT (light sleep only) 2.10.26 System Time Overview System time can be kept using either one time source or two time sources simultaneously. The choice depends on the application purpose and accuracy requirements for system time. There are the following two time sources: · RTC timer: Allows keeping the system time during any resets and sleep modes, only the power-up reset leads to resetting the RTC timer. The frequency deviation depends on an RTC Clock Source and affects accuracy only in sleep modes, in which case the time will be measured at 6.6667 us resolution. · High-resolution timer: Not available during any reset and sleep modes. The reason for using this timer is to achieve greater accuracy. It uses the APB_CLK clock source (typically 80 MHz), which has a frequency deviation of less than ±10 ppm. Time will be measured at 1 us resolution. The settings for the system time source are as follows: · RTC and high-resolution timer (default) · RTC · High-resolution timer · None It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure CONFIG_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. Espressif Systems 1610 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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 difftime gmtime localtime mktime strftime adjtime* * 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: Espressif Systems 1611 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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(); 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 Standard Toolchain Setup for Linux and macOS. 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/ xtensa-esp32-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. Espressif Systems 1612 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1613 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint32_t sntp_get_sync_interval(void) Get the sync interval of SNTP operation. Return the sync interval bool sntp_restart(void) Restart SNTP. Return True - Restart False - SNTP was not initialized yet Type Definitions typedef void (*sntp_sync_time_cb_t)(struct timeval *tv) SNTP callback function for notifying about time sync event. Parameters · tv: Time received from SNTP server. Enumerations enum sntp_sync_mode_t SNTP time update mode. Values: SNTP_SYNC_MODE_IMMED Update system time immediately when receiving a response from the SNTP server. SNTP_SYNC_MODE_SMOOTH Smooth time updating. Time error is gradually reduced using adjtime function. If the difference between SNTP response time and system time is large (more than 35 minutes) then update immediately. enum sntp_sync_status_t SNTP sync status. Values: SNTP_SYNC_STATUS_RESET SNTP_SYNC_STATUS_COMPLETED SNTP_SYNC_STATUS_IN_PROGRESS 2.10.27 The Async memcpy API 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. Espressif Systems 1614 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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; } // 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 Espressif Systems 1615 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 · [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 Espressif Systems 1616 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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.10.28 ULP Coprocessor programming The Ultra Low Power (ULP) coprocessor is a simple finite state machine (FSM) 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 the 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. This coprocessor is referred to as ULP FSM in ESP-IDF. ESP32-S3 provides a second type of ULP coprocessor which is based on a RISC-V instruction set architecture. For details regarding ULP RISC-V refer ULP-RISC-V Coprocessor. Installing the Toolchain The ULP FSM 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 FSM toolchain will already be installed. Programming ULP FSM The ULP FSM can be programmed using the supported instruction set. Alternatively, the ULP FSM coprocessor can also be programmed using C Macros on the main CPU. Theses two methods are described in the following section: ESP32-S3 ULP coprocessor instruction set This document provides details about the instructions used by ESP32-S3 ULP FSM coprocessor assembler. ULP FSM coprocessor has 4 16-bit general purpose registers, labeled R0, R1, R2, R3. It also has an 8-bit counter register (stage_cnt) which can be used to implement loops. Stage count register is accessed using special instructions. Espressif Systems 1617 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ULP coprocessor can access 8k bytes of RTC_SLOW_MEM memory region. Memory is addressed in 32-bit word units. It can also access peripheral registers in RTC_CNTL, RTC_IO, and SENS peripherals. All instructions are 32-bit. Jump instructions, ALU instructions, peripheral register and memory access instructions are executed in 1 cycle. Instructions which work with peripherals (TSENS, ADC, I2C) take variable number of cycles, depending on peripheral operation. The instruction syntax is case insensitive. Upper and lower case letters can be used and intermixed arbitrarily. This is true both for register names and instruction names. Note about addressing ESP32-S3 ULP FSM coprocessorns JUMP, ST, LD family of instructions expect the address argument to be expressed in the following way depending on the type of address argument used: · When the address argument is presented as a label then the instruction expects the address to be expressed as 32-bit words. Consider the following example program: entry: loop: NOP NOP NOP NOP MOVE R1, loop JUMP R1 When this program is assembled and linked, address of label loop will be equal to 16 (expressed in bytes). However JUMP instruction expects the address stored in register R1 to be expressed in 32-bit words. To account for this common use case, the assembler will convert the address of label loop from bytes to words, when generating the MOVE instruction. Hence, the code generated code will be equivalent to: 0000 0004 0008 000c 0010 0014 NOP NOP NOP NOP MOVE R1, 4 JUMP R1 · The other case is when the argument of MOVE instruction is not a label but a constant. In this case assembler will use the value as is, without any conversion: .set MOVE val, 0x10 R1, val In this case, value loaded into R1 will be 0x10. However, when an immediate value is used as an offset in LD and ST instructions, the assembler considers the address argument in bytes and converts it to 32-bit words before executing the instruction: ST R1, R2, 4 // offset = 4 bytes; Mem[R2 + 4 / 4] = R1 In this case, the value in R1 is stored at the memory location pointed by [R2 + offset / 4] Consider the following code: array: .global array .long 0 .long 0 .long 0 .long 0 MOVE R1, array MOVE R2, 0x1234 ST R2, R1, 0 // write value of R2 into the first array element, // i.e. array[0] (continues on next page) Espressif Systems 1618 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ST R2, R1, 4 ADD R1, R1, 2 ST R2, R1, 0 (continued from previous page) // write value of R2 into the second array element // (4 byte offset), i.e. array[1] // this increments address by 2 words (8 bytes) // write value of R2 into the third array element, // i.e. array[2] Note about instruction execution time ULP coprocessor is clocked from RTC_FAST_CLK, which is normally derived from the internal 8MHz oscillator. Applications which need to know exact ULP clock frequency can calibrate it against the main XTAL clock: #include "soc/rtc.h" // calibrate 8M/256 clock against XTAL, get 8M/256 clock period uint32_t rtc_8md256_period = rtc_clk_cal(RTC_CAL_8MD256, 100); uint32_t rtc_fast_freq_hz = 1000000ULL * (1 << RTC_CLK_CAL_FRACT) * 256 / rtc_ 8md256_period; ULP coprocessor needs certain number of clock cycles to fetch each instruction, plus certain number of cycles to execute it, depending on the instruction. See description of each instruction below for details on the execution time. Instruction fetch time is: · 2 clock cycles ifor instructions following ALU and branch instructions. · 4 clock cycles iin other cases. Note that when accessing RTC memories and RTC registers, ULP coprocessor has lower priority than the main CPUs. This means that ULP coprocessor execution may be suspended while the main CPUs access same memory region as the ULP. The detailed description of all instructions is presented below: Difference between ESP32 ULP and ESP32-S3 ULP Instruction sets Compared to the ESP32 ULP FSM coprocessor, the ESP32-S3 ULP FSM coprocessor has an extended instruction set. The ESP32-S3 ULP FSM is not binary compatible with ESP32 ULP FSM, but a ESP32 ULP FSM assembled program is expected to work on the ESP32-S3 ULP FSM after rebuilding. The list of the new instructions that was added to the ESP32-S3 ULP FSM is: LDL, LDH, STL, STH, ST32, STO, STI, STI32. NOP - no operation Syntax NOP Operands None Cycles 2 cycle to execute, 4 cycles to fetch next instruction Description No operation is performed. Only the PC is incremented. Example: 1: NOP ADD - Add to register Syntax ADD Rdst, Rsrc1, Rsrc2 ADD Rdst, Rsrc1, imm Operands · Rdst - Register R[0..3] · Rsrc1 - Register R[0..3] · Rsrc2 - Register R[0..3] Espressif Systems 1619 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · Imm - 16-bit signed value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction adds source register to another source register or to a 16-bit signed value and stores the result in the destination register. Examples: 1: ADD R1, R2, R3 // R1 = R2 + R3 2: Add R1, R2, 0x1234 // R1 = R2 + 0x1234 3: .set value1, 0x03 // constant value1=0x03 Add R1, R2, value1 // R1 = R2 + value1 4: .global label add R1, R2, label ... label: nop // declaration of variable label // R1 = R2 + label // definition of variable label SUB - Subtract from register Syntax SUB Rdst, Rsrc1, Rsrc2 SUB Rdst, Rsrc1, imm Operands · Rdst - Register R[0..3] · Rsrc1 - Register R[0..3] · Rsrc2 - Register R[0..3] · Imm - 16-bit signed value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction subtracts the source register from another source register or subtracts a 16-bit signed value from a source register, and stores the result to the destination register. Examples: 1: SUB R1, R2, R3 // R1 = R2 - R3 2: sub R1, R2, 0x1234 // R1 = R2 - 0x1234 3: 4: label: .set value1, 0x03 SUB R1, R2, value1 .global label SUB R1, R2, label .... nop // constant value1=0x03 // R1 = R2 - value1 // declaration of variable label // R1 = R2 - label // definition of variable label AND - Logical AND of two operands Syntax AND Rdst, Rsrc1, Rsrc2 AND Rdst, Rsrc1, imm Operands · Rdst - Register R[0..3] · Rsrc1 - Register R[0..3] · Rsrc2 - Register R[0..3] · Imm - 16-bit signed value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction does a logical AND of a source register and another source register or a 16-bit signed value and stores the result to the destination register. Examples: Espressif Systems 1620 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 1: AND R1, R2, R3 2: AND R1, R2, 0x1234 3: .set value1, 0x03 AND R1, R2, value1 4: label: .global label AND R1, R2, label ... nop // R1 = R2 & R3 // R1 = R2 & 0x1234 // constant value1=0x03 // R1 = R2 & value1 // declaration of variable label // R1 = R2 & label // definition of variable label OR - Logical OR of two operands Syntax OR Rdst, Rsrc1, Rsrc2 OR Rdst, Rsrc1, imm Operands · Rdst - Register R[0..3] · Rsrc1 - Register R[0..3] · Rsrc2 - Register R[0..3] · Imm - 16-bit signed value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction does a logical OR of a source register and another source register or a 16-bit signed value and stores the result to the destination register. Examples: 1: OR R1, R2, R3 // R1 = R2 || R3 2: OR R1, R2, 0x1234 // R1 = R2 || 0x1234 3: .set value1, 0x03 // constant value1=0x03 OR R1, R2, value1 // R1 = R2 || value1 4: .global label OR R1, R2, label ... label: nop // declaration of variable label // R1 = R2 || label // definition of variable label LSH - Logical Shift Left Syntax LSH Rdst, Rsrc1, Rsrc2 LSH Rdst, Rsrc1, imm Operands · Rdst - Register R[0..3] · Rsrc1 - Register R[0..3] · Rsrc2 - Register R[0..3] · Imm - 16-bit signed value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction does a logical shift to left of the source register by the number of bits from another source register or a 16-bit signed value and stores the result to the destination register. Examples: 1: LSH R1, R2, R3 // R1 = R2 << R3 2: LSH R1, R2, 0x03 // R1 = R2 << 0x03 3: .set value1, 0x03 // constant value1=0x03 (continues on next page) Espressif Systems 1621 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference LSH R1, R2, value1 4: .global label LSH R1, R2, label ... label: nop // R1 = R2 << value1 (continued from previous page) // declaration of variable label // R1 = R2 << label // definition of variable label RSH - Logical Shift Right Syntax RSH Rdst, Rsrc1, Rsrc2 RSH Rdst, Rsrc1, imm Operands Rdst - Register R[0..3] Rsrc1 - Register R[0..3] Rsrc2 - Register R[0..3] Imm - 16-bit signed value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction does a logical shift to right of a source register by the number of bits from another source register or a 16-bit signed value and stores the result to the destination register. Examples: 1: RSH R1, R2, R3 // R1 = R2 >> R3 2: RSH R1, R2, 0x03 // R1 = R2 >> 0x03 3: .set value1, 0x03 RSH R1, R2, value1 // constant value1=0x03 // R1 = R2 >> value1 4: .global label RSH R1, R2, label label: nop // declaration of variable label // R1 = R2 >> label // definition of variable label MOVE Move to register Syntax MOVE Rdst, Rsrc MOVE Rdst, imm Operands · Rdst Register R[0..3] · Rsrc Register R[0..3] · Imm 16-bit signed value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction moves the value from the source register or a 16-bit signed value to the destination register. Note: Note that when a label is used as an immediate, the address of the label will be converted from bytes to words. This is because LD, ST, and JUMP instructions expect the address register value to be expressed in words rather than bytes. See the section Note about addressing for more details. Examples: 1: MOVE 2: MOVE 3: .set MOVE 4: .global MOVE R1, R2 R1, 0x03 value1, 0x03 R1, value1 label R1, label // R1 = R2 // R1 = 0x03 // constant value1=0x03 // R1 = value1 // declaration of label // R1 = address_of(label) / 4 (continues on next page) Espressif Systems 1622 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ... label: nop // definition of label (continued from previous page) ST Store data to the memory Syntax ST Rsrc, Rdst, offset Operands · Rsrc Register R[0..3], holds the 16-bit value to store · Rdst Register R[0..3], address of the destination, in 32-bit words · Offset 13-bit signed value, offset in bytes Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction stores the 16-bit value of Rsrc to the lower half-word of memory with address Rdst+offset. The upper half-word is written with the current program counter (PC) (expressed in words, shifted left by 5 bits) ORnd with Rdst (0..3): Mem[Rdst + offset / 4]{31:0} = {PC[10:0], 3'b0, Rdst, Rsrc[15:0]} The application can use the higher 16 bits to determine which instruction in the ULP program has written any particular word into memory. Note: Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section Note about addressing for more details. Examples: 1: ST R1, R2, 0x12 // MEM[R2 + 0x12 / 4] = R1 2: Addr1: .data .word .set .text MOVE MOVE ST 123 offs, 0x00 R1, 1 R2, Addr1 R1, R2, offs // Data section definition // Define label Addr1 16 bit // Define constant offs // Text section definition // R1 = 1 // R2 = Addr1 // MEM[R2 + 0 / 4] = R1 // MEM[Addr1 + 0] will be 32'h600001 STL Store data to the lower 16 bits of 32-bit memory Syntax STL Rsrc, Rdst, offset, Label Operands · Rsrc Register R[0..3], holds the 16-bit value to store · Rdst Register R[0..3], address of the destination, in 32-bit words · Offset 11-bit signed value, offset in bytes · Label 2-bit user defined unsigned value Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction stores the 16-bit value of Rsrc to the lower half-word of the memory with address [Rdst + offset / 4]: Mem[Rdst + offset / 4]{15:0} = {Rsrc[15:0]} Mem[Rdst + offset / 4]{15:0} = {Label[1:0],Rsrc[13:0]} The ST and the STL commands can be used interchangeably and have been provided to maintain backward compatibility with previous versions of the ULP core. Note: Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section Note about addressing for more details. Espressif Systems 1623 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Examples: 1: STL R1, R2, 0x12 // MEM[R2 + 0x12 / 4] = R1 2: Addr1: .data .word .set .text MOVE MOVE STL 3: MOVE STL 123 offs, 0x00 R1, 1 R2, Addr1 R1, R2, offs // Data section definition // Define label Addr1 16 bit // Define constant offs // Text section definition // R1 = 1 // R2 = Addr1 // MEM[R2 + 0 / 4] = R1 // MEM[Addr1 + 0] will be 32'hxxxx0001 R1, 1 // R1 = 1 R1, R2, 0x12, 1 // MEM[R2 + 0x12 / 4] = 0xxxxx4001 STH Store data to the higher 16 bits of 32-bit memory Syntax STH Rsrc, Rdst, offset, Label Operands · Rsrc Register R[0..3], holds the 16-bit value to store · Rdst Register R[0..3], address of the destination, in 32-bit words · Offset 11-bit signed value, offset in bytes · Label 2-bit user defined unsigned value Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction stores the 16-bit value of Rsrc to the upper half-word of memory with address [Rdst + offset / 4]: Mem[Rdst + offset / 4]{31:16} = {Rsrc[15:0]} Mem[Rdst + offset / 4]{31:16} = {Label[1:0],Rsrc[13:0]} Note: Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section Note about addressing for more details. Examples: 1: STH R1, R2, 0x12 // MEM[R2 + 0x12 / 4][31:16] = R1 2: Addr1: .data .word .set .text MOVE MOVE STH 3: MOVE STH 123 offs, 0x00 R1, 1 R2, Addr1 R1, R2, offs // Data section definition // Define label Addr1 16 bit // Define constant offs // Text section definition // R1 = 1 // R2 = Addr1 // MEM[R2 + 0 / 4] = R1 // MEM[Addr1 + 0] will be 32'h0001xxxx R1, 1 // R1 = 1 R1, R2, 0x12, 1 // MEM[R2 + 0x12 / 4] 0x4001xxxx ST32 Store 32-bits data to the 32-bits memory Syntax ST32 Rsrc, Rdst, offset, Label Operands · Rsrc Register R[0..3], holds the 16-bit value to store · Rdst Register R[0..3], address of the destination, in 32-bit words · Offset 11-bit signed value, offset in bytes · Label 2-bit user defined unsigned value Espressif Systems 1624 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction stores 11 bits of the PC value, label value and the 16-bit value of Rsrc to the 32-bit memory with address [Rdst + offset / 4]: Mem[Rdst + offset / 4]{31:0} = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} Note: Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section Note about addressing for more details. Examples: 1: ST32 R1, R2, 0x12, 0 0[2:0],Label[1:0],Rsrc[15:0]} 2: .data Addr1: .word 123 .set offs, 0x00 .text MOVE R1, 1 MOVE R2, Addr1 ST32 R1, R2, offs, 1 Label[1:0],Rsrc[15:0]} // MEM[R2 + 0x12 / 4][31:0] = {PC[10:0], // Data section definition // Define label Addr1 16 bit // Define constant offs // Text section definition // R1 = 1 // R2 = Addr1 // MEM[R2 + 0] = {PC[10:0],0[2:0], // MEM[Addr1 + 0] will be 32'h00010001 STO Set offset value for auto increment operation Syntax STO offset Operands · Offset 11-bit signed value, offset in bytes Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction sets the 16-bit value to the offset register: offset = value / 4 Note: Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section Note about addressing for more details. Examples: 1: STO 0x12 2: Addr1: .data .word .set .text STO 123 offs, 0x00 offs // Offset = 0x12 / 4 // Data section definition // Define label Addr1 16 bit // Define constant offs // Text section definition // Offset = 0x00 STI Store data to the 32-bits memory with auto increment of predefined offset address Syntax STI Rsrc, Rdst, Label Operands · Rsrc Register R[0..3], holds the 16-bit value to store · Rdst Register R[0..3], address of the destination, in 32-bit words · Label 2-bit user defined unsigned value Cycles 4 cycles to execute, 4 cycles to fetch next instruction Espressif Systems 1625 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Description The instruction stores the 16-bit value of Rsrc to the lower and upper half-word of memory with address [Rdst + offset / 4]. The offset value is auto incremented when the STI instruction is called twice. Make sure to execute the STO instruction to set the offset value before executing the STI instruction: Mem[Rdst + offset / 4]{15:0/31:16} = {Rsrc[15:0]} Mem[Rdst + offset / 4]{15:0/31:16} = {Label[1:0],Rsrc[13:0]} Examples: 1: STO 4 STI R1, R2 STI R1, R2 1 word STI R1, R2 STI R1, R2 // Set offset to 4 // MEM[R2 + 4 / 4][15:0] = R1 // MEM[R2 + 4 / 4][31:16] = R1 // offset += (1 * 4) //offset is incremented by // MEM[R2 + 8 / 4][15:0] = R1 // MEM[R2 + 8 / 4][31:16] = R1 STI32 Store 32-bits data to the 32-bits memory with auto increment of adress offset Syntax STI32 Rsrc, Rdst, Label Operands · Rsrc Register R[0..3], holds the 16-bit value to store · Rdst Register R[0..3], address of the destination, in 32-bit words · Label 2-bit user defined unsigned value Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction stores 11 bits of the PC value, label value and the 16-bit value of Rsrc to the 32-bit memory with address [Rdst + offset / 4]. The offset value is auto incremented each time the STI32 instruction is called. Make sure to execute the STO instruction to set the offset value before executing the STI32 instruction: Mem[Rdst + offset / 4]{31:0} = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} Examples: 1: STO 0x12 STI32 R1, R2, 0 Label[1:0],Rsrc[15:0]} word STI32 R1, R2, 0 Label[1:0],Rsrc[15:0]} // MEM[R2 + 0x12 / 4][31:0] = {PC[10:0],0[2:0], // offset += (1 * 4) //offset is incremented by 1 // MEM[R2 + 0x16 / 4][31:0] = {PC[10:0],0[2:0], LD Load data from the memory Syntax LD Rdst, Rsrc, offset Operands · Rdst Register R[0..3], destination · Rsrc Register R[0..3], holds address of destination, in 32-bit words · Offset 13-bit signed value, offset in bytes Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction loads the lower 16-bit half-word from memory with address [Rsrc + offset / 4] into the destination register Rdst: Rdst[15:0] = Mem[Rsrc + offset / 4][15:0] Note: Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section Note about addressing for more details. Examples: Espressif Systems 1626 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 1: LD R1, R2, 0x12 2: .data Addr1: .word 123 .set offs, 0x00 .text MOVE R1, 1 MOVE R2, Addr1 converted into words) LD R1, R2, offs // R1 = MEM[R2 + 0x12 / 4] // Data section definition // Define label Addr1 16 bit // Define constant offs // Text section definition // R1 = 1 // R2 = Addr1 / 4 (address of label is // R1 = MEM[R2 + 0] // R1 will be 123 LDL Load data from the lower half-word of the 32-bit memory Syntax LDL Rdst, Rsrc, offset Operands · Rdst Register R[0..3], destination · Rsrc Register R[0..3], holds address of destination, in 32-bit words · Offset 13-bit signed value, offset in bytes Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction loads the lower 16-bit half-word from memory with address [Rsrc + offset / 4] into the destination register Rdst: Rdst[15:0] = Mem[Rsrc + offset / 4][15:0] The LD and the LDL commands can be used interchangeably and have been provided to maintain backward compatibility with previous versions of the ULP core. Note: Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section Note about addressing for more details. Examples: 1: LDL R1, R2, 0x12 2: .data Addr1: .word 123 .set offs, 0x00 .text MOVE R1, 1 MOVE R2, Addr1 converted into words) LDL R1, R2, offs // R1 = MEM[R2 + 0x12 / 4] // Data section definition // Define label Addr1 16 bit // Define constant offs // Text section definition // R1 = 1 // R2 = Addr1 / 4 (address of label is // R1 = MEM[R2 + 0] // R1 will be 123 LDH Load data from upper half-word of the 32-bit memory Syntax LDH Rdst, Rsrc, offset Operands · Rdst Register R[0..3], destination · Rsrc Register R[0..3], holds address of destination, in 32-bit words · Offset 13-bit signed value, offset in bytes Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction loads the upper 16-bit half-word from memory with address [Rsrc + offset / 4] into the destination register Rdst: Rdst[15:0] = Mem[Rsrc + offset / 4][15:0] Espressif Systems 1627 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note: Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section Note about addressing for more details. Examples: 1: LDH R1, R2, 0x12 2: .data Addr1: .word 0x12345678 .set offs, 0x00 .text MOVE R1, 1 MOVE R2, Addr1 converted into words) LDH R1, R2, offs // R1 = MEM[R2 + 0x12 / 4] // Data section definition // Define label Addr1 16 bit // Define constant offs // Text section definition // R1 = 1 // R2 = Addr1 / 4 (address of label is // R1 = MEM[R2 + 0] // R1 will be 0x1234 JUMP Jump to an absolute address Syntax JUMP Rdst JUMP ImmAddr JUMP Rdst, Condition JUMP ImmAddr, Condition Operands · Rdst Register R[0..3] containing address to jump to (expressed in 32-bit words) · ImmAddr 13 bits address (expressed in bytes), aligned to 4 bytes · Condition: EQ jump if last ALU operation result was zero OV jump if last ALU has set overflow flag Cycles 2 cycles to execute, 2 cycles to fetch next instruction Description The instruction makes jump to the specified address. Jump can be either unconditional or based on an ALU flag. Examples: 1: JUMP R1 32-bit words) // Jump to address in R1 (address in R1 is in 2: JUMP result is zero 0x120, EQ // Jump to address 0x120 (in bytes) if ALU 3: JUMP ... label: nop label // Jump to label // Definition of label 4: .global label // Declaration of global label label: MOVE JUMP ... nop R1, label R1 // R1 = label (value loaded into R1 is in words) // Jump to label // Definition of label JUMPR Jump to a relative offset (condition based on R0) Syntax JUMPR Step, Threshold, Condition Operands · Step relative shift from current position, in bytes · Threshold threshold value for branch condition Espressif Systems 1628 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · Condition: EQ (equal) jump if value in R0 == threshold LT (less than) jump if value in R0 < threshold LE (less or equal) jump if value in R0 <= threshold GT (greater than) jump if value in R0 > threshold GE (greater or equal) jump if value in R0 >= threshold Cycles Conditions EQ, GT and LT: 2 cycles to execute, 2 cycles to fetch next instruction Conditions LE and GE are implemented in the assembler using two JUMPR instructions: // JUMPR target, threshold, LE is implemented as: JUMPR target, threshold, EQ JUMPR target, threshold, LT // JUMPR target, threshold, GE is implemented as: JUMPR target, threshold, EQ JUMPR target, threshold, GT Therefore the execution time will depend on the branches taken: either 2 cycles to execute + 2 cycles to fetch, or 4 cycles to execute + 4 cycles to fetch. Description The instruction makes a jump to a relative address if condition is true. Condition is the result of comparison of R0 register value and the threshold value. Examples: 1:pos: JUMPR 16, 20, GE // Jump to address (position + 16 bytes) if value in R0 >= 20 2: label: // Down counting loop using R0 register MOVE R0, 16 // load 16 into R0 SUB R0, R0, 1 // R0-- NOP // do something JUMPR label, 1, GE // jump to label if R0 >= 1 JUMPS Jump to a relative address (condition based on stage count) Syntax JUMPS Step, Threshold, Condition Operands · Step relative shift from current position, in bytes · Threshold threshold value for branch condition · Condition: EQ (equal) jump if value in stage_cnt == threshold LT (less than) jump if value in stage_cnt < threshold LE (less or equal) - jump if value in stage_cnt <= threshold GT (greater than) jump if value in stage_cnt > threshold GE (greater or equal) ijump if value in stage_cnt >= threshold Cycles 2 cycles to execute, 2 cycles to fetch next instruction: // JUMPS target, threshold, EQ is implemented as: next: JUMPS next, threshold, LT JUMPS target, threshold, LE // JUMPS target, threshold, GT is implemented as: next: JUMPS next, threshold, LE JUMPS target, threshold, GE Espressif Systems 1629 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Therefore the execution time will depend on the branches taken: either 2 cycles to execute + 2 cycles to fetch, or 4 cycles to execute + 4 cycles to fetch. Description The instruction makes a jump to a relative address if condition is true. Condition is the result of comparison of count register value and threshold value. Examples: 1:pos: JUMPS == 20 16, 20, EQ // Jump to (position + 16 bytes) if stage_cnt 2: label: // Up counting loop using stage count register STAGE_RST // set stage_cnt to 0 STAGE_INC 1 // stage_cnt++ NOP // do something JUMPS label, 16, LT // jump to label if stage_cnt < 16 STAGE_RST Reset stage count register Syntax STAGE_RST Operands No operands Description The instruction sets the stage count register to 0 Cycles 2 cycles to execute, 4 cycles to fetch next instruction Examples: 1: STAGE_RST // Reset stage count register STAGE_INC Increment stage count register Syntax STAGE_INC Value Operands · Value 8 bits value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction increments the stage count register by the given value. Examples: 1: STAGE_INC 10 // stage_cnt += 10 2: label: // Up counting loop example: STAGE_RST // set stage_cnt to 0 STAGE_INC 1 // stage_cnt++ NOP // do something JUMPS label, 16, LT // jump to label if stage_cnt < 16 STAGE_DEC Decrement stage count register Syntax STAGE_DEC Value Operands · Value 8 bits value Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction decrements the stage count register by the given value. Examples: 1: STAGE_DEC 10 // stage_cnt -= 10; 2: // Down counting loop example STAGE_RST // set stage_cnt to 0 STAGE_INC 16 // increment stage_cnt to 16 (continues on next page) Espressif Systems 1630 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference label: STAGE_DEC NOP JUMPS 1 label, 0, GT (continued from previous page) // stage_cnt--; // do something // jump to label if stage_cnt > 0 HALT End the program Syntax HALT Operands No operands Cycles 2 cycles to execute Description The instruction halts the ULP coprocessor and restarts the ULP wakeup timer, if it is enabled. Examples: 1: HALT // Halt the coprocessor WAKE Wake up the chip Syntax WAKE Operands No operands Cycles 2 cycles to execute, 4 cycles to fetch next instruction Description The instruction sends an interrupt from the ULP coprocessor to the RTC controller. · If the SoC is in deep sleep mode, and ULP wakeup is enabled, this causes the SoC to wake up. · If the SoC is not in deep sleep mode, and ULP interrupt bit (RTC_CNTL_ULP_CP_INT_ENA) is set in RTC_CNTL_INT_ENA_REG register, RTC interrupt will be triggered. Note that before using WAKE instruction, ULP program may needs to wait until RTC controller is ready to wake up the main CPU. This is indicated using RTC_CNTL_RDY_FOR_WAKEUP bit of RTC_CNTL_LOW_POWER_ST_REG register. If WAKE instruction is executed while RTC_CNTL_RDY_FOR_WAKEUP is zero, it has no effect (wake up does not occur). Examples: 1: is_rdy_for_wakeup: // Read RTC_CNTL_RDY_FOR_WAKEUP bit READ_RTC_FIELD(RTC_CNTL_LOW_POWER_ST_REG, RTC_CNTL_RDY_FOR_WAKEUP) AND r0, r0, 1 JUMP is_rdy_for_wakeup, eq // Retry until the bit is set WAKE // Trigger wake up REG_WR 0x006, 24, 24, 0 // Stop ULP timer (clear RTC_CNTL_ULP_CP_ SLP_TIMER_EN) HALT // Stop the ULP program // After these instructions, SoC will wake up, // and ULP will not run again until started by the main program. WAIT wait some number of cycles Syntax WAIT Cycles Operands · Cycles number of cycles for wait Cycles 2 + Cycles cycles to execute, 4 cycles to fetch next instruction Description The instruction delays for given number of cycles. Examples: 1: WAIT 10 // Do nothing for 10 cycles 2: .set wait_cnt, 10 // Set a constant WAIT wait_cnt // wait for 10 cycles Espressif Systems 1631 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference TSENS do measurement with temperature sensor Syntax · TSENS Rdst, Wait_Delay Operands · Rdst Destination Register R[0..3], result will be stored to this register · Wait_Delay number of cycles used to perform the measurement Cycles 2 + Wait_Delay + 3 * TSENS_CLK to execute, 4 cycles to fetch next instruction Description The instruction performs measurement using TSENS and stores the result into a general purpose reg- ister. Examples: 1: TSENS R1, 1000 // Measure temperature sensor for 1000 cycles, // and store result to R1 ADC do measurement with ADC Syntax · ADC Rdst, Sar_sel, Mux · ADC Rdst, Sar_sel, Mux, 0 ideprecated form Operands · Rdst Destination Register R[0..3], result will be stored to this register · Sar_sel Select ADC: 0 = SARADC1, 1 = SARADC2 · Mux - selected PAD, SARADC Pad[Mux-1] is enabled. If the user passes Mux value 1, then ADC pad 0 gets used. Cycles 23 + max(1, SAR_AMP_WAIT1) + max(1, SAR_AMP_WAIT2) + max(1, SAR_AMP_WAIT3) + SARx_SAMPLE_CYCLE + SARx_SAMPLE_BIT cycles to execute, 4 cycles to fetch next instruction Description The instruction makes measurements from ADC. Examples: .. only:: esp32 1: ADC R1, 0, 1 // Measure value using ADC1 channel 0 and store result into R1 1: ADC R1, 0, 1 // Measure value using ADC1 pad 2 and store result into R1 REG_RD read from peripheral register Syntax REG_RD Addr, High, Low Operands · Addr Register address, in 32-bit words · High Register end bit number · Low Register start bit number Cycles 4 cycles to execute, 4 cycles to fetch next instruction Description The instruction reads up to 16 bits from a peripheral register into a general purpose register: R0 = REG[Addr][High:Low]. This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of the register, as seen from the ULP, can be calculated from the address of the same register on the PeriBUS1 as follows: addr_ulp = (addr_peribus1 - DR_REG_RTCCNTL_BASE) / 4 Examples: 1: REG_RD 0x120, 7, 4 // load 4 bits: R0 = {12'b0, REG[0x120][7:4]} Espressif Systems 1632 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference REG_WR write to peripheral register Syntax REG_WR Addr, High, Low, Data Operands · Addr Register address, in 32-bit words. · High Register end bit number · Low Register start bit number · Data Value to write, 8 bits Cycles 8 cycles to execute, 4 cycles to fetch next instruction Description The instruction writes up to 8 bits from an immediate data value into a peripheral register: REG[Addr][High:Low] = data. This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of the the register, as seen from the ULP, can be calculated from the address of the same register on the PeriBUS1 as follows: addr_ulp = (addr_peribus1 - DR_REG_RTCCNTL_BASE) / 4 Examples: 1: REG_WR 0x120, 7, 0, 0x10 // set 8 bits: REG[0x120][7:0] = 0x10 Convenience macros for peripheral registers access ULP source files are passed through C preprocessor before the assembler. This allows certain macros to be used to facilitate access to peripheral registers. Some existing macros are defined in soc/soc_ulp.h header file. These macros allow access to the fields of peripheral registers by their names. Peripheral registers names which can be used with these macros are the ones defined in soc/rtc_cntl_reg.h, soc/rtc_io_reg.h, soc/sens_reg.h, and soc/rtc_i2c_reg. h. READ_RTC_REG(rtc_reg, low_bit, bit_width) Read up to 16 bits from rtc_reg[low_bit + bit_width - 1 : low_bit] into R0. For example: #include "soc/soc_ulp.h" #include "soc/rtc_cntl_reg.h" /* Read 16 lower bits of RTC_CNTL_TIME0_REG into R0 */ READ_RTC_REG(RTC_CNTL_TIME0_REG, 0, 16) READ_RTC_FIELD(rtc_reg, field) Read from a field in rtc_reg into R0, up to 16 bits. For example: #include "soc/soc_ulp.h" #include "soc/sens_reg.h" /* Read 8-bit SENS_TSENS_OUT field of SENS_SAR_SLAVE_ADDR3_REG into R0 */ READ_RTC_FIELD(SENS_SAR_SLAVE_ADDR3_REG, SENS_TSENS_OUT) WRITE_RTC_REG(rtc_reg, low_bit, bit_width, value) Write immediate value into rtc_reg[low_bit + bit_width - 1 : low_bit], bit_width <= 8. For example: #include "soc/soc_ulp.h" #include "soc/rtc_io_reg.h" /* Set BIT(2) of RTC_GPIO_OUT_DATA_W1TS field in RTC_GPIO_OUT_W1TS_REG */ WRITE_RTC_REG(RTC_GPIO_OUT_W1TS_REG, RTC_GPIO_OUT_DATA_W1TS_S + 2, 1, 1) WRITE_RTC_FIELD(rtc_reg, field, value) Write immediate value into a field in rtc_reg, up to 8 bits. For example: #include "soc/soc_ulp.h" #include "soc/rtc_cntl_reg.h" /* Set RTC_CNTL_ULP_CP_SLP_TIMER_EN field of RTC_CNTL_STATE0_REG to 0 */ WRITE_RTC_FIELD(RTC_CNTL_STATE0_REG, RTC_CNTL_ULP_CP_SLP_TIMER_EN, 0) Espressif Systems 1633 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Programming ULP FSM coprocessor using C macros (legacy) In addition to the existing binutils port for the ESP32-S3 ULP coprocessor, it is possible to generate programs for the ULP FSM coprocessor by embedding assembly-like macros into an ESP32-S3 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 the API reference section at the end of this guide 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. Note: Load, store and move instructions use addresses expressed in 32-bit words. Address 0 corresponds to the first word of RTC_SLOW_MEM. This is different to how address arguments are handled in assembly code of the same instructions. See the section Note about addressing for more details for reference. 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); (continues on next page) Espressif Systems 1634 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ulp_process_macros_and_load(load_addr, program, &size); ulp_run(load_addr); (continued from previous page) API Reference Header File · components/ulp/ulp_fsm/include/esp32s3/ulp.h Functions static uint32_t SOC_REG_TO_ULP_PERIPH_SEL(uint32_t reg) Map SoC peripheral register to periph_sel field of RD_REG and WR_REG instructions. Return periph_sel value for the peripheral to which this register belongs. Parameters · reg: peripheral register in RTC_CNTL_, RTC_IO_, SENS_, RTC_I2C peripherals. Unions union ulp_insn #include <ulp.h> Instruction format structure. All ULP instructions are 32 bit long. This union contains field layouts used by all of the supported instructions. This union also includes a speciaol macropinstruction layout. This is not a real instruction which can be executed by the CPU. It acts as a token which is removed from the program by the ulp_process_macros_and_load function. These structures are not intended to be used directly. Preprocessor definitions provided below fill the fields of these structure with the right arguments. Public Members uint32_t cycles : 16 Number of cycles to sleep TBD, cycles used for measurement uint32_t unused : 12 Unused uint32_t opcode : 4 Opcode (OPCODE_DELAY) Opcode (OPCODE_ST) Opcode (OPCODE_LD) Opcode (OPCODE_HALT) Opcode (OPCODE_BRANCH) Opcode (OPCODE_ALU) Opcode (OPCODE_WR_REG) Opcode (OPCODE_RD_REG) Opcode (OPCODE_ADC) Opcode (OPCODE_TSENS) Opcode (OPCODE_I2C) Espressif Systems 1635 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Opcode (OPCODE_END) Opcode (OPCODE_MACRO) struct ulp_insn::[anonymous] delay Format of DELAY instruction uint32_t dreg : 2 Register which contains data to store Register where the data should be loaded to Register which contains target PC, expressed in words (used if .reg == 1) Destination register Register where to store ADC result Register where to store temperature measurement result uint32_t sreg : 2 Register which contains address in RTC memory (expressed in words) Register with operand A uint32_t label : 2 Data label, 2-bit user defined unsigned value Label number uint32_t upper : 1 0: write the low half-word; 1: write the high half-word uint32_t wr_way : 2 0: write the full-word; 1: with the label; 3: without the label uint32_t unused1 : 1 Unused uint32_t offset : 11 Offset to add to sreg Absolute value of target PC offset w.r.t. current PC, expressed in words uint32_t unused2 : 4 Unused uint32_t sub_opcode : 3 Sub opcode (SUB_OPCODE_ST) Sub opcode (SUB_OPCODE_BX) Sub opcode (SUB_OPCODE_B) Sub opcode (SUB_OPCODE_ALU_REG) Sub opcode (SUB_OPCODE_ALU_IMM) Sub opcode (SUB_OPCODE_ALU_CNT) Sub opcode (SUB_OPCODE_WAKEUP) SUB_OPCODE_MACRO_LABEL or SUB_OPCODE_MACRO_BRANCH struct ulp_insn::[anonymous] st Format of ST instruction uint32_t rd_upper : 1 0: read the high half-word; 1: read the low half-word struct ulp_insn::[anonymous] ld Format of LD instruction Espressif Systems 1636 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference struct ulp_insn::[anonymous] halt Format of HALT instruction uint32_t addr : 11 Target PC, expressed in words (used if .reg == 0) Address within either RTC_CNTL, RTC_IO, or SARADC uint32_t reg : 1 Target PC in register (1) or immediate (0) uint32_t type : 3 Jump condition (BX_JUMP_TYPE_xxx) struct ulp_insn::[anonymous] bx Format of BRANCH instruction (absolute address) uint32_t imm : 16 Immediate value to compare against Immediate value of operand B Immediate value uint32_t cmp : 2 Comparison to perform: B_CMP_L or B_CMP_GE uint32_t sign : 1 Sign of target PC offset: 0: positive, 1: negative struct ulp_insn::[anonymous] b Format of BRANCH instruction (relative address) uint32_t treg : 2 Register with operand B uint32_t sel : 4 Operation to perform, one of ALU_SEL_xxx struct ulp_insn::[anonymous] alu_reg Format of ALU instruction (both sources are registers) struct ulp_insn::[anonymous] alu_imm Format of ALU instruction (one source is an immediate) uint32_t unused3 : 1 Unused struct ulp_insn::[anonymous] alu_cnt Format of ALU instruction with stage count register and an immediate uint32_t periph_sel : 2 Select peripheral: RTC_CNTL (0), RTC_IO(1), SARADC(2) uint32_t data : 8 8 bits of data to write Data to read or write uint32_t low : 5 Low bit uint32_t high : 5 High bit struct ulp_insn::[anonymous] wr_reg Format of WR_REG instruction struct ulp_insn::[anonymous] rd_reg Format of RD_REG instruction Espressif Systems 1637 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference uint32_t mux : 4 Select SARADC pad (mux + 1) uint32_t sar_sel : 1 Select SARADC0 (0) or SARADC1 (1) struct ulp_insn::[anonymous] adc Format of ADC instruction uint32_t wait_delay : 14 Cycles to wait after measurement is done uint32_t reserved : 12 Reserved, set to 0 struct ulp_insn::[anonymous] tsens Format of TSENS instruction uint32_t i2c_addr : 8 I2C slave address uint32_t low_bits : 3 TBD uint32_t high_bits : 3 TBD uint32_t i2c_sel : 4 TBD, select reg_i2c_slave_address[7:0] uint32_t rw : 1 Write (1) or read (0) struct ulp_insn::[anonymous] i2c Format of I2C instruction uint32_t wakeup : 1 Set to 1 to wake up chip struct ulp_insn::[anonymous] end Format of END instruction with wakeup struct ulp_insn::[anonymous] macro Format of tokens used by LABEL and BRANCH macros Macros R0 general purpose register 0 R1 general purpose register 1 R2 general purpose register 2 R3 general purpose register 3 OPCODE_WR_REG Instruction: write peripheral register (RTC_CNTL/RTC_IO/SARADC) (not implemented yet) OPCODE_RD_REG Instruction: read peripheral register (RTC_CNTL/RTC_IO/SARADC) (not implemented yet) RD_REG_PERIPH_RTC_CNTL Identifier of RTC_CNTL peripheral for RD_REG and WR_REG instructions Espressif Systems 1638 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference RD_REG_PERIPH_RTC_IO Identifier of RTC_IO peripheral for RD_REG and WR_REG instructions RD_REG_PERIPH_SENS Identifier of SARADC peripheral for RD_REG and WR_REG instructions RD_REG_PERIPH_RTC_I2C Identifier of RTC_I2C peripheral for RD_REG and WR_REG instructions OPCODE_I2C Instruction: read/write I2C (not implemented yet) OPCODE_DELAY Instruction: delay (nop) for a given number of cycles OPCODE_ADC Instruction: SAR ADC measurement (not implemented yet) OPCODE_ST Instruction: store indirect to RTC memory SUB_OPCODE_ST_AUTO Automatic Storage Mode - Access continuous addresses. Use SUB_OPCODE_ST_OFFSET to configure the initial address before using this instruction. SUB_OPCODE_ST_OFFSET Automatic Storage Mode - Configure the initial address. SUB_OPCODE_ST Manual Storage Mode. Store 32 bits, 16 MSBs contain PC, 16 LSBs contain value from source register OPCODE_ALU Arithmetic instructions SUB_OPCODE_ALU_REG Arithmetic instruction, both source values are in register SUB_OPCODE_ALU_IMM Arithmetic instruction, one source value is an immediate SUB_OPCODE_ALU_CNT Arithmetic instruction between counter register and an immediate (not implemented yet) ALU_SEL_ADD Addition ALU_SEL_SUB Subtraction ALU_SEL_AND Logical AND ALU_SEL_OR Logical OR ALU_SEL_MOV Copy value (immediate to destination register or source register to destination register ALU_SEL_LSH Shift left by given number of bits ALU_SEL_RSH Shift right by given number of bits ALU_SEL_STAGE_INC Increment stage count register ALU_SEL_STAGE_DEC Decrement stage count register Espressif Systems 1639 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference ALU_SEL_STAGE_RST Reset stage count register OPCODE_BRANCH Branch instructions SUB_OPCODE_B Branch to a relative offset SUB_OPCODE_BX Branch to absolute PC (immediate or in register) SUB_OPCODE_BS Branch to a relative offset by comparing the stage_cnt register BX_JUMP_TYPE_DIRECT Unconditional jump BX_JUMP_TYPE_ZERO Branch if last ALU result is zero BX_JUMP_TYPE_OVF Branch if last ALU operation caused and overflow B_CMP_L Branch if R0 is less than an immediate B_CMP_G Branch if R0 is greater than an immediate B_CMP_E Branch if R0 is equal to an immediate BS_CMP_L Branch if stage_cnt is less than an immediate BS_CMP_GE Branch if stage_cnt is greater than or equal to an immediate BS_CMP_LE Branch if stage_cnt is less than or equal to an immediate OPCODE_END Stop executing the program SUB_OPCODE_END Stop executing the program and optionally wake up the chip SUB_OPCODE_SLEEP Stop executing the program and run it again after selected interval OPCODE_TSENS Instruction: temperature sensor measurement (not implemented yet) OPCODE_HALT Halt the coprocessor OPCODE_LD Indirect load lower 16 bits from RTC memory OPCODE_MACRO Not a real opcode. Used to identify labels and branches in the program SUB_OPCODE_MACRO_LABEL Label macro SUB_OPCODE_MACRO_BRANCH Branch macro Espressif Systems 1640 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SUB_OPCODE_MACRO_LABELPC Label pointer macro 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_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_WR_REG_BIT(reg, shift, val) Set or clear a bit in the peripheral register. Sets bit (1 << shift) of register reg to value val. This instruction can access RTC_CNTL_, RTC_IO_, SENS_, and RTC_I2C peripheral registers. I_WAKE() Wake the SoC from deep sleep. This instruction initiates wake up from deep sleep. Use esp_deep_sleep_enable_ulp_wakeup to enable deep sleep wakeup triggered by the ULP before going into deep sleep. Note that ULP program will still keep running until the I_HALT instruction, and it will still be restarted by timer at regular intervals, even when the SoC is woken up. To stop the ULP program, use I_HALT instruction. To disable the timer which start ULP program, use I_END() instruction. I_END instruction clears the RTC_CNTL_ULP_CP_SLP_TIMER_EN_S bit of RTC_CNTL_ULP_CP_TIMER_REG register, which controls the ULP timer. 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_TSENS(reg_dest, delay) Perform temperature sensor measurement and store it into reg_dest. Delay can be set between 1 and ((1 << 14) - 1). Higher values give higher measurement resolution. I_ADC(reg_dest, adc_idx, pad_idx) Perform ADC measurement and store result in reg_dest. adc_idx selects ADC (0 or 1). pad_idx selects ADC pad (0 - 7). I_ST_MANUAL(reg_val, reg_addr, offset_, label_, upper_, wr_way_) Store lower half-word, upper half-word or full-word data from register reg_val into RTC memory address. This instruction can be used to write data to discontinuous addresses in the RTC_SLOW_MEM. The value is written to an offset calculated by adding the value of reg_addr register and offset_ field (this offset is expressed Espressif Systems 1641 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference in 32-bit words). The storage method is dictated by the wr_way and upper field settings as summarized in the following table: * |--------|-------|----------------------------------------------------------- -----------------------------|----------------------------| * | wr_way | upper | data | operation | * |--------|-------|----------------------------------------------------------- -----------------------------|----------------------------| *| | | | Write full-word, including | * | 0 | X | RTC_SLOW_MEM[addr + offset_]{31:0} = {insn_PC[10:0], 3n b0, label_[1:0], reg_val[15:0]} | the PC and the data | * |--------|-------|----------------------------------------------------------- -----------------------------|----------------------------| *| | | | Store the data with label | * | 1 | 0 | RTC_SLOW_MEM[addr + offset_]{15:0} = {label_[1:0], reg_ val[13:0]} | in the low half-word | * |--------|-------|----------------------------------------------------------- -----------------------------|----------------------------| *| | | | Store the data with label | * | 1 | 1 | RTC_SLOW_MEM[addr + offset_]{31:16} = {label_[1:0], reg_ val[13:0]} | in the high half-word | * |--------|-------|----------------------------------------------------------- -----------------------------|----------------------------| *| | | | Store the data without | * | 3 | 0 | RTC_SLOW_MEM[addr + offset_]{15:0} = reg_val[15:0] | label in the low half-word | * |--------|-------|----------------------------------------------------------- -----------------------------|----------------------------| *| | | | Store the data without | * | 3 | 1 | RTC_SLOW_MEM[addr + offset_]{31:16} = reg_val[15:0] | label in the high half-word| * |--------|-------|----------------------------------------------------------- -----------------------------|----------------------------| * SUB_OPCODE_ST = manual_en:1, offset_set:0, wr_auto:0 I_ST(reg_val, reg_addr, offset_) Store value from register reg_val into RTC memory. I_ST() instruction provides backward compatibility for code written for esp32 to be run on esp32s2. This instruction is equivalent to calling I_ST_MANUAL() instruction with label = 0, upper = 0 and wr_way = 3. I_STL(reg_val, reg_addr, offset_) Store value from register reg_val to lower 16 bits of the RTC memory address. This instruction is equivalent to calling I_ST_MANUAL() instruction with label = 0, upper = 0 and wr_way = 3. I_STH(reg_val, reg_addr, offset_) Store value from register reg_val to upper 16 bits of the RTC memory address. This instruction is equivalent to calling I_ST_MANUAL() instruction with label = 0, upper = 1 and wr_way = 3. I_ST32(reg_val, reg_addr, offset_, label_) Store value from register reg_val to full 32 bit word of the RTC memory address. This instruction is equivalent to calling I_ST_MANUAL() instruction with wr_way = 0. Espressif Systems 1642 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference I_STL_LABEL(reg_val, reg_addr, offset_, label_) Store value from register reg_val with label to lower 16 bits of RTC memory address. This instruction is equivalent to calling I_ST_MANUAL() instruction with label = label_, upper = 0 and wr_way = 1. I_STH_LABEL(reg_val, reg_addr, offset_, label_) Store value from register reg_val with label to upper 16 bits of RTC memory address. This instruction is equivalent to calling I_ST_MANUAL() instruction with label = label_, upper = 1 and wr_way = 1. I_ST_AUTO(reg_val, reg_addr, label_, wr_way_) Store lower half-word, upper half-word or full-word data from register reg_val into RTC memory address with auto-increment of the offset value. This instruction can be used to write data to continuous addresses in the RTC_SLOW_MEM. The initial address must be set using the SUB_OPCODE_ST_OFFSET instruction before the auto store instruction is called. The data written to the RTC memory address could be written to the full 32 bit word or to the lower half-word or the upper half-word. The storage method is dictated by the wr_way field and the number of times the SUB_OPCODE_ST_AUTO instruction is called. write_cnt indicates the later. The following table summarizes the storage method: * |--------|-----------|------------------------------------------------------- ---------------------------------|----------------------------| * | wr_way | write_cnt | data | operation | * |--------|-----------|------------------------------------------------------- ---------------------------------|----------------------------| *| | | | Write full-word, including | *| 0 | X | RTC_SLOW_MEM[addr + offset_]{31:0} = {insn_PC[10:0], 3nb0, label_[1:0], reg_val[15:0]} | the PC and the data | * |--------|-----------|------------------------------------------------------- ---------------------------------|----------------------------| *| | | | Store the data with label | * | 1 | odd | RTC_SLOW_MEM[addr + offset_]{15:0} = {label_[1:0], reg_val[13:0]} | in the low half-word | * |--------|-----------|------------------------------------------------------- ---------------------------------|----------------------------| *| | | | Store the data with label | * | 1 | even | RTC_SLOW_MEM[addr + offset_]{31:16} = {label_[1:0], reg_val[13:0]} | in the high half-word | * |--------|-----------|------------------------------------------------------- ---------------------------------|----------------------------| *| | | | Store the data without | * | 3 | odd | RTC_SLOW_MEM[addr + offset_]{15:0} = reg_val[15:0] | label in the low half-word | * |--------|-----------|------------------------------------------------------- ---------------------------------|----------------------------| *| | | | Store the data without | * | 3 | even | RTC_SLOW_MEM[addr + offset_]{31:16} = reg_val[15:0] | label in the high half-word| * |--------|-----------|------------------------------------------------------- ---------------------------------|----------------------------| * The initial address offset is incremented after each store operation as follows: · When a full-word is written, the offset is automatically incremented by 1 after each Espressif Systems 1643 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference SUB_OPCODE_ST_AUTO operation. · When a half-word is written (lower half-word first), the offset is automatically incremented by 1 after two SUB_OPCODE_ST_AUTO operations. SUB_OPCODE_ST_AUTO = manual_en:0, offset_set:0, wr_auto:1 I_STO(offset_) Set the initial address offset for auto-store operation This instruction sets the initial address of the RTC_SLOW_MEM to be used by the auto-store operation. The offset is incremented automatically. Refer I_ST_AUTO() for detailed explaination. SUB_OPCODE_ST_OFFSET = manual_en:0, offset_set:1, wr_auto:1 I_STI(reg_val, reg_addr) Store value from register reg_val to 32 bit word of the RTC memory address. This instruction is equivalent to calling I_ST_AUTO() instruction with label = 0 and wr_way = 3. The data in reg_val will be either written to the lower half-word or the upper half-word of the RTC memory address depending on the count of the number of times the I_STI() instruction is called. The initial offset is automatically incremented with I_STI() is called twice. Refer I_ST_AUTO() for detailed explaination. I_STI_LABEL(reg_val, reg_addr, label_) Store value from register reg_val with label to 32 bit word of the RTC memory address. This instruction is equivalent to calling I_ST_AUTO() instruction with label = label_ and wr_way = 1. The data in reg_val will be either written to the lower half-word or the upper half-word of the RTC memory address depending on the count of the number of times the I_STI_LABEL() instruction is called. The initial offset is automatically incremented with I_STI_LABEL() is called twice. Refer I_ST_AUTO() for detailed explaination. I_STI32(reg_val, reg_addr, label_) Store value from register reg_val to full 32 bit word of the RTC memory address. This instruction is equivalent to calling I_ST_AUTO() instruction with label = label_ and wr_way = 0. The data in reg_val will be written to the RTC memory address along with the label and the PC. The initial offset is automatically incremented each time the I_STI32() instruction is called. Refer I_ST_AUTO() for detailed explaination. I_LD_MANUAL(reg_dest, reg_addr, offset_, rd_upper_) Load lower half-word, upper half-word or full-word data from RTC memory address into the register reg_dest. This instruction reads the lower half-word or upper half-word of the RTC memory address depending on the value of rd_upper_. The following table summarizes the loading method: * |----------|------------------------------------------------------|---------- ---------------| * | rd_upper | data | operation | * |----------|------------------------------------------------------|---------- ---------------| *| | | Read lower half-word of | *| 0 | reg_dest{15:0} = RTC_SLOW_MEM[addr + offset_]{31:16} | the memory | * |----------|------------------------------------------------------|---------- ---------------| *| | | Read upper half-word of | *| 1 | reg_dest{15:0} = RTC_SLOW_MEM[addr + offset_]{15:0} | the memory | * |----------|------------------------------------------------------|---------- ---------------| * Espressif Systems 1644 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference I_LD(reg_dest, reg_addr, offset_) Load lower 16 bits value from RTC memory into reg_dest register. Loads 16 LSBs (rd_upper = 1) from RTC memory word given by the sum of value in reg_addr and value of offset_. I_LD() instruction provides backward compatibility for code written for esp32 to be run on esp32s2. I_LDL(reg_dest, reg_addr, offset_) Load lower 16 bits value from RTC memory into reg_dest register. I_LDL() instruction and I_LD() instruction can be used interchangably. I_LDH(reg_dest, reg_addr, offset_) Load upper 16 bits value from RTC memory into reg_dest register. Loads 16 MSBs (rd_upper = 0) from RTC memory word given by the sum of value in reg_addr and value of offset_. I_BL(pc_offset, imm_value) Branch relative if R0 register less than the 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_BG(pc_offset, imm_value) Branch relative if R0 register greater than the 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_BE(pc_offset, imm_value) Branch relative if R0 register is equal to the 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_BSLE(pc_offset, imm_value) Branch relative if stage_cnt is less than or equal to the 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 Espressif Systems 1645 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference I_BSGE(pc_offset, imm_value) Branch relative if stage_cnt register is greater than or equal to the 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_BSL(pc_offset, imm_value) Branch relative if stage_cnt register is less than the 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_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 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 I_STAGE_INC(reg_dest, reg_src, imm_) Increment stage_cnt register by an immediate: stage_cnt = stage_cnt + imm I_STAGE_DEC(reg_dest, reg_src, imm_) Decrement stage_cnt register by an immediate: stage_cnt = stage_cnt - imm I_STAGE_RST(reg_dest, reg_src, imm_) Reset stage_cnt register by an immediate: stage_cnt = 0 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. Espressif Systems 1646 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference M_BRANCH(label_num) Token macro used by M_B and M_BX macros. Not to be used directly. 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_BG(label_num, imm_value) Macro: branch to label label_num if R0 is greater 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_BE(label_num, imm_value) Macro: branch to label label_num if R0 equal to the 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. 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. Compiling the ULP Code To compile the ULP FSM code as part of the component, the following steps must be taken: 1. The ULP FSM 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 FSM 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 Espressif Systems 1647 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference argument specifies the ULP FSM 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 the 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 FSM 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. 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 a 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. Accessing the ULP FSM Program Variables Global symbols defined in the ULP FSM program may be used inside the main program. For example, the ULP FSM 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: Espressif Systems 1648 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference #include "ulp_app_name.h" // later void init_ulp_vars() { ulp_measurement_count = 64; } Starting the ULP FSM Program To run a ULP FSM 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 that the Enable Ultra Low Power (ULP) Coprocessor option must be enabled in menuconfig to work with ULP. To select the type of ULP to be used, the ULP Co-processor type option must be set. To reserve memory for the ULP, the RTC slow memory reserved for coprocessor option must be set to a value big enough 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)) ); } Once the program is loaded into RTC memory, the application can start it by passing the address of the entry point to the ulp_run function: ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) ); 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 FSM application, this symbol must be marked as .global: .global entry entry: // code starts here ESP32-S3 ULP program flow ESP32-S3 ULP coprocessor is started by a timer. The timer is started once ulp_run() is called. The timer counts a number of RTC_SLOW_CLK ticks (by default, produced by an internal 90 kHz RC oscillator). The number of ticks is set using RTC_CNTL_ULP_CP_TIMER_1_REG register. The application can set ULP timer period values by ulp_set_wakeup_period() function. Once the timer counts the number of ticks set in the selected RTC_CNTL_ULP_CP_TIMER_1_REG register, ULP coprocessor powers up and starts running the program from the entry point set in the call to ulp_run(). The program runs until it encounters a halt instruction or an illegal instruction. Once the program halts, ULP coprocessor powers down, and the timer is started again. Espressif Systems 1649 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference To disable the timer (effectively preventing the ULP program from running again), clear the RTC_CNTL_ULP_CP_SLP_TIMER_EN bit in the RTC_CNTL_ULP_CP_TIMER_REG register. This can be done both from ULP code and from the main program. Application Examples · ULP FSM Coprocessor counts pulses on an IO while main CPU is in deep sleep: system/ulp_fsm/ulp. · ULP FSM Coprocessor polls ADC in while main CPU is in deep sleep: system/ulp_fsm/ulp_adc. API Reference Header File · components/ulp/ulp_fsm/include/ulp_fsm_common.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_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 esp_err_t ulp_run(uint32_t entry_point) Run the program loaded into RTC memory. Espressif Systems 1650 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Return ESP_OK on success Parameters · entry_point: entry point, expressed in 32-bit words Macros 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) Type Definitions typedef union ulp_insn ulp_insn_t Header File · components/ulp/ulp_common/include/ulp_common.h Functions esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) Set one of ULP wakeup period values. ULP coprocessor starts running the program when the wakeup timer counts up to a given value (called period). There are 5 period values which can be programmed into SENS_ULP_CP_SLEEP_CYCx_REG registers, x = 0..4 for ESP32, and one period value which can be programmed into RTC_CNTL_ULP_CP_TIMER_1_REG register for ESP32-S2/S3. By default, for ESP32, wakeup timer will use the period set into SENS_ULP_CP_SLEEP_CYC0_REG, i.e. period number 0. ULP program code can use SLEEP instruction to select which of the SENS_ULP_CP_SLEEP_CYCx_REG should be used for subsequent wakeups. However, please note that SLEEP instruction issued (from ULP program) while the system is in deep sleep mode does not have effect, and sleep cycle count 0 is used. For ESP32-S2/S3 the SLEEP instruction not exist. Instead a WAKE instruction will be used. Note The ULP FSM requires two clock cycles to wakeup before being able to run the program. Then additional 16 cycles are reserved after wakeup waiting until the 8M clock is stable. The FSM also requires two more clock cycles to go to sleep after the program execution is halted. The minimum wakeup period that may be set up for the ULP is equal to the total number of cycles spent on the above internal tasks. For a default configuration of the ULP running at 150kHz it makes about 133us. Return · ESP_OK on success · ESP_ERR_INVALID_ARG if period_index is out of range Parameters · period_index: wakeup period setting number (0 - 4) · period_us: wakeup period, us void ulp_timer_stop(void) Stop the ULP timer. Espressif Systems 1651 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Note This will stop the ULP from waking up if halted, but will not abort any program currently executing on the ULP. void ulp_timer_resume(void) Resume the ULP timer. Note This will resume an already configured timer, but does no other configuration Header File · components/ulp/ulp_common/include/esp32s3/ulp_common_defs.h Macros RTC_SLOW_MEM RTC slow memory, 8k size 2.10.29 ULP RISC-V Coprocessor programming The ULP RISC-V coprocessor is a variant of the ULP present in ESP32-S3. Similar to ULP FSM, the ULP RISC-V coprocessor can perform tasks such as sensor readings while the main CPU stays in low power modes. The main difference between ULP FSM and ULP RISC-V is that the latter 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. Installing the ULP RISC-V Toolchain The ULP RISC-V coprocessor code is written in C (assembly is also possible) and compiled using the 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. 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 in 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 the section below for the concept of generated header files for ULP applications. Espressif Systems 1652 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 2. Run the linker script template through the C preprocessor. The template is located in components/ulp/ld directory. 3. 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. 4. Dump the contents of the ELF file into a binary (ulp_app_name.bin) which can then be embedded into the application. 5. Generate a list of global symbols (ulp_app_name.sym) in the ELF file using riscv32-espelf-nm. 6. Create an LD export script and a 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. 7. Add the generated binary to the list of binary files to be embedded into the application. 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 as 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 RISC-V program. Each global symbol defined in the ULP RISC-V 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 RISC-V program variables to be accessed as regular variables. #include "ulp_app_name.h" void init_ulp_vars() { ulp_measurement_count = 64; } Espressif Systems 1653 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. Note that CONFIG_ULP_COPROC_ENABLED and CONFIG_ULP_COPROC_TYPE_RISCV options must be enabled in menuconfig to work with ULP RISC-V. To reserve memory for the ULP, the RTC slow memory reserved for coprocessor option must be set to a value big enough to store ULP RISC-V 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)) ); } Once the program is loaded into RTC memory, the application can start it by calling the ulp_riscv_run() function: ESP_ERROR_CHECK( ulp_riscv_run() ); 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 136kHz 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 RISC-V 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 RISC-V 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_ULP_CP_TIMER_REG register. This can be done both from the ULP code and from the main program. Application Examples · ULP RISC-V Coprocessor polls GPIO while main CPU is in deep sleep: system/ulp_riscv/gpio. · ULP RISC-V Coprocessor reads external temperature sensor while main CPU is in deep sleep: sys- tem/ulp_riscv/ds18b20_onewire. API Reference Header File · components/ulp/ulp_riscv/include/ulp_riscv.h Espressif Systems 1654 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Functions esp_err_t ulp_riscv_config_and_run(ulp_riscv_cfg_t *cfg) Configure the ULP and run the program loaded into RTC memory. Return ESP_OK on success Parameters · cfg: pointer to the config struct esp_err_t ulp_riscv_run(void) Configure the ULP with default settings and run the program loaded into RTC memory. Return ESP_OK on success 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 void ulp_riscv_timer_stop(void) Stop the ULP timer. Note This will stop the ULP from waking up if halted, but will not abort any program currently executing on the ULP. void ulp_riscv_timer_resume(void) Resumes the ULP timer. Note This will resume an already configured timer, but does no other configuration void ulp_riscv_halt(void) Halts the program currently running on the ULP-RISC-V. Note Program will restart at the next ULP timer trigger if timer is still running. If you want to stop the ULP from waking up then call ulp_riscv_timer_stop() first. Structures struct ulp_riscv_cfg_t Macros ULP_RISCV_DEFAULT_CONFIG() Enumerations enum ulp_riscv_wakeup_source_t Values: ULP_RISCV_WAKEUP_SOURCE_TIMER ULP_RISCV_WAKEUP_SOURCE_GPIO Espressif Systems 1655 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 2.10.30 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. 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 Espressif Systems 1656 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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. 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. Espressif Systems 1657 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference 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 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 Espressif Systems 1658 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference · 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. Code examples for this API section are provided in the system directory of ESP-IDF examples. Espressif Systems 1659 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 2. API Reference Espressif Systems 1660 Release v5.0-dev-2349-g4350e6fef8 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 1661 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 1662 Release v5.0-dev-2349-g4350e6fef8 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 1663 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 3. ESP32-S3 Hardware Reference · ESP32-S3 Datasheet (PDF) · ESP Product Selector Espressif Systems 1664 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4 API Guides 4.1 Application Level Tracing library 4.1.1 Overview IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and ESP32-S3 via JTAG, UART or USB interfaces with small overhead on program execution. It is possible to use JTAG and UART interfaces simultaneously. The UART interface are mostly used for connection with SEGGER SystemView tool (see SystemView). Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are: 1. Collecting application specific data, see Application Specific Tracing 2. Lightweight logging to the host, see Logging to Host 3. System behavior analysis, see System Behavior Analysis with SEGGER SystemView 4. Source code coverage, see Gcov (Source Code Coverage) Tracing components when working over JTAG interface are shown in the figure below. 4.1.2 Modes of Operation The library supports two modes of operation: Post-mortem mode. This is the default mode. The mode does not need interaction with the host side. In this mode tracing module does not check whether host has read all the data from HW UP BUFFER buffer and overwrites old data with the new ones. This mode is useful when only the latest trace data are interesting to the user, e.g. for analyzing programns behavior just before the crash. Host can read the data later on upon user request, e.g. via special OpenOCD command in case of working via JTAG interface. Streaming mode. Tracing module enters this mode when host connects to ESP32-S3. In this mode, before writing new data to HW UP BUFFER, the tracing module checks that whether there is enough space in it and if necessary, waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to the trace buffer using finite value of the maximum waiting time, it is possible situation that this data will be dropped. This is especially true for tracing from time critical code (ISRs, OS scheduler code, etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data, developers can enable additional data buffering via menuconfig option CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g. due to USB bus congestions. But it will not help when the average bitrate of the trace data stream exceeds the hardware interface capabilities. 1665 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: JTAG or/and UART). Choosing any of the destinations automatically enables CONFIG_APPTRACE_ENABLE option. For UART interface user have to define baud rate, TX and RX pins numbers, and additional UART related parameters. Note: In order to achieve higher data rates and minimize number of dropped packets it is recommended to optimize setting of JTAG clock frequency, so it is at maximum and still provides stable operation of JTAG, see Optimize JTAG speed. There are two additional menuconfig options not mentioned above: 1. Threshold for flushing last trace data to host on panic (CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH). This option is necessary due to the nature of working over JTAG. In that mode trace data are exposed to the host in 16 KB blocks. In post-mortem mode when one block is filled it is exposed to the host and the previous one becomes unavailable. In other words trace data are overwritten in 16 KB granularity. On panic the latest data from the current input block are exposed to host and host can read them for post-analysis. System panic may occur when very small amount of data are not exposed to the host yet. In this case the previous 16 KB of collected data will be lost and host will see the latest, but very small piece of the trace. It can be insufficient to diagnose the problem. This menuconfig option allows avoiding such situations. It controls the threshold for flushing data in case of panic. For example user can decide that it needs not less then 512 bytes of the recent trace data, so if there is less then 512 bytes of pending data at the moment of panic they will not be flushed and will not overwrite previous 16 KB. The option is only meaningful in post-mortem mode and when working over JTAG. 2. Timeout for flushing last trace data to host on panic (CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO). Espressif Systems 1666 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 3. UART RX/TX ring buffer size (CONFIG_APPTRACE_UART_TX_BUFF_SIZE). The size of the buffer depends on amount of data transfered through the UART. 4. UART TX message size (CONFIG_APPTRACE_UART_TX_MSG_SIZE). The maximum size of the single message to transfer. 4.1.4 How to use this library This library provides API for transferring arbitrary data between host and ESP32-S3. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data. Application Specific Tracing In general user should decide what type of data should be transferred in every direction and how these data must be interpreted (processed). The following steps must be performed to transfer data between target and host: 1. On target side user should implement algorithms for writing trace data to the host. Piece of code below shows an example how to do this. #include "esp_app_trace.h" ... char buf[] = "Hello World!"; esp_err_t res = esp_apptrace_write(ESP_APPTRACE_DEST_TRAX, buf, strlen(buf), ESP_APPTRACE_TMO_INFINITE); if (res != ESP_OK) { ESP_LOGE(TAG, "Failed to write data to host!"); return res; } esp_apptrace_write() function uses memcpy to copy user data to the internal buffer. In some cases it can be more optimal to use esp_apptrace_buffer_get() and esp_apptrace_buffer_put() functions. They allow developers to allocate buffer and fill it themselves. The following piece of code shows how to do this. #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; } Also according to his needs user may want to receive data from the host. Piece of code below shows an example how to do this. #include "esp_app_trace.h" ... (continues on next page) Espressif Systems 1667 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides char buf[32]; char down_buf[32]; size_t sz = sizeof(buf); (continued from previous page) /* 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*/); if (res != ESP_OK) { ESP_LOGE(TAG, "Failed to read data from host!"); return res; } if (sz > 0) { /* we have data, process them */ ... } esp_apptrace_read() function uses memcpy to copy host data to user buffer. In some cases it can be more optimal to use esp_apptrace_down_buffer_get() and esp_apptrace_down_buffer_put() functions. They allow developers to occupy chunk of read buffer and process it in-place. The following piece of code shows how to do this. #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 Espressif Systems 1668 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides of the scope of this document. Good starting points for data processor are python scripts in $IDF_PATH/ tools/esp_app_trace: apptrace_proc.py (used for feature tests) and logtrace_proc.py (see more details in section Logging to Host). OpenOCD Application Level Tracing Commands HW UP BUFFER is shared between user data blocks and filling of the allocated memory is performed on behalf of the API caller (in task or ISR context). In multithreading environment it can happen that task/ISR which fills the buffer is preempted by another high priority task/ISR. So it is possible situation that user data preparation process is not completed at the moment when that chunk is read by the host. To handle such conditions tracing module prepends all user data chunks with header which contains allocated user buffer size (2 bytes) and length of actually written data (2 bytes). So total length of the header is 4 bytes. OpenOCD command which reads trace data reports error when it reads incomplete user data chunk, but in any case it puts contents of the whole user chunk (including unfilled area) to output file. Below is the description of available OpenOCD application tracing commands. Note: Currently OpenOCD does not provide commands to send arbitrary user data to the target. Command usage: esp apptrace [start <options>] | [stop] | [status] | [dump <cores_num> <outfile>] Sub-commands: start Start tracing (continuous streaming). stop Stop tracing. status Get tracing status. dump Dump all data from (post-mortem dump). Start command syntax: start <outfile> [poll_period [trace_size [stop_tmo [wait4halt [skip_size]]]] outfile Path to file to save data from both CPUs. This argument should have the following format: file:// path/to/file. poll_period Data polling period (in ms) for available trace data. If greater than 0 then command runs in 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). Optionally set it to value longer than longest pause between tracing commands from target. wait4halt If 0 start tracing immediately, otherwise command waits for the target to be halted (after reset, by breakpoint etc.) and then automatically resumes it and starts tracing. By default 0. skip_size Number of bytes to skip at the start. By default 0. Note: If poll_period is 0, OpenOCD telnet command line will not be available until tracing is stopped. You must stop it manually by resetting the board or pressing Ctrl+C in OpenOCD window (not one with the telnet session). Another option is to set trace_size and wait until this size of data is collected. At this point tracing stops automatically. Command usage examples: 1. Collect 2048 bytes of tracing data to a 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. Espressif Systems 1669 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Note: Tracing data is buffered before it is made available to OpenOCD. If you seeoData timeout!pmessage, then the target is likely sending not enough data to empty the buffer to OpenOCD before expiration of 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. esp apptrace start file://trace.log 1 -1 -1 0 0 There is no limitation on the size of collected data and there is no any data timeout set. This process may be stopped by issuing esp apptrace stop command on OpenOCD telnet prompt, or by pressing Ctrl+C in OpenOCD window. 3. Retrieve tracing data and save them indefinitely. esp apptrace start file://trace.log 0 -1 -1 0 0 OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing press Ctrl+C in OpenOCD window. 4. Wait for target to be halted. Then resume 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 useful feature: logging to host via application level tracing library. This is a kind of semihosting when all ESP_LOGx calls send strings to be printed to the host instead of UART. This can be useful becauseoprinting to hostpeliminates some steps performed when logging to UART. The most part of work is done on the host. By default IDFns logging library uses vprintf-like function to write formatted output to dedicated UART. In general it involves the following steps: 1. Format string is parsed to obtain type of each argument. 2. According to its type every argument is converted to string representation. 3. Format string combined with converted arguments is sent to UART. Though implementation of vprintf-like function can be optimized to a certain level, all steps above have to be performed in any case and every step takes some time (especially item 3). So it frequently occurs that with additional log added to the program to identify the problem, the program behavior is changed and the problem cannot be reproduced or in the worst cases the program cannot work normally at all and ends up with an error or even hangs. Possible ways to overcome this problem are to use higher UART bitrates (or another faster interface) and/or move string formatting procedure to the host. Application level tracing feature can be used to transfer log information to host using esp_apptrace_vprintf function. This function does not perform full parsing of the format string and arguments, instead it just calculates number of arguments passed and sends them along with the format string address to the host. On the host log data are processed and printed out by a special Python script. Limitations Current implementation of logging over JTAG has some limitations: 1. Tracing from ESP_EARLY_LOGx macros is not supported. 2. No support for printf arguments which size exceeds 4 bytes (e.g. double and uint64_t). 3. Only strings from .rodata section are supported as format strings and arguments. 4. Maximum number of printf arguments is 256. How To Use It In order to use logging via trace module user needs to perform the following steps: Espressif Systems 1670 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 1. On target side special vprintf-like function needs to be installed. As it was mentioned earlier this function is esp_apptrace_vprintf. It sends 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. 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. It is possible to view events in real-time through the UART interface. 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. SytemView destination. Select the destination interface: JTAG or UART. In case of UART it will be possible to connect SystemView application to the ESP32-S3 directly and receive data in real-time. 2. 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 ESP32-S3 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. 3. 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. Espressif Systems 1671 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4. Select Pro or App CPU in menuconfig options Component config > Application Level Tracing > FreeRTOS SystemView Tracing to trace over UART interface in real-time. OpenOCD SystemView Tracing Command Options Command usage: esp sysview [start <options>] | [stop] | [status] Sub-commands: start Start tracing (continuous streaming). stop Stop tracing. status Get tracing status. Start command syntax: start <outfile1> [outfile2] [poll_period [trace_size [stop_tmo]]] outfile1 Path to file to save data from PRO CPU. This argument should have the following format: file:// path/to/file. outfile2 Path to file to save data from APP CPU. This argument should have the following format: file:// path/to/file. poll_period Data polling period (in ms) for available trace data. If greater then 0 then command runs in 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 are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from ESP32-S3 working with JTAG in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool. For tracing over UART, user can select in menuconfig Pro or App Component config > Application Level Tracing > FreeRTOS SystemView Tracing with CPU has to be traced. It is uneasy and awkward to analyze data for every core in separate instance of the tool. Fortunately there is Eclipse plugin called Impulse which can load several trace files and makes it possible to inspect events from both cores in one view. Also this plugin has no limitation of 1,000,000 events as compared to free version of SystemView. Good instruction on how to install, configure and visualize data in Impulse from one core can be found here. Espressif Systems 1672 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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: 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 by the fact that the program is running remotely from the Host (i.e., on the target). The code coverage data (i.e., the .gcda files) is initially stored on the target itself. OpenOCD is then used to dump the code coverage data from the target to the host via JTAG during runtime. Using Gcov in ESP-IDF can be split into the following steps. 1. Setting Up a Project for Gcov 2. Dumping Code Coverage Data 3. Generating Coverage Report Espressif Systems 1673 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. · To cause a select number of source files (e.g. sourec1.c and source2.c) in the same component to be compiled with the --coverage option, you can add set_source_files_properties(source1. c source2.c PROPERTIES COMPILE_FLAGS --coverage) to the CMakeLists.txt file of the component. When a source file is compiled with the --coverage option (e.g. gcov_example.c), the compiler will generate the gcov_example.gcno file in the 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_DESTINATION1 option. · Enable Gcov to host via the CONFIG_APPTRACE_GCOV_ENABLE Dumping Code Coverage Data Once a project has been complied with the --coverage option and flashed onto the target, code coverage data will be stored internally on the target (i.e., in trace memory) whilst the application runs. The process of transferring code coverage data from the target to the Host is know as dumping. The dumping of coverage data is done via OpenOCD (see JTAG Debugging on how to setup and run OpenOCD). A dump is triggered by issuing commands to OpenOCD, therefore a telnet session to OpenOCD must be opened to issue such commands (run telnet localhost 4444). Note that GDB could be used instead of telnet to issue 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 life time. Each dump will simply update the .gcda file with the newest code coverage information. Code coverage data is accumulative, thus the newest data will contain the total execution count of each code path over the applicationns entire lifetime. ESP-IDF supports two methods of dumping code coverage data form the target to the host: · Instant Run-Time Dumpgit · Hard-coded Dump Instant Run-Time Dump An Instant Run-Time Dump is triggered by calling the ESP32-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 itns 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. Espressif Systems 1674 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. b esp_gcov_dump commands mon esp gcov dump end Note: Note that all OpenOCD commands should be invoked in GDB as: mon <oocd_command>. Generating Coverage Report Once the code coverage data has been dumped, the .gcno, .gcda and the source files can be used to generate a code coverage report. A code coverage report is simply a report indicating the number of times each line in a source file has been executed. Both Gcov and Gcovr can be used to generate code coverage reports. Gcov is provided along with the Xtensa toolchain, whilst Gcovr may need to be installed separately. For details on how to use Gcov or Gcovr, refer to Gcov documentation and Gcovr documentation. Adding Gcovr Build Target to Project To make report generation more convenient, users can define additional build targets in their projects such report generation can be done with a single build command. Add the following lines to the CMakeLists.txt file of your project. include($ENV{IDF_PATH}/tools/cmake/gcov.cmake) idf_create_coverage_report(${CMAKE_CURRENT_BINARY_DIR}/coverage_report) idf_clean_coverage_report(${CMAKE_CURRENT_BINARY_DIR}/coverage_report) The following commands can now be used: · cmake --build build/ --target gcovr-report will generate an HTML coverage report in $(BUILD_DIR_BASE)/coverage_report/html directory. · cmake --build build/ --target cov-data-clean will remove all coverage data files. 4.2 Application Startup Flow This note explains various steps which happen before app_main function of an ESP-IDF application is called. The high level view of startup process is as follows: 1. First stage bootloader in ROM loads second-stage bootloader image to RAM (IRAM & DRAM) from flash offset 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. Espressif Systems 1675 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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: 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. Espressif Systems 1676 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.2.3 Application startup Application startup covers everything that happens after the app starts executing and before the app_main function starts running inside the main task. This is split into three stages: · Port initialization of hardware and basic C runtime environment. · System initialization of software services and FreeRTOS. · Running the main task and calling app_main. Note: Understanding all stages of ESP-IDF app initialization is often not necessary. To understand initialization from the application 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. Espressif Systems 1677 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides After doing some more initialization tasks (that require the scheduler to have started), the main task runs the application-provided function app_main in the firmware. The main task that runs app_main has a fixed RTOS priority (one higher than the minimum) and a configurable stack size. The main task core affinity is also configurable: CONFIG_ESP_MAIN_TASK_AFFINITY. Unlike normal FreeRTOS tasks (or embedded C main functions), the app_main task is allowed to return. If this happens, The task is cleaned up and the system will continue running with other RTOS tasks scheduled normally. Therefore, it is possible to implement app_main as either a function that creates other application tasks and then returns, or as a main application task itself. Second core startup A similar but simpler startup process happens on the APP CPU: When running system initialization, the code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, APP CPU jumps to call_start_cpu1 function in components/esp_system/port/cpu_start.c. While PRO CPU does initialization in start_cpu0 function, APP CPU runs start_cpu_other_cores function. Similar to start_cpu0, this function is weak-linked and defaults to the start_cpu_other_cores_default function but can be replaced with a different function by the application. The start_cpu_other_cores_default function does some core-specific system 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. Espressif Systems 1678 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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 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 Espressif Systems 1679 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 2: BluFi Flow Chart Espressif Systems 1680 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 1681 Release v5.0-dev-2349-g4350e6fef8 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 1682 Document Feeamdbofobalilcloekwp-huopnRefer.laemasee ovf5.W0-di-eFvi-2li3st49re-gp4o3rt50toe6tfheef8 Chapter 4. API Guides 1.2 Data Frame (Binary: 0x1 bn01) Espressif Systems 1683 Release v5.0-dev-2349-g4350e6fef8 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 priva1te68ke4y of Please referRteoleNaosetev25.b0e-dloewv-.2349-g4350e6fef8 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 1685 Release v5.0-dev-2349-g4350e6fef8 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 1686 Release v5.0-dev-2349-g4350e6fef8 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 1687 Release v5.0-dev-2349-g4350e6fef8 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 1688 Release v5.0-dev-2349-g4350e6fef8 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 1689 Release v5.0-dev-2349-g4350e6fef8 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 of 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 1690 Release v5.0-dev-2349-g4350e6fef8 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 1691 Release v5.0-dev-2349-g4350e6fef8 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 1692 Release v5.0-dev-2349-g4350e6fef8 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 Python version 3.7+. 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 1693 Release v5.0-dev-2349-g4350e6fef8 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 1694 Release v5.0-dev-2349-g4350e6fef8 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 1695 Release v5.0-dev-2349-g4350e6fef8 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 1696 Release v5.0-dev-2349-g4350e6fef8 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 1697 Release v5.0-dev-2349-g4350e6fef8 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 1698 Release v5.0-dev-2349-g4350e6fef8 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 1699 Release v5.0-dev-2349-g4350e6fef8 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 1700 Release v5.0-dev-2349-g4350e6fef8 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 1701 Release v5.0-dev-2349-g4350e6fef8 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 1702 Release v5.0-dev-2349-g4350e6fef8 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 1703 Release v5.0-dev-2349-g4350e6fef8 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 1704 Release v5.0-dev-2349-g4350e6fef8 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 1705 Release v5.0-dev-2349-g4350e6fef8 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 1706 Release v5.0-dev-2349-g4350e6fef8 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 1707 Release v5.0-dev-2349-g4350e6fef8 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 1708 Release v5.0-dev-2349-g4350e6fef8 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 of 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 1709 Release v5.0-dev-2349-g4350e6fef8 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 1710 Release v5.0-dev-2349-g4350e6fef8 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 1711 Release v5.0-dev-2349-g4350e6fef8 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 1712 Release v5.0-dev-2349-g4350e6fef8 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 1713 Release v5.0-dev-2349-g4350e6fef8 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 1714 Release v5.0-dev-2349-g4350e6fef8 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 1715 Release v5.0-dev-2349-g4350e6fef8 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 1716 Release v5.0-dev-2349-g4350e6fef8 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 1717 Release v5.0-dev-2349-g4350e6fef8 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 1718 Release v5.0-dev-2349-g4350e6fef8 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 Core Dump 4.6.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 Espressif Systems 1719 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.6.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 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.6.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> Espressif Systems 1720 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides or espcoredump.py -p </path/to/serial/port> dbg_corefile </path/to/program/elf/file> 4.6.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. 4.6.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.6.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. Espressif Systems 1721 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.6.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 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. Espressif Systems 1722 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 4: Core dump ELF image format Espressif Systems Fig. 5: Core dump binary image format 1723 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Overview of implementation The figure below describes some basic aspects related to implementation of core dump: Fig. 6: Core dump implementation overview Note: The diagram above hide some details and represents current implementation of the core dump and can be changed later. 4.7 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.7.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 1724 Release v5.0-dev-2349-g4350e6fef8 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.7.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.7.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.7.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 1725 Release v5.0-dev-2349-g4350e6fef8 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.7.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.8 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 1726 Release v5.0-dev-2349-g4350e6fef8 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 Software 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.8.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.8.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 Software 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 1727 Release v5.0-dev-2349-g4350e6fef8 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 Software 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.9 Error Handling 4.9.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 1728 Release v5.0-dev-2349-g4350e6fef8 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.9.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.9.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.9.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 1729 Release v5.0-dev-2349-g4350e6fef8 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.9.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.9.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.9.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.9.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.9.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.9.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 1730 Release v5.0-dev-2349-g4350e6fef8 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.9.11 Error handling patterns 1. Attempt to recover. Depending on the situation, we may try the following methods: · retry the call after some time; · attempt to de-initialize the driver and re-initialize it again; · 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 behavior 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 1731 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.9.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.10 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.10.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 1732 Release v5.0-dev-2349-g4350e6fef8 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 1733 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 7: ESP-BLE-MESH Devices Power On Espressif Systems Fig. 8: nRF Mesh - Scanner 1734 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 9: 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 1735 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 10: nRF Mesh - Configuration Complete Espressif Systems Fig. 11: nRF Mesh - Initial Configuration Failed 1736 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 12: nRF Mesh - Reconnect - Initial Configuration Espressif Systems Fig. 13: nRF Mesh - Reconnect - Three Nodes 1737 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 14: 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.10.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 1738 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 15: nRF Mesh - Generic OnOff Control Espressif Systems Fig. 16: Three ESP-BLE-MESH Nodes On 1739 Release v5.0-dev-2349-g4350e6fef8 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.10.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.10.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.10.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 1740 Release v5.0-dev-2349-g4350e6fef8 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 1741 Release v5.0-dev-2349-g4350e6fef8 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 1742 Release v5.0-dev-2349-g4350e6fef8 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 1743 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 17: Figure 1.1 ESP-BLE-MESH Architecture Diagram Espressif Systems 1744 Release v5.0-dev-2349-g4350e6fef8 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 1745 Release v5.0-dev-2349-g4350e6fef8 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 1746 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 18: Figure 2.1 ESP-BLE-MESH Architecture Implementation Diagram Espressif Systems 1747 Release v5.0-dev-2349-g4350e6fef8 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 1748 Release v5.0-dev-2349-g4350e6fef8 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 1749 Release v5.0-dev-2349-g4350e6fef8 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 1750 Release v5.0-dev-2349-g4350e6fef8 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 1751 Release v5.0-dev-2349-g4350e6fef8 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 1752 Release v5.0-dev-2349-g4350e6fef8 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 1753 Release v5.0-dev-2349-g4350e6fef8 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 1754 Release v5.0-dev-2349-g4350e6fef8 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 1755 Release v5.0-dev-2349-g4350e6fef8 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 1756 Release v5.0-dev-2349-g4350e6fef8 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 1757 Release v5.0-dev-2349-g4350e6fef8 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 1758 Release v5.0-dev-2349-g4350e6fef8 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 1759 Release v5.0-dev-2349-g4350e6fef8 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 1760 Release v5.0-dev-2349-g4350e6fef8 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 1761 Release v5.0-dev-2349-g4350e6fef8 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 1762 Release v5.0-dev-2349-g4350e6fef8 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 1763 Release v5.0-dev-2349-g4350e6fef8 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 1764 Release v5.0-dev-2349-g4350e6fef8 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 1765 Release v5.0-dev-2349-g4350e6fef8 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 1766 Release v5.0-dev-2349-g4350e6fef8 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 1767 Release v5.0-dev-2349-g4350e6fef8 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 1768 Release v5.0-dev-2349-g4350e6fef8 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.11 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 Startup and Termination Critical Sections API Changes Implementation Restrictions and Considerations Misc Floating Point Usage ESP-IDF FreeRTOS Single Core 4.11.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: Espressif Systems 1769 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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.11.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: · 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.11.3 Tasks Creation Vanilla FreeRTOS provides the following functions to create a task: Espressif Systems 1770 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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 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 Espressif Systems 1771 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.11.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 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. Espressif Systems 1772 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 Head [ B0 , C1 , D0 , AX ] Tail -------------------------------------------------------------------------------- 3. Core 1 has a tick interrupt and searches for a task to run. Task B cannot be run due to incompatible affinity, so core 1 skips to Task C. Task C is selected and is moved to the back of the list Core1-------| 0 Head [ B0 , C1 , D0 , AX ] Tail 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 (continues on next page) Espressif Systems 1773 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Head [ D0 , AX , C1 , B0 ] Tail (continued from previous page) -------------------------------------------------------------------------------- 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: · 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. Espressif Systems 1774 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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.11.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 Espressif Systems 1775 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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) 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.11.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 Espressif Systems 1776 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 4.12 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.12.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 Espressif Systems 1777 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 6. Channel Switching 7. Performance 8. Further Notes 4.12.2 Introduction Fig. 19: Traditional Wi-Fi Network Architecture A traditional infrastructure Wi-Fi network is a point-to-multipoint network where a single central node known as the access point (AP) is directly connected to all other nodes known as stations. The AP is responsible for arbitrating and forwarding transmissions between the stations. Some APs also relay transmissions to/from an external IP network via a router. Traditional infrastructure Wi-Fi networks suffer the disadvantage of limited coverage area due to the requirement that every station must be in range to directly connect with the AP. Furthermore, traditional Wi-Fi networks are susceptible to overloading as the maximum number of stations permitted in the network is limited by the capacity of the AP. Espressif Systems Fig. 20: ESP-WIFI-MESH Network Architecture 1778 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.12.3 ESP-WIFI-MESH Concepts 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 Espressif Systems 1779 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 21: ESP-WIFI-MESH Tree Topology 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. 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 Espressif Systems 1780 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 22: ESP-WIFI-MESH Node Types 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: Espressif Systems 1781 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 23: Effects of RSSI Thresholding · Which layer the parent node candidate is situated on · The number of downstream connections (child nodes) the parent node candidate currently has 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. 24: 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 Espressif Systems 1782 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides preferred parent node due it having fewer downstream connections (fewer child nodes) compared to node B. Panel B of the illustration above demonstrates the case where the root node is within range of the idle node G. In other words, the root 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. 25: 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. Espressif Systems 1783 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides esp_mesh_get_subnet_nodes_list() can be used to obtain the corresponding subtable of a specific child node. Likewise esp_mesh_get_subnet_nodes_num() can be used to obtain the size of the subtable. 4.12.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. 26: 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. Espressif Systems 1784 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 3. Formation of remaining layers The remaining idle nodes will connect with intermediate parent nodes within range thereby forming a new layer in the network. Once connected, the idles nodes become intermediate parent node or leaf nodes depending on the networks maximum permitted layers. This step is repeated until there are no more idle nodes within the network or until the maximum permitted layer of the network has been reached. Referring to the figure above, nodes E/F/G connect with nodes B/C/D respectively and become intermediate parent nodes themselves. 4. Limiting Tree Depth To prevent the network from exceeding the maximum permitted number of layers, nodes on the maximum layer will automatically become leaf nodes once connected. This prevents any other idle node from connecting with the leaf node thereby prevent a new layer form forming. However if an idle node has no other potential parent node, it will remain idle indefinitely. Referring to the figure above, the 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. Espressif Systems Fig. 27: Root Node Election Example 1785 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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. 28: Root Node Designation Example (Root Node = A, Max Layers = 4) Espressif Systems 1786 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 1. Node A is designated the root node by the user therefore directly connects with the router. All other nodes forgo the election process. 2. Nodes C/D connect with node A as their preferred parent node. Both nodes form the second layer of the network. 3. Likewise, nodes B/E connect with node C, and node F connects with node D. Nodes B/E/F form the third layer of the network. 4. Node G connects with node E, forming the fourth layer of the network. However the maximum permitted number of layers in this network is configured as four, therefore node G becomes a leaf node to prevent any new layers from forming. Note: When designating a root node, the root node should call esp_mesh_set_parent() in order to directly connect with the router. Likewise, all other nodes should call esp_mesh_fix_root() to forgo the election process. Parent Node Selection By default, ESP-WIFI-MESH is self organizing meaning that each node will autonomously select which potential parent node to form an upstream connection with. The autonomously selected parent node is known as the preferred parent node. The criteria used for selecting the preferred parent node is designed to reduce the number of layers in the ESP-WIFI-MESH network and to balance the number of downstream connections between potential parent nodes (see section on Preferred Parent Node). However ESP-WIFI-MESH also allows users to disable self-organizing behavior which will allow users to define their own criteria for parent node selection, or to configure nodes to have designated parent nodes (see the Mesh Manual Networking Example). Asynchronous Power-on Reset ESP-WIFI-MESH network building can be affected by the order in which nodes power-on. If certain nodes within the network power-on asynchronously (i.e. separated by several minutes), the final structure of the network could differ from the ideal case where all nodes are powered on synchronously. Nodes that are delayed in powering on will adhere to the following rules: Rule 1: If a root node already exists in the network, the delayed node will not attempt to elect a new root node, even if it has a stronger RSSI with the router. The delayed node will instead join the network like any other idle node by connecting with a preferred parent node. If the delayed node is the designated root node, all other nodes in the network will remain idle until the delayed node powers-on. Rule 2: If a delayed node forms an upstream connection and becomes an intermediate parent node, it may also become the new preferred parent of other nodes (i.e. being a shallower node). This will cause the other nodes to switch their upstream connections to connect with the delayed node (see Parent Node Switching). Rule 3: If an idle node has a designated parent node which is delayed in powering-on, the idle node will not attempt to form any upstream connections in the absence of its designated parent node. The idle node will remain idle indefinitely until its designated parent node powers-on. The following example demonstrates the effects of asynchronous power-on with regards to network building. 1. Nodes A/C/D/F/G/H are powered-on synchronously and begin the root node election process by broadcasting their MAC addresses and router RSSIs. Node A is elected as the root node as it has the strongest RSSI. 2. Once node A becomes the root node, the remaining nodes begin forming upstream connections layer by layer with their preferred parent nodes. The result is a network with five layers. 3. Node B/E are delayed in powering-on but neither attempt to become the root node even though they have stronger router RSSIs (-20 dB and -10 dB) compared to node A. Instead both delayed nodes form upstream connections with their preferred parent nodes A and C respectively. Both nodes B/E become intermediate parent nodes after connecting. Espressif Systems 1787 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 29: Network Building with Asynchronous Power On Example Espressif Systems 1788 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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.12.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 1789 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 30: 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. 31: 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 1790 Release v5.0-dev-2349-g4350e6fef8 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. 32: 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 1791 Release v5.0-dev-2349-g4350e6fef8 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.12.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. 33: 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 1792 Release v5.0-dev-2349-g4350e6fef8 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 1793 Release v5.0-dev-2349-g4350e6fef8 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. 34: 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.12.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 1794 Release v5.0-dev-2349-g4350e6fef8 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 1795 Release v5.0-dev-2349-g4350e6fef8 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 1796 Release v5.0-dev-2349-g4350e6fef8 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.12.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 1797 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Note: The performance figures can vary greatly between installations based on network configuration and operating environment. 4.12.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.13 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.13.1 Wi-Fi, Ethernet, and IP Events Before the introduction of esp_event library, events from Wi-Fi driver, Ethernet driver, and TCP/IP stack were dispatched using the so-called legacy event loop. The following sections explain each of the methods. esp_event Library Event Loop esp_event library is designed to supersede the legacy event loop for the purposes of event handling in ESP-IDF. In the legacy event loop, all possible event types and event data structures had to be defined in system_event_id_t enumeration and system_event_info_t union, which made it impossible to send custom events to the event loop, and use the event loop for other kinds of events (e.g. Mesh). Legacy event loop also supported only one event handler function, therefore application components could not handle some of Wi-Fi or IP events themselves, and required application to forward these events from its event handler function. See esp_event library API reference for general information on using this library. Wi-Fi, Ethernet, and IP events are sent to the default event loop provided by this library. Legacy Event Loop This event loop implementation is started using esp_event_loop_init() function. Application typically 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. Espressif Systems 1798 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides If application event handler needs to relay the event to some other task, it is important to note that event pointer passed to the event handler is a pointer to temporary structure. To pass the event to another task, application has to make a copy of the entire structure. Event IDs and Corresponding Data Structures Event ID (legacy event ID) 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.13.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 1799 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.13.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_ble_gattc_cb_event_t, esp_ble_gattc_cb_param_t. · GATTS: esp_ble_gatts_register_callback(), esp_ble_gatts_cb_event_t, esp_ble_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_bt_hf_register_callback(), esp_hf_cb_event_t, esp_hf_cb_param_t. 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. 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. Espressif Systems 1800 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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_ESP_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 A6 : 0x00000000 A7 0x3ffb5000 A10 : 0x00000000 A11 0x06ff1ff8 A14 : 0x3ffb7078 A15 0x0000001d EXCVADDR: 0x00000000 LBEG 0xffffffff : 0x00060030 A0 : 0x00000001 A4 : 0x00000001 A8 : 0x3ffb2bac A12 : 0x00000000 SAR : 0x4000c46c LEND : 0x800d0805 A1 : : 0x00000001 A5 : : 0x00000000 A9 : : 0x40082d1c A13 : : 0x00000014 EXCCAUSE: : 0x4000c477 LCOUNT : (continues on next page) Espressif Systems 1801 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 35: Panic Handler Flowchart (click to enlarge) Espressif Systems 1802 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides (continued from previous page) 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: 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. (continues on next page) Espressif Systems 1803 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides (continued from previous page) 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. 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). Espressif Systems 1804 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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. Espressif Systems 1805 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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_ESP_BROWNOUT_DET and CONFIG_ESP_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. 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. Espressif Systems 1806 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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: Espressif Systems 1807 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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). 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. Espressif Systems 1808 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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]. Espressif Systems 1809 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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: 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 Espressif Systems 1810 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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 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... (continues on next page) Espressif Systems 1811 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides (continued from previous page) 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 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 (continues on next page) Espressif Systems 1812 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides (continued from previous page) 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. 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): Espressif Systems 1813 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 · 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 Espressif Systems 1814 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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 Espressif Systems 1815 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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: Espressif Systems 1816 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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: Espressif Systems 1817 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 Data stored using the Non-Volatile Storage (NVS) API is always stored and read decrypted from the perspective of flash encryption. It is up to the library to provide encryption feature if required. Refer to NVS Encryption for more details. Writing to Encrypted Flash It is recommended to use the partition write function esp_partition_write(). This function will only encrypt data when it is written to an encrypted partition. Data written to unencrypted partitions will not be encrypted. In this way, software can access encrypted and non-encrypted flash in the same way. You can also pre-encrypt and write data using the function esp_flash_write_encrypted() Also, the following ROM function exist but not supported in esp-idf applications: · esp_rom_spiflash_write_encrypted pre-encrypts and writes data to flash · SPIWrite writes unencrypted data to flash Since data is encrypted in blocks, the minimum write size for encrypted data is 16 bytes and the alignment is also 16 bytes. Espressif Systems 1818 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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). Espressif Systems 1819 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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. Espressif Systems 1820 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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 encryption. 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. 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. Espressif Systems 1821 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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. Espressif Systems 1822 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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. Espressif Systems 1823 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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. Espressif Systems 1824 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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.17.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 1825 Release v5.0-dev-2349-g4350e6fef8 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.17.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 1826 Release v5.0-dev-2349-g4350e6fef8 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.17.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 1827 Release v5.0-dev-2349-g4350e6fef8 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.18 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.18.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.18.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 1828 Release v5.0-dev-2349-g4350e6fef8 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.19 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.19.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 1829 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.19.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.19.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 1830 Release v5.0-dev-2349-g4350e6fef8 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.19.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.19.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 1831 Release v5.0-dev-2349-g4350e6fef8 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 For guidance about which JTAG interface to select to enable operation with OpenOCD and ESP32-S3, refer to section Selecting JTAG Adapter. Then follow the 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 usable, 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 hardware that may disturb JTAG operation. 3. Connect identified pin/signals of ESP32-S3 and JTAG interface. Espressif Systems 1832 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Configure Drivers You may need to install driver software to make JTAG work with computer. Refer to documentation of your JTAG adapter for related details. Connect Connect JTAG interface to the computer. Power on ESP32-S3 and JTAG interface boards. Check if the JTAG interface is visible on the 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 1833 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Upload application for debugging Build and upload your application to ESP32-S3 as usual, see Step 5. First Steps on ESP-IDF. 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.19.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.19.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.19.8 Building OpenOCD from Sources Please refer to separate documents listed below, that describe build process. Espressif Systems 1834 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Building OpenOCD from Sources for Windows Note: This document outlines how to build a binary of OpenOCD from its source files instead of downloading the pre-built binary. For a quick setup, users can download a pre-built binary of OpenOCD from Espressif GitHub instead of compiling it themselves (see Setup of OpenOCD for more details). Note: All code snippets in this document are assumed to be running in an MSYS2 shell with the 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 Espressifns GitHub under https://github.com/espressif/openocd-esp32. These source files can be pulled via Git using 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 The libusb library is also required when building OpenOCD. The following commands will download a particular release of libusb and uncompress it to the current directory. wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z 7z x -olibusb ./libusb-1.0.22.7z We now need to export the following variables such that the libusb library gets linked into the OpenOCD build. export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0" export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll" Build OpenOCD The following commands will configure OpenOCD then build it. 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 Once the build is completed, the OpenOCD binary will be placed in ~/esp/openocd-esp32/src/. You can then optionally call make install. This will copy the OpenOCD binary to a user specified location. Espressif Systems 1835 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · This location can be specified when OpenOCD is configured, or by setting export DESTDIR="/custom/ install/dir" before calling make install. · If you have an existing OpenOCD (from e.g. another development platform), you may want to skip this call as your existing OpenOCD 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.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 For greater convenience, all of commands called throughout the OpenOCD build process have been listed in the code snippet below. Users can copy this code snippet into a shell script then execute it: 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. Espressif Systems 1836 Release v5.0-dev-2349-g4350e6fef8 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. 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. Espressif Systems 1837 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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 Espressif Systems 1838 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 and Windows: src\openocd -f board/esp32s3-builtin.cfg 4.19.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: Espressif Systems 1839 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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_ESP_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. Espressif Systems 1840 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. · board configuration files are provided for development boards with a built-in JTAG adapter. Such files in- clude an interface configuration file to choose the adapter, and target configuration file to choose the chip/module. The following configuration files are available for ESP32-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. Espressif Systems 1841 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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. Espressif Systems 1842 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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.19.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. Espressif Systems 1843 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. Fig. 37: Configuration of GDB Hardware Debugging - Main tab 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. 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: Espressif Systems 1844 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 38: Configuration of GDB Hardware Debugging - Debugger tab Espressif Systems 1845 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. Fig. 39: Configuration of GDB Hardware Debugging - Startup tab 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. 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. If you are not quite sure how to use GDB, check Eclipse example debugging session in section Debugging Examples. Command Line Espressif Systems 1846 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 40: Debug Perspective in Eclipse Espressif Systems 1847 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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? 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] (continues on next page) Espressif Systems 1848 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides [New Thread 1073413708] [New Thread 1073431316] [New Thread 1073410672] [New Thread 1073408876] [New Thread 1073432196] [New Thread 1073411552] [Switching to Thread 1073411996] (continued from previous page) Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink. c:43 43 xTaskCreate(&blink_task, "blink_task", 512, NULL, 5, NULL); (gdb) Note the third line from bottom that shows debugger halting at breakpoint established in gdbinit file at function app_main(). Since the processor is halted, the LED should not be blinking. If this is what you see as well, you are ready to start debugging. If you are not quite sure how to use GDB, check Command Line example debugging session in section Debugging Examples. idf.py debug targets It is also possible to execute the described debugging tools conveniently from idf.py. These commands are supported: 1. idf.py openocd Runs OpenOCD in a console with configuration defined in the environment or via command line. It uses default script directory defined as OPENOCD_SCRIPTS environmental variable, which is automatically added from an Export script (export.sh or export.bat). It is possible to override the script location using command line argument --openocd-scripts. As for the JTAG configuration of the current board, please use the environmental variable OPENOCD_COMMANDS or --openocd-commands command line argument. If none of the above is defined, OpenOCD is started with -f board/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(). Espressif Systems 1849 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 41: Debug Perspective in Eclipse Espressif Systems 1850 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. Fig. 42: Target halted during debugging 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. 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. 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 Espressif Systems 1851 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 43: Navigate through the call stack Espressif Systems 1852 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. Fig. 44: Setting a breakpoint 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. 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. Espressif Systems 1853 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 45: Three breakpoints are set / maximum two are allowed Espressif Systems 1854 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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. Espressif Systems 1855 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 47: Stepping through the code with oStep Over (F6)p Espressif Systems 1856 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 48: Stepping through the code with oStep Into (F5)p Espressif Systems 1857 Release v5.0-dev-2349-g4350e6fef8 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. 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 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. Espressif Systems 1858 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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(): 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 Espressif Systems 1859 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 52: Setting a conditional breakpoint Espressif Systems 1860 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 } 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) (continues on next page) Espressif Systems 1861 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides (continued from previous page) 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 [Switching to thread 5 (Thread 1073410208)] #0 0x4000bfea in ?? () (gdb) Then check the backtrace: (gdb) bt #0 0x4000bfea in ?? () #1 0x40083a85 in vPortCPUReleaseMutex (mux=<optimized out>) at /home/user-name/ esp/esp-idf/components/freertos/./port.c:415 #2 0x40083fc8 in vTaskSwitchContext () at /home/user-name/esp/esp-idf/components/ freertos/./tasks.c:2846 #3 0x4008532b in _frxt_dispatch () (continues on next page) Espressif Systems 1862 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides (continued from previous page) #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); (gdb) You will be also able to see that LED is changing the state only if you resume program execution by entering c. To examine how many breakpoints are set and where, use command info break: (gdb) info break Num Type Disp Enb Address What 2 breakpoint keep y 0x400db6f6 in blink_task at /home/user-name/esp/ blink/main/./blink.c:33 breakpoint already hit 1 time 3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/ blink/main/./blink.c:36 (continues on next page) Espressif Systems 1863 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides breakpoint already hit 1 time (gdb) (continued from previous page) 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. 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: Espressif Systems 1864 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides (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. 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 (continues on next page) Espressif Systems 1865 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides (continued from previous page) 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: (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 (continues on next page) Espressif Systems 1866 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 33 (gdb) i++; (continued from previous page) 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: (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) Espressif Systems 1867 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.20 Linker Script Generation 4.20.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.20.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 src/ my_src1.c my_src2.c my_src3.c my_linker_fragment_file.lf · a component named my_component that is archived as library libmy_component.a during build · three source files archived under the library, my_src1.c, my_src2.c and my_src3.c which are com- piled as my_src1.o, my_src2.o and my_src3.o, respectively Espressif Systems 1868 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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: [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: Espressif Systems 1869 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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) my_src2 (noflash) elif PERFORMANCE_LEVEL = 3: my_src1 (noflash) my_src2 (noflash) my_src3 (noflash) else: * (rtc) Nesting condition-checking is also possible. The following is equivalent to the snippet above: Espressif Systems 1870 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides [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.20.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 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 (continues on next page) Espressif Systems 1871 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides value ... (continued from previous page) · 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: if CONDITION = y: value_a else: value_b # Entire fragment definition is dependent on config if CONDITION = y: [type:name] key_1: (continues on next page) Espressif Systems 1872 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides value_1 key_2: value_b else: [type:name] key_1: value_2 key_2: value_b (continued from previous page) 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 sections -> target ... Example: [scheme:noflash] entries: (continues on next page) Espressif Systems 1873 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides text -> iram0_text text will go to iram0_text rodata -> dram0_data rodata will go to dram0_data (continued from previous page) # 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, .section, # same should be done for these sections ... -> target, ...) # and so on Example: Espressif Systems 1874 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides [mapping:map] archive: libfreertos.a entries: * (noflash) Aside from the entity and scheme, flags can also be specified in an entry. The following flags are supported (note: <> = argument name, [] = optional): 1. ALIGN(<alignment>[, pre, post]) Align the placement by the amount specified in alignment. Generates 2. SORT([<sort_by_first>, <sort_by_second>]) Emits SORT_BY_NAME, SORT_BY_ALIGNMENT, SORT_BY_INIT_PRIORITY or SORT in the input section description. Possible values for sort_by_first and sort_by_second are: name, alignment, init_priority. If both sort_by_first and sort_by_second are not specified, the input sections are sorted by name. If both are specified, then the nested sorting follows the same rules discussed in https: //sourceware.org/binutils/docs/ld/Input-Section-Wildcards.html. 3. KEEP() Prevent the linker from discarding the placement by surrounding the input section description with KEEP command. See https://sourceware.org/binutils/docs/ld/Input-Section-Keep.html for more details. 4.SURROUND(<name>) Generate symbols before and after the placement. The generated symbols follow the naming _<name>_start and _<name>_end. For example, if name == sym1, When adding flags, the specific section -> target in the scheme needs to be specified. For multiple section -> target, use a comma as a separator. For example, # Notes: # A. semicolon after entity-scheme # B. comma before section2 -> target2 # C. section1 -> target1 and section2 -> target2 should be defined in entries of scheme1 entity1 (scheme1); section1 -> target1 KEEP() ALIGN(4, pre, post), section2 -> target2 SURROUND(sym) ALIGN(4, post) SORT() Putting it all together, the following mapping fragment, for example, [mapping:name] archive: lib1.a entries: obj1 (noflash); rodata -> dram0_data KEEP() SORT() ALIGN(8) SURROUND(my_sym) generates an output on the linker script: . = ALIGN(8) _my_sym_start = ABSOLUTE(.) KEEP(lib1.a:obj1.*( SORT(.rodata) SORT(.rodata.*) )) _my_sym_end = ABSOLUTE(.) Note that ALIGN and SURROUND, as mentioned in the flag descriptions, are order sensitive. Therefore, if for the same mapping fragment these two are switched, the following is generated instead: _my_sym_start = ABSOLUTE(.) . = ALIGN(8) KEEP(lib1.a:obj1.*( SORT(.rodata) SORT(.rodata.*) )) _my_sym_end = ABSOLUTE(.) Espressif Systems 1875 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 iram -> iram0_text [scheme:noflash] entries: text -> iram0_text [mapping:freertos] archive: libfreertos.a entries: * (noflash) Espressif Systems 1876 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.21 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.21.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 Espressif Systems 1877 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.21.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 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) Espressif Systems 1878 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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 · 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. Espressif Systems 1879 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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 Espressif Systems 1880 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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) 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: Espressif Systems 1881 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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.21.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.21.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: · CONFIG_LWIP_TCPIP_RECVMBOX_SIZE · CONFIG_LWIP_TCPIP_TASK_STACK_SIZE · CONFIG_LWIP_TCPIP_TASK_AFFINITY 4.21.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 Espressif Systems 1882 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.21.6 esp-lwip custom modifications Additions The following code is added which is not present in the upstream lwIP release: 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() Espressif Systems 1883 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.21.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. 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. Espressif Systems 1884 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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). 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. 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). Espressif Systems 1885 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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: #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. Espressif Systems 1886 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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. 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; Espressif Systems 1887 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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: 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 Espressif Systems 1888 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.23 OpenThread OpenThread is a IP stack running on the 802.15.4 MAC layer which features mesh network and low power consumption. 4.23.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.23.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 1889 Release v5.0-dev-2349-g4350e6fef8 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.23.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.24 Partition Tables Espressif Systems 1890 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.24.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.24.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.24.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 1891 Release v5.0-dev-2349-g4350e6fef8 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 1892 Release v5.0-dev-2349-g4350e6fef8 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 1893 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.24.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.24.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.24.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 1894 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.24.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 1895 Release v5.0-dev-2349-g4350e6fef8 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.25 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.25.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.25.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 1896 Release v5.0-dev-2349-g4350e6fef8 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 %llu milliseconds (%llu 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 1897 Release v5.0-dev-2349-g4350e6fef8 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 1898 Release v5.0-dev-2349-g4350e6fef8 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_level_set() 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 1899 Release v5.0-dev-2349-g4350e6fef8 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 1900 Release v5.0-dev-2349-g4350e6fef8 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 1901 Release v5.0-dev-2349-g4350e6fef8 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 ...] 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 libesp_pm.a 0 0 0 0 0 8 0 8 (continues on next page) Espressif Systems 1902 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 0 0 libesp_eth.a 0 libmesh.a 0 0 0 0 0 0 0 0 0 (continued from previous page) 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 ieee80211_sta.o 1 41 0 1498 0 10858 2218 14616 (continues on next page) Espressif Systems 1903 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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 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 look in the Linker Map File for the full path. Espressif Systems 1904 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 $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: Espressif Systems 1905 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides $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. Reducing Overall Size The following configuration options will reduce the final binary size of almost any ESP-IDF project: Espressif Systems 1906 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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. Note: IPv6 is required by some components such as coap and ASIO port, These components will not be available if IPV6 is disabled. Espressif Systems 1907 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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_CLIENT_SSL_SESSION_TICKETS · CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS · CONFIG_MBEDTLS_SSL_CONTEXT_SERIALIZATION · CONFIG_MBEDTLS_SSL_ALPN · CONFIG_MBEDTLS_SSL_RENEGOTIATION · 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.) · Change CONFIG_MBEDTLS_TLS_MODE if both server & client functionalities 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. 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. Espressif Systems 1908 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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. Espressif Systems 1909 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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. Espressif Systems 1910 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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_HOST_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. · Several Mbed TLS configuration options can be used to reduce heap memory usage. See the Mbed TLS docs for details. 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. Espressif Systems 1911 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.26 RF calibration ESP32-S3 supports three RF calibration methods during RF initialization: 1. Partial calibration 2. Full calibration 3. No calibration 4.26.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. 4.26.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. Espressif Systems 1912 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.26.3 No calibration No calibration method is only used when the device wakes up from deep sleep. 4.26.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.26.5 API Reference Header File · components/esp_phy/include/esp_phy_init.h Functions const esp_phy_init_data_t *esp_phy_get_init_data(void) Get PHY init data. If oUse a partition to store PHY init datapoption is set in menuconfig, This function will load PHY init data from a partition. Otherwise, PHY init data will be compiled into the application itself, and this function will return a pointer to PHY init data located in read-only memory (DROM). IfoUse a partition to store PHY init datapoption is enabled, this function may return NULL if the data loaded from flash is not valid. Note Call esp_phy_release_init_data to release the pointer obtained using this function after the call to esp_wifi_init. Return pointer to PHY init data structure void esp_phy_release_init_data(const esp_phy_init_data_t *data) Release PHY init data. Espressif Systems 1913 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Parameters · data: pointer to PHY init data structure obtained from esp_phy_get_init_data function esp_err_t esp_phy_load_cal_data_from_nvs(esp_phy_calibration_data_t *out_cal_data) Function called by esp_phy_init to load PHY calibration data. This is a convenience function which can be used to load PHY calibration data from NVS. Data can be stored to NVS using esp_phy_store_cal_data_to_nvs function. If calibration data is not present in the NVS, or data is not valid (was obtained for a chip with a different MAC address, or obtained for a different version of software), this function will return an error. IfoInitialize PHY in startup codepoption is set in menuconfig, this function will be used to load calibration data. To provide a different mechanism for loading calibration data, disableoInitialize PHY in startup codepoption in menuconfig and call esp_phy_init function from the application. For an example usage of esp_phy_init and this function, see esp_phy_store_cal_data_to_nvs function in cpu_start.c Return ESP_OK on success Parameters · out_cal_data: pointer to calibration data structure to be filled with loaded data. esp_err_t esp_phy_store_cal_data_to_nvs(const esp_phy_calibration_data_t *cal_data) Function called by esp_phy_init to store PHY calibration data. This is a convenience function which can be used to store PHY calibration data to the NVS. Calibration data is returned by esp_phy_init function. Data saved using this function to the NVS can later be loaded using esp_phy_store_cal_data_to_nvs function. If oInitialize PHY in startup codepoption is set in menuconfig, this function will be used to store calibration data. To provide a different mechanism for storing calibration data, disable oInitialize PHY in startup codep option in menuconfig and call esp_phy_init function from the application. Return ESP_OK on success Parameters · cal_data: pointer to calibration data which has to be saved. esp_err_t esp_phy_erase_cal_data_in_nvs(void) Erase PHY calibration data which is stored in the NVS. This is a function which can be used to trigger full calibration as a last-resort remedy if partial calibration is used. It can be called in the application based on some conditions (e.g. an option provided in some diagnostic mode). Return ESP_OK on success Return others on fail. Please refer to NVS API return value error number. void esp_phy_enable(void) Enable PHY and RF module. PHY and RF module should be enabled in order to use WiFi or BT. Now PHY and RF enabling job is done automatically when start WiFi or BT. Users should not call this API in their application. void esp_phy_disable(void) Disable PHY and RF module. PHY module should be disabled in order to shutdown WiFi or BT. Now PHY and RF disabling job is done automatically when stop WiFi or BT. Users should not call this API in their application. void esp_phy_load_cal_and_init(void) Load calibration data from NVS and initialize PHY and RF module. void esp_phy_common_clock_enable(void) Enable WiFi/BT common clock. void esp_phy_common_clock_disable(void) Disable WiFi/BT common clock. Espressif Systems 1914 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides int64_t esp_phy_rf_get_on_ts(void) Get the time stamp when PHY/RF was switched on. Return return 0 if PHY/RF is never switched on. Otherwise return time in microsecond since boot when phy/rf was last switched on esp_err_t esp_phy_update_country_info(const char *country) Update the corresponding PHY init type according to the country code of Wi-Fi. char *get_phy_version_str(void) Get PHY lib version. Return PHY lib version. Structures struct esp_phy_init_data_t Structure holding PHY init parameters. Public Members uint8_t params[128] opaque PHY initialization parameters struct esp_phy_calibration_data_t Opaque PHY calibration data. Public Members uint8_t version[4] PHY version uint8_t mac[6] The MAC address of the station uint8_t opaque[1894] calibration data Enumerations enum esp_phy_calibration_mode_t Values: PHY_RF_CAL_PARTIAL = 0x00000000 Do part of RF calibration. This should be used after power-on reset. PHY_RF_CAL_NONE = 0x00000001 Donnt do any RF calibration. This mode is only suggested to be used after deep sleep reset. PHY_RF_CAL_FULL = 0x00000002 Do full RF calibration. Produces best results, but also consumes a lot of time and current. Suggested to be used once. 4.27 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. Espressif Systems 1915 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.27.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 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.27.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.27.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. Espressif Systems 1916 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 4.27.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.27.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.27.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. Espressif Systems 1917 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.27.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. 4.27.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.27.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. Espressif Systems 1918 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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.27.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.27.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. Espressif Systems 1919 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.27.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: espsecure.py sign_data --version 2 --keyfile PRIVATE_SIGNING_KEY --output SIGNED_ BINARY_FILE BINARY_FILE 4.27.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.27.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.27.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 Espressif Systems 1920 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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.27.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). 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 bootloader 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.27.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 Espressif Systems 1921 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Keyfile is the PEM file containing an RSA-3072 private signing key. 4.27.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.27.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. 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.27.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. Espressif Systems 1922 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.28 Support for External RAM 4.28.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.28.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. 4.28.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. Espressif Systems 1923 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 4.28.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. Therefore when External RAM is enabled, any buffers that will be used in combination with DMA must be allocated using heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL) and can be freed using a standard free() call. Note, although ESP32-S3 has hardware support for DMA to/from external RAM, this is not yet supported in ESP-IDF. · 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 canopush outpcached flash, possibly making the execution of code slower afterwards. · In general, external RAM will not be used as task stack memory. xTaskCreate() and similar functions will always allocate internal memory for stack and task TCBs. xTaskCreateStatic() can be used to explicitly place task stacks into external memory. Espressif Systems 1924 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.28.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.28.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.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. 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. Espressif Systems 1925 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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. Espressif Systems 1926 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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 pack- age 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. 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: export optional parameters: --unset Creates statement that unset some global variables, so the environment gets to the state it was before calling export.{sh/fish}. --add_paths_extras Adds extra ESP-IDF-related paths of $PATH to ${IDF_TOOLS_PATH}/esp-idf.json, which is used to remove global variables when the active ESP-IDF environment is deactivated. Example: While processing export.{sh/ fish} script, new paths are added to global variable $PATH. This option is used to save these new paths to the ${IDF_TOOLS_PATH}/esp-idf.json. 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. Espressif Systems 1927 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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}/tools/requirements/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}/tools/requirements/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. · uninstall: Print and remove tools, that are currently not used by active ESP-IDF version. --dry-run Print installed unused tools. --remove-archives Additionally remove all older versions of previously downloaded installation packages. 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 · 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. Espressif Systems 1928 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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 Espressif Systems 1929 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Platform Required Download linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ amd64 xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch3-linux-amd64.tar.gz SHA256: 9edd1e77627688f435561922d14299f6a0021ba1f6ff67e472e1108695a69e53 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ arm64 xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch3-linux-arm64.tar.gz SHA256: 3a21a3e310e6b1e7d7bed1f3e59698a5bd29ed3a5ca79fba9265d7dd2f1e0cd2 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ armel xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch3-linux-armel.tar.gz SHA256: 89313c4c1d8db1b01624f31b58bf3fbe527160569828ac4301e9daa75c52716d linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ armhf xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch3-linux-armhf.tar.gz SHA256: ec07a9c75a0aa4b86496cacf2034154cd4a693b6f317c66a4a122c71fd04a518 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ i686 xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch3-linux-i686.tar.gz SHA256: a1f165a836f175daa6fbfde4ca99cb93b377f021fbfc41f79a700bd4df965a9a macos required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch3-macos.tar.gz SHA256: dda3d7a43efd995d9a51d5a5741626dbf915df46078aef0b5aea7163ac82398b win32 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch3-win32.zip SHA256: fd147592928ef2d7092ba34b01ecd776fe26ba3d7e3f9b6b215a3b46e981ee2c win64 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch3-win64.zip SHA256: 9395315c07de0b9f05c9a6616ba1f05e76ab651053f2f40479163a8e03cfa830 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 Platform Required Download linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ amd64 xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch3-linux-amd64.tar.gz SHA256: a32451a8edc1104b83cd9971178e61826e957d7db9ad9f81798a8969fd5a954e linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ arm64 xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch3-linux-arm64.tar.gz SHA256: 2ac2c94a533a99a091d2159c678c611c712c494b5f68d97913254712047260f9 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ armel xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch3-linux-armel.tar.gz SHA256: da49afee1e2e03eaab3f492718789442d33b562800e2a892679f95b50be24d14 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ armhf xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch3-linux-armhf.tar.gz SHA256: f2b9b89522f28547c8725a54c4e57e8a35dac56edc26aa8cd607c87a050249ac linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ i686 xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch3-linux-i686.tar.gz SHA256: 36d3c4990a5feb68aa8534463bc9e8ee367fe23886f78e1d726f4411c7571462 macos required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch3-macos.tar.gz SHA256: de9af641678c93775e932ee5ec4f478f8925cfc1ebc22e41adc4fb85430a0c35 win32 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch3-win32.zip SHA256: ccf08afe60046f87b0e81ca17dc5073eda68ab5e7522c163dd5b583d713b7b39 win64 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32s2-elf-gcc8_4_0-esp-2021r2-patch3-win64.zip SHA256: 37c91490b8fc75e638c23785e261eaf553be2dcd106cf6cff5b76981fa02955b Espressif Systems 1930 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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-patch3/ amd64 xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch3-linux-amd64.tar.gz SHA256: 59b271d014ff3915b6db1b43b610a45eea15fe5d6877d12cae8a191cc996ed37 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ arm64 xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch3-linux-arm64.tar.gz SHA256: 7051b32483e61f98606d71c98e372929428a5165df791dcd5830ed9517763152 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ armel xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch3-linux-armel.tar.gz SHA256: 48c8dbbf96eec691a812327dc580042d9718fe989e60c2111ebfd692ac710081 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ armhf xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch3-linux-armhf.tar.gz SHA256: efc037db5b3565d907c611ef9d17f156080949c0382feeaec86ed7b54d9fa2ae linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ i686 xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch3-linux-i686.tar.gz SHA256: 552dca3f4302ab7ca88a934b0391200198c9d10a4d8ac413fe604cbf8601f950 macos required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch3-macos.tar.gz SHA256: e5af78f05d3af07617805d06ebb45ff2fe9b6aed6970a84c35eea28a5d8d5e53 win32 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch3-win32.zip SHA256: 1b70163acccc5655449de1d149427a54f384156bd35816ec60c422d76d033f05 win64 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ xtensa-esp32s3-elf-gcc8_4_0-esp-2021r2-patch3-win64.zip SHA256: 58e58575d1938879fd51e822181e54bcb343aa846eb3fca8f616c2cde7bd0041 xtensa-clang LLVM for Xtensa (ESP32, ESP32-S2) based on clang License: Apache-2.0 More info: https://github.com/espressif/llvm-project 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 Espressif Systems 1931 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Platform Required Download linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ amd64 riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch3-linux-amd64.tar.gz SHA256: 179cbad579790ad35e0f414a18d90017c0f158c397022411a8e9867db2174f15 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ arm64 riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch3-linux-arm64.tar.gz SHA256: fb339d476c79c76db8f903b265cab6bb6950d5ed954dec644445252d3378023c linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ armel riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch3-linux-armel.tar.gz SHA256: 51a6296d8334b7452dba44b2b62e87afd7fd1c74bafa1aa29b1f4ab72cb9e5e0 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ armhf riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch3-linux-armhf.tar.gz SHA256: faa723e2fe84154ea8081ef204d9db51c5b7e5702497dff4f3b33e250e42f776 linux- required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ i686 riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch3-linux-i686.tar.gz SHA256: fef60f7ef37ffaa50416d8f244cdbd710d6729dae41ef06c4ec0e50a1f3b7dd7 macos required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch3-macos.tar.gz SHA256: 4aacc1742a76349d790b1ac8e9e9d963daefda5346dbd6741cfe8e7a35a44e4e win32 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch3-win32.zip SHA256: eb2a442d7f551ebeb842995ec372ec4b364314ca2d7aae779399a74972f7d6bc win64 required https://github.com/espressif/crosstool-NG/releases/download/esp-2021r2-patch3/ riscv32-esp-elf-gcc8_4_0-esp-2021r2-patch3-win64.zip SHA256: f5607e5187317d521f0474cade83f8eb590f2d165d95c3779b6ce11fbac21d1f esp32ulp-elf Toolchain for ESP32 ULP coprocessor 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-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 Espressif Systems 1932 Release v5.0-dev-2349-g4350e6fef8 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-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 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 Espressif Systems 1933 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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) Espressif Systems 1934 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.7 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. 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. Espressif Systems 1935 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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. Espressif Systems 1936 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · /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 dependencies. 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. 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 Espressif Systems 1937 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 # # # 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. Espressif Systems 1938 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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 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. Espressif Systems 1939 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.31.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.31.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: 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, (continues on next page) Espressif Systems 1940 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides }; gpio_config(&master_config); gpio_set_level(SLAVE_GPIO_PIN, 1); unity_send_signal("output high level"); } (continued from previous page) 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.31.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(); } 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. Espressif Systems 1941 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.31.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. 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.31.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: Espressif Systems 1942 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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.31.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" (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: Espressif Systems 1943 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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.31.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 technique 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(); Espressif Systems 1944 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.31.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. 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: Espressif Systems 1945 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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: 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.32 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. Espressif Systems 1946 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.32.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.32.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: - 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. Espressif Systems 1947 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.33 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.33.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. 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.33.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. Espressif Systems 1948 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.33.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. 4.33.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. Espressif Systems 1949 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.34 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.34.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 USB Serial/JTAG Controller iin that case, no extra connections are required. 4.34.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. Espressif Systems 1950 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.34.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.34.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.35 Wi-Fi Driver 4.35.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 Espressif Systems 1951 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.35.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. 4.35.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. Espressif Systems 1952 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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.35.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.35.5 ESP32-S3 Wi-Fi Programming Model The ESP32-S3 Wi-Fi programming model is depicted as follows: Fig. 54: Wi-Fi Programming Model 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.35.6 ESP32-S3 Wi-Fi Event Description Espressif Systems 1953 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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. 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. Espressif Systems 1954 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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. 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_EVENT_STA_LOST_IP This event arises when the IPV4 address become invalid. Espressif Systems 1955 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides IP_EVENT_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.35.7 ESP32-S3 Wi-Fi Station General Scenario Below is a obig scenariopwhich describes some small scenarios in station mode: 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. Espressif Systems 1956 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Espressif Systems Fig. 55: Sample Wi-Fi Event Scenarios in Station Mode 1957 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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. 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. Espressif Systems 1958 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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.35.8 ESP32-S3 Wi-Fi AP General Scenario Below is a obig scenariopwhich describes some small scenarios in AP mode: 4.35.9 ESP32-S3 Wi-Fi Scan Currently, the esp_wifi_scan_start() API is supported only in station or station/AP mode. 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 Espressif Systems 1959 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Espressif Systems Fig. 56: Sample Wi-Fi Event Scenarios in AP Mode 1960 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides · 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 Station Basic Configuration Scan All APs on All Channels (Foreground) Scenario: 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. · 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. Espressif Systems 1961 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 57: Foreground Scan of all Wi-Fi Channels Espressif Systems 1962 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 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. Espressif Systems 1963 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Espressif Systems Fig. 58: Background Scan of all Wi-Fi Channels 1964 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 59: Scan of specific Wi-Fi Channels Espressif Systems 1965 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 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 re- connect 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.35.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 1966 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Espressif Systems Fig. 60: Wi-Fi Station Connecting Process 1967 Release v5.0-dev-2349-g4350e6fef8 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 1968 Release v5.0-dev-2349-g4350e6fef8 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. 1969 Release v5.0-dev-2349-g4350e6fef8 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.35.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.35.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.35.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.35.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 1970 Release v5.0-dev-2349-g4350e6fef8 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 1971 Release v5.0-dev-2349-g4350e6fef8 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 1972 Release v5.0-dev-2349-g4350e6fef8 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 1973 Release v5.0-dev-2349-g4350e6fef8 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 1974 Release v5.0-dev-2349-g4350e6fef8 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.35.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 1975 Release v5.0-dev-2349-g4350e6fef8 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.35.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.35.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.35.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 1976 Release v5.0-dev-2349-g4350e6fef8 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.35.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.35.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 1977 Release v5.0-dev-2349-g4350e6fef8 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 1978 Release v5.0-dev-2349-g4350e6fef8 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.35.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 1979 Release v5.0-dev-2349-g4350e6fef8 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.35.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 1980 Release v5.0-dev-2349-g4350e6fef8 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.35.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 1981 Release v5.0-dev-2349-g4350e6fef8 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.35.24 Wi-Fi Channel State Information Configure To use Wi-Fi CSI, the following steps need to be done. Espressif Systems 1982 Release v5.0-dev-2349-g4350e6fef8 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.35.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.35.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 1983 Release v5.0-dev-2349-g4350e6fef8 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.35.27 Wi-Fi AMSDU ESP32-S3 supports receiving and transmitting AMSDU. 4.35.28 Wi-Fi Fragment ESP32-S3 supports Wi-Fi receiving and transmitting fragment. 4.35.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.35.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 1984 Release v5.0-dev-2349-g4350e6fef8 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.35.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 1985 Release v5.0-dev-2349-g4350e6fef8 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 1986 Release v5.0-dev-2349-g4350e6fef8 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 1987 Release v5.0-dev-2349-g4350e6fef8 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 1988 Release v5.0-dev-2349-g4350e6fef8 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.35.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 1989 Release v5.0-dev-2349-g4350e6fef8 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 1990 Release v5.0-dev-2349-g4350e6fef8 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 1991 Release v5.0-dev-2349-g4350e6fef8 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.35.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 1992 Release v5.0-dev-2349-g4350e6fef8 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 1993 Release v5.0-dev-2349-g4350e6fef8 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 1994 Release v5.0-dev-2349-g4350e6fef8 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 1995 Release v5.0-dev-2349-g4350e6fef8 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.36 Wi-Fi Security Espressif Systems 1996 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Fig. 72: Starting or Resuming the Packets Capture Fig. 73: Saving Captured Packets Espressif Systems 1997 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.36.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.36.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. There are 3 types of PMF configuration modes on both station and AP side · PMF Optional · PMF Required · PMF Disabled Depending on PMF configurations on Station and AP side, the resulting connection will behave differently. The table below summarises all possible outcomes - 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 API & Usage ESP32-S3 supports PMF in both Station and SoftAP mode. For both, the default mode is PMF Optional and disabling PMF is not possible. For even higher security, PMF required mode can be enabled by setting the required flag in pmf_cfg while using the esp_wifi_set_config() API. This will result in the device only connecting to a PMF enabled device and rejecting others. Attention: capable flag in pmf_cfg is deprecated and set to true internally. This is to take the additional security benefit of PMF whenever possible. Espressif Systems 1998 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.36.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. 4.37 RF Coexistence 4.37.1 Overview ESP32-S3 has only one 2.4 GHz ISM band RF module, which is shared by Bluetooth (BT & BLE) and Wi-Fi, so Bluetooth cannt receive or transmit data while Wi-Fi is receiving or transmitting data and vice versa. Under such circumstances, ESP32-S3 uses the time-division multiplexing method to receive and transmit packets. Espressif Systems 1999 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 4.37.2 Supported Coexistence Scenario for ESP32-S3 Wi-Fi Table 28: Supported Features of Wi-Fi and BLE Coexistence BLE Scan Advertising Connecting Connected STA Scan YY Y Y Connecting Y Y Y Y Connected Y Y Y Y SOFTAP TX Beacon Y Y Y Y Connecting Y Y Y Y Connected C1 C1 C1 C1 Sniffer RX C2 C2 C2 C2 ESP-NOW RX XX X X TX YY Y Y Note: Y: supported and performance is stable C1: supported but the performance is unstable C2: supported but the packet loss rate of Sniffer is unstable X: not supported 4.37.3 Coexistence Mechanism and Policy Coexistence Mechanism The RF resource allocation mechanism is based on priority. As shown below, both Bluetooth module and Wi-Fi module request RF resources from the coexistence module, and the coexistence module decides who will use the RF resource based on their priority. Fig. 74: Coexistence Mechanism Coexistence Policy Coexistence Period and Time Slice Wi-Fi and BLE have their fixed time slice to use the RF. In the Wi-Fi time slice, Wi-Fi will send a higher priority request to the coexistence arbitration module. Similarly, BLE can enjoy higher priority at their own time slice. The duration of the coexistence period and the proportion of each time slice are divided into four categories according to the Wi-Fi status: 1) IDLE status: RF module is controlled by Bluetooth module. Espressif Systems 2000 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides 2) CONNECTED status: the coexistence period starts at the Target Beacon Transmission Time (TBTT) and is more than 100 ms. 3) SCAN status: Wi-Fi slice and coexistence period are longer than in the CONNECTED status. To ensure Bluetooth performance, the Bluetooth time slice will also be adjusted accordingly. 4) CONNECTING status: Wi-Fi slice is longer than in the CONNECTED status. To ensure Bluetooth performance, the Bluetooth time slice will also be adjusted accordingly. According to the coexistence logic, different coexistence periods and time slice strategies will be selected based on the Wi-Fi and Bluetooth usage scenarios. A Coexistence policy corresponding to a certain usage scenarios is called a ocoexistence schemep. For example, the scenario of Wi-Fi CONNECTED and BLE CONNECTED has a corresponding coexistence scheme. In this scheme, the time slices of Wi-Fi and BLE in a coexistence period each account for 50%. The time allocation is shown in the following figure: Fig. 75: Time Slice Under the Status of Wi-Fi CONNECTED and BLE CONNECTED Dynamic Priority The coexistence module assigns different priorities to different status of Wi-Fi and Bluetooth. And the priority for each status is dynamic. For example, in every N BLE Advertising events, there is always one event with high priority. If a high-priority BLE Advertising event occurs within the Wi-Fi time slice, the right to use the RF may be preempted by BLE. 4.37.4 How to Use the Coexistence Feature Coexistence API For most coexistence cases, ESP32-S3 will switch the coexistence status automatically without calling API. However, ESP32-S3 provides two APIs for the coexistence of BLE MESH and Wi-Fi. When the status of BLE MESH changes, call esp_coex_status_bit_clear to clear the previous status first and then call esp_coex_status_bit_set to set the current status. BLE MESH Coexistence Status As the firmware of Wi-Fi and Bluetooth are not aware of the current scenario of the upper layer application, some coexistence schemes require application code to call the coexistence API to take effect. The application layer needs to pass the working status of BLE MESH to the coexistence module for selecting the coexistence scheme. · ESP_COEX_BLE_ST_MESH_CONFIG: network is provisioning · ESP_COEX_BLE_ST_MESH_TRAFFIC: data is transmitting · ESP_COEX_BLE_ST_MESH_STANDBY: in idle status with no significant data interaction Coexistence API Error Codes All coexistence APIs have custom return values, i.e. error codes. These error codes can be categorized as: · No error. For example, the return value ESP_OK siginifies the API returned successfully. · Recoverable errors. For example, the return value ESP_ERR_INVALID_ARG signifies API parameter errors. Espressif Systems 2001 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 4. API Guides Setting Coexistence Compile-time Options · After writing the coexistence program, you must check CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE op- tion through menuconfig to open coexistence configuration on software, otherwise the coexistence function mentioned above cannot be used. · To ensure better communication performance of Wi-Fi and Bluetooth in the case of coexistence, run the task of the Wi-Fi protocol stack, the task of the Bluetooth Controller and Host pro- tocol stack on different CPUs. You can use CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE and CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE (or CON- FIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE to put the tasks of the Bluetooth controller and the host protocol stack on the same CPU, and then use CONFIG_ESP32_WIFI_TASK_CORE_ID to place the task of the Wi-Fi protocol stack on another CPU. · When using LE Coded PHY during a BLE connection, to avoid affecting Wi-Fi performance due to the long duration of Bluetooth packets, you can select BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_EN in the sub- options of CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM to limit the maximum time of TX/RX. · You can reduce the memory consumption by configuring the following options on menuconfig. 1) CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY: enable the configuration of dynamic memory for Blue- tooth protocol stack. 2) CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM: reduce the number of Wi-Fi static RX buffers. 3) CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM: reduce the number of Wi-Fi dynamic RX buffers. 4) CONFIG_ESP32_WIFI_TX_BUFFER: enable the configuration of dynamic allocation TX buffers. 5) CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM: reduce the number of Wi-Fi dynamic TX buffers. 6) CONFIG_ESP32_WIFI_TX_BA_WIN: reduce the number of Wi-Fi Block Ack TX windows. 7) CONFIG_ESP32_WIFI_RX_BA_WIN: reduce the number of Wi-Fi Block Ack RX windows. 8) CONFIG_ESP32_WIFI_MGMT_SBUF_NUM: reduce the number of Wi-Fi Management Short Buffer. 9) CONFIG_ESP32_WIFI_RX_IRAM_OPT: turning off this configuration option will reduce the IRAM memory by approximately 17 KB. 10) CONFIG_LWIP_TCP_SND_BUF_DEFAULT: reduce the default TX buffer size for TCP sockets. 11) CONFIG_LWIP_TCP_WND_DEFAULT: reduce the default size of the RX window for TCP sockets. 12) CONFIG_LWIP_TCP_RECVMBOX_SIZE: reduce the size of the TCP receive mailbox. 13) CONFIG_LWIP_UDP_RECVMBOX_SIZE: reduce the size of the UDP receive mailbox. 14) CONFIG_LWIP_TCPIP_RECVMBOX_SIZE: reduce the size of TCPIP task receive mailbox. Note: Since the coexistence configuration option depends on the Bluetooth configuration option, please turn on the Bluetooth configuration option first before configuring the coexistence feature in the Wi-Fi configuration option. Espressif Systems 2002 Release v5.0-dev-2349-g4350e6fef8 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.1.3 Component dependencies that shall be explicit In previous versions of ESP-IDF, target components (components/esp32*) had a dependency on driver and efuse components. Since target components were part of common requirements (more info about common requirements), all components in the project implicitly had a dependency on driver and efuse. Now that the dependency of target components on these components has been removed, every component depending on driver or efuse has to declare this dependency explicitly. This can be done by adding REQUIRES <component_name> or PRIV_REQUIRES <component_name> in idf_component_register call inside componentns CMakeLists.txt. See Component Requirements for more information on specifying requirements. 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: 2003 Chapter 5. ESP-IDF 5.0 Migration Guides 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: 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 Legacy API and Data Types Previously, the configENABLE_BACKWARD_COMPATIBILITY option was set by default, thus allowed pre FreeRTOS v8.0.0 function names and data types to be used. The configENABLE_BACKWARD_COMPATIBILITY is now disabled by default, thus legacy FreeRTOS names/types are no longer supportd by default. Users should either: · Update their code to remove usage of legacy FreeRTOS names/types · Enable the CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY to explicitly allow the usage of legacy names/types 5.4.2 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. Espressif Systems 2004 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides 5.4.3 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. 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. · Enums ADC_UNIT_BOTH, ADC_UNIT_ALTER and ADC_UNIT_MAX in adc_unit_t are removed. 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 legacy timer group driver is deprecated, please migrate to driver/gptimer.h. 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: Espressif Systems 2005 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides 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 gptimer_alarm_config_t::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 gptimer_event_callbacks_t::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, ore-enable 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 gptimer_alarm_config_t::auto_reload_on_alarm is set to true. 5.5.6 UART · uart_isr_register and uart_isr_free have been removed as the UART interrupt handling is closely related to the driver implementation. 5.5.7 I2C · i2c_isr_register and i2c_isr_free have been removed as the I2C interrupt handling is closely related to the driver implementation. 5.5.8 Pulse Counter Driver Pulse counter driver has been redesigned (see PCNT), which aims to unify and simplify the usage of PCNT peripheral. Although itns recommended to use the new driver APIs, the legacy driver is still available in the previous include path driver/pcnt.h. However, by default, including driver/pcnt.h will bring a build warning like legacy pcnt driver is deprecated, please migrate to use driver/pulse_cnt.h. The warning can be suppressed by the Kconfig option CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN. The major breaking changes in concept and usage are listed as follows: Espressif Systems 2006 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides Breaking Changes in Concepts · pcnt_port_t, pcnt_unit_t and pcnt_channel_t which used to identify the hardware unit and channel are removed from userns code. In the new driver, PCNT unit is represented by pcnt_unit_handle_t, likewise, PCNT channel is represented by pcnt_channel_handle_t. Both of them are opaque pointers. · pcnt_evt_type_t is not used any more, they have been replaced by a universal Watch Point Event. In the event callback pcnt_watch_cb_t, itns still possible to distinguish different watch points from pcnt_watch_event_data_t. · pcnt_count_mode_t is replaced by pcnt_channel_edge_action_t, and pcnt_ctrl_mode_t is replaced by pcnt_channel_level_action_t. Breaking Changes in Usage · In the legacy driver, the PCNT unit configuration and channel configuration were combined into a sin- gle function: pcnt_unit_config. Now this is split into two factory APIs: pcnt_new_unit() and pcnt_new_channel(). Only the count range is necessary for initializing a PCNT unit. GPIO number assignment has been moved to pcnt_new_channel(). High/Low control mode and posi- tive/negative edge count mode are set by stand-alone functions: pcnt_channel_set_edge_action() and pcnt_channel_set_level_action(). · pcnt_get_counter_value is replaced by pcnt_unit_get_count(). · pcnt_counter_pause is replaced by pcnt_unit_stop(). · pcnt_counter_resume is replaced by pcnt_unit_start(). · pcnt_counter_clear is replaced by pcnt_unit_clear_count(). · pcnt_intr_enable and pcnt_intr_disable are removed. In the new driver, the interrupt is enabled by registering event callbacks pcnt_unit_register_event_callbacks(). · pcnt_event_enable and pcnt_event_disable are removed. In the new driver, the PCNT events are enabled/disabled by adding/removing watch points pcnt_unit_add_watch_point(), pcnt_unit_remove_watch_point(). · pcnt_set_event_value is removed. In the new driver, event value is also set when adding watch point by pcnt_unit_add_watch_point(). · pcnt_get_event_value and pcnt_get_event_status are removed. In the new driver, these information are provided by event callback pcnt_watch_cb_t in the pcnt_watch_event_data_t. · pcnt_isr_register and pcnt_isr_unregister are removed. Register of the ISR han- dler from user code is no longer permitted. Users should register event callbacks instead by calling pcnt_unit_register_event_callbacks(). · pcnt_set_pin is removed and the new driver no longer allows the switching of the GPIO at runtime. If you want to change to other GPIOs, please delete the existing PCNT channel by pcnt_del_channel() and reinstall with the new GPIO number by pcnt_new_channel(). · pcnt_filter_enable, pcnt_filter_disable, and pcnt_set_filter_value are replaced by pcnt_unit_set_glitch_filter(). Meanwhile, pcnt_get_filter_value has been re- moved. · pcnt_set_mode is replaced by pcnt_channel_set_edge_action() and pcnt_channel_set_level_action(). · pcnt_isr_service_install, pcnt_isr_service_uninstall, pcnt_isr_handler_add and pcnt_isr_handler_remove are replaced by pcnt_unit_register_event_callbacks(). The default ISR handler is lazy installed in the new driver. 5.5.9 Temperature Sensor Driver · Old API header temp_sensor.h has been redesigned as temperature_sensor.h, it is recommended to use the new driver and the old driver is not allowed to be used at the same time. · Although itns recommended to use the new driver APIs, the legacy driver is still available in the previous include path driver/temp_sensor.h. However, by default, including driver/temp_sensor. h will bring a build warning like olegacy temperature sensor driver is deprecated, please migrate to Espressif Systems 2007 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides driver/temperature_sensor.hp. The warning can be suppressed by enabling the menuconfig option CONFIG_TEMP_SENSOR_SUPPRESS_DEPRECATE_WARN . · Configuration contents has been changed. In old version, user need to configure the clk_div and dac_offset. While in new version, user only need to choose tsens_range · The process of using temperature sensor has been changed. In old version, user can use config->start>read_celsius to get value. In the new version, user must install the temperature sensor driver firstly, by temperature_sensor_install and uninstall it when finished. For more information, you can refer to Temperature Sensor . 5.5.10 RMT Driver · rmt_set_intr_enable_mask and rmt_clr_intr_enable_mask are removed, as the interrupt is handled by the driver, user doesnnt need to take care of it. · rmt_set_pin is removed, as rmt_set_gpio can do the same thing. · rmt_memory_rw_rst is removed, user can use rmt_tx_memory_reset and rmt_rx_memory_reset for TX and RX channel respectively. 5.6 Migration of Protocol Components to ESP-IDF 5.0 5.6.1 Mbed TLS For ESP-IDF v5.0, Mbed TLS has been updated from v2.x to v3.1.0. The official guide for Mbed TLS to migrate from version 2.x to version 3.0 or greater can be found here. Breaking Changes (Summary) Most structure fields are now private · Direct access to fields of structures (struct types) declared in public headers is no longer supported. · Appropriate accessor functions (getter/setter) must be used for the same. A temporary workaround would be to use MBEDTLS_PRIVATE macro (not recommended). · For more details, refer to the official guide here. SSL · Removed support for TLS 1.0, 1.1 and DTLS 1.0 · Removed support for SSL 3.0 Deprecated functions were removed from cryptography modules · The functions mbedtls_*_ret() (related to MD, SHA, RIPEMD, RNG, HMAC modules) was renamed to replace the corresponding functions without _ret appended and updated return value. · For more details, refer to the official guide here. Deprecated Config Options Following are some of the important config options deprecated by this update. The configs related to and/or dependent on these have also been deprecated. · MBEDTLS_SSL_PROTO_SSL3 : Support for SSL 3.0 · MBEDTLS_SSL_PROTO_TLS1 : Support for TLS 1.0 · MBEDTLS_SSL_PROTO_TLS1_1: Support for TLS 1.1 · MBEDTLS_SSL_PROTO_DTLS : Support for DTLS 1.1 (Only DTLS 1.2 is supported now) · MBEDTLS_DES_C : Support for 3DES ciphersuites · MBEDTLS_RC4_MODE : Support for RC4-based ciphersuites Espressif Systems 2008 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides Note: This list includes only major options configurable through idf.py menuconfig. For more details on deprecated options, refer to the official migration guide. 5.6.2 Miscellaneous Disabled Diffie-Hellman Key Exchange modes The Diffie-Hellman Key Exchange modes have now been disabled by default due to security risks (see warning text here). Related configs are given below: · MBEDTLS_DHM_C : Support for the Diffie-Hellman-Merkle module · MBEDTLS_KEY_EXCHANGE_DHE_PSK : Support for Diffie-Hellman PSK (pre-shared-key) TLS authenti- cation modes · MBEDTLS_KEY_EXCHANGE_DHE_RSA : Support for cipher suites with the prefix TLS-DHE-RSA- WITH- Note: During the initial step of the handshake (i.e. client_hello), the server selects a cipher from the list that the client publishes. As the DHE_PSK/DHE_RSA ciphers have now been disabled by the above change, the server would fall back to an alternative cipher; if in a rare case, it does not support any other cipher, the handshake would fail. To retrieve the list of ciphers supported by the server, one must attempt to connect with the server with a specific cipher from the client-side. Few utilities can help do this, e.g. sslscan. Remove certs module from X509 library mbedtls/certs.h header is no longer available in mbedtls 3.1, most applications can safely remove it from the list of includes. Breaking change for oesp_crt_bundle_setpAPI esp_crt_bundle_set() API now requires one additional argument named bundle_size. The return type of the API has also been changed to esp_err_t from void. 5.6.3 ESP HTTPS SERVER Breaking Changes (Summary) Names of variables holding different certs in httpd_ssl_config_t structure have been updated. · httpd_ssl_config::servercert variable inherits role of cacert_pem variable. · httpd_ssl_config::servercert_len variable inherits role of cacert_len variable · httpd_ssl_config::cacert_pem variable inherits role of client_verify_cert_pem variable · httpd_ssl_config::cacert_len variable inherits role of client_verify_cert_len variable 5.6.4 ESP HTTPS OTA Breaking Changes (Summary) · The function esp_https_ota() now requires pointer to esp_https_ota_config_t as argument instead of pointer to esp_http_client_config_t. Espressif Systems 2009 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides 5.7 Removed or deprecated components Following components are removed from ESP-IDF and moved to IDF Component Registry: · libsodium · cbor · jsmn · esp_modem · nghttp · esp_websocket_client Note: Please note that http parser functionality which was previously part of nghttp component is now part of http_parser component. · sh2lib · expat · coap 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. Following components are removed since they were deprecated in IDF v4.x · tcpip_adapter Please use the ESP-NETIF component instead; you can follow the Migration guide to ESP- NETIF<tcpip-adapter> Note: OpenSSL-API component is no longer supported. It is not available in the IDF Component Registry, either. Please use ESP-TLS or mbedtls API directly. 5.8 Migrate Storage to ESP-IDF 5.0 5.8.1 Breaking changes: f_mkfs() signature change in FATFS v0.14 New signature is FRESULT f_mkfs (const TCHAR* path, const MKFS_PARM* opt, void* work, UINT len); which now uses MKFS_PARM struct as a second argument. Partition table generation no longer supports misaligned partitions When generating a partiton table, esp-idf will no longer accept partitions which offset does not align to 4kB. This change only affects generating new partition tables, reading and writing to already existing partitions remains unchanged. Espressif Systems 2010 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides 5.9 Migrate System to ESP-IDF 5.0 5.9.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.9.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. 5.9.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.9.4 Brownout The header brownout.h has been made private. ESP-IDF developers should include esp_private/ brownout.h instead. 5.9.5 Trax The header trax.h has been made private. ESP-IDF developers should include esp_private/trax.h instead. 5.9.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.9.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. · The header file soc_log.h is now renamed to esp_hw_log.h and all logging macros have been updated from SOC_LOGx to ESP_HW_LOGx. ESP-IDF users must use the later form. · The header file esp_spiram.h file is deleted. Users should use the <target>/spiram.h file instead. · The header file esp32/himem.h file is deleted. Users should use the esp_himem.h file instead. · The header files spinlock.h, clk_ctrl_os.h and rtc_wdt.h must now be included without the soc prefix. Eg:- #include "spinlock.h". Espressif Systems 2011 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides 5.9.8 ESP System · The header files esp_random.h, esp_mac.h and esp_chip_info.h, which were all previously indirectly included via the header file esp_system.h, must now be included directly. These headers are removed from esp_system.h. · The header file eh_frame_parser.h must now be included with a esp_private prefix like #include "esp_private/eh_frame_parser.h". 5.9.9 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.9.10 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.9.11 ESP Timer Removed the FRC2 based legacy implementation of esp_timer available on ESP32. The simpler and more efficient implementation based on the LAC timer is now the only option. 5.10 Migrate Tools to ESP-IDF 5.0 5.10.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. Please note that the baud-rate argument has been renamed from -B to -b in order to be consistent with the global baud-rate idf.py -b <baud>. Run idf.py monitor --help for more information. 5.10.2 Deprecated commands idf.py sub-commands and cmake targets are unified to contain - instead of _. The following changes have been made. Deprecated sub-commands and targets produce a warning. It is advised to migrate to the new ones. Old name efuse_common_table efuse_custom_table erase_flash partition_table partition_table-flash post_debug show_efuse_table erase_otadata read_otadata Table 1: Target and sub-command deprecation New name efuse-common-table efuse-custom-table erase-flash partition-table partition-table-flash post-debug show-efuse-table erase-otadata read-otadata Espressif Systems 2012 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides 5.11 TCP/IP Adapter Migration Guide TCP/IP Adapter was a network interface abstraction component used in ESP-IDF prior to v4.1. This page outlines migration from tcpip_adapter API to its successor ESP-NETIF. 5.11.1 Updating network connection code Network stack initialization Simply replace tcpip_adapter_init() with esp_netif_init(). Please note that the ESP-NETIF initialization API returns standard error code and the esp_netif_deinit() for un-initialization is available. Also replace #include "tcpip_adapter.h" with #include "esp_netif.h". Network interface creation TCP/IP Adapter defined these three interfaces statically: · WiFi Station · WiFi Access Point · Ethernet Network interface instance shall be explicitly constructed for the ESP-NETIF to enable its 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. Espressif Systems 2013 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 5. ESP-IDF 5.0 Migration Guides 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. Espressif Systems 2014 Release v5.0-dev-2349-g4350e6fef8 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. 2015 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 2016 Release v5.0-dev-2349-g4350e6fef8 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. · esp_websocket_client is a managed component for esp-idf that contains implementation of [WebSocket protocol client](https://datatracker.ietf.org/doc/html/rfc6455) for ESP32, see the esp_websocket_client documentation. Espressif Systems 2017 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 6. Libraries and Frameworks Espressif Systems 2018 Release v5.0-dev-2349-g4350e6fef8 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. 2019 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 2020 Release v5.0-dev-2349-g4350e6fef8 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 2021 Release v5.0-dev-2349-g4350e6fef8 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 2022 Release v5.0-dev-2349-g4350e6fef8 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 2023 Release v5.0-dev-2349-g4350e6fef8 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 2024 Release v5.0-dev-2349-g4350e6fef8 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 2025 Release v5.0-dev-2349-g4350e6fef8 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 2026 Release v5.0-dev-2349-g4350e6fef8 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.7.* 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 2027 Release v5.0-dev-2349-g4350e6fef8 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 2028 Release v5.0-dev-2349-g4350e6fef8 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 2029 Release v5.0-dev-2349-g4350e6fef8 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 2030 Release v5.0-dev-2349-g4350e6fef8 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 2031 Release v5.0-dev-2349-g4350e6fef8 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 2032 Release v5.0-dev-2349-g4350e6fef8 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 2033 Release v5.0-dev-2349-g4350e6fef8 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 a pytest_<example name>.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. Please refer to IDF Tests with Pytest Guide for details. 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 2034 Release v5.0-dev-2349-g4350e6fef8 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 2035 Release v5.0-dev-2349-g4350e6fef8 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/apireference/storage/fatfs.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 2036 Release v5.0-dev-2349-g4350e6fef8 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 2037 Release v5.0-dev-2349-g4350e6fef8 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 2038 Release v5.0-dev-2349-g4350e6fef8 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. 7.5.8 ESP-IDF Tests with Pytest Guide This documentation is a guide that introduces the following aspects: 1. The basic idea of different test types in ESP-IDF 2. How to apply the pytest framework to the test python scripts to make sure the apps are working as expected. 3. ESP-IDF CI target test process 4. Run ESP-IDF tests with pytest locally Espressif Systems 2039 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 7. Contributions Guide 5. Tips and tricks on pytest Disclaimer In ESP-IDF, we use the following plugins by default: · pytest-embedded with default services esp,idf · pytest-rerunfailures All the introduced concepts and usages are based on the default behavior in ESP-IDF. Not all of them are available in vanilla pytest. Basic Concepts Component-based Unit Tests Component-based unit tests are our recommended way to test your component. All the test apps should be located under ${IDF_PATH}/components/<COMPONENT_NAME>/test_apps. For example: components/ my_component/ include/ ... test_apps/ test_app_1 main/ ... CMakeLists.txt pytest_my_component_app_1.py test_app_2 ... pytest_my_component_app_2.py parent_folder test_app_3 ... pytest_my_component_app_3.py ... my_component.c CMakeLists.txt Example Tests Example Tests are tests for examples that are intended to demonstrate parts of the ESP-IDF functionality to our customers. All the test apps should be located under ${IDF_PATH}/examples. For more information please refer to the Examples Readme . For example: examples/ parent_folder/ example_1/ main/ ... CMakeLists.txt pytest_example_1.py Custom Tests Custom Tests are tests that aim to run some arbitrary test internally. They are not intended to demonstrate the ESP-IDF functionality to our customers in any way. Espressif Systems 2040 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 7. Contributions Guide All the test apps should be located under ${IDF_PATH}/tools/test_apps. For more information please refer to the Custom Test Readme . Pytest in ESP-IDF Pytest Execution Process 1. Bootstrapping Phase Create session-scoped caches: · port-target cache · port-app cache 2. Collection Phase 1. Get all the python files with the prefix pytest_ 2. Get all the test functions with the prefix test_ 3. Apply the params, duplicate the test functions. 4. Filter the test cases with CLI options. Introduced detail usages here 3. Test Running Phase 1. Construct the fixtures. In ESP-IDF, the common fixtures are initialized with this order: 1. pexpect_proc: pexpect instance 2. app: IdfApp instance The information of the app, like sdkconfig, flash_files, partition_table, etc., would be parsed at this phase. 3. serial: IdfSerial instance The port of the host which connected to the target type parsed from the app would be auto-detected. The flash files would be auto flashed. 4. dut: IdfDut instance 2. Run the real test function 3. Deconstruct the fixtures with this order: 1. dut 1. close the serial port 2. (Only for apps with unity test framework) generate junit report of the unity test cases 2. serial 3. app 4. pexpect_proc: Close the file descriptor 4. (Only for apps with unity test framework) Raise AssertionError when detected unity test failed if you call dut. expect_from_unity_output() in the test function. 4. Reporting Phase 1. Generate junit report of the test functions 2. Modify the junit report test case name into ESP-IDF test case ID format: <target>.<config>. <test function name> 5. Finalizing Phase (Only for apps with unity test framework) Combine the junit reports if the junit reports of the unity test cases are generated. Example Code This code example is taken from pytest_console_basic.py . @pytest.mark.esp32 @pytest.mark.esp32c3 @pytest.mark.generic @pytest.mark.parametrize('config', [ 'history', 'nohistory', ], indirect=True) def test_console_advanced(config: str, dut: Dut) -> None: if config == 'history': dut.expect('Command history enabled') elif config == 'nohistory': dut.expect('Command history disabled') Espressif Systems 2041 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 7. Contributions Guide Note: Using expect_exact is better here. For further reading about the different types of expect functions, please refer to the pytest-embedded Expecting documentation. Use Markers to Specify the Supported Targets You can use markers to specify the supported targets and the test env in CI. You can run pytest --markers to get more details about different markers. @pytest.mark.esp32 @pytest.mark.esp32c3 @pytest.mark.generic `generic` # <-- support esp32 # <-- support esp32c3 # <-- test env `generic, would assign to runner with tag Besides, if the test case supports all officially ESP-IDF-supported targets, like esp32, esp32s2, esp32s3, esp32c3 for now (2022.2), you can use a special marker supported_targets to apply them all in one line. This code example is taken from pytest_gptimer_example.py . @pytest.mark.supported_targets @pytest.mark.generic def test_gptimer_example(dut: Dut) -> None: ... Use Params to Specify the sdkconfig Files You can use pytest.mark.parametrize with oconfigpto apply the same test to different apps with different sdkconfig files. For more information about sdkconfig.ci. xxx files, please refer to the Configuration Files section under this readme . @pytest.mark.parametrize('config', [ 'history', # <-- run with app built by sdkconfig.ci.history 'nohistory', # <-- run with app built by sdkconfig.ci.nohistory ], indirect=True) # <-- `indirect=True` is required Overall, this test case would be duplicated to 4 test functions: · esp32.history.test_console_advanced · esp32.nohistory.test_console_advanced · esp32c3.history.test_console_advanced · esp32c3.nohistory.test_console_advanced Advanced Examples Support different targets with different sdkconfig files This code example is taken from pytest_panic.py as an advanced example. CONFIGS = [ pytest.param('coredump_flash_bin_crc', marks=[pytest.mark.esp32, pytest.mark. esp32s2]), pytest.param('coredump_flash_elf_sha', marks=[pytest.mark.esp32]), # sha256 only supported on esp32 pytest.param('coredump_uart_bin_crc', marks=[pytest.mark.esp32, pytest.mark. esp32s2]), pytest.param('coredump_uart_elf_crc', marks=[pytest.mark.esp32, pytest.mark. esp32s2]), pytest.param('gdbstub', marks=[pytest.mark.esp32, pytest.mark.esp32s2]), pytest.param('panic', marks=[pytest.mark.esp32, pytest.mark.esp32s2]), ] @pytest.mark.parametrize('config', CONFIGS, indirect=True) ... Espressif Systems 2042 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 7. Contributions Guide Use Custom Class Usually, you can write a custom class in these conditions: 1. Add more reusable functions for a certain number of DUTs 2. Add custom setup and teardown functions in different phases described here This code example is taken from panic/conftest.py class PanicTestDut(IdfDut): ... @pytest.fixture(scope='module') def monkeypatch_module(request: FixtureRequest) -> MonkeyPatch: mp = MonkeyPatch() request.addfinalizer(mp.undo) return mp @pytest.fixture(scope='module', autouse=True) def replace_dut_class(monkeypatch_module: MonkeyPatch) -> None: monkeypatch_module.setattr('pytest_embedded_idf.dut.IdfDut', PanicTestDut) monkeypatch_module provide a module-scoped monkeypatch fixture. replace_dut_class is a module-scoped autouse fixture. This function replaces the IdfDut class with your custom class. Mark Flaky Tests Sometimes, our test is based on ethernet or wifi. The network may cause the test flaky. We could mark the single test case within the code repo. This code example is taken from pytest_esp_eth.py @pytest.mark.flaky(reruns=3, reruns_delay=5) def test_esp_eth_ip101(dut: Dut) -> None: ... This flaky marker means that if the test function failed, the test case would rerun for a maximum of 3 times with 5 seconds delay. Mark Known Failure Cases Sometimes a test couldnnt pass for the following reasons: · Has a bug · Success ratio too low because of environment issue, such as network issue. Retry couldnnt help Now you may mark this test case with marker xfail with a user-friendly readable reason. This code example is taken from pytest_panic.py @pytest.mark.xfail('config.getvalue("target") == "esp32s2"', reason='raised IllegalInstruction instead') def test_cache_error(dut: PanicTestDut, config: str, test_func_name: str) -> None: This marker means that if the test would be a known failure one on esp32s2. Run the Tests in CI The workflow in CI is simple, build jobs -> target test jobs. Build Jobs Espressif Systems 2043 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 7. Contributions Guide Build Job Names · Component-based Unit Tests: build_pytest_components_<target> · Example Tests: build_pytest_examples_<target> · Custom Tests: build_pytest_test_apps_<target> Build Job Command The command used by CI to build all the relevant tests is: python $IDF_PATH/tools/ ci/build_pytest_apps.py <parent_dir> --target <target> -vv All apps which supported the specified target would be built with all supported sdkconfig files under build_<target>_<config>. For example, If you run python $IDF_PATH/tools/ci/build_pytest_apps.py $IDF_PATH/ examples/system/console/basic --target esp32, the folder structure would be like this: basic build_esp32_history/ ... build_esp32_nohistory/ ... main/ CMakeLists.txt pytest_console_basic.py ... All the binaries folders would be uploaded as artifacts under the same directories. Target Test Jobs Target Test Job Names · Component-based Unit Tests: component_ut_pytest_<target>_<test_env> · Example Tests: example_test_pytest_<target>_<test_env> · Custom Tests: test_app_test_pytest_<target>_<test_env> Target Test Job Command The command used by CI to run all the relevant tests is: pytest <parent_dir> --target <target> -m <test_env_marker> All test cases with the specified target marker and the test env marker under the parent folder would be executed. The binaries in the target test jobs are downloaded from build jobs, the artifacts would be placed under the same directories. Run the Tests Locally The local executing process is the same as the CI process. For example, if you want to run all the esp32 tests under the $IDF_PATH/examples/system/console/ basic folder, you may: $ pip install pytest-embedded-serial-esp pytest-embedded-idf $ cd $IDF_PATH $ . ./export.sh $ cd examples/system/console/basic $ python $IDF_PATH/tools/ci/build_pytest_apps.py . --target esp32 -vv $ pytest --target esp32 Espressif Systems 2044 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 7. Contributions Guide Tips and Tricks Filter the Test Cases · filter by target with pytest --target <target> pytest would run all the test cases that support specified target. · filter by sdkconfig file with pytest --sdkconfig <sdkconfig> if <sdkconfig> is default, pytest would run all the test cases with the sdkconfig file sdkconfig. defaults. In other cases, pytest would run all the test cases with sdkconfig file sdkconfig.ci.<sdkconfig>. Add New Markers Wenre using two types of custom markers, target markers which indicate that the test cases should support this target, and env markers which indicate that the test case should be assigned to runners with these tags in CI. You can add new markers by adding one line under the ${IDF_PATH}/pytest.ini markers = section. The grammar should be: <marker_name>: <marker_description> Generate JUnit Report You can call pytest with --junitxml <filepath> to generate the JUnit report. In ESP-IDF, the test case name would be unified as o<target>.<config>.<function_name>p. Skip Auto Flash Binary Skipping auto-flash binary everytime would be useful when younre debugging your test script. You can call pytest with --skip-autoflash y to achieve it. Record Statistics Sometimes you may need to record some statistics while running the tests, like the performance test statistics. You can use record_xml_attribute fixture in your test script, and the statistics would be recorded as attributes in the JUnit report. Logging System Sometimes you may need to add some extra logging lines while running the test cases. You can use python logging module to achieve this. Known Limitations and Workarounds Avoid Using Thread for Performance Test pytest-embedded is using some threads internally to help gather all stdout to the pexpect process. Due to the limitation of Global Interpreter Lock, if younre using threads to do performance tests, these threads would block each other and there would be great performance loss. workaround Use Process instead, the APIs should be almost the same as Thread. Further Readings · pytest documentation: https://docs.pytest.org/en/latest/contents.html · pytest-embedded documentation: https://docs.espressif.com/projects/pytest-embedded/en/latest/ Espressif Systems 2045 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 7. Contributions Guide Espressif Systems 2046 Release v5.0-dev-2349-g4350e6fef8 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. 2047 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 2048 Release v5.0-dev-2349-g4350e6fef8 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 2049 Release v5.0-dev-2349-g4350e6fef8 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 2050 Release v5.0-dev-2349-g4350e6fef8 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 2051 Release v5.0-dev-2349-g4350e6fef8 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 2052 Release v5.0-dev-2349-g4350e6fef8 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 2053 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 2054 Release v5.0-dev-2349-g4350e6fef8 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. · 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 . · SD/MMC driver is derived from OpenBSD SD/MMC driver, Copyright (c) 2006 Uwe Stuehler, and is licensed under BSD license. 2055 Chapter 10. Copyrights and Licenses · 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. · SEGGER SystemView target-side library, Copyright (c) 2015-2017 SEGGER Microcontroller GmbH & Co. KG, is licensed under BSD 3-clause license. 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 2056 Release v5.0-dev-2349-g4350e6fef8 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 2057 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Chapter 10. Copyrights and Licenses Espressif Systems 2058 Release v5.0-dev-2349-g4350e6fef8 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 macOS operating systems. 2059 Chapter 11. About Espressif Systems 2060 Release v5.0-dev-2349-g4350e6fef8 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 2061 Chapter 12. Switch Between Languages Espressif Systems 2062 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index Symbols _ESP_LOG_EARLY_ENABLED (C macro), 1558 _XFER_2_RD (C macro), 63 _XFER_2_WR (C macro), 63 _XFER_4_RD (C macro), 63 _XFER_4_WR (C macro), 63 _ip_addr (C++ class), 635 [anonymous] (C++ enum), 281, 336, 1306 A ADC1_CHANNEL_0 (C++ enumerator), 651 ADC1_CHANNEL_0_GPIO_NUM (C macro), 659 ADC1_CHANNEL_1 (C++ enumerator), 651 ADC1_CHANNEL_1_GPIO_NUM (C macro), 659 ADC1_CHANNEL_2 (C++ enumerator), 651 ADC1_CHANNEL_2_GPIO_NUM (C macro), 659 ADC1_CHANNEL_3 (C++ enumerator), 651 ADC1_CHANNEL_3_GPIO_NUM (C macro), 659 ADC1_CHANNEL_4 (C++ enumerator), 651 ADC1_CHANNEL_4_GPIO_NUM (C macro), 659 ADC1_CHANNEL_5 (C++ enumerator), 651 ADC1_CHANNEL_5_GPIO_NUM (C macro), 659 ADC1_CHANNEL_6 (C++ enumerator), 651 ADC1_CHANNEL_6_GPIO_NUM (C macro), 659 ADC1_CHANNEL_7 (C++ enumerator), 651 ADC1_CHANNEL_7_GPIO_NUM (C macro), 660 ADC1_CHANNEL_8 (C++ enumerator), 651 ADC1_CHANNEL_8_GPIO_NUM (C macro), 660 ADC1_CHANNEL_9 (C++ enumerator), 651 ADC1_CHANNEL_9_GPIO_NUM (C macro), 660 ADC1_CHANNEL_MAX (C++ enumerator), 651 adc1_channel_t (C++ enum), 651 adc1_config_channel_atten (C++ function), 645 adc1_config_width (C++ function), 646 adc1_get_raw (C++ function), 646 ADC1_GPIO10_CHANNEL (C macro), 660 ADC1_GPIO1_CHANNEL (C macro), 659 ADC1_GPIO2_CHANNEL (C macro), 659 ADC1_GPIO3_CHANNEL (C macro), 659 ADC1_GPIO4_CHANNEL (C macro), 659 ADC1_GPIO5_CHANNEL (C macro), 659 ADC1_GPIO6_CHANNEL (C macro), 659 ADC1_GPIO7_CHANNEL (C macro), 659 ADC1_GPIO8_CHANNEL (C macro), 659 ADC1_GPIO9_CHANNEL (C macro), 660 adc1_pad_get_io_num (C++ function), 645 adc1_ulp_enable (C++ function), 647 ADC2_CHANNEL_0 (C++ enumerator), 651 ADC2_CHANNEL_0_GPIO_NUM (C macro), 660 ADC2_CHANNEL_1 (C++ enumerator), 651 ADC2_CHANNEL_1_GPIO_NUM (C macro), 660 ADC2_CHANNEL_2 (C++ enumerator), 651 ADC2_CHANNEL_2_GPIO_NUM (C macro), 660 ADC2_CHANNEL_3 (C++ enumerator), 651 ADC2_CHANNEL_3_GPIO_NUM (C macro), 660 ADC2_CHANNEL_4 (C++ enumerator), 651 ADC2_CHANNEL_4_GPIO_NUM (C macro), 660 ADC2_CHANNEL_5 (C++ enumerator), 651 ADC2_CHANNEL_5_GPIO_NUM (C macro), 660 ADC2_CHANNEL_6 (C++ enumerator), 651 ADC2_CHANNEL_6_GPIO_NUM (C macro), 660 ADC2_CHANNEL_7 (C++ enumerator), 651 ADC2_CHANNEL_7_GPIO_NUM (C macro), 660 ADC2_CHANNEL_8 (C++ enumerator), 652 ADC2_CHANNEL_8_GPIO_NUM (C macro), 660 ADC2_CHANNEL_9 (C++ enumerator), 652 ADC2_CHANNEL_9_GPIO_NUM (C macro), 660 ADC2_CHANNEL_MAX (C++ enumerator), 652 adc2_channel_t (C++ enum), 651 adc2_config_channel_atten (C++ function), 647 adc2_get_raw (C++ function), 648 ADC2_GPIO11_CHANNEL (C macro), 660 ADC2_GPIO12_CHANNEL (C macro), 660 ADC2_GPIO13_CHANNEL (C macro), 660 ADC2_GPIO14_CHANNEL (C macro), 660 ADC2_GPIO15_CHANNEL (C macro), 660 ADC2_GPIO16_CHANNEL (C macro), 660 ADC2_GPIO17_CHANNEL (C macro), 660 ADC2_GPIO18_CHANNEL (C macro), 660 ADC2_GPIO19_CHANNEL (C macro), 660 ADC2_GPIO20_CHANNEL (C macro), 660 adc2_pad_get_io_num (C++ function), 647 adc2_vref_to_gpio (C++ function), 648 ADC_ARB_MODE_FIX (C++ enumerator), 656 ADC_ARB_MODE_LOOP (C++ enumerator), 656 ADC_ARB_MODE_SHIELD (C++ enumerator), 655 ADC_ARBITER_CONFIG_DEFAULT (C macro), 654 adc_arbiter_mode_t (C++ enum), 655 adc_arbiter_t (C++ class), 653 adc_arbiter_t::dig_pri (C++ member), 653 adc_arbiter_t::mode (C++ member), 653 adc_arbiter_t::pwdet_pri (C++ member), 2063 Index 653 ADC_DIGI_FILTER_IIR_2 (C++ enumerator), 656 adc_arbiter_t::rtc_pri (C++ member), 653 ADC_DIGI_FILTER_IIR_4 (C++ enumerator), 656 ADC_ATTEN_0db (C macro), 650 ADC_DIGI_FILTER_IIR_64 (C++ enumerator), ADC_ATTEN_11db (C macro), 650 656 ADC_ATTEN_2_5db (C macro), 650 ADC_DIGI_FILTER_IIR_8 (C++ enumerator), 656 ADC_ATTEN_6db (C macro), 650 ADC_DIGI_FILTER_IIR_MAX (C++ enumerator), ADC_ATTEN_DB_0 (C++ enumerator), 654 656 ADC_ATTEN_DB_11 (C++ enumerator), 655 adc_digi_filter_mode_t (C++ enum), 656 ADC_ATTEN_DB_2_5 (C++ enumerator), 654 adc_digi_filter_t (C++ class), 653 ADC_ATTEN_DB_6 (C++ enumerator), 655 adc_digi_filter_t::adc_unit (C++ mem- ADC_ATTEN_MAX (C++ enumerator), 655 ber), 653 adc_atten_t (C++ enum), 654 adc_digi_filter_t::channel (C++ member), adc_bits_width_t (C++ enum), 655 653 ADC_CHANNEL_0 (C++ enumerator), 654 adc_digi_filter_t::mode (C++ member), 653 ADC_CHANNEL_1 (C++ enumerator), 654 ADC_DIGI_FORMAT_11BIT (C++ enumerator), 655 ADC_CHANNEL_2 (C++ enumerator), 654 ADC_DIGI_FORMAT_12BIT (C++ enumerator), 655 ADC_CHANNEL_3 (C++ enumerator), 654 ADC_DIGI_FORMAT_MAX (C++ enumerator), 655 ADC_CHANNEL_4 (C++ enumerator), 654 adc_digi_init_config_s (C++ class), 649 ADC_CHANNEL_5 (C++ enumerator), 654 adc_digi_init_config_s::adc1_chan_mask ADC_CHANNEL_6 (C++ enumerator), 654 (C++ member), 650 ADC_CHANNEL_7 (C++ enumerator), 654 adc_digi_init_config_s::adc2_chan_mask ADC_CHANNEL_8 (C++ enumerator), 654 (C++ member), 650 ADC_CHANNEL_9 (C++ enumerator), 654 adc_digi_init_config_s::conv_num_each_intr ADC_CHANNEL_MAX (C++ enumerator), 654 (C++ member), 650 adc_channel_t (C++ enum), 654 adc_digi_init_config_s::max_store_buf_size ADC_CONV_ALTER_UNIT (C++ enumerator), 655 (C++ member), 650 ADC_CONV_BOTH_UNIT (C++ enumerator), 655 adc_digi_init_config_t (C++ type), 651 ADC_CONV_SINGLE_UNIT_1 (C++ enumerator), adc_digi_initialize (C++ function), 649 655 ADC_DIGI_MONITOR_HIGH (C++ enumerator), 657 ADC_CONV_SINGLE_UNIT_2 (C++ enumerator), ADC_DIGI_MONITOR_IDX0 (C++ enumerator), 656 655 ADC_DIGI_MONITOR_IDX1 (C++ enumerator), 656 ADC_CONV_UNIT_MAX (C++ enumerator), 655 ADC_DIGI_MONITOR_IDX_MAX (C++ enumerator), adc_digi_configuration_t (C++ class), 650 656 adc_digi_configuration_t::adc_pattern adc_digi_monitor_idx_t (C++ enum), 656 (C++ member), 650 ADC_DIGI_MONITOR_LOW (C++ enumerator), 657 adc_digi_configuration_t::conv_limit_enADC_DIGI_MONITOR_MAX (C++ enumerator), 657 (C++ member), 650 adc_digi_monitor_mode_t (C++ enum), 656 adc_digi_configuration_t::conv_limit_nuamdc_digi_monitor_t (C++ class), 653 (C++ member), 650 adc_digi_monitor_t::adc_unit (C++ mem- adc_digi_configuration_t::conv_mode ber), 653 (C++ member), 650 adc_digi_monitor_t::channel (C++ mem- adc_digi_configuration_t::format (C++ ber), 653 member), 650 adc_digi_monitor_t::mode (C++ member), adc_digi_configuration_t::pattern_num 653 (C++ member), 650 adc_digi_monitor_t::threshold (C++ adc_digi_configuration_t::sample_freq_hz member), 653 (C++ member), 650 adc_digi_output_data_t (C++ class), 652 adc_digi_controller_configure (C++ func- adc_digi_output_data_t::channel (C++ tion), 649 member), 652 adc_digi_convert_mode_t (C++ enum), 655 adc_digi_output_data_t::data (C++ mem- adc_digi_deinitialize (C++ function), 649 ber), 652 ADC_DIGI_FILTER_IDX0 (C++ enumerator), 656 adc_digi_output_data_t::reserved17_31 ADC_DIGI_FILTER_IDX1 (C++ enumerator), 656 (C++ member), 652 ADC_DIGI_FILTER_IDX_MAX (C++ enumerator), adc_digi_output_data_t::type2 (C++ 656 member), 652 adc_digi_filter_idx_t (C++ enum), 656 adc_digi_output_data_t::unit (C++ mem- ADC_DIGI_FILTER_IIR_16 (C++ enumerator), ber), 652 656 adc_digi_output_data_t::val (C++ mem- Espressif Systems 2064 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ber), 653 adc_digi_output_format_t (C++ enum), 655 ADC_DIGI_OUTPUT_FORMAT_TYPE1 (C++ enu- merator), 655 ADC_DIGI_OUTPUT_FORMAT_TYPE2 (C++ enu- merator), 655 adc_digi_pattern_config_t (C++ class), 652 adc_digi_pattern_config_t::atten (C++ member), 652 adc_digi_pattern_config_t::bit_width (C++ member), 652 adc_digi_pattern_config_t::channel (C++ member), 652 adc_digi_pattern_config_t::unit (C++ member), 652 adc_digi_read_bytes (C++ function), 649 adc_digi_start (C++ function), 649 adc_digi_stop (C++ function), 649 ADC_ENCODE_11BIT (C++ enumerator), 652 ADC_ENCODE_12BIT (C++ enumerator), 652 ADC_ENCODE_MAX (C++ enumerator), 652 ADC_I2S_DATA_SRC_ADC (C++ enumerator), 657 ADC_I2S_DATA_SRC_IO_SIG (C++ enumerator), 657 ADC_I2S_DATA_SRC_MAX (C++ enumerator), 657 adc_i2s_encode_t (C++ enum), 652 adc_i2s_source_t (C++ enum), 657 ADC_MAX_DELAY (C macro), 650 adc_power_acquire (C++ function), 645 adc_power_off (C++ function), 645 adc_power_on (C++ function), 645 adc_power_release (C++ function), 645 adc_set_clk_div (C++ function), 646 adc_set_data_inv (C++ function), 646 adc_set_data_width (C++ function), 647 ADC_UNIT_1 (C++ enumerator), 654 ADC_UNIT_2 (C++ enumerator), 654 adc_unit_t (C++ enum), 654 adc_vref_to_gpio (C++ function), 648 ADC_WIDTH_10Bit (C macro), 650 ADC_WIDTH_11Bit (C macro), 650 ADC_WIDTH_12Bit (C macro), 650 ADC_WIDTH_9Bit (C macro), 650 ADC_WIDTH_BIT_12 (C++ enumerator), 655 ADC_WIDTH_BIT_DEFAULT (C macro), 650 ADC_WIDTH_MAX (C++ enumerator), 655 ADD_DEV_FLUSHABLE_DEV_FLAG (C macro), 318 ADD_DEV_RM_AFTER_PROV_FLAG (C macro), 318 ADD_DEV_START_PROV_NOW_FLAG (C macro), 318 ADV_CHNL_37 (C++ enumerator), 224 ADV_CHNL_38 (C++ enumerator), 224 ADV_CHNL_39 (C++ enumerator), 224 ADV_CHNL_ALL (C++ enumerator), 224 ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY (C++ enumerator), 224 ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST (C++ enumerator), 224 ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY (C++ enumerator), 224 ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST (C++ enumerator), 224 ADV_TYPE_DIRECT_IND_HIGH (C++ enumerator), 224 ADV_TYPE_DIRECT_IND_LOW (C++ enumerator), 224 ADV_TYPE_IND (C++ enumerator), 224 ADV_TYPE_NONCONN_IND (C++ enumerator), 224 ADV_TYPE_SCAN_IND (C++ enumerator), 224 ALU_SEL_ADD (C macro), 1639 ALU_SEL_AND (C macro), 1639 ALU_SEL_LSH (C macro), 1639 ALU_SEL_MOV (C macro), 1639 ALU_SEL_OR (C macro), 1639 ALU_SEL_RSH (C macro), 1639 ALU_SEL_STAGE_DEC (C macro), 1639 ALU_SEL_STAGE_INC (C macro), 1639 ALU_SEL_STAGE_RST (C macro), 1639 ALU_SEL_SUB (C macro), 1639 async_memcpy_config_t (C++ class), 1616 async_memcpy_config_t::backlog (C++ member), 1616 async_memcpy_config_t::flags (C++ mem- ber), 1617 async_memcpy_config_t::psram_trans_align (C++ member), 1617 async_memcpy_config_t::sram_trans_align (C++ member), 1616 ASYNC_MEMCPY_DEFAULT_CONFIG (C macro), 1617 async_memcpy_event_t (C++ class), 1616 async_memcpy_event_t::data (C++ member), 1616 async_memcpy_isr_cb_t (C++ type), 1617 async_memcpy_t (C++ type), 1617 B B_CMP_E (C macro), 1640 B_CMP_G (C macro), 1640 B_CMP_L (C macro), 1640 BD_ADDR (C++ type), 329 BD_ADDR_LEN (C macro), 317 BLE_ADDR_TYPE_PUBLIC (C++ enumerator), 181 BLE_ADDR_TYPE_RANDOM (C++ enumerator), 181 BLE_ADDR_TYPE_RPA_PUBLIC (C++ enumerator), 181 BLE_ADDR_TYPE_RPA_RANDOM (C++ enumerator), 181 BLE_BIT (C macro), 219 BLE_HCI_UART_H4_ACL (C macro), 497 BLE_HCI_UART_H4_CMD (C macro), 497 BLE_HCI_UART_H4_EVT (C macro), 497 BLE_HCI_UART_H4_NONE (C macro), 497 BLE_HCI_UART_H4_SCO (C macro), 497 BLE_SCAN_DUPLICATE_DISABLE (C++ enumera- tor), 225 Espressif Systems 2065 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index BLE_SCAN_DUPLICATE_ENABLE (C++ enumera- cdcacm_event_line_state_changed_data_t::rts tor), 225 (C++ member), 915 BLE_SCAN_DUPLICATE_MAX (C++ enumerator), cdcacm_event_rx_wanted_char_data_t 225 (C++ class), 914 BLE_SCAN_FILTER_ALLOW_ALL (C++ enumera- cdcacm_event_rx_wanted_char_data_t::wanted_char tor), 225 (C++ member), 915 BLE_SCAN_FILTER_ALLOW_ONLY_WLST (C++ cdcacm_event_t (C++ class), 915 enumerator), 225 cdcacm_event_t::line_coding_changed_data BLE_SCAN_FILTER_ALLOW_UND_RPA_DIR (C++ member), 915 (C++ enumerator), 225 cdcacm_event_t::line_state_changed_data BLE_SCAN_FILTER_ALLOW_WLIST_RPA_DIR (C++ member), 915 (C++ enumerator), 225 cdcacm_event_t::rx_wanted_char_data BLE_SCAN_TYPE_ACTIVE (C++ enumerator), 225 (C++ member), 915 BLE_SCAN_TYPE_PASSIVE (C++ enumerator), 225 cdcacm_event_t::type (C++ member), 915 BLE_UUID128_VAL_LENGTH (C macro), 1213 cdcacm_event_type_t (C++ enum), 916 BLE_WL_ADDR_TYPE_PUBLIC (C++ enumerator), CHIP_ESP32 (C++ enumerator), 1566 181 CHIP_ESP32C2 (C++ enumerator), 1567 BLE_WL_ADDR_TYPE_RANDOM (C++ enumerator), CHIP_ESP32C3 (C++ enumerator), 1567 181 CHIP_ESP32H2 (C++ enumerator), 1567 bootloader_fill_random (C++ function), 1600 CHIP_ESP32S2 (C++ enumerator), 1566 bootloader_random_disable (C++ function), CHIP_ESP32S3 (C++ enumerator), 1567 1600 CHIP_FEATURE_BLE (C macro), 1566 bootloader_random_enable (C++ function), CHIP_FEATURE_BT (C macro), 1566 1600 CHIP_FEATURE_EMB_FLASH (C macro), 1566 BS_CMP_GE (C macro), 1640 CHIP_FEATURE_EMB_PSRAM (C macro), 1566 BS_CMP_L (C macro), 1640 CHIP_FEATURE_IEEE802154 (C macro), 1566 BS_CMP_LE (C macro), 1640 CHIP_FEATURE_WIFI_BGN (C macro), 1566 BT_CONTROLLER_INIT_CONFIG_DEFAULT (C CONFIG_FEATURE_CACHE_TX_BUF_BIT (C macro), 280 macro), 562 BT_OCTET32 (C++ type), 329 CONFIG_FEATURE_FTM_INITIATOR_BIT (C BT_OCTET32_LEN (C macro), 317 macro), 562 BX_JUMP_TYPE_DIRECT (C macro), 1640 CONFIG_FEATURE_FTM_RESPONDER_BIT (C BX_JUMP_TYPE_OVF (C macro), 1640 macro), 562 BX_JUMP_TYPE_ZERO (C macro), 1640 CONFIG_FEATURE_WPA3_SAE_BIT (C macro), 562 C CONFIG_HEAP_TRACING_STACK_DEPTH (C cap_event_data_t (C++ class), 772 macro), 1536 cap_event_data_t::cap_edge (C++ member), 772 D cap_event_data_t::cap_value (C++ mem- dedic_gpio_bundle_config_t (C++ class), ber), 772 689 cap_isr_cb_t (C++ type), 773 dedic_gpio_bundle_config_t::array_size CDC_EVENT_LINE_CODING_CHANGED (C++ enu- (C++ member), 689 merator), 916 dedic_gpio_bundle_config_t::flags CDC_EVENT_LINE_STATE_CHANGED (C++ enu- (C++ member), 690 merator), 916 dedic_gpio_bundle_config_t::gpio_array CDC_EVENT_RX (C++ enumerator), 916 (C++ member), 689 CDC_EVENT_RX_WANTED_CHAR (C++ enumerator), dedic_gpio_bundle_config_t::in_en 916 (C++ member), 689 cdcacm_event_line_coding_changed_data_tdedic_gpio_bundle_config_t::in_invert (C++ class), 915 (C++ member), 689 cdcacm_event_line_coding_changed_data_td:e:dpi_cl_ignpei_oc_obduinndgle_config_t::out_en (C++ member), 915 (C++ member), 689 cdcacm_event_line_state_changed_data_t dedic_gpio_bundle_config_t::out_invert (C++ class), 915 (C++ member), 689 cdcacm_event_line_state_changed_data_t:d:eddtirc_gpio_bundle_handle_t (C++ type), 690 (C++ member), 915 dedic_gpio_bundle_read_in (C++ function), 689 Espressif Systems 2066 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index dedic_gpio_bundle_read_out (C++ function), 689 dedic_gpio_bundle_write (C++ function), 689 dedic_gpio_del_bundle (C++ function), 688 dedic_gpio_get_in_mask (C++ function), 688 dedic_gpio_get_out_mask (C++ function), 688 dedic_gpio_new_bundle (C++ function), 688 DEFAULT_HTTP_BUF_SIZE (C macro), 106 DEL_DEV_ADDR_FLAG (C macro), 318 DEL_DEV_UUID_FLAG (C macro), 318 DPP_BOOTSTRAP_NFC_URI (C++ enumerator), 586 DPP_BOOTSTRAP_PKEX (C++ enumerator), 586 DPP_BOOTSTRAP_QR_CODE (C++ enumerator), 586 dpp_bootstrap_type (C++ enum), 586 E eAbortSleep (C++ enumerator), 1425 eBlocked (C++ enumerator), 1425 eDeleted (C++ enumerator), 1425 EFD_SUPPORT_ISR (C macro), 1330 EFUSE_BLK0 (C++ enumerator), 1364 EFUSE_BLK1 (C++ enumerator), 1364 EFUSE_BLK10 (C++ enumerator), 1364 EFUSE_BLK2 (C++ enumerator), 1364 EFUSE_BLK3 (C++ enumerator), 1364 EFUSE_BLK4 (C++ enumerator), 1364 EFUSE_BLK5 (C++ enumerator), 1364 EFUSE_BLK6 (C++ enumerator), 1364 EFUSE_BLK7 (C++ enumerator), 1364 EFUSE_BLK8 (C++ enumerator), 1364 EFUSE_BLK9 (C++ enumerator), 1364 EFUSE_BLK_KEY0 (C++ enumerator), 1364 EFUSE_BLK_KEY1 (C++ enumerator), 1364 EFUSE_BLK_KEY2 (C++ enumerator), 1364 EFUSE_BLK_KEY3 (C++ enumerator), 1364 EFUSE_BLK_KEY4 (C++ enumerator), 1364 EFUSE_BLK_KEY5 (C++ enumerator), 1364 EFUSE_BLK_KEY_MAX (C++ enumerator), 1364 EFUSE_BLK_MAX (C++ enumerator), 1365 EFUSE_BLK_SYS_DATA_PART1 (C++ enumerator), 1364 EFUSE_BLK_SYS_DATA_PART2 (C++ enumerator), 1364 EFUSE_BLK_USER_DATA (C++ enumerator), 1364 EFUSE_CODING_SCHEME_NONE (C++ enumerator), 1365 EFUSE_CODING_SCHEME_RS (C++ enumerator), 1365 eIncrement (C++ enumerator), 1425 eInvalid (C++ enumerator), 1425 EMAC_APPL_CLK_OUT_GPIO (C++ enumerator), 604 EMAC_CLK_DEFAULT (C++ enumerator), 604 EMAC_CLK_EXT_IN (C++ enumerator), 604 EMAC_CLK_IN_GPIO (C++ enumerator), 604 EMAC_CLK_OUT (C++ enumerator), 604 EMAC_CLK_OUT_180_GPIO (C++ enumerator), 604 EMAC_CLK_OUT_GPIO (C++ enumerator), 604 emac_rmii_clock_gpio_t (C++ enum), 604 emac_rmii_clock_mode_t (C++ enum), 604 eNoAction (C++ enumerator), 1425 eNoTasksWaitingTimeout (C++ enumerator), 1425 eNotifyAction (C++ enum), 1425 eReady (C++ enumerator), 1425 eRunning (C++ enumerator), 1425 eSetBits (C++ enumerator), 1425 eSetValueWithoutOverwrite (C++ enumera- tor), 1425 eSetValueWithOverwrite (C++ enumerator), 1425 eSleepModeStatus (C++ enum), 1425 ESP32S3_ERR_HW_CRYPTO_DS_HMAC_FAIL (C macro), 697 ESP32S3_ERR_HW_CRYPTO_DS_INVALID_DIGEST (C macro), 697 ESP32S3_ERR_HW_CRYPTO_DS_INVALID_KEY (C macro), 697 ESP32S3_ERR_HW_CRYPTO_DS_INVALID_PADDING (C macro), 697 esp_adc_cal_characteristics_t (C++ class), 658 esp_adc_cal_characteristics_t::adc_num (C++ member), 658 esp_adc_cal_characteristics_t::atten (C++ member), 658 esp_adc_cal_characteristics_t::bit_width (C++ member), 658 esp_adc_cal_characteristics_t::coeff_a (C++ member), 658 esp_adc_cal_characteristics_t::coeff_b (C++ member), 658 esp_adc_cal_characteristics_t::high_curve (C++ member), 659 esp_adc_cal_characteristics_t::low_curve (C++ member), 659 esp_adc_cal_characteristics_t::version (C++ member), 659 esp_adc_cal_characteristics_t::vref (C++ member), 658 esp_adc_cal_characterize (C++ function), 657 esp_adc_cal_check_efuse (C++ function), 657 esp_adc_cal_get_voltage (C++ function), 658 esp_adc_cal_raw_to_voltage (C++ function), 658 ESP_ADC_CAL_VAL_DEFAULT_VREF (C++ enu- merator), 659 ESP_ADC_CAL_VAL_EFUSE_TP (C++ enumerator), 659 ESP_ADC_CAL_VAL_EFUSE_TP_FIT (C++ enu- merator), 659 ESP_ADC_CAL_VAL_EFUSE_VREF (C++ enumera- tor), 659 ESP_ADC_CAL_VAL_MAX (C++ enumerator), 659 ESP_ADC_CAL_VAL_NOT_SUPPORTED (C++ enu- Espressif Systems 2067 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index merator), 659 esp_adc_cal_value_t (C++ enum), 659 esp_alloc_failed_hook_t (C++ type), 1521 ESP_APP_DESC_MAGIC_WORD (C macro), 1338 esp_app_desc_t (C++ class), 1337 esp_app_desc_t::app_elf_sha256 (C++ member), 1338 esp_app_desc_t::date (C++ member), 1338 esp_app_desc_t::idf_ver (C++ member), 1338 esp_app_desc_t::magic_word (C++ member), 1337 esp_app_desc_t::project_name (C++ mem- ber), 1338 esp_app_desc_t::reserv1 (C++ member), 1337 esp_app_desc_t::reserv2 (C++ member), 1338 esp_app_desc_t::secure_version (C++ member), 1337 esp_app_desc_t::time (C++ member), 1338 esp_app_desc_t::version (C++ member), 1338 ESP_APP_ID_MAX (C macro), 180 ESP_APP_ID_MIN (C macro), 180 esp_apptrace_buffer_get (C++ function), 1340 esp_apptrace_buffer_put (C++ function), 1340 ESP_APPTRACE_DEST_JTAG (C++ enumerator), 1343 ESP_APPTRACE_DEST_MAX (C++ enumerator), 1343 ESP_APPTRACE_DEST_NUM (C++ enumerator), 1343 esp_apptrace_dest_t (C++ enum), 1343 ESP_APPTRACE_DEST_TRAX (C++ enumerator), 1343 ESP_APPTRACE_DEST_UART (C++ enumerator), 1343 esp_apptrace_down_buffer_config (C++ function), 1340 esp_apptrace_down_buffer_get (C++ func- tion), 1341 esp_apptrace_down_buffer_put (C++ func- tion), 1341 esp_apptrace_fclose (C++ function), 1342 esp_apptrace_flush (C++ function), 1341 esp_apptrace_flush_nolock (C++ function), 1341 esp_apptrace_fopen (C++ function), 1342 esp_apptrace_fread (C++ function), 1342 esp_apptrace_fseek (C++ function), 1342 esp_apptrace_fstop (C++ function), 1343 esp_apptrace_ftell (C++ function), 1342 esp_apptrace_fwrite (C++ function), 1342 esp_apptrace_host_is_connected (C++ function), 1342 esp_apptrace_init (C++ function), 1340 esp_apptrace_read (C++ function), 1341 esp_apptrace_vprintf (C++ function), 1341 esp_apptrace_vprintf_to (C++ function), 1340 esp_apptrace_write (C++ function), 1340 esp_async_memcpy (C++ function), 1616 esp_async_memcpy_install (C++ function), 1616 esp_async_memcpy_uninstall (C++ function), 1616 esp_attr_control_t (C++ class), 228 esp_attr_control_t::auto_rsp (C++ mem- ber), 229 esp_attr_desc_t (C++ class), 228 esp_attr_desc_t::length (C++ member), 228 esp_attr_desc_t::max_length (C++ mem- ber), 228 esp_attr_desc_t::perm (C++ member), 228 esp_attr_desc_t::uuid_length (C++ mem- ber), 228 esp_attr_desc_t::uuid_p (C++ member), 228 esp_attr_desc_t::value (C++ member), 228 esp_attr_value_t (C++ class), 229 esp_attr_value_t::attr_len (C++ member), 229 esp_attr_value_t::attr_max_len (C++ member), 229 esp_attr_value_t::attr_value (C++ mem- ber), 229 esp_base_mac_addr_get (C++ function), 1564 esp_base_mac_addr_set (C++ function), 1564 ESP_BD_ADDR_HEX (C macro), 180 ESP_BD_ADDR_LEN (C macro), 179, 273 ESP_BD_ADDR_STR (C macro), 180 esp_bd_addr_t (C++ type), 180, 273 ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE (C++ enumerator), 224 ESP_BLE_AD_TYPE_128SERVICE_DATA (C++ enumerator), 223 ESP_BLE_AD_TYPE_128SOL_SRV_UUID (C++ enumerator), 223 ESP_BLE_AD_TYPE_128SRV_CMPL (C++ enumer- ator), 223 ESP_BLE_AD_TYPE_128SRV_PART (C++ enumer- ator), 223 ESP_BLE_AD_TYPE_16SRV_CMPL (C++ enumera- tor), 223 ESP_BLE_AD_TYPE_16SRV_PART (C++ enumera- tor), 223 ESP_BLE_AD_TYPE_32SERVICE_DATA (C++ enumerator), 223 ESP_BLE_AD_TYPE_32SOL_SRV_UUID (C++ enumerator), 223 ESP_BLE_AD_TYPE_32SRV_CMPL (C++ enumera- tor), 223 ESP_BLE_AD_TYPE_32SRV_PART (C++ enumera- tor), 223 Espressif Systems 2068 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_AD_TYPE_ADV_INT (C++ enumerator), 223 ESP_BLE_AD_TYPE_APPEARANCE (C++ enumerator), 223 ESP_BLE_AD_TYPE_CHAN_MAP_UPDATE (C++ enumerator), 224 ESP_BLE_AD_TYPE_DEV_CLASS (C++ enumerator), 223 ESP_BLE_AD_TYPE_FLAG (C++ enumerator), 223 ESP_BLE_AD_TYPE_INDOOR_POSITION (C++ enumerator), 224 ESP_BLE_AD_TYPE_INT_RANGE (C++ enumera- tor), 223 ESP_BLE_AD_TYPE_LE_DEV_ADDR (C++ enumer- ator), 223 ESP_BLE_AD_TYPE_LE_ROLE (C++ enumerator), 223 ESP_BLE_AD_TYPE_LE_SECURE_CONFIRM (C++ enumerator), 223 ESP_BLE_AD_TYPE_LE_SECURE_RANDOM (C++ enumerator), 224 ESP_BLE_AD_TYPE_LE_SUPPORT_FEATURE (C++ enumerator), 224 ESP_BLE_AD_TYPE_NAME_CMPL (C++ enumera- tor), 223 ESP_BLE_AD_TYPE_NAME_SHORT (C++ enumera- tor), 223 ESP_BLE_AD_TYPE_PUBLIC_TARGET (C++ enu- merator), 223 ESP_BLE_AD_TYPE_RANDOM_TARGET (C++ enu- merator), 223 ESP_BLE_AD_TYPE_SERVICE_DATA (C++ enu- merator), 223 ESP_BLE_AD_TYPE_SM_OOB_FLAG (C++ enumer- ator), 223 ESP_BLE_AD_TYPE_SM_TK (C++ enumerator), 223 ESP_BLE_AD_TYPE_SOL_SRV_UUID (C++ enu- merator), 223 ESP_BLE_AD_TYPE_SPAIR_C256 (C++ enumera- tor), 223 ESP_BLE_AD_TYPE_SPAIR_R256 (C++ enumera- tor), 223 ESP_BLE_AD_TYPE_TRANS_DISC_DATA (C++ enumerator), 224 ESP_BLE_AD_TYPE_TX_PWR (C++ enumerator), 223 ESP_BLE_AD_TYPE_URI (C++ enumerator), 224 esp_ble_addr_type_t (C++ enum), 181 esp_ble_adv_channel_t (C++ enum), 224 ESP_BLE_ADV_DATA_LEN_MAX (C macro), 219 esp_ble_adv_data_t (C++ class), 207 esp_ble_adv_data_t::appearance (C++ member), 208 esp_ble_adv_data_t::flag (C++ member), 208 esp_ble_adv_data_t::include_name (C++ member), 207 esp_ble_adv_data_t::include_txpower (C++ member), 207 esp_ble_adv_data_t::manufacturer_len (C++ member), 208 esp_ble_adv_data_t::max_interval (C++ member), 207 esp_ble_adv_data_t::min_interval (C++ member), 207 esp_ble_adv_data_t::p_manufacturer_data (C++ member), 208 esp_ble_adv_data_t::p_service_data (C++ member), 208 esp_ble_adv_data_t::p_service_uuid (C++ member), 208 esp_ble_adv_data_t::service_data_len (C++ member), 208 esp_ble_adv_data_t::service_uuid_len (C++ member), 208 esp_ble_adv_data_t::set_scan_rsp (C++ member), 207 esp_ble_adv_data_type (C++ enum), 223 esp_ble_adv_filter_t (C++ enum), 224 ESP_BLE_ADV_FLAG_BREDR_NOT_SPT (C macro), 216 ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT (C macro), 216 ESP_BLE_ADV_FLAG_DMT_HOST_SPT (C macro), 216 ESP_BLE_ADV_FLAG_GEN_DISC (C macro), 216 ESP_BLE_ADV_FLAG_LIMIT_DISC (C macro), 216 ESP_BLE_ADV_FLAG_NON_LIMIT_DISC (C macro), 216 esp_ble_adv_params_t (C++ class), 207 esp_ble_adv_params_t::adv_filter_policy (C++ member), 207 esp_ble_adv_params_t::adv_int_max (C++ member), 207 esp_ble_adv_params_t::adv_int_min (C++ member), 207 esp_ble_adv_params_t::adv_type (C++ member), 207 esp_ble_adv_params_t::channel_map (C++ member), 207 esp_ble_adv_params_t::own_addr_type (C++ member), 207 esp_ble_adv_params_t::peer_addr (C++ member), 207 esp_ble_adv_params_t::peer_addr_type (C++ member), 207 ESP_BLE_ADV_REPORT_EXT_ADV_IND (C macro), 220 ESP_BLE_ADV_REPORT_EXT_DIRECT_ADV (C macro), 220 ESP_BLE_ADV_REPORT_EXT_SCAN_IND (C macro), 220 ESP_BLE_ADV_REPORT_EXT_SCAN_RSP (C macro), 220 esp_ble_adv_type_t (C++ enum), 224 Espressif Systems 2069 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_APP_ENC_KEY_SIZE (C++ enumerator), ESP_BLE_APPEARANCE_GENERIC_THERMOMETER 225 (C macro), 218 ESP_BLE_APPEARANCE_BLOOD_PRESSURE_ARM ESP_BLE_APPEARANCE_GENERIC_WALKING (C (C macro), 218 macro), 218 ESP_BLE_APPEARANCE_BLOOD_PRESSURE_WRISTESP_BLE_APPEARANCE_GENERIC_WATCH (C (C macro), 218 macro), 217 ESP_BLE_APPEARANCE_CYCLING_CADENCE (C ESP_BLE_APPEARANCE_GENERIC_WEIGHT (C macro), 218 macro), 218 ESP_BLE_APPEARANCE_CYCLING_COMPUTER (C ESP_BLE_APPEARANCE_HEART_RATE_BELT (C macro), 218 macro), 218 ESP_BLE_APPEARANCE_CYCLING_POWER (C ESP_BLE_APPEARANCE_HID_BARCODE_SCANNER macro), 218 (C macro), 218 ESP_BLE_APPEARANCE_CYCLING_SPEED (C ESP_BLE_APPEARANCE_HID_CARD_READER (C macro), 218 macro), 218 ESP_BLE_APPEARANCE_CYCLING_SPEED_CADENCEESP_BLE_APPEARANCE_HID_DIGITAL_PEN (C (C macro), 218 macro), 218 ESP_BLE_APPEARANCE_GENERIC_BARCODE_SCANENSEPR_BLE_APPEARANCE_HID_DIGITIZER_TABLET (C macro), 217 (C macro), 218 ESP_BLE_APPEARANCE_GENERIC_BLOOD_PRESSUERSEP_BLE_APPEARANCE_HID_GAMEPAD (C (C macro), 218 macro), 218 ESP_BLE_APPEARANCE_GENERIC_CLOCK (C ESP_BLE_APPEARANCE_HID_JOYSTICK (C macro), 217 macro), 218 ESP_BLE_APPEARANCE_GENERIC_COMPUTER (C ESP_BLE_APPEARANCE_HID_KEYBOARD (C macro), 217 macro), 218 ESP_BLE_APPEARANCE_GENERIC_CONTINUOUS_GELSUPC_OBSLEE__MAOPNPIETAORRANCE_HID_MOUSE (C macro), (C macro), 218 218 ESP_BLE_APPEARANCE_GENERIC_CYCLING (C ESP_BLE_APPEARANCE_INSULIN_PEN (C macro), 218 macro), 218 ESP_BLE_APPEARANCE_GENERIC_DISPLAY (C ESP_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP macro), 217 (C macro), 218 ESP_BLE_APPEARANCE_GENERIC_EYEGLASSES ESP_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP (C macro), 217 (C macro), 218 ESP_BLE_APPEARANCE_GENERIC_GLUCOSE (C ESP_BLE_APPEARANCE_MOBILITY_SCOOTER (C macro), 218 macro), 218 ESP_BLE_APPEARANCE_GENERIC_HEART_RATE ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION (C macro), 218 (C macro), 219 ESP_BLE_APPEARANCE_GENERIC_HID (C ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NA macro), 218 (C macro), 219 ESP_BLE_APPEARANCE_GENERIC_INSULIN_PUMPESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD (C macro), 218 (C macro), 219 ESP_BLE_APPEARANCE_GENERIC_KEYRING (C ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AN macro), 217 (C macro), 219 ESP_BLE_APPEARANCE_GENERIC_MEDIA_PLAYERESP_BLE_APPEARANCE_POWERED_WHEELCHAIR (C macro), 217 (C macro), 218 ESP_BLE_APPEARANCE_GENERIC_MEDICATION_DEESLPI_VBELREY_APPEARANCE_PULSE_OXIMETER_FINGERTIP (C macro), 219 (C macro), 218 ESP_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORETSSP_BLE_APPEARANCE_PULSE_OXIMETER_WRIST (C macro), 219 (C macro), 218 ESP_BLE_APPEARANCE_GENERIC_PERSONAL_MOBEISLPI_TBYL_ED_EAVPIPCEEARANCE_SPORTS_WATCH (C (C macro), 218 macro), 217 ESP_BLE_APPEARANCE_GENERIC_PHONE (C ESP_BLE_APPEARANCE_THERMOMETER_EAR (C macro), 217 macro), 218 ESP_BLE_APPEARANCE_GENERIC_PULSE_OXIMETEESRP_BLE_APPEARANCE_UNKNOWN (C macro), 217 (C macro), 218 ESP_BLE_APPEARANCE_WALKING_IN_SHOE (C ESP_BLE_APPEARANCE_GENERIC_REMOTE (C macro), 218 macro), 217 ESP_BLE_APPEARANCE_WALKING_ON_HIP (C ESP_BLE_APPEARANCE_GENERIC_TAG (C macro), 218 macro), 217 ESP_BLE_APPEARANCE_WALKING_ON_SHOE (C Espressif Systems 2070 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index macro), 218 (C++ enumerator), 226 esp_ble_auth_cmpl_t (C++ class), 212 ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN esp_ble_auth_cmpl_t::addr_type (C++ (C++ enumerator), 226 member), 212 ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_REMOVE esp_ble_auth_cmpl_t::auth_mode (C++ (C++ enumerator), 226 member), 212 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST esp_ble_auth_cmpl_t::bd_addr (C++ mem- (C++ enumerator), 227 ber), 212 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ALL_LIST esp_ble_auth_cmpl_t::dev_type (C++ (C++ enumerator), 227 member), 212 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_ADV_ADDR esp_ble_auth_cmpl_t::fail_reason (C++ (C++ enumerator), 227 member), 212 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_BEAC esp_ble_auth_cmpl_t::key (C++ member), (C++ enumerator), 227 212 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_LINK esp_ble_auth_cmpl_t::key_present (C++ (C++ enumerator), 227 member), 212 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROV esp_ble_auth_cmpl_t::key_type (C++ (C++ enumerator), 227 member), 212 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROX esp_ble_auth_cmpl_t::success (C++ mem- (C++ enumerator), 227 ber), 212 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_BEACON_TY esp_ble_auth_req_t (C++ type), 220 (C++ enumerator), 227 esp_ble_bond_dev_t (C++ class), 211 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_L esp_ble_bond_dev_t::bd_addr (C++ mem- (C++ enumerator), 227 ber), 211 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROV_SRV_ esp_ble_bond_dev_t::bond_key (C++ mem- (C++ enumerator), 227 ber), 211 ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROXY_SRV esp_ble_bond_key_info_t (C++ class), 211 (C++ enumerator), 227 esp_ble_bond_key_info_t::key_mask ESP_BLE_ENC_KEY_MASK (C macro), 179 (C++ member), 211 ESP_BLE_EVT_CONN_ADV (C++ enumerator), 226 esp_ble_bond_key_info_t::pcsrk_key ESP_BLE_EVT_CONN_DIR_ADV (C++ enumerator), (C++ member), 211 226 esp_ble_bond_key_info_t::penc_key ESP_BLE_EVT_DISC_ADV (C++ enumerator), 226 (C++ member), 211 ESP_BLE_EVT_NON_CONN_ADV (C++ enumerator), esp_ble_bond_key_info_t::pid_key (C++ 226 member), 211 ESP_BLE_EVT_SCAN_RSP (C++ enumerator), 226 esp_ble_confirm_reply (C++ function), 188 esp_ble_evt_type_t (C++ enum), 226 ESP_BLE_CONN_INT_MAX (C macro), 179 esp_ble_ext_adv_type_mask_t (C++ type), ESP_BLE_CONN_INT_MIN (C macro), 179 220 ESP_BLE_CONN_LATENCY_MAX (C macro), 179 esp_ble_ext_scan_cfg_mask_t (C++ type), ESP_BLE_CONN_PARAM_UNDEF (C macro), 179 220 ESP_BLE_CONN_SUP_TOUT_MAX (C macro), 179 esp_ble_ext_scan_cfg_t (C++ class), 213 ESP_BLE_CONN_SUP_TOUT_MIN (C macro), 179 esp_ble_ext_scan_cfg_t::scan_interval esp_ble_conn_update_params_t (C++ class), (C++ member), 213 209 esp_ble_ext_scan_cfg_t::scan_type esp_ble_conn_update_params_t::bda (C++ member), 213 (C++ member), 209 esp_ble_ext_scan_cfg_t::scan_window esp_ble_conn_update_params_t::latency (C++ member), 213 (C++ member), 209 esp_ble_ext_scan_params_t (C++ class), 213 esp_ble_conn_update_params_t::max_int esp_ble_ext_scan_params_t::cfg_mask (C++ member), 209 (C++ member), 213 esp_ble_conn_update_params_t::min_int esp_ble_ext_scan_params_t::coded_cfg (C++ member), 209 (C++ member), 213 esp_ble_conn_update_params_t::timeout esp_ble_ext_scan_params_t::filter_policy (C++ member), 209 (C++ member), 213 ESP_BLE_CSR_KEY_MASK (C macro), 179 esp_ble_ext_scan_params_t::own_addr_type esp_ble_duplicate_exceptional_info_type_t (C++ member), 213 (C++ enum), 227 esp_ble_ext_scan_params_t::scan_duplicate ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_ADD (C++ member), 213 Espressif Systems 2071 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_ext_scan_params_t::uncoded_cfg (C++ class), 198 (C++ member), 213 esp_ble_gap_cb_param_t::ble_ext_adv_report_param: esp_ble_gap_add_duplicate_scan_exceptional_dev(Ci+c+e member), 198 (C++ function), 186 esp_ble_gap_cb_param_t::ble_ext_adv_scan_rsp_set_ esp_ble_gap_adv_type_t (C++ type), 220 (C++ class), 198 esp_ble_gap_all_phys_t (C++ type), 220 esp_ble_gap_cb_param_t::ble_ext_adv_scan_rsp_set_ esp_ble_gap_cb_param_t (C++ union), 194 (C++ member), 198 esp_ble_gap_cb_param_t::adv_data_cmpl esp_ble_gap_cb_param_t::ble_ext_adv_set_clear_cmp (C++ member), 194 (C++ class), 198 esp_ble_gap_cb_param_t::adv_data_raw_cmepslp_ble_gap_cb_param_t::ble_ext_adv_set_clear_cmp (C++ member), 194 (C++ member), 198 esp_ble_gap_cb_param_t::adv_start_cmpl esp_ble_gap_cb_param_t::ble_ext_adv_set_params_cm (C++ member), 194 (C++ class), 198 esp_ble_gap_cb_param_t::adv_stop_cmpl esp_ble_gap_cb_param_t::ble_ext_adv_set_params_cm (C++ member), 195 (C++ member), 199 esp_ble_gap_cb_param_t::adv_terminate esp_ble_gap_cb_param_t::ble_ext_adv_set_rand_addr (C++ member), 196 (C++ class), 199 esp_ble_gap_cb_param_t::ble_adv_data_cmepslp__ebvlte__pgaarpa_mcb_param_t::ble_ext_adv_set_rand_addr (C++ class), 197 (C++ member), 199 esp_ble_gap_cb_param_t::ble_adv_data_cmepslp__ebvlte__pgaarpa_mc:b:_sptaartaums_t::ble_ext_adv_set_remove_cm (C++ member), 197 (C++ class), 199 esp_ble_gap_cb_param_t::ble_adv_data_raews_pc_mbplle__egvatp__pcabr_apmaram_t::ble_ext_adv_set_remove_cm (C++ class), 197 (C++ member), 199 esp_ble_gap_cb_param_t::ble_adv_data_raews_pc_mbplle__egvatp__pcabr_apma:r:asmt_att:u:sble_ext_adv_start_cmpl_ev (C++ member), 197 (C++ class), 199 esp_ble_gap_cb_param_t::ble_adv_start_cemsppl__belvet__gpaapr_acmb_param_t::ble_ext_adv_start_cmpl_ev (C++ class), 197 (C++ member), 199 esp_ble_gap_cb_param_t::ble_adv_start_cemsppl__belvet__gpaapr_acmb:_:psatraatmu_st::ble_ext_adv_stop_cmpl_evt (C++ member), 197 (C++ class), 199 esp_ble_gap_cb_param_t::ble_adv_stop_cmepslp__ebvlte__pgaarpa_mcb_param_t::ble_ext_adv_stop_cmpl_evt (C++ class), 197 (C++ member), 199 esp_ble_gap_cb_param_t::ble_adv_stop_cmepslp__ebvlte__pgaarpa_mc:b:_sptaartaums_t::ble_ext_conn_params_set_c (C++ member), 197 (C++ class), 199 esp_ble_gap_cb_param_t::ble_adv_terminaetsep__pbalrea_mgap_cb_param_t::ble_ext_conn_params_set_c (C++ class), 197 (C++ member), 199 esp_ble_gap_cb_param_t::ble_adv_terminaetsep__pbalrea_mg:a:pa_dcvb__ipnasrtaamn_cte::ble_ext_scan_start_cmpl_p (C++ member), 197 (C++ class), 199 esp_ble_gap_cb_param_t::ble_adv_terminaetsep__pbalrea_mg:a:pc_ocmbp_lpeatreadm__etv:e:nbtle_ext_scan_start_cmpl_p (C++ member), 197 (C++ member), 199 esp_ble_gap_cb_param_t::ble_adv_terminaetsep__pbalrea_mg:a:pc_ocnbn__piadrxam_t::ble_ext_scan_stop_cmpl_pa (C++ member), 197 (C++ class), 199 esp_ble_gap_cb_param_t::ble_adv_terminaetsep__pbalrea_mg:a:ps_tcabt_upsaram_t::ble_ext_scan_stop_cmpl_pa (C++ member), 197 (C++ member), 200 esp_ble_gap_cb_param_t::ble_channel_sele_sapl_gb_lpea_rgaamp_cb_param_t::ble_get_bond_dev_cmpl_evt (C++ class), 197 (C++ class), 200 esp_ble_gap_cb_param_t::ble_channel_sele_sapl_gb_lpea_rgaamp:_:ccbh_apnanrealm__ste:l:_balleg_get_bond_dev_cmpl_evt (C++ member), 198 (C++ member), 200 esp_ble_gap_cb_param_t::ble_channel_sele_sapl_gb_lpea_rgaamp:_:ccbo_npna_rhaamn_dtl:e:ble_get_bond_dev_cmpl_evt (C++ member), 198 (C++ member), 200 esp_ble_gap_cb_param_t::ble_clear_bond_edsepv__bclmep_lg_aepv_tc_bp_apraarmam_t::ble_get_bond_dev_cmpl_evt (C++ class), 198 (C++ member), 200 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), 198 (C++ class), 200 esp_ble_gap_cb_param_t::ble_ext_adv_dateas_ps_ebtl_ec_mgpalp__ecvbt__ppaarraamm_t::ble_local_privacy_cmpl_ev (C++ class), 198 (C++ member), 200 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), 198 (C++ class), 200 esp_ble_gap_cb_param_t::ble_ext_adv_repeosrpt__bplaer_agmap_cb_param_t::ble_period_adv_add_dev_cm Espressif Systems 2072 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 200 (C++ member), 202 esp_ble_gap_cb_param_t::ble_period_adv_ecslpe_abrl_ed_egva_pc_mcpbl__ppaarraamm_t::ble_periodic_adv_sync_los (C++ class), 200 (C++ class), 202 esp_ble_gap_cb_param_t::ble_period_adv_ecslpe_abrl_ed_egva_pc_mcpbl__ppaarraamm_:t::s:tbalteu_speriodic_adv_sync_los (C++ member), 200 (C++ member), 202 esp_ble_gap_cb_param_t::ble_period_adv_ecsrpe_abtlee__sgyanpc__ccbm_ppla_rpaamr_atm::ble_phy_update_cmpl_param (C++ class), 200 (C++ class), 202 esp_ble_gap_cb_param_t::ble_period_adv_ecsrpe_abtlee__sgyanpc__ccbm_ppla_rpaamr_atm::::bsltea_tpuhsy_update_cmpl_param (C++ member), 200 (C++ member), 202 esp_ble_gap_cb_param_t::ble_period_adv_ersepm_obvlee__dgeavp__ccmbp_lp_apraarma_mt::ble_phy_update_cmpl_param (C++ class), 200 (C++ member), 202 esp_ble_gap_cb_param_t::ble_period_adv_ersepm_obvlee__dgeavp__ccmbp_lp_apraarma_mt::::sbtlaet_upshy_update_cmpl_param (C++ member), 201 (C++ member), 202 esp_ble_gap_cb_param_t::ble_period_adv_essypn_cb_lcea_ngcaepl__ccbm_ppla_rpaamr_atm::ble_phy_update_cmpl_param (C++ class), 201 (C++ member), 202 esp_ble_gap_cb_param_t::ble_period_adv_essypn_cb_lcea_ngcaepl__ccbm_ppla_rpaamr_atm::::bsltea_tpukst_data_length_cmpl_ (C++ member), 201 (C++ class), 202 esp_ble_gap_cb_param_t::ble_period_adv_essypn_cb_ltee_rgmaipn_actbe__pcamrpalm__pta:r:abmle_pkt_data_length_cmpl_ (C++ class), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_period_adv_essypn_cb_ltee_rgmaipn_actbe__pcamrpalm__pta:r:abml:e:_sptkatt_udsata_length_cmpl_ (C++ member), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_pd_abtlae__sgeatp__ccmbp_lp_apraarma_mt::ble_read_phy_cmpl_evt_par (C++ class), 201 (C++ class), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_pd_abtlae__sgeatp__ccmbp_lp_apraarma_mt::::sbtlaet_ursead_phy_cmpl_evt_par (C++ member), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_pr_ebploer_tg_appa_rcabm_param_t::ble_read_phy_cmpl_evt_par (C++ class), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_pr_ebploer_tg_appa_rcabm_:p:apraarma_mts::ble_read_phy_cmpl_evt_par (C++ member), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ebtl_ep_agraapm_sc_bc_mppalr_apma_rta:m:ble_read_phy_cmpl_evt_par (C++ class), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ebtl_ep_agraapm_sc_bc_mppalr_apma_rta:m::b:lset_arteuasd_rssi_cmpl_evt_pa (C++ member), 201 (C++ class), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_tbalret__gcampp_lc_bp_apraarmam_t::ble_read_rssi_cmpl_evt_pa (C++ class), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_tbalret__gcampp_lc_bp_apraarma:m:_stt:a:tbulse_read_rssi_cmpl_evt_pa (C++ member), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_tbolpe__cgmappl__cpba_rpaamram_t::ble_read_rssi_cmpl_evt_pa (C++ class), 201 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_tbolpe__cgmappl__cpba_rpaamr:a:ms_tta:t:ubsle_remove_bond_dev_cmpl_ (C++ member), 202 (C++ class), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarmam_t::ble_remove_bond_dev_cmpl_ (C++ class), 202 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_atd:v:_balded_rremove_bond_dev_cmpl_ (C++ member), 202 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_atd:v:_balded_rs_ctaynp_eparam_cmpl_evt_p (C++ member), 202 (C++ class), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_atd:v:_bcllek__saccacnu_rpaacryam_cmpl_evt_p (C++ member), 202 (C++ member), 203 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_atd:v:_bplhey_scan_req_received_par (C++ member), 202 (C++ class), 203 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), 202 (C++ member), 204 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), 202 (C++ member), 204 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), 202 (C++ member), 204 esp_ble_gap_cb_param_t::ble_periodic_adevs_ps_ybnlce__egsatpa_bc_bp_apraarma:m:_sty:n:cb_lhea_nsdclaen_result_evt_param Espressif Systems 2073 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ class), 204 (C++ class), 205 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cabd_vp_adraatma__tl:e:nble_set_perf_phy_cmpl_evt (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cbbd_aparam_t::ble_set_rand_cmpl_evt_par (C++ member), 204 (C++ class), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cbbl_ep_aardadmr__tt:y:pbele_set_rand_cmpl_evt_par (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cbbl_ep_aardavm_t::ble_update_conn_params_ev (C++ member), 204 (C++ class), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cbbl_ep_aervatm__tty:p:eble_update_conn_params_ev (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cdbe_vp_atryapme_t::ble_update_conn_params_ev (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cfbl_apgaram_t::ble_update_conn_params_ev (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cnbu_mp_adriasm_t::ble_update_conn_params_ev (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:cnbu_mp_arreasmp_st::ble_update_conn_params_ev (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:crbs_spiaram_t::ble_update_conn_params_ev (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:csbc_apna_rrasmp__tl:e:nble_update_conn_params_ev (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_resulte_sepv_tb_lpea_rgaamp:_:csbe_apracrha_me_vtt::ble_update_duplicate_exce (C++ member), 204 (C++ class), 206 esp_ble_gap_cb_param_t::ble_scan_rsp_daetsap__cbmlpel__geavpt__cpba_rpaamram_t::ble_update_duplicate_exce (C++ class), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_rsp_daetsap__cbmlpel__geavpt__cpba_rpaamr:a:ms_tta:t:ubsle_update_duplicate_exce (C++ member), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_rsp_daetsap__rbalwe__cgmappl__cebv_tp_apraarma_mt::ble_update_duplicate_exce (C++ class), 204 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_rsp_daetsap__rbalwe__cgmappl__cebv_tp_apraarma_mt::::sbtlaet_uuspdate_duplicate_exce (C++ member), 205 (C++ member), 206 esp_ble_gap_cb_param_t::ble_scan_start_ecsmpp_lb_leev_tg_appa_rcabm_param_t::ble_update_whitelist_cmpl (C++ class), 205 (C++ class), 206 esp_ble_gap_cb_param_t::ble_scan_start_ecsmpp_lb_leev_tg_appa_rcabm_:p:asrtaamt_uts::ble_update_whitelist_cmpl (C++ member), 205 (C++ member), 207 esp_ble_gap_cb_param_t::ble_scan_stop_cemsppl__belvet__gpaapr_acmb_param_t::ble_update_whitelist_cmpl (C++ class), 205 (C++ member), 207 esp_ble_gap_cb_param_t::ble_scan_stop_cemsppl__belvet__gpaapr_acmb:_:psatraatmu_st::channel_sel_alg (C++ member), 205 (C++ member), 196 esp_ble_gap_cb_param_t::ble_security esp_ble_gap_cb_param_t::clear_bond_dev_cmpl (C++ member), 194 (C++ member), 195 esp_ble_gap_cb_param_t::ble_set_channelessp_ble_gap_cb_param_t::ext_adv_clear (C++ member), 195 (C++ member), 196 esp_ble_gap_cb_param_t::ble_set_channeless_pe_vbtl_ep_agraapm_cb_param_t::ext_adv_data_set (C++ class), 205 (C++ member), 195 esp_ble_gap_cb_param_t::ble_set_channeless_pe_vbtl_ep_agraapm_:c:bs_tpaatram_t::ext_adv_remove (C++ member), 205 (C++ member), 195 esp_ble_gap_cb_param_t::ble_set_ext_scaens_pp_abrlaem_sg_acpm_pclb__ppaarraamm_t::ext_adv_report (C++ class), 205 (C++ member), 196 esp_ble_gap_cb_param_t::ble_set_ext_scaens_pp_abrlaem_sg_acpm_pclb__ppaarraamm:_:ts:t:aetxuts_adv_set_params (C++ member), 205 (C++ member), 195 esp_ble_gap_cb_param_t::ble_set_perf_deefs_pp_hbyl_ec_mgpalp__ecvbt__ppaarraamm_t::ext_adv_set_rand_addr (C++ class), 205 (C++ member), 195 esp_ble_gap_cb_param_t::ble_set_perf_deefs_pp_hbyl_ec_mgpalp__ecvbt__ppaarraamm_:t::s:teaxttu_sadv_start (C++ member), 205 (C++ member), 195 esp_ble_gap_cb_param_t::ble_set_perf_pheys_pc_mbplle__egvatp__pcabr_apmaram_t::ext_adv_stop Espressif Systems 2074 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 195 member), 194 esp_ble_gap_cb_param_t::ext_conn_paramse_sspe_tble_gap_cb_param_t::scan_start_cmpl (C++ member), 196 (C++ member), 194 esp_ble_gap_cb_param_t::ext_scan_start esp_ble_gap_cb_param_t::scan_stop_cmpl (C++ member), 196 (C++ member), 195 esp_ble_gap_cb_param_t::ext_scan_stop esp_ble_gap_cb_param_t::set_ext_scan_params (C++ member), 196 (C++ member), 196 esp_ble_gap_cb_param_t::get_bond_dev_cmepslp_ble_gap_cb_param_t::set_perf_def_phy (C++ member), 195 (C++ member), 195 esp_ble_gap_cb_param_t::local_privacy_cemsppl_ble_gap_cb_param_t::set_perf_phy (C++ member), 195 (C++ member), 195 esp_ble_gap_cb_param_t::period_adv_add_edsepv_ble_gap_cb_param_t::set_rand_addr_cmpl (C++ member), 196 (C++ member), 195 esp_ble_gap_cb_param_t::period_adv_cleaers_pd_ebvle_gap_cb_param_t::update_conn_params (C++ member), 196 (C++ member), 195 esp_ble_gap_cb_param_t::period_adv_creaetsep__sbylnec_gap_cb_param_t::update_duplicate_exceptio (C++ member), 196 (C++ member), 195 esp_ble_gap_cb_param_t::period_adv_datae_sspe_tble_gap_cb_param_t::update_whitelist_cmpl (C++ member), 196 (C++ member), 195 esp_ble_gap_cb_param_t::period_adv_remoevsep__dbelve_gap_clean_duplicate_scan_exceptional_list (C++ member), 196 (C++ function), 187 esp_ble_gap_cb_param_t::period_adv_repoerstp_ble_gap_clear_rand_addr (C++ func- (C++ member), 196 tion), 184 esp_ble_gap_cb_param_t::period_adv_staretsp_ble_gap_clear_whitelist (C++ func- (C++ member), 196 tion), 185 esp_ble_gap_cb_param_t::period_adv_stopesp_ble_gap_config_adv_data (C++ func- (C++ member), 196 tion), 183 esp_ble_gap_cb_param_t::period_adv_synce_scpa_nbcleel_gap_config_adv_data_raw (C++ (C++ member), 196 function), 186 esp_ble_gap_cb_param_t::period_adv_synce_stpe_rbmle_gap_config_ext_adv_data_raw (C++ member), 196 (C++ function), 190 esp_ble_gap_cb_param_t::periodic_adv_syenscp__ebsltea_bgap_config_ext_scan_rsp_data_raw (C++ member), 196 (C++ function), 190 esp_ble_gap_cb_param_t::periodic_adv_syenscp__lbolset_gap_config_local_icon (C++ func- (C++ member), 196 tion), 185 esp_ble_gap_cb_param_t::peroid_adv_set_epsapr_abmlse_gap_config_local_privacy (C++ (C++ member), 196 function), 184 esp_ble_gap_cb_param_t::phy_update esp_ble_gap_config_periodic_adv_data_raw (C++ member), 196 (C++ function), 191 esp_ble_gap_cb_param_t::pkt_data_lenth_ecsmpp_lble_gap_config_scan_rsp_data_raw (C++ member), 195 (C++ function), 186 esp_ble_gap_cb_param_t::read_phy (C++ esp_ble_gap_conn_params_t (C++ class), 214 member), 195 esp_ble_gap_conn_params_t::interval_max esp_ble_gap_cb_param_t::read_rssi_cmpl (C++ member), 214 (C++ member), 195 esp_ble_gap_conn_params_t::interval_min esp_ble_gap_cb_param_t::remove_bond_dev_cmpl (C++ member), 214 (C++ member), 195 esp_ble_gap_conn_params_t::latency esp_ble_gap_cb_param_t::scan_param_cmpl (C++ member), 214 (C++ member), 194 esp_ble_gap_conn_params_t::max_ce_len esp_ble_gap_cb_param_t::scan_req_received (C++ member), 214 (C++ member), 196 esp_ble_gap_conn_params_t::min_ce_len esp_ble_gap_cb_param_t::scan_rsp_data_cmpl (C++ member), 214 (C++ member), 194 esp_ble_gap_conn_params_t::scan_interval esp_ble_gap_cb_param_t::scan_rsp_data_raw_cmpl(C++ member), 214 (C++ member), 194 esp_ble_gap_conn_params_t::scan_window esp_ble_gap_cb_param_t::scan_rsp_set (C++ member), 214 (C++ member), 195 esp_ble_gap_conn_params_t::supervision_timeout esp_ble_gap_cb_param_t::scan_rst (C++ (C++ member), 214 Espressif Systems 2075 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_gap_disconnect (C++ function), 189 (C++ member), 215 ESP_BLE_GAP_EXT_ADV_DATA_COMPLETE (C esp_ble_gap_ext_adv_reprot_t::primary_phy macro), 220 (C++ member), 215 ESP_BLE_GAP_EXT_ADV_DATA_INCOMPLETE (C esp_ble_gap_ext_adv_reprot_t::rssi macro), 220 (C++ member), 215 esp_ble_gap_ext_adv_data_status_t esp_ble_gap_ext_adv_reprot_t::secondly_phy (C++ type), 220 (C++ member), 215 ESP_BLE_GAP_EXT_ADV_DATA_TRUNCATED (C esp_ble_gap_ext_adv_reprot_t::sid macro), 220 (C++ member), 215 esp_ble_gap_ext_adv_params_t (C++ class), esp_ble_gap_ext_adv_reprot_t::tx_power 212 (C++ member), 215 esp_ble_gap_ext_adv_params_t::channel_measpp_ble_gap_ext_adv_set_clear (C++ func- (C++ member), 212 tion), 191 esp_ble_gap_ext_adv_params_t::filter_poelsipc_yble_gap_ext_adv_set_params (C++ (C++ member), 213 function), 190 esp_ble_gap_ext_adv_params_t::interval_emsapx_ble_gap_ext_adv_set_rand_addr (C++ member), 212 (C++ function), 190 esp_ble_gap_ext_adv_params_t::interval_emsipn_ble_gap_ext_adv_set_remove (C++ (C++ member), 212 function), 191 esp_ble_gap_ext_adv_params_t::max_skip esp_ble_gap_ext_adv_start (C++ function), (C++ member), 213 191 esp_ble_gap_ext_adv_params_t::own_addr_etsypp_eble_gap_ext_adv_stop (C++ function), (C++ member), 212 191 esp_ble_gap_ext_adv_params_t::peer_addresp_ble_gap_ext_adv_t (C++ class), 214 (C++ member), 213 esp_ble_gap_ext_adv_t::duration (C++ esp_ble_gap_ext_adv_params_t::peer_addr_type member), 214 (C++ member), 213 esp_ble_gap_ext_adv_t::instance (C++ esp_ble_gap_ext_adv_params_t::primary_phy member), 214 (C++ member), 213 esp_ble_gap_ext_adv_t::max_events esp_ble_gap_ext_adv_params_t::scan_req_notif (C++ member), 214 (C++ member), 213 ESP_BLE_GAP_EXT_SCAN_CFG_CODE_MASK (C esp_ble_gap_ext_adv_params_t::secondary_phy macro), 220 (C++ member), 213 ESP_BLE_GAP_EXT_SCAN_CFG_UNCODE_MASK esp_ble_gap_ext_adv_params_t::sid (C macro), 220 (C++ member), 213 esp_ble_gap_get_local_used_addr (C++ esp_ble_gap_ext_adv_params_t::tx_power function), 186 (C++ member), 213 esp_ble_gap_get_whitelist_size (C++ esp_ble_gap_ext_adv_params_t::type function), 185 (C++ member), 212 ESP_BLE_GAP_NO_PREFER_RECEIVE_PHY (C esp_ble_gap_ext_adv_reprot_t (C++ class), macro), 219 215 ESP_BLE_GAP_NO_PREFER_TRANSMIT_PHY (C esp_ble_gap_ext_adv_reprot_t::addr macro), 219 (C++ member), 215 esp_ble_gap_periodic_adv_add_dev_to_list esp_ble_gap_ext_adv_reprot_t::addr_type (C++ function), 193 (C++ member), 215 esp_ble_gap_periodic_adv_clear_dev esp_ble_gap_ext_adv_reprot_t::adv_data (C++ function), 193 (C++ member), 215 esp_ble_gap_periodic_adv_create_sync esp_ble_gap_ext_adv_reprot_t::adv_data_len (C++ function), 192 (C++ member), 215 esp_ble_gap_periodic_adv_params_t esp_ble_gap_ext_adv_reprot_t::data_status (C++ class), 214 (C++ member), 215 esp_ble_gap_periodic_adv_params_t::interval_max esp_ble_gap_ext_adv_reprot_t::dir_addr (C++ member), 214 (C++ member), 215 esp_ble_gap_periodic_adv_params_t::interval_min esp_ble_gap_ext_adv_reprot_t::dir_addr_type (C++ member), 214 (C++ member), 215 esp_ble_gap_periodic_adv_params_t::properties esp_ble_gap_ext_adv_reprot_t::event_type (C++ member), 214 (C++ member), 215 esp_ble_gap_periodic_adv_remove_dev_from_list esp_ble_gap_ext_adv_reprot_t::per_adv_interval(C++ function), 193 Espressif Systems 2076 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_gap_periodic_adv_report_t 219 (C++ class), 215 ESP_BLE_GAP_PHY_2M (C macro), 219 esp_ble_gap_periodic_adv_report_t::dataESP_BLE_GAP_PHY_2M_PREF_MASK (C macro), (C++ member), 216 219 esp_ble_gap_periodic_adv_report_t::dataE_SlPe_nBgLtEh_GAP_PHY_CODED (C macro), 219 (C++ member), 216 ESP_BLE_GAP_PHY_CODED_PREF_MASK (C esp_ble_gap_periodic_adv_report_t::data_statusmacro), 219 (C++ member), 216 esp_ble_gap_phy_mask_t (C++ type), 220 esp_ble_gap_periodic_adv_report_t::rssiESP_BLE_GAP_PHY_OPTIONS_NO_PREF (C (C++ member), 216 macro), 219 esp_ble_gap_periodic_adv_report_t::syncE_ShPa_nBdLlEe_GAP_PHY_OPTIONS_PREF_S2_CODING (C++ member), 216 (C macro), 219 esp_ble_gap_periodic_adv_report_t::tx_pEoSwPe_rBLE_GAP_PHY_OPTIONS_PREF_S8_CODING (C++ member), 216 (C macro), 220 esp_ble_gap_periodic_adv_set_params esp_ble_gap_phy_t (C++ type), 220 (C++ function), 191 esp_ble_gap_prefer_ext_connect_params_set esp_ble_gap_periodic_adv_start (C++ (C++ function), 193 function), 192 esp_ble_gap_prefer_phy_options_t (C++ esp_ble_gap_periodic_adv_stop (C++ func- type), 220 tion), 192 ESP_BLE_GAP_PRI_PHY_1M (C macro), 219 esp_ble_gap_periodic_adv_sync_cancel ESP_BLE_GAP_PRI_PHY_CODED (C macro), 219 (C++ function), 192 esp_ble_gap_pri_phy_t (C++ type), 220 esp_ble_gap_periodic_adv_sync_estab_t esp_ble_gap_read_phy (C++ function), 189 (C++ class), 216 esp_ble_gap_read_rssi (C++ function), 186 esp_ble_gap_periodic_adv_sync_estab_t::easdpd_rb_ltey_pgeap_register_callback (C++ func- (C++ member), 216 tion), 183 esp_ble_gap_periodic_adv_sync_estab_t::easdpv__balded_rgap_remove_duplicate_scan_exceptional_dev (C++ member), 216 (C++ function), 187 esp_ble_gap_periodic_adv_sync_estab_t::easdpv__bcllek__gaacpc_usreaccuyrity_rsp (C++ function), (C++ member), 216 188 esp_ble_gap_periodic_adv_sync_estab_t::easdpv__bplhey_gap_set_device_name (C++ func- (C++ member), 216 tion), 186 esp_ble_gap_periodic_adv_sync_estab_t::EpSePr_iBoLdE__aGdAvP__iSnEtTe_rEvXaTl_ADV_PROP_ANON_ADV (C++ member), 216 (C macro), 219 esp_ble_gap_periodic_adv_sync_estab_t::EsSiPd_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE (C++ member), 216 (C macro), 219 esp_ble_gap_periodic_adv_sync_estab_t::EsStPa_tBuLsE_GAP_SET_EXT_ADV_PROP_DIRECTED (C++ member), 216 (C macro), 219 esp_ble_gap_periodic_adv_sync_estab_t::EsSyPn_cB_LhEa_nGdAlPe_SET_EXT_ADV_PROP_HD_DIRECTED (C++ member), 216 (C macro), 219 esp_ble_gap_periodic_adv_sync_params_t ESP_BLE_GAP_SET_EXT_ADV_PROP_INCLUDE_TX_PWR (C++ class), 214 (C macro), 219 esp_ble_gap_periodic_adv_sync_params_t:E:SaPd_dBrLE_GAP_SET_EXT_ADV_PROP_LEGACY (C (C++ member), 215 macro), 219 esp_ble_gap_periodic_adv_sync_params_t:E:SaPd_dBrL_Et_yGpAeP_SET_EXT_ADV_PROP_LEGACY_HD_DIR (C++ member), 215 (C macro), 219 esp_ble_gap_periodic_adv_sync_params_t:E:SfPi_lBtLeEr__GpAoPl_iScEyT_EXT_ADV_PROP_LEGACY_IND (C++ member), 215 (C macro), 219 esp_ble_gap_periodic_adv_sync_params_t:E:SsPi_dBLE_GAP_SET_EXT_ADV_PROP_LEGACY_LD_DIR (C++ member), 215 (C macro), 219 esp_ble_gap_periodic_adv_sync_params_t:E:SsPk_iBpLE_GAP_SET_EXT_ADV_PROP_LEGACY_NONCONN (C++ member), 215 (C macro), 219 esp_ble_gap_periodic_adv_sync_params_t:E:SsPy_nBcL_Et_iGmAePo_uStET_EXT_ADV_PROP_LEGACY_SCAN (C++ member), 215 (C macro), 219 esp_ble_gap_periodic_adv_sync_terminateESP_BLE_GAP_SET_EXT_ADV_PROP_MASK (C (C++ function), 192 macro), 219 ESP_BLE_GAP_PHY_1M (C macro), 219 ESP_BLE_GAP_SET_EXT_ADV_PROP_NONCONN_NONSCANNABLE ESP_BLE_GAP_PHY_1M_PREF_MASK (C macro), (C macro), 219 Espressif Systems 2077 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE (C++ member), 258 (C macro), 219 esp_ble_gattc_cb_param_t::connect esp_ble_gap_set_ext_scan_params (C++ (C++ member), 258 function), 192 esp_ble_gattc_cb_param_t::dis_srvc_cmpl esp_ble_gap_set_pkt_data_len (C++ func- (C++ member), 259 tion), 184 esp_ble_gattc_cb_param_t::disconnect esp_ble_gap_set_prefer_conn_params (C++ member), 258 (C++ function), 185 esp_ble_gattc_cb_param_t::exec_cmpl esp_ble_gap_set_prefered_default_phy (C++ member), 258 (C++ function), 190 esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param esp_ble_gap_set_prefered_phy (C++ func- (C++ class), 259 tion), 190 esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param esp_ble_gap_set_rand_addr (C++ function), (C++ member), 259 184 esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param esp_ble_gap_set_scan_params (C++ func- (C++ member), 259 tion), 183 esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param esp_ble_gap_set_security_param (C++ (C++ member), 259 function), 187 esp_ble_gattc_cb_param_t::gattc_close_evt_param esp_ble_gap_start_advertising (C++ func- (C++ class), 259 tion), 184 esp_ble_gattc_cb_param_t::gattc_close_evt_param:: esp_ble_gap_start_ext_scan (C++ function), (C++ member), 259 192 esp_ble_gattc_cb_param_t::gattc_close_evt_param:: esp_ble_gap_start_scanning (C++ function), (C++ member), 259 183 esp_ble_gattc_cb_param_t::gattc_close_evt_param:: esp_ble_gap_stop_advertising (C++ func- (C++ member), 259 tion), 184 esp_ble_gattc_cb_param_t::gattc_close_evt_param:: esp_ble_gap_stop_ext_scan (C++ function), (C++ member), 259 192 esp_ble_gattc_cb_param_t::gattc_congest_evt_param esp_ble_gap_stop_scanning (C++ function), (C++ class), 259 184 esp_ble_gattc_cb_param_t::gattc_congest_evt_param ESP_BLE_GAP_SYNC_POLICY_BY_ADV_INFO (C (C++ member), 259 macro), 220 esp_ble_gattc_cb_param_t::gattc_congest_evt_param ESP_BLE_GAP_SYNC_POLICY_BY_PERIODIC_LIST (C++ member), 259 (C macro), 220 esp_ble_gattc_cb_param_t::gattc_connect_evt_param esp_ble_gap_sync_t (C++ type), 220 (C++ class), 259 esp_ble_gap_update_conn_params (C++ esp_ble_gattc_cb_param_t::gattc_connect_evt_param function), 184 (C++ member), 260 esp_ble_gap_update_whitelist (C++ func- esp_ble_gattc_cb_param_t::gattc_connect_evt_param tion), 185 (C++ member), 260 esp_ble_gattc_app_register (C++ function), esp_ble_gattc_cb_param_t::gattc_connect_evt_param 250 (C++ member), 260 esp_ble_gattc_app_unregister (C++ func- esp_ble_gattc_cb_param_t::gattc_connect_evt_param tion), 250 (C++ member), 260 esp_ble_gattc_aux_open (C++ function), 251 esp_ble_gattc_cb_param_t::gattc_dis_srvc_cmpl_evt esp_ble_gattc_cache_assoc (C++ function), (C++ class), 260 257 esp_ble_gattc_cb_param_t::gattc_dis_srvc_cmpl_evt esp_ble_gattc_cache_clean (C++ function), (C++ member), 260 258 esp_ble_gattc_cb_param_t::gattc_dis_srvc_cmpl_evt esp_ble_gattc_cache_get_addr_list (C++ member), 260 (C++ function), 257 esp_ble_gattc_cb_param_t::gattc_disconnect_evt_pa esp_ble_gattc_cache_refresh (C++ func- (C++ class), 260 tion), 257 esp_ble_gattc_cb_param_t::gattc_disconnect_evt_pa esp_ble_gattc_cb_param_t (C++ union), 258 (C++ member), 260 esp_ble_gattc_cb_param_t::cfg_mtu esp_ble_gattc_cb_param_t::gattc_disconnect_evt_pa (C++ member), 258 (C++ member), 260 esp_ble_gattc_cb_param_t::close (C++ esp_ble_gattc_cb_param_t::gattc_disconnect_evt_pa member), 258 (C++ member), 260 esp_ble_gattc_cb_param_t::congest esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_par Espressif Systems 2078 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ class), 260 (C++ class), 262 esp_ble_gattc_cb_param_t::gattc_exec_cmepslp__ebvlte__pgaartatmc:_:ccbo_npna_riadm_t::gattc_reg_evt_param::ap (C++ member), 260 (C++ member), 262 esp_ble_gattc_cb_param_t::gattc_exec_cmepslp__ebvlte__pgaartatmc:_:csbt_aptaursam_t::gattc_reg_evt_param::st (C++ member), 260 (C++ member), 262 esp_ble_gattc_cb_param_t::gattc_get_adders_pl_ibslte__egvatt_tpca_rcabm_param_t::gattc_reg_for_notify_ev (C++ class), 260 (C++ class), 262 esp_ble_gattc_cb_param_t::gattc_get_adders_pl_ibslte__egvatt_tpca_rcabm_:p:aardadmr__tl:i:sgtattc_reg_for_notify_ev (C++ member), 260 (C++ member), 262 esp_ble_gattc_cb_param_t::gattc_get_adders_pl_ibslte__egvatt_tpca_rcabm_:p:anruamm__atd:d:rgattc_reg_for_notify_ev (C++ member), 260 (C++ member), 262 esp_ble_gattc_cb_param_t::gattc_get_adders_pl_ibslte__egvatt_tpca_rcabm_:p:asrtaamt_uts::gattc_search_cmpl_evt_p (C++ member), 260 (C++ class), 262 esp_ble_gattc_cb_param_t::gattc_notify_eesvpt__bplaer_agmattc_cb_param_t::gattc_search_cmpl_evt_p (C++ class), 261 (C++ member), 262 esp_ble_gattc_cb_param_t::gattc_notify_eesvpt__bplaer_agma:t:tcco_ncnb__ipdaram_t::gattc_search_cmpl_evt_p (C++ member), 261 (C++ member), 262 esp_ble_gattc_cb_param_t::gattc_notify_eesvpt__bplaer_agma:t:thca_ncdbl_eparam_t::gattc_search_cmpl_evt_p (C++ member), 261 (C++ member), 262 esp_ble_gattc_cb_param_t::gattc_notify_eesvpt__bplaer_agma:t:tics__cnbo_tpiafryam_t::gattc_search_res_evt_pa (C++ member), 261 (C++ class), 262 esp_ble_gattc_cb_param_t::gattc_notify_eesvpt__bplaer_agma:t:trce_mcobt_ep_abrdaam_t::gattc_search_res_evt_pa (C++ member), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_notify_eesvpt__bplaer_agma:t:tvca_lcube_param_t::gattc_search_res_evt_pa (C++ member), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_notify_eesvpt__bplaer_agma:t:tvca_lcube__plaernam_t::gattc_search_res_evt_pa (C++ member), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_open_evets_pp_abrlaem_gattc_cb_param_t::gattc_search_res_evt_pa (C++ class), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_open_evets_pp_abrlaem_:g:actotncn__cibd_param_t::gattc_search_res_evt_pa (C++ member), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_open_evets_pp_abrlaem_:g:amtttuc_cb_param_t::gattc_set_assoc_addr_cm (C++ member), 261 (C++ class), 263 esp_ble_gattc_cb_param_t::gattc_open_evets_pp_abrlaem_:g:artetmco_tceb__bpdaaram_t::gattc_set_assoc_addr_cm (C++ member), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_open_evets_pp_abrlaem_:g:astttact_ucsb_param_t::gattc_srvc_chg_evt_para (C++ member), 261 (C++ class), 263 esp_ble_gattc_cb_param_t::gattc_queue_feuslpl__belvet__gpaatrtacm_cb_param_t::gattc_srvc_chg_evt_para (C++ class), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_queue_feuslpl__belvet__gpaatrtacm_:c:bc_opnanr_aimd_t::gattc_unreg_for_notify_ (C++ member), 261 (C++ class), 263 esp_ble_gattc_cb_param_t::gattc_queue_feuslpl__belvet__gpaatrtacm_:c:bi_sp_afrualml_t::gattc_unreg_for_notify_ (C++ member), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_queue_feuslpl__belvet__gpaatrtacm_:c:bs_tpaatruasm_t::gattc_unreg_for_notify_ (C++ member), 261 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_read_cheasrp__ebvlte__pgaartatmc_cb_param_t::gattc_write_evt_param (C++ class), 261 (C++ class), 263 esp_ble_gattc_cb_param_t::gattc_read_cheasrp__ebvlte__pgaartatmc:_:ccbo_npna_riadm_t::gattc_write_evt_param:: (C++ member), 262 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_read_cheasrp__ebvlte__pgaartatmc:_:chba_npdalream_t::gattc_write_evt_param:: (C++ member), 262 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_read_cheasrp__ebvlte__pgaartatmc:_:csbt_aptaursam_t::gattc_write_evt_param:: (C++ member), 262 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_read_cheasrp__ebvlte__pgaartatmc:_:cvba_lpuaeram_t::gattc_write_evt_param:: (C++ member), 262 (C++ member), 263 esp_ble_gattc_cb_param_t::gattc_read_cheasrp__ebvlte__pgaartatmc:_:cvba_lpuaer_alme_nt::get_addr_list (C++ member), 262 (C++ member), 259 esp_ble_gattc_cb_param_t::gattc_reg_evte_sppa_rbalme_gattc_cb_param_t::notify (C++ Espressif Systems 2079 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index member), 258 (C++ function), 257 esp_ble_gattc_cb_param_t::open (C++ esp_ble_gattc_search_service (C++ func- member), 258 tion), 251 esp_ble_gattc_cb_param_t::queue_full esp_ble_gattc_send_mtu_req (C++ function), (C++ member), 259 251 esp_ble_gattc_cb_param_t::read (C++ esp_ble_gattc_unregister_for_notify member), 258 (C++ function), 257 esp_ble_gattc_cb_param_t::reg (C++ esp_ble_gattc_write_char (C++ function), member), 258 255 esp_ble_gattc_cb_param_t::reg_for_notifeysp_ble_gattc_write_char_descr (C++ (C++ member), 258 function), 255 esp_ble_gattc_cb_param_t::search_cmpl esp_ble_gatts_add_char (C++ function), 239 (C++ member), 258 esp_ble_gatts_add_char_descr (C++ func- esp_ble_gattc_cb_param_t::search_res tion), 239 (C++ member), 258 esp_ble_gatts_add_included_service esp_ble_gattc_cb_param_t::set_assoc_cmp (C++ function), 239 (C++ member), 258 esp_ble_gatts_app_register (C++ function), esp_ble_gattc_cb_param_t::srvc_chg 238 (C++ member), 258 esp_ble_gatts_app_unregister (C++ func- esp_ble_gattc_cb_param_t::unreg_for_notify tion), 238 (C++ member), 258 esp_ble_gatts_cb_param_t (C++ union), 241 esp_ble_gattc_cb_param_t::write (C++ esp_ble_gatts_cb_param_t::add_attr_tab member), 258 (C++ member), 242 esp_ble_gattc_close (C++ function), 251 esp_ble_gatts_cb_param_t::add_char esp_ble_gattc_execute_write (C++ func- (C++ member), 242 tion), 256 esp_ble_gatts_cb_param_t::add_char_descr esp_ble_gattc_get_all_char (C++ function), (C++ member), 242 252 esp_ble_gatts_cb_param_t::add_incl_srvc esp_ble_gattc_get_all_descr (C++ func- (C++ member), 242 tion), 252 esp_ble_gatts_cb_param_t::cancel_open esp_ble_gattc_get_attr_count (C++ func- (C++ member), 242 tion), 254 esp_ble_gatts_cb_param_t::close (C++ esp_ble_gattc_get_char_by_uuid (C++ member), 242 function), 252 esp_ble_gatts_cb_param_t::conf (C++ esp_ble_gattc_get_db (C++ function), 254 member), 242 esp_ble_gattc_get_descr_by_char_handle esp_ble_gatts_cb_param_t::congest (C++ function), 253 (C++ member), 242 esp_ble_gattc_get_descr_by_uuid (C++ esp_ble_gatts_cb_param_t::connect function), 253 (C++ member), 242 esp_ble_gattc_get_include_service esp_ble_gatts_cb_param_t::create (C++ (C++ function), 253 member), 242 esp_ble_gattc_get_service (C++ function), esp_ble_gatts_cb_param_t::del (C++ 251 member), 242 esp_ble_gattc_open (C++ function), 251 esp_ble_gatts_cb_param_t::disconnect esp_ble_gattc_prepare_write (C++ func- (C++ member), 242 tion), 256 esp_ble_gatts_cb_param_t::exec_write esp_ble_gattc_prepare_write_char_descr (C++ member), 242 (C++ function), 256 esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_ esp_ble_gattc_read_by_type (C++ function), (C++ class), 243 255 esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_ esp_ble_gattc_read_char (C++ function), 254 (C++ member), 243 esp_ble_gattc_read_char_descr (C++ func- esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_ tion), 255 (C++ member), 243 esp_ble_gattc_read_multiple (C++ func- esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_ tion), 255 (C++ member), 243 esp_ble_gattc_register_callback (C++ esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_ function), 250 (C++ member), 243 esp_ble_gattc_register_for_notify esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_ Espressif Systems 2080 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 243 (C++ class), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pd_ebslcer__geavttt_sp_acrba_mparam_t::gatts_connect_evt_param (C++ class), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pd_ebslcer__geavttt_sp_acrba_mp:a:raatmt_rt_:h:agnadtltes_connect_evt_param (C++ member), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pd_ebslcer__geavttt_sp_acrba_mp:a:rdaems_ctr:_:uguaitdts_connect_evt_param (C++ member), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pd_ebslcer__geavttt_sp_acrba_mp:a:rsaemr_vti:c:eg_ahtatnsd_lceonnect_evt_param (C++ member), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pd_ebslcer__geavttt_sp_acrba_mp:a:rsatma_ttu:s:gatts_create_evt_param (C++ member), 243 (C++ class), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pe_vbtl_ep_agraatmts_cb_param_t::gatts_create_evt_param: (C++ class), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pe_vbtl_ep_agraatmt:s:_actbt_rp_ahraanmd_lte::gatts_create_evt_param: (C++ member), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pe_vbtl_ep_agraatmt:s:_cchba_rp_auruaimd_t::gatts_create_evt_param: (C++ member), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pe_vbtl_ep_agraatmt:s:_scebr_vpiacrea_mh_atn:d:lgeatts_delete_evt_param (C++ member), 243 (C++ class), 245 esp_ble_gatts_cb_param_t::gatts_add_chaers_pe_vbtl_ep_agraatmt:s:_sctba_tpuasram_t::gatts_delete_evt_param: (C++ member), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_incels_ps_rbvlce__egvatt_tpsa_rcabm_param_t::gatts_delete_evt_param: (C++ class), 243 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_incels_ps_rbvlce__egvatt_tpsa_rcabm_:p:aartatmr__th:a:ngdaltets_disconnect_evt_pa (C++ member), 244 (C++ class), 245 esp_ble_gatts_cb_param_t::gatts_add_incels_ps_rbvlce__egvatt_tpsa_rcabm_:p:asrearmv_itc:e:_ghaatntdsl_edisconnect_evt_pa (C++ member), 244 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_add_incels_ps_rbvlce__egvatt_tpsa_rcabm_:p:asrtaamt_uts::gatts_disconnect_evt_pa (C++ member), 244 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_cancel_eosppe_nb_leev_tg_aptatrsa_mcb_param_t::gatts_disconnect_evt_pa (C++ class), 244 (C++ member), 245 esp_ble_gatts_cb_param_t::gatts_cancel_eosppe_nb_leev_tg_aptatrsa_mc:b:_sptaartaums_t::gatts_exec_write_evt_pa (C++ member), 244 (C++ class), 245 esp_ble_gatts_cb_param_t::gatts_close_eevstp__pbalrea_mgatts_cb_param_t::gatts_exec_write_evt_pa (C++ class), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_close_eevstp__pbalrea_mg:a:tctosn_nc_bi_dparam_t::gatts_exec_write_evt_pa (C++ member), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_close_eevstp__pbalrea_mg:a:tsttsa_tcubs_param_t::gatts_exec_write_evt_pa (C++ member), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_conf_evets_pp_abrlaem_gatts_cb_param_t::gatts_exec_write_evt_pa (C++ class), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_conf_evets_pp_abrlaem_:g:actotnsn__cibd_param_t::gatts_mtu_evt_param (C++ member), 244 (C++ class), 246 esp_ble_gatts_cb_param_t::gatts_conf_evets_pp_abrlaem_:g:ahtatnsd_lceb_param_t::gatts_mtu_evt_param::co (C++ member), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_conf_evets_pp_abrlaem_:g:altetns_cb_param_t::gatts_mtu_evt_param::mt (C++ member), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_conf_evets_pp_abrlaem_:g:astttast_ucsb_param_t::gatts_open_evt_param (C++ member), 244 (C++ class), 246 esp_ble_gatts_cb_param_t::gatts_conf_evets_pp_abrlaem_:g:avtatlsu_ecb_param_t::gatts_open_evt_param::s (C++ member), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_congeste_sepv_tb_lpea_rgaamtts_cb_param_t::gatts_read_evt_param (C++ class), 244 (C++ class), 246 esp_ble_gatts_cb_param_t::gatts_congeste_sepv_tb_lpea_rgaamt:t:sc_ocnbg_epsatreadm_t::gatts_read_evt_param::b (C++ member), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_congeste_sepv_tb_lpea_rgaamt:t:sc_ocnbn__piadram_t::gatts_read_evt_param::c (C++ member), 244 (C++ member), 246 esp_ble_gatts_cb_param_t::gatts_connecte_sepv_tb_lpea_rgaamtts_cb_param_t::gatts_read_evt_param::h Espressif Systems 2081 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 246 (C++ member), 248 esp_ble_gatts_cb_param_t::gatts_read_evets_pp_abrlaem_:g:aitst_sl_ocnbg_param_t::gatts_write_evt_param:: (C++ member), 246 (C++ member), 248 esp_ble_gatts_cb_param_t::gatts_read_evets_pp_abrlaem_:g:antetesd__crbs_pparam_t::gatts_write_evt_param:: (C++ member), 246 (C++ member), 248 esp_ble_gatts_cb_param_t::gatts_read_evets_pp_abrlaem_:g:aotftfss_ectb_param_t::gatts_write_evt_param:: (C++ member), 246 (C++ member), 248 esp_ble_gatts_cb_param_t::gatts_read_evets_pp_abrlaem_:g:attrtasn_sc_bi_dparam_t::mtu (C++ (C++ member), 246 member), 242 esp_ble_gatts_cb_param_t::gatts_reg_evte_sppa_rbalme_gatts_cb_param_t::open (C++ (C++ class), 247 member), 242 esp_ble_gatts_cb_param_t::gatts_reg_evte_sppa_rbalme:_:gaaptpt_si_dcb_param_t::read (C++ (C++ member), 247 member), 242 esp_ble_gatts_cb_param_t::gatts_reg_evte_sppa_rbalme:_:gsattattsu_scb_param_t::reg (C++ (C++ member), 247 member), 242 esp_ble_gatts_cb_param_t::gatts_rsp_evte_sppa_rbalme_gatts_cb_param_t::rsp (C++ (C++ class), 247 member), 242 esp_ble_gatts_cb_param_t::gatts_rsp_evte_sppa_rbalme:_:ghaatntdsl_ecb_param_t::service_change (C++ member), 247 (C++ member), 243 esp_ble_gatts_cb_param_t::gatts_rsp_evte_sppa_rbalme:_:gsattattsu_scb_param_t::set_attr_val (C++ member), 247 (C++ member), 242 esp_ble_gatts_cb_param_t::gatts_send_seersvpi_cbel_ec_hgaantgtes__ecvbt__ppaarraamm_t::start (C++ (C++ class), 247 member), 242 esp_ble_gatts_cb_param_t::gatts_send_seersvpi_cbel_ec_hgaantgtes__ecvbt__ppaarraamm_:t::s:tsattoups (C++ (C++ member), 247 member), 242 esp_ble_gatts_cb_param_t::gatts_set_atters_pv_abll_ee_vgta_tptasr_acmb_param_t::write (C++ (C++ class), 247 member), 242 esp_ble_gatts_cb_param_t::gatts_set_atters_pv_abll_ee_vgta_tptasr_acml:o:saet(tCr+_+hafunndcltioen), 241 (C++ member), 247 esp_ble_gatts_create_attr_tab (C++ func- esp_ble_gatts_cb_param_t::gatts_set_attr_val_etivont)_, p23a9ram::srvc_handle (C++ member), 247 esp_ble_gatts_create_service (C++ func- esp_ble_gatts_cb_param_t::gatts_set_attr_val_etivont)_, p23a8ram::status (C++ member), 247 esp_ble_gatts_delete_service (C++ func- esp_ble_gatts_cb_param_t::gatts_start_evt_paratimon), 240 (C++ class), 247 esp_ble_gatts_get_attr_value (C++ func- esp_ble_gatts_cb_param_t::gatts_start_evt_paratimon:):, s24e1rvice_handle (C++ member), 247 esp_ble_gatts_open (C++ function), 241 esp_ble_gatts_cb_param_t::gatts_start_eevstp__pbalrea_mg:a:tsttsa_truesgister_callback (C++ (C++ member), 247 function), 238 esp_ble_gatts_cb_param_t::gatts_stop_evets_pp_abrlaem_gatts_send_indicate (C++ func- (C++ class), 247 tion), 240 esp_ble_gatts_cb_param_t::gatts_stop_evets_pp_abrlaem_:g:astetrsv_isceen_dh_arnedslpeonse (C++ func- (C++ member), 248 tion), 240 esp_ble_gatts_cb_param_t::gatts_stop_evets_pp_abrlaem_:g:astttast_ussend_service_change_indication (C++ member), 248 (C++ function), 241 esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mgatts_set_attr_value (C++ func- (C++ class), 248 tion), 241 esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mg:a:tbtdsa_start_service (C++ func- (C++ member), 248 tion), 240 esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mg:a:tctosn_ns_tiodp_service (C++ function), (C++ member), 248 240 esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mg:e:th_abnodnlde_device_list (C++ func- (C++ member), 248 tion), 188 esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mg:e:ti_sb_opnrde_pdevice_num (C++ func- (C++ member), 248 tion), 188 esp_ble_gatts_cb_param_t::gatts_write_eevstp__pbalrea_mg:e:tl_ecnurrent_conn_params (C++ (C++ member), 248 function), 189 esp_ble_gatts_cb_param_t::gatts_write_eEvStP__pBaLrEa_mI:D:_nKeEeYd__MrAsSpK (C macro), 179 Espressif Systems 2082 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_io_cap_t (C++ type), 220 macro), 384 ESP_BLE_IS_VALID_PARAM (C macro), 179 ESP_BLE_MESH_ACTUATOR_BLOCKED_WARNING esp_ble_key_mask_t (C++ type), 180 (C macro), 384 esp_ble_key_t (C++ class), 211 ESP_BLE_MESH_ADDR_ALL_NODES (C macro), esp_ble_key_t::bd_addr (C++ member), 211 315 esp_ble_key_t::key_type (C++ member), 211 ESP_BLE_MESH_ADDR_FRIENDS (C macro), 315 esp_ble_key_t::p_key_value (C++ member), ESP_BLE_MESH_ADDR_IS_GROUP (C macro), 316 211 ESP_BLE_MESH_ADDR_IS_RFU (C macro), 316 esp_ble_key_type_t (C++ type), 220 ESP_BLE_MESH_ADDR_IS_UNICAST (C macro), esp_ble_key_value_t (C++ union), 193 316 esp_ble_key_value_t::lcsrk_key (C++ ESP_BLE_MESH_ADDR_IS_VIRTUAL (C macro), member), 194 316 esp_ble_key_value_t::lenc_key (C++ ESP_BLE_MESH_ADDR_PROXIES (C macro), 315 member), 194 ESP_BLE_MESH_ADDR_RELAYS (C macro), 315 esp_ble_key_value_t::pcsrk_key (C++ ESP_BLE_MESH_ADDR_TYPE_PUBLIC (C macro), member), 194 317 esp_ble_key_value_t::penc_key (C++ ESP_BLE_MESH_ADDR_TYPE_RANDOM (C macro), member), 194 317 esp_ble_key_value_t::pid_key (C++ mem- ESP_BLE_MESH_ADDR_TYPE_RPA_PUBLIC (C ber), 194 macro), 317 esp_ble_lcsrk_keys (C++ class), 210 ESP_BLE_MESH_ADDR_TYPE_RPA_RANDOM (C esp_ble_lcsrk_keys::counter (C++ mem- macro), 317 ber), 210 esp_ble_mesh_addr_type_t (C++ type), 329 esp_ble_lcsrk_keys::csrk (C++ member), ESP_BLE_MESH_ADDR_UNASSIGNED (C macro), 210 315 esp_ble_lcsrk_keys::div (C++ member), 210 ESP_BLE_MESH_BATTERY_LOW_ERROR (C esp_ble_lcsrk_keys::sec_level (C++ macro), 384 member), 210 ESP_BLE_MESH_BATTERY_LOW_WARNING (C ESP_BLE_LEGACY_ADV_TYPE_DIRECT_IND (C macro), 384 macro), 220 esp_ble_mesh_bd_addr_t (C++ type), 329 ESP_BLE_LEGACY_ADV_TYPE_IND (C macro), ESP_BLE_MESH_BEACON_DISABLED (C macro), 220 315 ESP_BLE_LEGACY_ADV_TYPE_NONCON_IND (C ESP_BLE_MESH_BEACON_ENABLED (C macro), macro), 220 315 ESP_BLE_LEGACY_ADV_TYPE_SCAN_IND (C ESP_BLE_MESH_BEEP (C++ enumerator), 331 macro), 220 ESP_BLE_MESH_BLINK (C++ enumerator), 331 ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADVe_sIpN_Dble_mesh_cb_t (C++ type), 329 (C macro), 220 esp_ble_mesh_cb_type_t (C++ enum), 330 ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADVe_sSpC_AbNl_eI_NmDesh_cfg_app_key_add_t (C++ (C macro), 220 class), 362 esp_ble_lenc_keys_t (C++ class), 210 esp_ble_mesh_cfg_app_key_add_t::app_idx esp_ble_lenc_keys_t::div (C++ member), (C++ member), 362 210 esp_ble_mesh_cfg_app_key_add_t::app_key esp_ble_lenc_keys_t::key_size (C++ (C++ member), 362 member), 210 esp_ble_mesh_cfg_app_key_add_t::net_idx esp_ble_lenc_keys_t::ltk (C++ member), (C++ member), 362 210 esp_ble_mesh_cfg_app_key_delete_t esp_ble_lenc_keys_t::sec_level (C++ (C++ class), 366 member), 210 esp_ble_mesh_cfg_app_key_delete_t::app_idx ESP_BLE_LINK_KEY_MASK (C macro), 179 (C++ member), 366 esp_ble_local_id_keys_t (C++ class), 211 esp_ble_mesh_cfg_app_key_delete_t::net_idx esp_ble_local_id_keys_t::dhk (C++ mem- (C++ member), 366 ber), 212 esp_ble_mesh_cfg_app_key_get_t (C++ esp_ble_local_id_keys_t::ir (C++ mem- class), 360 ber), 212 esp_ble_mesh_cfg_app_key_get_t::net_idx esp_ble_local_id_keys_t::irk (C++ mem- (C++ member), 360 ber), 212 esp_ble_mesh_cfg_app_key_list_cb_t ESP_BLE_MESH_ACTUATOR_BLOCKED_ERROR (C (C++ class), 372 Espressif Systems 2083 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_cfg_app_key_list_cb_t::appe_sipd_xble_mesh_cfg_client_common_cb_param_t::heartb (C++ member), 372 (C++ member), 357 esp_ble_mesh_cfg_app_key_list_cb_t::nete_sipd_xble_mesh_cfg_client_common_cb_param_t::heartb (C++ member), 372 (C++ member), 357 esp_ble_mesh_cfg_app_key_list_cb_t::staetsups_ble_mesh_cfg_client_common_cb_param_t::kr_pha (C++ member), 372 (C++ member), 358 esp_ble_mesh_cfg_app_key_status_cb_t esp_ble_mesh_cfg_client_common_cb_param_t::lpn_ti (C++ class), 370 (C++ member), 358 esp_ble_mesh_cfg_app_key_status_cb_t::aepspp__ibdlxe_mesh_cfg_client_common_cb_param_t::model_ (C++ member), 370 (C++ member), 357 esp_ble_mesh_cfg_app_key_status_cb_t::neestp__ibdlxe_mesh_cfg_client_common_cb_param_t::model_ (C++ member), 370 (C++ member), 357 esp_ble_mesh_cfg_app_key_status_cb_t::setsapt_ubsle_mesh_cfg_client_common_cb_param_t::model_ (C++ member), 370 (C++ member), 357 esp_ble_mesh_cfg_app_key_update_t esp_ble_mesh_cfg_client_common_cb_param_t::model_ (C++ class), 366 (C++ member), 357 esp_ble_mesh_cfg_app_key_update_t::app_eisdpx_ble_mesh_cfg_client_common_cb_param_t::model_ (C++ member), 366 (C++ member), 357 esp_ble_mesh_cfg_app_key_update_t::app_eksepy_ble_mesh_cfg_client_common_cb_param_t::net_tr (C++ member), 366 (C++ member), 357 esp_ble_mesh_cfg_app_key_update_t::net_eisdpx_ble_mesh_cfg_client_common_cb_param_t::netkey (C++ member), 366 (C++ member), 357 esp_ble_mesh_cfg_beacon_set_t (C++ esp_ble_mesh_cfg_client_common_cb_param_t::netkey class), 361 (C++ member), 357 esp_ble_mesh_cfg_beacon_set_t::beacon esp_ble_mesh_cfg_client_common_cb_param_t::node_i (C++ member), 361 (C++ member), 357 esp_ble_mesh_cfg_beacon_status_cb_t esp_ble_mesh_cfg_client_common_cb_param_t::relay_ (C++ class), 368 (C++ member), 357 esp_ble_mesh_cfg_beacon_status_cb_t::beEaScPo_nBLE_MESH_CFG_CLIENT_EVT_MAX (C++ (C++ member), 368 enumerator), 377 esp_ble_mesh_cfg_client_cb_event_t ESP_BLE_MESH_CFG_CLIENT_GET_STATE_EVT (C++ enum), 377 (C++ enumerator), 377 esp_ble_mesh_cfg_client_cb_param_t esp_ble_mesh_cfg_client_get_state_t (C++ class), 373 (C++ union), 355 esp_ble_mesh_cfg_client_cb_param_t::erreosrp__cboldee_mesh_cfg_client_get_state_t::app_key_get (C++ member), 373 (C++ member), 355 esp_ble_mesh_cfg_client_cb_param_t::pareasmps_ble_mesh_cfg_client_get_state_t::comp_data_ge (C++ member), 373 (C++ member), 355 esp_ble_mesh_cfg_client_cb_param_t::staetsups__bclbe_mesh_cfg_client_get_state_t::kr_phase_get (C++ member), 373 (C++ member), 355 esp_ble_mesh_cfg_client_cb_t (C++ type), esp_ble_mesh_cfg_client_get_state_t::lpn_pollto_g 377 (C++ member), 355 esp_ble_mesh_cfg_client_common_cb_parame_stp_ble_mesh_cfg_client_get_state_t::model_pub_ge (C++ union), 357 (C++ member), 355 esp_ble_mesh_cfg_client_common_cb_parame_stp:_:balpep_kmeeys_hl_icsftg_client_get_state_t::node_identit (C++ member), 357 (C++ member), 355 esp_ble_mesh_cfg_client_common_cb_parame_stp:_:balpep_kmeeys_hs_tcaftgu_sclient_get_state_t::sig_model_ap (C++ member), 357 (C++ member), 355 esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bbleea_cmoens_hs_tcaftgu_sclient_get_state_t::sig_model_su (C++ member), 357 (C++ member), 355 esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bcloem_pm_edsaht_ac_fsgt_actluisent_get_state_t::vnd_model_ap (C++ member), 357 (C++ member), 355 esp_ble_mesh_cfg_client_common_cb_parame_stp:_:bdleef_amuelsth__tctflg__sctlaiteunst_get_state_t::vnd_model_su (C++ member), 357 (C++ member), 355 esp_ble_mesh_cfg_client_common_cb_paramE_StP:_:BfLrEi_eMnEdS_Hs_tCaFtGu_sCLIENT_PUBLISH_EVT (C++ member), 357 (C++ enumerator), 377 esp_ble_mesh_cfg_client_common_cb_paramE_StP:_:BgLaEt_tM_EpSrHo_xCyF_Gs_tCaLtIuEsNT_SET_STATE_EVT (C++ member), 357 (C++ enumerator), 377 Espressif Systems 2084 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_cfg_client_set_state_t esp_ble_mesh_cfg_comp_data_status_cb_t (C++ union), 355 (C++ class), 368 esp_ble_mesh_cfg_client_set_state_t::apeps_pk_ebyl_ea_dmdesh_cfg_comp_data_status_cb_t::compositi (C++ member), 356 (C++ member), 368 esp_ble_mesh_cfg_client_set_state_t::apeps_pk_ebyl_ed_emleesthe_cfg_comp_data_status_cb_t::page (C++ member), 356 (C++ member), 368 esp_ble_mesh_cfg_client_set_state_t::apeps_pk_ebyl_eu_pmdeasthe_cfg_composition_data_get_t (C++ member), 356 (C++ class), 360 esp_ble_mesh_cfg_client_set_state_t::beeascpo_nb_lsee_tmesh_cfg_composition_data_get_t::page (C++ member), 355 (C++ member), 360 esp_ble_mesh_cfg_client_set_state_t::deefsapu_lbtl_et_tmle_sshe_tcfg_default_ttl_set_t (C++ member), 355 (C++ class), 361 esp_ble_mesh_cfg_client_set_state_t::freisepn_db_lsee_tmesh_cfg_default_ttl_set_t::ttl (C++ member), 356 (C++ member), 362 esp_ble_mesh_cfg_client_set_state_t::gaetstp__pbrloex_ym_esseht_cfg_default_ttl_status_cb_t (C++ member), 356 (C++ class), 368 esp_ble_mesh_cfg_client_set_state_t::heeasrpt_bbelaet__mpeusbh__sceftg_default_ttl_status_cb_t::default (C++ member), 356 (C++ member), 368 esp_ble_mesh_cfg_client_set_state_t::heeasrpt_bbelaet__mseusbh__sceftg_friend_set_t (C++ (C++ member), 356 class), 362 esp_ble_mesh_cfg_client_set_state_t::kre_spph_abslee__smeetsh_cfg_friend_set_t::friend_state (C++ member), 357 (C++ member), 362 esp_ble_mesh_cfg_client_set_state_t::moedsepl__balpep__mbeisnhd_cfg_friend_status_cb_t (C++ member), 356 (C++ class), 370 esp_ble_mesh_cfg_client_set_state_t::moedsepl__balpep__muensbhi_ncdfg_friend_status_cb_t::friend_state (C++ member), 356 (C++ member), 370 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bplueb__mseesth_cfg_gatt_proxy_set_t (C++ member), 356 (C++ class), 362 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bplueb__mveas_hs_ectfg_gatt_proxy_set_t::gatt_proxy (C++ member), 356 (C++ member), 362 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bslueb__maedsdh_cfg_gatt_proxy_status_cb_t (C++ member), 356 (C++ class), 368 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bslueb__mdeeslhe_tcefg_gatt_proxy_status_cb_t::gatt_pro (C++ member), 356 (C++ member), 368 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bslueb__mdeeslhe_tcef_ga_lhlb_pub_status_cb_t (C++ member), 356 (C++ class), 370 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bslueb__moevsehr_wcrfigt_ehb_pub_status_cb_t::count (C++ member), 356 (C++ member), 370 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bslueb__mveas_ha_dcdfg_hb_pub_status_cb_t::dst (C++ member), 356 (C++ member), 370 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bslueb__mveas_hd_eclfegt_ehb_pub_status_cb_t::features (C++ member), 356 (C++ member), 371 esp_ble_mesh_cfg_client_set_state_t::moedsepl__bslueb__mveas_ho_vcefrgw_rhibt_epub_status_cb_t::net_idx (C++ member), 356 (C++ member), 371 esp_ble_mesh_cfg_client_set_state_t::neets_pk_ebyl_ea_dmdesh_cfg_hb_pub_status_cb_t::period (C++ member), 356 (C++ member), 370 esp_ble_mesh_cfg_client_set_state_t::neets_pk_ebyl_ed_emleesthe_cfg_hb_pub_status_cb_t::status (C++ member), 356 (C++ member), 370 esp_ble_mesh_cfg_client_set_state_t::neets_pk_ebyl_eu_pmdeasthe_cfg_hb_pub_status_cb_t::ttl (C++ member), 356 (C++ member), 370 esp_ble_mesh_cfg_client_set_state_t::neets_pt_rbalnes_mmiets_hs_ectfg_hb_sub_status_cb_t (C++ member), 357 (C++ class), 371 esp_ble_mesh_cfg_client_set_state_t::noedsep__ibdleen_tmietsyh__sceftg_hb_sub_status_cb_t::count (C++ member), 356 (C++ member), 371 esp_ble_mesh_cfg_client_set_state_t::reelsapy__bsleet_mesh_cfg_hb_sub_status_cb_t::dst (C++ member), 356 (C++ member), 371 ESP_BLE_MESH_CFG_CLIENT_TIMEOUT_EVT esp_ble_mesh_cfg_hb_sub_status_cb_t::max_hops (C++ enumerator), 377 (C++ member), 371 Espressif Systems 2085 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_cfg_hb_sub_status_cb_t::miens_ph_obplse_mesh_cfg_mod_app_status_cb_t (C++ member), 371 (C++ class), 370 esp_ble_mesh_cfg_hb_sub_status_cb_t::peersipo_dble_mesh_cfg_mod_app_status_cb_t::app_idx (C++ member), 371 (C++ member), 370 esp_ble_mesh_cfg_hb_sub_status_cb_t::srecsp_ble_mesh_cfg_mod_app_status_cb_t::company_id (C++ member), 371 (C++ member), 370 esp_ble_mesh_cfg_hb_sub_status_cb_t::steastpu_sble_mesh_cfg_mod_app_status_cb_t::element_add (C++ member), 371 (C++ member), 370 esp_ble_mesh_cfg_heartbeat_pub_set_t esp_ble_mesh_cfg_mod_app_status_cb_t::model_id (C++ class), 367 (C++ member), 370 esp_ble_mesh_cfg_heartbeat_pub_set_t::ceosupn_tble_mesh_cfg_mod_app_status_cb_t::status (C++ member), 367 (C++ member), 370 esp_ble_mesh_cfg_heartbeat_pub_set_t::desstp_ble_mesh_cfg_model_app_bind_t (C++ member), 367 (C++ class), 362 esp_ble_mesh_cfg_heartbeat_pub_set_t::feesapt_ubrlee_mesh_cfg_model_app_bind_t::company_id (C++ member), 367 (C++ member), 363 esp_ble_mesh_cfg_heartbeat_pub_set_t::neestp__ibdlxe_mesh_cfg_model_app_bind_t::element_addr (C++ member), 367 (C++ member), 363 esp_ble_mesh_cfg_heartbeat_pub_set_t::peesrpi_obdle_mesh_cfg_model_app_bind_t::model_app_idx (C++ member), 367 (C++ member), 363 esp_ble_mesh_cfg_heartbeat_pub_set_t::tetslp_ble_mesh_cfg_model_app_bind_t::model_id (C++ member), 367 (C++ member), 363 esp_ble_mesh_cfg_heartbeat_sub_set_t esp_ble_mesh_cfg_model_app_list_cb_t (C++ class), 367 (C++ class), 372 esp_ble_mesh_cfg_heartbeat_sub_set_t::desstp_ble_mesh_cfg_model_app_list_cb_t::app_idx (C++ member), 368 (C++ member), 372 esp_ble_mesh_cfg_heartbeat_sub_set_t::peesrpi_obdle_mesh_cfg_model_app_list_cb_t::company_id (C++ member), 368 (C++ member), 372 esp_ble_mesh_cfg_heartbeat_sub_set_t::serscp_ble_mesh_cfg_model_app_list_cb_t::element_add (C++ member), 368 (C++ member), 372 esp_ble_mesh_cfg_kr_phase_get_t (C++ esp_ble_mesh_cfg_model_app_list_cb_t::model_id class), 361 (C++ member), 372 esp_ble_mesh_cfg_kr_phase_get_t::net_idexsp_ble_mesh_cfg_model_app_list_cb_t::status (C++ member), 361 (C++ member), 372 esp_ble_mesh_cfg_kr_phase_set_t (C++ esp_ble_mesh_cfg_model_app_unbind_t class), 367 (C++ class), 366 esp_ble_mesh_cfg_kr_phase_set_t::net_idexsp_ble_mesh_cfg_model_app_unbind_t::company_id (C++ member), 367 (C++ member), 367 esp_ble_mesh_cfg_kr_phase_set_t::transietsipo_nble_mesh_cfg_model_app_unbind_t::element_addr (C++ member), 367 (C++ member), 367 esp_ble_mesh_cfg_kr_phase_status_cb_t esp_ble_mesh_cfg_model_app_unbind_t::model_app_id (C++ class), 372 (C++ member), 367 esp_ble_mesh_cfg_kr_phase_status_cb_t::ensept__bildex_mesh_cfg_model_app_unbind_t::model_id (C++ member), 373 (C++ member), 367 esp_ble_mesh_cfg_kr_phase_status_cb_t::epshpa_sbele_mesh_cfg_model_pub_get_t (C++ (C++ member), 373 class), 360 esp_ble_mesh_cfg_kr_phase_status_cb_t::esstpa_tbulse_mesh_cfg_model_pub_get_t::company_id (C++ member), 373 (C++ member), 360 esp_ble_mesh_cfg_lpn_polltimeout_get_t esp_ble_mesh_cfg_model_pub_get_t::element_addr (C++ class), 361 (C++ member), 360 esp_ble_mesh_cfg_lpn_polltimeout_get_t:e:slpp_nb_laed_dmresh_cfg_model_pub_get_t::model_id (C++ member), 361 (C++ member), 360 esp_ble_mesh_cfg_lpn_pollto_status_cb_tesp_ble_mesh_cfg_model_pub_set_t (C++ (C++ class), 373 class), 363 esp_ble_mesh_cfg_lpn_pollto_status_cb_te:s:pl_pbnl_ea_dmdersh_cfg_model_pub_set_t::company_id (C++ member), 373 (C++ member), 363 esp_ble_mesh_cfg_lpn_pollto_status_cb_te:s:pp_obllle__tmiemseho_uctfg_model_pub_set_t::cred_flag (C++ member), 373 (C++ member), 363 Espressif Systems 2086 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_cfg_model_pub_set_t::elemeenstp__abdlder_mesh_cfg_model_sub_add_t::company_id (C++ member), 363 (C++ member), 363 esp_ble_mesh_cfg_model_pub_set_t::modele_sipd_ble_mesh_cfg_model_sub_add_t::element_addr (C++ member), 363 (C++ member), 363 esp_ble_mesh_cfg_model_pub_set_t::publiesshp__abdlder_mesh_cfg_model_sub_add_t::model_id (C++ member), 363 (C++ member), 363 esp_ble_mesh_cfg_model_pub_set_t::publiesshp__abplpe__imdexsh_cfg_model_sub_add_t::sub_addr (C++ member), 363 (C++ member), 363 esp_ble_mesh_cfg_model_pub_set_t::publiesshp__pbelrei_omdesh_cfg_model_sub_delete_all_t (C++ member), 363 (C++ class), 365 esp_ble_mesh_cfg_model_pub_set_t::publiesshp__rbelter_amnessmhi_tcfg_model_sub_delete_all_t::company_ (C++ member), 363 (C++ member), 365 esp_ble_mesh_cfg_model_pub_set_t::publiesshp__tbtlle_mesh_cfg_model_sub_delete_all_t::element_ (C++ member), 363 (C++ member), 365 esp_ble_mesh_cfg_model_pub_status_cb_t esp_ble_mesh_cfg_model_sub_delete_all_t::model_id (C++ class), 368 (C++ member), 365 esp_ble_mesh_cfg_model_pub_status_cb_t:e:sapp_pb_lied_xmesh_cfg_model_sub_delete_t (C++ member), 369 (C++ class), 363 esp_ble_mesh_cfg_model_pub_status_cb_t:e:scpo_mbplaen_ym_eisdh_cfg_model_sub_delete_t::company_id (C++ member), 369 (C++ member), 364 esp_ble_mesh_cfg_model_pub_status_cb_t:e:scpr_ebdl_ef_lmaegsh_cfg_model_sub_delete_t::element_addr (C++ member), 369 (C++ member), 364 esp_ble_mesh_cfg_model_pub_status_cb_t:e:sepl_ebmleen_tm_easdhd_rcfg_model_sub_delete_t::model_id (C++ member), 369 (C++ member), 364 esp_ble_mesh_cfg_model_pub_status_cb_t:e:smpo_dbelle__imdesh_cfg_model_sub_delete_t::sub_addr (C++ member), 369 (C++ member), 364 esp_ble_mesh_cfg_model_pub_status_cb_t:e:sppe_rbiloed_mesh_cfg_model_sub_list_cb_t (C++ member), 369 (C++ class), 371 esp_ble_mesh_cfg_model_pub_status_cb_t:e:sppu_bbllies_hm_easdhd_rcfg_model_sub_list_cb_t::company_id (C++ member), 369 (C++ member), 371 esp_ble_mesh_cfg_model_pub_status_cb_t:e:sspt_abtlues_mesh_cfg_model_sub_list_cb_t::element_add (C++ member), 369 (C++ member), 371 esp_ble_mesh_cfg_model_pub_status_cb_t:e:stpr_abnlsem_imtesh_cfg_model_sub_list_cb_t::model_id (C++ member), 369 (C++ member), 371 esp_ble_mesh_cfg_model_pub_status_cb_t:e:stpt_lble_mesh_cfg_model_sub_list_cb_t::status (C++ member), 369 (C++ member), 371 esp_ble_mesh_cfg_model_pub_va_set_t esp_ble_mesh_cfg_model_sub_list_cb_t::sub_addr (C++ class), 365 (C++ member), 371 esp_ble_mesh_cfg_model_pub_va_set_t::coemsppa_nbyl_ei_dmesh_cfg_model_sub_overwrite_t (C++ member), 365 (C++ class), 364 esp_ble_mesh_cfg_model_pub_va_set_t::creesdp__fbllaeg_mesh_cfg_model_sub_overwrite_t::company_i (C++ member), 365 (C++ member), 364 esp_ble_mesh_cfg_model_pub_va_set_t::eleesmpe_nbtl_ea_dmdersh_cfg_model_sub_overwrite_t::element_a (C++ member), 365 (C++ member), 364 esp_ble_mesh_cfg_model_pub_va_set_t::laebsepl__buluei_dmesh_cfg_model_sub_overwrite_t::model_id (C++ member), 365 (C++ member), 364 esp_ble_mesh_cfg_model_pub_va_set_t::moedsepl__bilde_mesh_cfg_model_sub_overwrite_t::sub_addr (C++ member), 365 (C++ member), 364 esp_ble_mesh_cfg_model_pub_va_set_t::puebslpi_sbhl_ea_pmpe_sihd_xcfg_model_sub_status_cb_t (C++ member), 365 (C++ class), 369 esp_ble_mesh_cfg_model_pub_va_set_t::puebslpi_sbhl_ep_emreisohd_cfg_model_sub_status_cb_t::company_i (C++ member), 365 (C++ member), 369 esp_ble_mesh_cfg_model_pub_va_set_t::puebslpi_sbhl_er_emtersahn_scmfigt_model_sub_status_cb_t::element_a (C++ member), 365 (C++ member), 369 esp_ble_mesh_cfg_model_pub_va_set_t::puebslpi_sbhl_et_tmlesh_cfg_model_sub_status_cb_t::model_id (C++ member), 365 (C++ member), 369 esp_ble_mesh_cfg_model_sub_add_t (C++ esp_ble_mesh_cfg_model_sub_status_cb_t::status class), 363 (C++ member), 369 Espressif Systems 2087 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_cfg_model_sub_status_cb_t:e:sspu_bb_laed_dmresh_cfg_net_trans_status_cb_t (C++ member), 369 (C++ class), 371 esp_ble_mesh_cfg_model_sub_va_add_t esp_ble_mesh_cfg_net_trans_status_cb_t::net_trans (C++ class), 364 (C++ member), 371 esp_ble_mesh_cfg_model_sub_va_add_t::coemsppa_nbyl_ei_dmesh_cfg_net_trans_status_cb_t::net_trans (C++ member), 364 (C++ member), 371 esp_ble_mesh_cfg_model_sub_va_add_t::eleesmpe_nbtl_ea_dmdersh_cfg_net_transmit_set_t (C++ member), 364 (C++ class), 367 esp_ble_mesh_cfg_model_sub_va_add_t::laebsepl__buluei_dmesh_cfg_net_transmit_set_t::net_transmit (C++ member), 364 (C++ member), 367 esp_ble_mesh_cfg_model_sub_va_add_t::moedsepl__bilde_mesh_cfg_node_id_status_cb_t (C++ member), 364 (C++ class), 372 esp_ble_mesh_cfg_model_sub_va_delete_t esp_ble_mesh_cfg_node_id_status_cb_t::identity (C++ class), 364 (C++ member), 372 esp_ble_mesh_cfg_model_sub_va_delete_t:e:scpo_mbplaen_ym_eisdh_cfg_node_id_status_cb_t::net_idx (C++ member), 364 (C++ member), 372 esp_ble_mesh_cfg_model_sub_va_delete_t:e:sepl_ebmleen_tm_easdhd_rcfg_node_id_status_cb_t::status (C++ member), 364 (C++ member), 372 esp_ble_mesh_cfg_model_sub_va_delete_t:e:slpa_bbelle__umueisdh_cfg_node_identity_get_t (C++ member), 364 (C++ class), 360 esp_ble_mesh_cfg_model_sub_va_delete_t:e:smpo_dbelle__imdesh_cfg_node_identity_get_t::net_idx (C++ member), 364 (C++ member), 361 esp_ble_mesh_cfg_model_sub_va_overwritee_stp_ble_mesh_cfg_node_identity_set_t (C++ class), 365 (C++ class), 366 esp_ble_mesh_cfg_model_sub_va_overwritee_stp:_:bcloem_pmaensyh__icdfg_node_identity_set_t::identity (C++ member), 365 (C++ member), 366 esp_ble_mesh_cfg_model_sub_va_overwritee_stp:_:bellee_mmeensth__acdfdgr_node_identity_set_t::net_idx (C++ member), 365 (C++ member), 366 esp_ble_mesh_cfg_model_sub_va_overwritee_stp:_:bllaeb_emle_suhu_icdfg_relay_set_t (C++ class), (C++ member), 365 362 esp_ble_mesh_cfg_model_sub_va_overwritee_stp:_:bmloed_emle_sihd_cfg_relay_set_t::relay (C++ member), 365 (C++ member), 362 esp_ble_mesh_cfg_net_key_add_t (C++ esp_ble_mesh_cfg_relay_set_t::relay_retransmit class), 362 (C++ member), 362 esp_ble_mesh_cfg_net_key_add_t::net_idxesp_ble_mesh_cfg_relay_status_cb_t (C++ member), 362 (C++ class), 368 esp_ble_mesh_cfg_net_key_add_t::net_keyesp_ble_mesh_cfg_relay_status_cb_t::relay (C++ member), 362 (C++ member), 368 esp_ble_mesh_cfg_net_key_delete_t esp_ble_mesh_cfg_relay_status_cb_t::retransmit (C++ class), 366 (C++ member), 368 esp_ble_mesh_cfg_net_key_delete_t::net_eisdpx_ble_mesh_cfg_server_cb_event_t (C++ member), 366 (C++ enum), 377 esp_ble_mesh_cfg_net_key_list_cb_t esp_ble_mesh_cfg_server_cb_param_t (C++ class), 372 (C++ class), 376 esp_ble_mesh_cfg_net_key_list_cb_t::nete_sipd_xble_mesh_cfg_server_cb_param_t::ctx (C++ member), 372 (C++ member), 376 esp_ble_mesh_cfg_net_key_status_cb_t esp_ble_mesh_cfg_server_cb_param_t::model (C++ class), 369 (C++ member), 376 esp_ble_mesh_cfg_net_key_status_cb_t::neestp__ibdlxe_mesh_cfg_server_cb_param_t::value (C++ member), 369 (C++ member), 376 esp_ble_mesh_cfg_net_key_status_cb_t::setsapt_ubsle_mesh_cfg_server_cb_t (C++ type), (C++ member), 369 377 esp_ble_mesh_cfg_net_key_update_t esp_ble_mesh_cfg_server_cb_value_t (C++ class), 366 (C++ union), 358 esp_ble_mesh_cfg_net_key_update_t::net_eisdpx_ble_mesh_cfg_server_cb_value_t::state_change (C++ member), 366 (C++ member), 358 esp_ble_mesh_cfg_net_key_update_t::net_EkSePy_BLE_MESH_CFG_SERVER_EVT_MAX (C++ (C++ member), 366 enumerator), 377 Espressif Systems 2088 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_CFG_SERVER_STATE_CHANGE_EVT (C++ member), 359 (C++ enumerator), 377 esp_ble_mesh_cfg_srv::heartbeat_recv_cb esp_ble_mesh_cfg_server_state_change_t (C++ member), 359 (C++ union), 358 esp_ble_mesh_cfg_srv::heartbeat_sub esp_ble_mesh_cfg_server_state_change_t::appkey(C_+a+ddmember), 359 (C++ member), 358 esp_ble_mesh_cfg_srv::max_hops (C++ esp_ble_mesh_cfg_server_state_change_t::appkeym_edmeblere)t, 3e59 (C++ member), 358 esp_ble_mesh_cfg_srv::min_hops (C++ esp_ble_mesh_cfg_server_state_change_t::appkeym_eumpbdera)t, 3e59 (C++ member), 358 esp_ble_mesh_cfg_srv::model (C++ mem- esp_ble_mesh_cfg_server_state_change_t::kr_phabsere),_3s5e9t (C++ member), 358 esp_ble_mesh_cfg_srv::net_idx (C++ esp_ble_mesh_cfg_server_state_change_t::mod_apmpe_mbbiern)d, 359 (C++ member), 358 esp_ble_mesh_cfg_srv::net_transmit esp_ble_mesh_cfg_server_state_change_t::mod_ap(Cp+_+unmbeimnbder), 359 (C++ member), 358 esp_ble_mesh_cfg_srv::period (C++ mem- esp_ble_mesh_cfg_server_state_change_t::mod_pubber_),s3e5t9 (C++ member), 358 esp_ble_mesh_cfg_srv::relay (C++ mem- esp_ble_mesh_cfg_server_state_change_t::mod_subber_),a3d5d9 (C++ member), 358 esp_ble_mesh_cfg_srv::relay_retransmit esp_ble_mesh_cfg_server_state_change_t::mod_su(Cb+_+demleemtbeer), 359 (C++ member), 358 esp_ble_mesh_cfg_srv::src (C++ member), esp_ble_mesh_cfg_server_state_change_t::netkey3_59add (C++ member), 358 esp_ble_mesh_cfg_srv::timer (C++ mem- esp_ble_mesh_cfg_server_state_change_t::netkeyb_erd),e3l5e9te (C++ member), 358 esp_ble_mesh_cfg_srv::ttl (C++ member), esp_ble_mesh_cfg_server_state_change_t::netkey3_59update (C++ member), 358 esp_ble_mesh_cfg_srv_t (C++ type), 377 esp_ble_mesh_cfg_sig_model_app_get_t ESP_BLE_MESH_CFG_STATUS_CANNOT_BIND (C (C++ class), 361 macro), 323 esp_ble_mesh_cfg_sig_model_app_get_t::eElSePm_eBnLtE__aMdEdSrH_CFG_STATUS_CANNOT_REMOVE (C++ member), 361 (C macro), 323 esp_ble_mesh_cfg_sig_model_app_get_t::mEoSdPe_lB_LiEd_MESH_CFG_STATUS_CANNOT_SET (C (C++ member), 361 macro), 323 esp_ble_mesh_cfg_sig_model_sub_get_t ESP_BLE_MESH_CFG_STATUS_CANNOT_UPDATE (C++ class), 360 (C macro), 323 esp_ble_mesh_cfg_sig_model_sub_get_t::eElSePm_eBnLtE__aMdEdSrH_CFG_STATUS_FEATURE_NOT_SUPPORTED (C++ member), 360 (C macro), 322 esp_ble_mesh_cfg_sig_model_sub_get_t::mEoSdPe_lB_LiEd_MESH_CFG_STATUS_INSUFFICIENT_RESOURCES (C++ member), 360 (C macro), 322 esp_ble_mesh_cfg_srv (C++ class), 358 ESP_BLE_MESH_CFG_STATUS_INVALID_ADDRESS esp_ble_mesh_cfg_srv::beacon (C++ mem- (C macro), 322 ber), 359 ESP_BLE_MESH_CFG_STATUS_INVALID_APPKEY esp_ble_mesh_cfg_srv::count (C++ mem- (C macro), 322 ber), 359 ESP_BLE_MESH_CFG_STATUS_INVALID_BINDING esp_ble_mesh_cfg_srv::default_ttl (C macro), 323 (C++ member), 359 ESP_BLE_MESH_CFG_STATUS_INVALID_MODEL esp_ble_mesh_cfg_srv::dst (C++ member), (C macro), 322 359 ESP_BLE_MESH_CFG_STATUS_INVALID_NETKEY esp_ble_mesh_cfg_srv::expiry (C++ mem- (C macro), 322 ber), 359 ESP_BLE_MESH_CFG_STATUS_INVALID_PUBLISH_PARAMETER esp_ble_mesh_cfg_srv::feature (C++ (C macro), 322 member), 359 ESP_BLE_MESH_CFG_STATUS_KEY_INDEX_ALREADY_STORED esp_ble_mesh_cfg_srv::friend_state (C macro), 322 (C++ member), 359 ESP_BLE_MESH_CFG_STATUS_NOT_A_SUBSCRIBE_MODEL esp_ble_mesh_cfg_srv::gatt_proxy (C++ (C macro), 322 member), 359 ESP_BLE_MESH_CFG_STATUS_STORAGE_FAILURE esp_ble_mesh_cfg_srv::heartbeat_pub (C macro), 322 Espressif Systems 2089 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_CFG_STATUS_SUCCESS (C member), 313 macro), 322 esp_ble_mesh_client_t::op_pair (C++ esp_ble_mesh_cfg_status_t (C++ type), 330 member), 313 ESP_BLE_MESH_CFG_STATUS_TEMP_UNABLE_TO_eCsHpA_NbGlEe__SmTeAsThE_client_t::op_pair_size (C macro), 323 (C++ member), 313 ESP_BLE_MESH_CFG_STATUS_UNSPECIFIED_ERReOsRp_ble_mesh_client_t::publish_status (C macro), 323 (C++ member), 313 esp_ble_mesh_cfg_vnd_model_app_get_t esp_ble_mesh_comp_t (C++ class), 310 (C++ class), 361 esp_ble_mesh_comp_t::cid (C++ member), esp_ble_mesh_cfg_vnd_model_app_get_t::company_3i10d (C++ member), 361 esp_ble_mesh_comp_t::element_count esp_ble_mesh_cfg_vnd_model_app_get_t::element_(Ca+d+drmember), 310 (C++ member), 361 esp_ble_mesh_comp_t::elements (C++ esp_ble_mesh_cfg_vnd_model_app_get_t::model_idmember), 310 (C++ member), 361 esp_ble_mesh_comp_t::pid (C++ member), esp_ble_mesh_cfg_vnd_model_sub_get_t 310 (C++ class), 360 esp_ble_mesh_comp_t::vid (C++ member), esp_ble_mesh_cfg_vnd_model_sub_get_t::company_3i10d (C++ member), 360 ESP_BLE_MESH_CONDENSATION_ERROR (C esp_ble_mesh_cfg_vnd_model_sub_get_t::element_maadcrdor), 384 (C++ member), 360 ESP_BLE_MESH_CONDENSATION_WARNING (C esp_ble_mesh_cfg_vnd_model_sub_get_t::model_idmacro), 384 (C++ member), 360 esp_ble_mesh_config_client_get_state ESP_BLE_MESH_CID_NVAL (C macro), 315 (C++ function), 354 esp_ble_mesh_client_common_param_t esp_ble_mesh_config_client_set_state (C++ class), 313 (C++ function), 354 esp_ble_mesh_client_common_param_t::ctxESP_BLE_MESH_CONFIGURATION_ERROR (C (C++ member), 313 macro), 384 esp_ble_mesh_client_common_param_t::modEeSlP_BLE_MESH_CONFIGURATION_WARNING (C (C++ member), 313 macro), 384 esp_ble_mesh_client_common_param_t::msge_srpo_lbele_mesh_deinit (C++ function), 337 (C++ member), 313 ESP_BLE_MESH_DEINIT_MESH_COMP_EVT esp_ble_mesh_client_common_param_t::msg_timeou(Ct++ enumerator), 336 (C++ member), 313 esp_ble_mesh_deinit_param_t (C++ class), esp_ble_mesh_client_common_param_t::opcode 307 (C++ member), 313 esp_ble_mesh_deinit_param_t::erase_flash esp_ble_mesh_client_model_deinit (C++ (C++ member), 307 function), 341 esp_ble_mesh_dev_add_flag_t (C++ type), esp_ble_mesh_client_model_init (C++ 329 function), 341 esp_ble_mesh_dev_role_t (C++ enum), 332 ESP_BLE_MESH_CLIENT_MODEL_RECV_PUBLISH_eMsSpG__bElVeT_mesh_device_delete_t (C++ class), (C++ enumerator), 336 310 esp_ble_mesh_client_model_send_msg esp_ble_mesh_device_delete_t::addr (C++ function), 341 (C++ member), 310 ESP_BLE_MESH_CLIENT_MODEL_SEND_TIMEOUT_eEsVpT_ble_mesh_device_delete_t::addr_type (C++ enumerator), 336 (C++ member), 310 esp_ble_mesh_client_op_pair_t (C++ esp_ble_mesh_device_delete_t::flag class), 312 (C++ member), 311 esp_ble_mesh_client_op_pair_t::cli_op esp_ble_mesh_device_delete_t::uuid (C++ member), 312 (C++ member), 311 esp_ble_mesh_client_op_pair_t::status_oEpSP_BLE_MESH_DEVICE_DROPPED_ERROR (C (C++ member), 312 macro), 385 esp_ble_mesh_client_t (C++ class), 312 ESP_BLE_MESH_DEVICE_DROPPED_WARNING (C esp_ble_mesh_client_t::internal_data macro), 385 (C++ member), 313 ESP_BLE_MESH_DEVICE_MOVED_ERROR (C esp_ble_mesh_client_t::model (C++ mem- macro), 385 ber), 313 ESP_BLE_MESH_DEVICE_MOVED_WARNING (C esp_ble_mesh_client_t::msg_role (C++ macro), 385 Espressif Systems 2090 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_DEVICE_NAME_MAX_LEN (C esp_ble_mesh_find_element (C++ function), macro), 315 338 ESP_BLE_MESH_DISPLAY_NUMBER (C++ enumer- esp_ble_mesh_find_sig_model (C++ func- ator), 331 tion), 338 ESP_BLE_MESH_DISPLAY_STRING (C++ enumer- esp_ble_mesh_find_vendor_model (C++ ator), 331 function), 338 esp_ble_mesh_elem_t (C++ class), 307 ESP_BLE_MESH_FRIEND_DISABLED (C macro), esp_ble_mesh_elem_t::element_addr 316 (C++ member), 307 ESP_BLE_MESH_FRIEND_ENABLED (C macro), esp_ble_mesh_elem_t::location (C++ 316 member), 307 ESP_BLE_MESH_FRIEND_FRIENDSHIP_ESTABLISH_EVT esp_ble_mesh_elem_t::sig_model_count (C++ enumerator), 335 (C++ member), 307 ESP_BLE_MESH_FRIEND_FRIENDSHIP_TERMINATE_EVT esp_ble_mesh_elem_t::sig_models (C++ (C++ enumerator), 335 member), 307 ESP_BLE_MESH_FRIEND_NOT_SUPPORTED (C esp_ble_mesh_elem_t::vnd_model_count macro), 316 (C++ member), 307 ESP_BLE_MESH_GATT_PROXY_DISABLED (C esp_ble_mesh_elem_t::vnd_models (C++ macro), 315 member), 307 ESP_BLE_MESH_GATT_PROXY_ENABLED (C ESP_BLE_MESH_ELEMENT (C macro), 317 macro), 315 ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_ERREOSRP_BLE_MESH_GATT_PROXY_NOT_SUPPORTED (C macro), 384 (C macro), 315 ESP_BLE_MESH_ELEMENT_NOT_CALIBRATED_WARENSIPN_GBLE_MESH_GEN_ADMIN_ACCESS_READ (C macro), 384 (C++ enumerator), 416 ESP_BLE_MESH_EMPTY_ERROR (C macro), 385 ESP_BLE_MESH_GEN_ADMIN_ACCESS_READ_WRITE ESP_BLE_MESH_EMPTY_WARNING (C macro), 385 (C++ enumerator), 416 ESP_BLE_MESH_ENTER_NUMBER (C++ enumera- ESP_BLE_MESH_GEN_ADMIN_ACCESS_WRITE tor), 331 (C++ enumerator), 416 ESP_BLE_MESH_ENTER_STRING (C++ enumera- ESP_BLE_MESH_GEN_ADMIN_NOT_USER_PROP tor), 331 (C++ enumerator), 416 esp_ble_mesh_fast_prov_action_t (C++ esp_ble_mesh_gen_admin_prop_access_t enum), 332 (C++ enum), 416 esp_ble_mesh_fast_prov_info_t (C++ esp_ble_mesh_gen_admin_prop_srv_t class), 312 (C++ class), 404 esp_ble_mesh_fast_prov_info_t::flags esp_ble_mesh_gen_admin_prop_srv_t::model (C++ member), 312 (C++ member), 404 esp_ble_mesh_fast_prov_info_t::iv_indexesp_ble_mesh_gen_admin_prop_srv_t::properties (C++ member), 312 (C++ member), 404 esp_ble_mesh_fast_prov_info_t::match_leensp_ble_mesh_gen_admin_prop_srv_t::property_count (C++ member), 312 (C++ member), 404 esp_ble_mesh_fast_prov_info_t::match_vaelsp_ble_mesh_gen_admin_prop_srv_t::rsp_ctrl (C++ member), 312 (C++ member), 404 esp_ble_mesh_fast_prov_info_t::net_idx esp_ble_mesh_gen_admin_properties_status_cb_t (C++ member), 312 (C++ class), 397 esp_ble_mesh_fast_prov_info_t::offset esp_ble_mesh_gen_admin_properties_status_cb_t::pr (C++ member), 312 (C++ member), 397 esp_ble_mesh_fast_prov_info_t::unicast_emsapx_ble_mesh_gen_admin_property_get_t (C++ member), 312 (C++ class), 393 esp_ble_mesh_fast_prov_info_t::unicast_emsipn_ble_mesh_gen_admin_property_get_t::property_i (C++ member), 312 (C++ member), 394 ESP_BLE_MESH_FEATURE_ALL_SUPPORTED (C esp_ble_mesh_gen_admin_property_set_t macro), 316 (C++ class), 394 ESP_BLE_MESH_FEATURE_FRIEND (C macro), esp_ble_mesh_gen_admin_property_set_t::property_i 316 (C++ member), 394 ESP_BLE_MESH_FEATURE_LOW_POWER (C esp_ble_mesh_gen_admin_property_set_t::property_v macro), 316 (C++ member), 394 ESP_BLE_MESH_FEATURE_PROXY (C macro), 316 esp_ble_mesh_gen_admin_property_set_t::user_acces ESP_BLE_MESH_FEATURE_RELAY (C macro), 316 (C++ member), 394 Espressif Systems 2091 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_gen_admin_property_status_ecsbp__tble_mesh_gen_client_status_cb_t::admin_proper (C++ class), 397 (C++ member), 388 esp_ble_mesh_gen_admin_property_status_ecsbp__tb:l:eo_pm_eesnh_gen_client_status_cb_t::admin_proper (C++ member), 398 (C++ member), 388 esp_ble_mesh_gen_admin_property_status_ecsbp__tb:l:ep_rmoepsehr_tgye_ni_dclient_status_cb_t::battery_stat (C++ member), 398 (C++ member), 388 esp_ble_mesh_gen_admin_property_status_ecsbp__tb:l:ep_rmoepsehr_tgye_nv_aclluieent_status_cb_t::client_prope (C++ member), 398 (C++ member), 388 esp_ble_mesh_gen_admin_property_status_ecsbp__tb:l:eu_smeers_ha_cgceens_sclient_status_cb_t::def_trans_ti (C++ member), 398 (C++ member), 388 esp_ble_mesh_gen_battery_srv_t (C++ esp_ble_mesh_gen_client_status_cb_t::level_status class), 402 (C++ member), 388 esp_ble_mesh_gen_battery_srv_t::model esp_ble_mesh_gen_client_status_cb_t::location_glo (C++ member), 402 (C++ member), 388 esp_ble_mesh_gen_battery_srv_t::rsp_ctrelsp_ble_mesh_gen_client_status_cb_t::location_loc (C++ member), 402 (C++ member), 388 esp_ble_mesh_gen_battery_srv_t::state esp_ble_mesh_gen_client_status_cb_t::manufacturer (C++ member), 402 (C++ member), 388 esp_ble_mesh_gen_battery_state_t (C++ esp_ble_mesh_gen_client_status_cb_t::manufacturer class), 402 (C++ member), 388 esp_ble_mesh_gen_battery_state_t::batteersyp__fbllaeg_smesh_gen_client_status_cb_t::onoff_status (C++ member), 402 (C++ member), 388 esp_ble_mesh_gen_battery_state_t::batteersyp__lbelvee_lmesh_gen_client_status_cb_t::onpowerup_st (C++ member), 402 (C++ member), 388 esp_ble_mesh_gen_battery_state_t::time_etsop__cbhlaer_gmeesh_gen_client_status_cb_t::power_defaul (C++ member), 402 (C++ member), 388 esp_ble_mesh_gen_battery_state_t::time_etsop__dbilsec_hmaersghe_gen_client_status_cb_t::power_last_s (C++ member), 402 (C++ member), 388 esp_ble_mesh_gen_battery_status_cb_t esp_ble_mesh_gen_client_status_cb_t::power_level_ (C++ class), 396 (C++ member), 388 esp_ble_mesh_gen_battery_status_cb_t::beastpt_ebrlye__lmeevsehl_gen_client_status_cb_t::power_range_ (C++ member), 396 (C++ member), 388 esp_ble_mesh_gen_battery_status_cb_t::felsapg_sble_mesh_gen_client_status_cb_t::user_propert (C++ member), 396 (C++ member), 388 esp_ble_mesh_gen_battery_status_cb_t::teismpe__btloe__cmheasrhg_egen_client_status_cb_t::user_propert (C++ member), 396 (C++ member), 388 esp_ble_mesh_gen_battery_status_cb_t::teismpe__btloe__dmiesschh_agregne_def_trans_time_set_t (C++ member), 396 (C++ class), 392 esp_ble_mesh_gen_client_prop_srv_t esp_ble_mesh_gen_def_trans_time_set_t::trans_time (C++ class), 404 (C++ member), 392 esp_ble_mesh_gen_client_prop_srv_t::id_ecsopu_nbtle_mesh_gen_def_trans_time_srv_t (C++ member), 404 (C++ class), 400 esp_ble_mesh_gen_client_prop_srv_t::modeeslp_ble_mesh_gen_def_trans_time_srv_t::model (C++ member), 404 (C++ member), 400 esp_ble_mesh_gen_client_prop_srv_t::proepsepr_tbyl_ei_dmsesh_gen_def_trans_time_srv_t::rsp_ctrl (C++ member), 405 (C++ member), 400 esp_ble_mesh_gen_client_prop_srv_t::rspe_scpt_rblle_mesh_gen_def_trans_time_srv_t::state (C++ member), 404 (C++ member), 400 esp_ble_mesh_gen_client_properties_get_etsp_ble_mesh_gen_def_trans_time_state_t (C++ class), 394 (C++ class), 400 esp_ble_mesh_gen_client_properties_get_ets:p:_pbrloep_emretsyh__igden_def_trans_time_state_t::trans_ti (C++ member), 394 (C++ member), 400 esp_ble_mesh_gen_client_properties_stateussp__cbbl_et_mesh_gen_def_trans_time_status_cb_t (C++ class), 398 (C++ class), 395 esp_ble_mesh_gen_client_properties_stateussp__cbbl_et_:m:epsrho_pgeernt_yd_eifd_strans_time_status_cb_t::tran (C++ member), 398 (C++ member), 395 esp_ble_mesh_gen_client_status_cb_t esp_ble_mesh_gen_delta_set_t (C++ class), (C++ union), 388 391 Espressif Systems 2092 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_gen_delta_set_t::delay esp_ble_mesh_gen_level_status_cb_t::target_level (C++ member), 391 (C++ member), 395 esp_ble_mesh_gen_delta_set_t::level esp_ble_mesh_gen_loc_global_set_t (C++ member), 391 (C++ class), 393 esp_ble_mesh_gen_delta_set_t::op_en esp_ble_mesh_gen_loc_global_set_t::global_altitud (C++ member), 391 (C++ member), 393 esp_ble_mesh_gen_delta_set_t::tid esp_ble_mesh_gen_loc_global_set_t::global_latitud (C++ member), 391 (C++ member), 393 esp_ble_mesh_gen_delta_set_t::trans_timeesp_ble_mesh_gen_loc_global_set_t::global_longitu (C++ member), 391 (C++ member), 393 esp_ble_mesh_gen_level_set_t (C++ class), esp_ble_mesh_gen_loc_global_status_cb_t 391 (C++ class), 396 esp_ble_mesh_gen_level_set_t::delay esp_ble_mesh_gen_loc_global_status_cb_t::global_a (C++ member), 391 (C++ member), 396 esp_ble_mesh_gen_level_set_t::level esp_ble_mesh_gen_loc_global_status_cb_t::global_l (C++ member), 391 (C++ member), 396 esp_ble_mesh_gen_level_set_t::op_en esp_ble_mesh_gen_loc_global_status_cb_t::global_l (C++ member), 391 (C++ member), 396 esp_ble_mesh_gen_level_set_t::tid esp_ble_mesh_gen_loc_local_set_t (C++ (C++ member), 391 class), 393 esp_ble_mesh_gen_level_set_t::trans_timeesp_ble_mesh_gen_loc_local_set_t::floor_number (C++ member), 391 (C++ member), 393 esp_ble_mesh_gen_level_srv_t (C++ class), esp_ble_mesh_gen_loc_local_set_t::local_altitude 399 (C++ member), 393 esp_ble_mesh_gen_level_srv_t::last esp_ble_mesh_gen_loc_local_set_t::local_east (C++ member), 400 (C++ member), 393 esp_ble_mesh_gen_level_srv_t::model esp_ble_mesh_gen_loc_local_set_t::local_north (C++ member), 400 (C++ member), 393 esp_ble_mesh_gen_level_srv_t::rsp_ctrl esp_ble_mesh_gen_loc_local_set_t::uncertainty (C++ member), 400 (C++ member), 393 esp_ble_mesh_gen_level_srv_t::state esp_ble_mesh_gen_loc_local_status_cb_t (C++ member), 400 (C++ class), 397 esp_ble_mesh_gen_level_srv_t::transitioensp_ble_mesh_gen_loc_local_status_cb_t::floor_num (C++ member), 400 (C++ member), 397 esp_ble_mesh_gen_level_srv_t::tt_delta_elsepv_eblle_mesh_gen_loc_local_status_cb_t::local_alt (C++ member), 400 (C++ member), 397 esp_ble_mesh_gen_level_state_t (C++ esp_ble_mesh_gen_loc_local_status_cb_t::local_eas class), 399 (C++ member), 397 esp_ble_mesh_gen_level_state_t::last_deelstpa_ble_mesh_gen_loc_local_status_cb_t::local_nor (C++ member), 399 (C++ member), 397 esp_ble_mesh_gen_level_state_t::last_leevsepl_ble_mesh_gen_loc_local_status_cb_t::uncertain (C++ member), 399 (C++ member), 397 esp_ble_mesh_gen_level_state_t::level esp_ble_mesh_gen_location_setup_srv_t (C++ member), 399 (C++ class), 403 esp_ble_mesh_gen_level_state_t::move_steasrpt_ble_mesh_gen_location_setup_srv_t::model (C++ member), 399 (C++ member), 403 esp_ble_mesh_gen_level_state_t::positiveesp_ble_mesh_gen_location_setup_srv_t::rsp_ctrl (C++ member), 399 (C++ member), 403 esp_ble_mesh_gen_level_state_t::target_elsepv_eblle_mesh_gen_location_setup_srv_t::state (C++ member), 399 (C++ member), 403 esp_ble_mesh_gen_level_status_cb_t esp_ble_mesh_gen_location_srv_t (C++ (C++ class), 395 class), 403 esp_ble_mesh_gen_level_status_cb_t::op_eesnp_ble_mesh_gen_location_srv_t::model (C++ member), 395 (C++ member), 403 esp_ble_mesh_gen_level_status_cb_t::preessepn_tb_llee_vmeelsh_gen_location_srv_t::rsp_ctrl (C++ member), 395 (C++ member), 403 esp_ble_mesh_gen_level_status_cb_t::remeasipn__btliem_emesh_gen_location_srv_t::state (C++ member), 395 (C++ member), 403 Espressif Systems 2093 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_gen_location_state_t esp_ble_mesh_gen_move_set_t (C++ class), (C++ class), 402 391 esp_ble_mesh_gen_location_state_t::flooers_pn_ubmlbee_rmesh_gen_move_set_t::delay (C++ member), 403 (C++ member), 392 esp_ble_mesh_gen_location_state_t::globeaslp__ablltei_tmuedseh_gen_move_set_t::delta_level (C++ member), 402 (C++ member), 391 esp_ble_mesh_gen_location_state_t::globeaslp__lbaltei_tmuedseh_gen_move_set_t::op_en (C++ member), 402 (C++ member), 391 esp_ble_mesh_gen_location_state_t::globeaslp__lbolneg_imteusdhe_gen_move_set_t::tid (C++ (C++ member), 402 member), 392 esp_ble_mesh_gen_location_state_t::locaels_pa_lbtliet_umdeesh_gen_move_set_t::trans_time (C++ member), 403 (C++ member), 392 esp_ble_mesh_gen_location_state_t::locaels_pe_abslte_mesh_gen_onoff_set_t (C++ class), (C++ member), 403 390 esp_ble_mesh_gen_location_state_t::locaels_pn_obrlteh_mesh_gen_onoff_set_t::delay (C++ member), 402 (C++ member), 391 esp_ble_mesh_gen_location_state_t::unceerstpa_ibnltey_mesh_gen_onoff_set_t::onoff (C++ member), 403 (C++ member), 391 ESP_BLE_MESH_GEN_MANU_ACCESS_READ esp_ble_mesh_gen_onoff_set_t::op_en (C++ enumerator), 416 (C++ member), 391 ESP_BLE_MESH_GEN_MANU_NOT_USER_PROP esp_ble_mesh_gen_onoff_set_t::tid (C++ enumerator), 416 (C++ member), 391 esp_ble_mesh_gen_manu_prop_access_t esp_ble_mesh_gen_onoff_set_t::trans_time (C++ enum), 416 (C++ member), 391 esp_ble_mesh_gen_manu_prop_srv_t (C++ esp_ble_mesh_gen_onoff_srv_t (C++ class), class), 404 399 esp_ble_mesh_gen_manu_prop_srv_t::modelesp_ble_mesh_gen_onoff_srv_t::last (C++ member), 404 (C++ member), 399 esp_ble_mesh_gen_manu_prop_srv_t::propeerstpi_ebsle_mesh_gen_onoff_srv_t::model (C++ member), 404 (C++ member), 399 esp_ble_mesh_gen_manu_prop_srv_t::propeerstpy__bcloeu_nmtesh_gen_onoff_srv_t::rsp_ctrl (C++ member), 404 (C++ member), 399 esp_ble_mesh_gen_manu_prop_srv_t::rsp_cetsrpl_ble_mesh_gen_onoff_srv_t::state (C++ member), 404 (C++ member), 399 esp_ble_mesh_gen_manufacturer_propertieess_ps_tbalteu_sm_ecsbh__tgen_onoff_srv_t::transition (C++ class), 398 (C++ member), 399 esp_ble_mesh_gen_manufacturer_propertieess_ps_tbalteu_sm_ecsbh__tg:e:np_roonpoefrft_ys_tiadtse_t (C++ (C++ member), 398 class), 398 esp_ble_mesh_gen_manufacturer_property_egsept__btle_mesh_gen_onoff_state_t::onoff (C++ class), 394 (C++ member), 399 esp_ble_mesh_gen_manufacturer_property_egsept__btl:e:_pmreosphe_rgteyn__iodnoff_state_t::target_onoff (C++ member), 394 (C++ member), 399 esp_ble_mesh_gen_manufacturer_property_essept__btle_mesh_gen_onoff_status_cb_t (C++ class), 394 (C++ class), 394 esp_ble_mesh_gen_manufacturer_property_essept__btl:e:_pmreosphe_rgteyn__iodnoff_status_cb_t::op_en (C++ member), 394 (C++ member), 395 esp_ble_mesh_gen_manufacturer_property_essept__btl:e:_umseesrh__agcecne_sosnoff_status_cb_t::present_onoff (C++ member), 394 (C++ member), 395 esp_ble_mesh_gen_manufacturer_property_esstpa_tbulse__cmbe_sth_gen_onoff_status_cb_t::remain_time (C++ class), 398 (C++ member), 395 esp_ble_mesh_gen_manufacturer_property_esstpa_tbulse__cmbe_sth:_:goepn__eonnoff_status_cb_t::target_onoff (C++ member), 398 (C++ member), 395 esp_ble_mesh_gen_manufacturer_property_esstpa_tbulse__cmbe_sth:_:gperno_poenrptoyw_eirdup_set_t (C++ (C++ member), 398 class), 392 esp_ble_mesh_gen_manufacturer_property_esstpa_tbulse__cmbe_sth:_:gperno_poenrptoyw_evraulpu_eset_t::onpowerup (C++ member), 398 (C++ member), 392 esp_ble_mesh_gen_manufacturer_property_esstpa_tbulse__cmbe_sth:_:guesne_ro_napcocweesrsup_state_t (C++ member), 398 (C++ class), 400 Espressif Systems 2094 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_gen_onpowerup_state_t::onpeoswpe_rbulpe_mesh_gen_power_level_state_t::power_last (C++ member), 400 (C++ member), 401 esp_ble_mesh_gen_onpowerup_status_cb_t esp_ble_mesh_gen_power_level_state_t::power_range (C++ class), 395 (C++ member), 401 esp_ble_mesh_gen_onpowerup_status_cb_t:e:sopn_pbolwee_rmuepsh_gen_power_level_state_t::power_range (C++ member), 395 (C++ member), 401 esp_ble_mesh_gen_power_default_set_t esp_ble_mesh_gen_power_level_state_t::status_code (C++ class), 392 (C++ member), 401 esp_ble_mesh_gen_power_default_set_t::peoswpe_rble_mesh_gen_power_level_state_t::target_powe (C++ member), 392 (C++ member), 401 esp_ble_mesh_gen_power_default_status_cebs_pt_ble_mesh_gen_power_level_status_cb_t (C++ class), 396 (C++ class), 395 esp_ble_mesh_gen_power_default_status_cebs_pt_:b:lpeo_wmeersh_gen_power_level_status_cb_t::op_en (C++ member), 396 (C++ member), 395 esp_ble_mesh_gen_power_last_status_cb_tesp_ble_mesh_gen_power_level_status_cb_t::present (C++ class), 396 (C++ member), 395 esp_ble_mesh_gen_power_last_status_cb_te:s:pp_obwleer_mesh_gen_power_level_status_cb_t::remain_ (C++ member), 396 (C++ member), 395 esp_ble_mesh_gen_power_level_set_t esp_ble_mesh_gen_power_level_status_cb_t::target_ (C++ class), 392 (C++ member), 395 esp_ble_mesh_gen_power_level_set_t::deleasyp_ble_mesh_gen_power_onoff_setup_srv_t (C++ member), 392 (C++ class), 401 esp_ble_mesh_gen_power_level_set_t::op_eesnp_ble_mesh_gen_power_onoff_setup_srv_t::model (C++ member), 392 (C++ member), 401 esp_ble_mesh_gen_power_level_set_t::poweesrp_ble_mesh_gen_power_onoff_setup_srv_t::rsp_ctr (C++ member), 392 (C++ member), 401 esp_ble_mesh_gen_power_level_set_t::tidesp_ble_mesh_gen_power_onoff_setup_srv_t::state (C++ member), 392 (C++ member), 401 esp_ble_mesh_gen_power_level_set_t::traenssp__tbilmee_mesh_gen_power_onoff_srv_t (C++ member), 392 (C++ class), 400 esp_ble_mesh_gen_power_level_setup_srv_etsp_ble_mesh_gen_power_onoff_srv_t::model (C++ class), 402 (C++ member), 400 esp_ble_mesh_gen_power_level_setup_srv_ets:p:_mboldee_lmesh_gen_power_onoff_srv_t::rsp_ctrl (C++ member), 402 (C++ member), 400 esp_ble_mesh_gen_power_level_setup_srv_ets:p:_rbslpe__cmterslh_gen_power_onoff_srv_t::state (C++ member), 402 (C++ member), 400 esp_ble_mesh_gen_power_level_setup_srv_ets:p:_sbtlaet_emesh_gen_power_range_set_t (C++ member), 402 (C++ class), 392 esp_ble_mesh_gen_power_level_srv_t esp_ble_mesh_gen_power_range_set_t::range_max (C++ class), 401 (C++ member), 393 esp_ble_mesh_gen_power_level_srv_t::lasetsp_ble_mesh_gen_power_range_set_t::range_min (C++ member), 401 (C++ member), 393 esp_ble_mesh_gen_power_level_srv_t::modeeslp_ble_mesh_gen_power_range_status_cb_t (C++ member), 401 (C++ class), 396 esp_ble_mesh_gen_power_level_srv_t::rspe_scpt_rblle_mesh_gen_power_range_status_cb_t::range_m (C++ member), 401 (C++ member), 396 esp_ble_mesh_gen_power_level_srv_t::staetsep_ble_mesh_gen_power_range_status_cb_t::range_m (C++ member), 401 (C++ member), 396 esp_ble_mesh_gen_power_level_srv_t::traensspi_tbiloen_mesh_gen_power_range_status_cb_t::status_ (C++ member), 401 (C++ member), 396 esp_ble_mesh_gen_power_level_srv_t::tt_EdSePl_tBaL_El_eMvEeSlH_GEN_USER_ACCESS_PROHIBIT (C++ member), 401 (C++ enumerator), 415 esp_ble_mesh_gen_power_level_state_t ESP_BLE_MESH_GEN_USER_ACCESS_READ (C++ class), 401 (C++ enumerator), 416 esp_ble_mesh_gen_power_level_state_t::pEoSwPe_rB_LaEc_tMuEaSlH_GEN_USER_ACCESS_READ_WRITE (C++ member), 401 (C++ enumerator), 416 esp_ble_mesh_gen_power_level_state_t::pEoSwPe_rB_LdEe_fMaEuSlHt_GEN_USER_ACCESS_WRITE (C++ member), 401 (C++ enumerator), 416 Espressif Systems 2095 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_gen_user_prop_access_t esp_ble_mesh_generic_client_get_state_t::client_p (C++ enum), 415 (C++ member), 387 esp_ble_mesh_gen_user_prop_srv_t (C++ esp_ble_mesh_generic_client_get_state_t::manufact class), 403 (C++ member), 387 esp_ble_mesh_gen_user_prop_srv_t::modelesp_ble_mesh_generic_client_get_state_t::user_pro (C++ member), 404 (C++ member), 387 esp_ble_mesh_gen_user_prop_srv_t::propeErStPi_eBsLE_MESH_GENERIC_CLIENT_PUBLISH_EVT (C++ member), 404 (C++ enumerator), 415 esp_ble_mesh_gen_user_prop_srv_t::propeerstpy__bcloeu_nmtesh_generic_client_set_state (C++ member), 404 (C++ function), 386 esp_ble_mesh_gen_user_prop_srv_t::rsp_cEtSrPl_BLE_MESH_GENERIC_CLIENT_SET_STATE_EVT (C++ member), 404 (C++ enumerator), 415 esp_ble_mesh_gen_user_properties_statuse_scpb__btle_mesh_generic_client_set_state_t (C++ class), 397 (C++ union), 387 esp_ble_mesh_gen_user_properties_statuse_scpb__btl:e:_pmreosphe_rgteyn_eirdisc_client_set_state_t::admin_pr (C++ member), 397 (C++ member), 387 esp_ble_mesh_gen_user_property_get_t esp_ble_mesh_generic_client_set_state_t::def_tran (C++ class), 393 (C++ member), 387 esp_ble_mesh_gen_user_property_get_t::persopp_ebrltey__miedsh_generic_client_set_state_t::delta_se (C++ member), 393 (C++ member), 387 esp_ble_mesh_gen_user_property_set_t esp_ble_mesh_generic_client_set_state_t::level_se (C++ class), 393 (C++ member), 387 esp_ble_mesh_gen_user_property_set_t::persopp_ebrltey__miedsh_generic_client_set_state_t::loc_glob (C++ member), 393 (C++ member), 387 esp_ble_mesh_gen_user_property_set_t::persopp_ebrltey__mveaslhu_egeneric_client_set_state_t::loc_loca (C++ member), 393 (C++ member), 387 esp_ble_mesh_gen_user_property_status_cebs_pt_ble_mesh_generic_client_set_state_t::manufact (C++ class), 397 (C++ member), 387 esp_ble_mesh_gen_user_property_status_cebs_pt_:b:loep__meensh_generic_client_set_state_t::move_set (C++ member), 397 (C++ member), 387 esp_ble_mesh_gen_user_property_status_cebs_pt_:b:lper_ompeesrht_yg_einderic_client_set_state_t::onoff_se (C++ member), 397 (C++ member), 387 esp_ble_mesh_gen_user_property_status_cebs_pt_:b:lper_ompeesrht_yg_evnaelruiec_client_set_state_t::power_de (C++ member), 397 (C++ member), 387 esp_ble_mesh_gen_user_property_status_cebs_pt_:b:lues_emre_sahc_cgeesnseric_client_set_state_t::power_le (C++ member), 397 (C++ member), 387 esp_ble_mesh_generic_client_cb_event_t esp_ble_mesh_generic_client_set_state_t::power_ra (C++ enum), 415 (C++ member), 387 esp_ble_mesh_generic_client_cb_param_t esp_ble_mesh_generic_client_set_state_t::power_se (C++ class), 398 (C++ member), 387 esp_ble_mesh_generic_client_cb_param_t:e:sepr_rbolre__cmoedseh_generic_client_set_state_t::user_pro (C++ member), 398 (C++ member), 387 esp_ble_mesh_generic_client_cb_param_t:E:SpPa_rBaLmEs_MESH_GENERIC_CLIENT_TIMEOUT_EVT (C++ member), 398 (C++ enumerator), 415 esp_ble_mesh_generic_client_cb_param_t:E:SsPt_aBtLuEs__McEbSH_GENERIC_LEVEL_STATE (C++ (C++ member), 398 enumerator), 336 esp_ble_mesh_generic_client_cb_t (C++ esp_ble_mesh_generic_message_opcode_t type), 415 (C++ type), 330 ESP_BLE_MESH_GENERIC_CLIENT_EVT_MAX ESP_BLE_MESH_GENERIC_ONOFF_STATE (C++ (C++ enumerator), 415 enumerator), 336 esp_ble_mesh_generic_client_get_state ESP_BLE_MESH_GENERIC_ONPOWERUP_STATE (C++ function), 386 (C++ enumerator), 336 ESP_BLE_MESH_GENERIC_CLIENT_GET_STATE_EEVSTP_BLE_MESH_GENERIC_POWER_ACTUAL_STATE (C++ enumerator), 415 (C++ enumerator), 336 esp_ble_mesh_generic_client_get_state_tesp_ble_mesh_generic_property_t (C++ (C++ union), 386 class), 403 esp_ble_mesh_generic_client_get_state_te:s:pa_dbmlien__mpersohp_egretnye_rgiect_property_t::admin_access (C++ member), 387 (C++ member), 403 Espressif Systems 2096 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_generic_property_t::id esp_ble_mesh_generic_server_recv_set_msg_t::manu_ (C++ member), 403 (C++ member), 390 esp_ble_mesh_generic_property_t::manu_aecscpe_sbsle_mesh_generic_server_recv_set_msg_t::move (C++ member), 403 (C++ member), 390 esp_ble_mesh_generic_property_t::user_aecscpe_sbsle_mesh_generic_server_recv_set_msg_t::onoff (C++ member), 403 (C++ member), 390 esp_ble_mesh_generic_property_t::val esp_ble_mesh_generic_server_recv_set_msg_t::onpow (C++ member), 403 (C++ member), 390 esp_ble_mesh_generic_server_cb_event_t esp_ble_mesh_generic_server_recv_set_msg_t::power (C++ enum), 416 (C++ member), 390 esp_ble_mesh_generic_server_cb_param_t esp_ble_mesh_generic_server_recv_set_msg_t::power (C++ class), 411 (C++ member), 390 esp_ble_mesh_generic_server_cb_param_t:e:scpt_xble_mesh_generic_server_recv_set_msg_t::power (C++ member), 411 (C++ member), 390 esp_ble_mesh_generic_server_cb_param_t:e:smpo_dbelle_mesh_generic_server_recv_set_msg_t::user_ (C++ member), 411 (C++ member), 390 esp_ble_mesh_generic_server_cb_param_t:E:SvPa_lBuLeE_MESH_GENERIC_SERVER_STATE_CHANGE_EVT (C++ member), 411 (C++ enumerator), 416 esp_ble_mesh_generic_server_cb_t (C++ esp_ble_mesh_generic_server_state_change_t type), 415 (C++ union), 388 esp_ble_mesh_generic_server_cb_value_t esp_ble_mesh_generic_server_state_change_t::admin (C++ union), 390 (C++ member), 389 esp_ble_mesh_generic_server_cb_value_t:e:sgpe_tble_mesh_generic_server_state_change_t::def_t (C++ member), 390 (C++ member), 389 esp_ble_mesh_generic_server_cb_value_t:e:sspe_tble_mesh_generic_server_state_change_t::delta (C++ member), 390 (C++ member), 389 esp_ble_mesh_generic_server_cb_value_t:e:sspt_abtlee__cmheasnhg_egeneric_server_state_change_t::level (C++ member), 390 (C++ member), 389 ESP_BLE_MESH_GENERIC_SERVER_EVT_MAX esp_ble_mesh_generic_server_state_change_t::loc_g (C++ enumerator), 416 (C++ member), 389 ESP_BLE_MESH_GENERIC_SERVER_RECV_GET_MSeGs_pE_VbTle_mesh_generic_server_state_change_t::loc_l (C++ enumerator), 416 (C++ member), 389 esp_ble_mesh_generic_server_recv_get_msegs_pt_ble_mesh_generic_server_state_change_t::manu_ (C++ union), 389 (C++ member), 389 esp_ble_mesh_generic_server_recv_get_msegs_pt_:b:laed_mmiens_hp_rgoepneerrtiyc_server_state_change_t::move_ (C++ member), 389 (C++ member), 389 esp_ble_mesh_generic_server_recv_get_msegs_pt_:b:lcel_imeensth__pgreonpeerritci_esserver_state_change_t::onoff (C++ member), 389 (C++ member), 389 esp_ble_mesh_generic_server_recv_get_msegs_pt_:b:lmea_nmue_sphr_ogpeenretryic_server_state_change_t::onpow (C++ member), 389 (C++ member), 389 esp_ble_mesh_generic_server_recv_get_msegs_pt_:b:lues_emre_sphr_ogpeenretryic_server_state_change_t::power (C++ member), 389 (C++ member), 389 ESP_BLE_MESH_GENERIC_SERVER_RECV_SET_MSeGs_pE_VbTle_mesh_generic_server_state_change_t::power (C++ enumerator), 416 (C++ member), 389 esp_ble_mesh_generic_server_recv_set_msegs_pt_ble_mesh_generic_server_state_change_t::power (C++ union), 389 (C++ member), 389 esp_ble_mesh_generic_server_recv_set_msegs_pt_:b:laed_mmiens_hp_rgoepneerrtiyc_server_state_change_t::user_ (C++ member), 390 (C++ member), 389 esp_ble_mesh_generic_server_recv_set_msegs_pt_:b:ldee_fm_etsrha_ngse_tt_icmoemposition_data (C++ member), 390 (C++ function), 338 esp_ble_mesh_generic_server_recv_set_msegs_pt_:b:ldee_lmteash_get_element_count (C++ (C++ member), 390 function), 338 esp_ble_mesh_generic_server_recv_set_msegs_pt_:b:llee_vmeelsh_get_fast_prov_app_key (C++ member), 390 (C++ function), 347 esp_ble_mesh_generic_server_recv_set_msegs_pt_:b:lleo_cmaetsiho_ng_egtl_omboadlel_publish_period (C++ member), 390 (C++ function), 338 esp_ble_mesh_generic_server_recv_set_msegs_pt_:b:lleo_cmaetsiho_ng_elto_cparlimary_element_address (C++ member), 390 (C++ function), 338 Espressif Systems 2097 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_GET_PUBLISH_TRANSMIT_COUNTESP_BLE_MESH_HEALTH_CLIENT_GET_STATE_EVT (C macro), 316 (C++ enumerator), 385 ESP_BLE_MESH_GET_PUBLISH_TRANSMIT_INTEReVsApL_ble_mesh_health_client_get_state_t (C macro), 317 (C++ union), 378 ESP_BLE_MESH_GET_SENSOR_DATA_FORMAT (C esp_ble_mesh_health_client_get_state_t::fault_get macro), 429 (C++ member), 378 ESP_BLE_MESH_GET_SENSOR_DATA_LENGTH (C ESP_BLE_MESH_HEALTH_CLIENT_PUBLISH_EVT macro), 430 (C++ enumerator), 385 ESP_BLE_MESH_GET_SENSOR_DATA_PROPERTY_IeDsp_ble_mesh_health_client_set_state (C macro), 430 (C++ function), 378 ESP_BLE_MESH_GET_TRANSMIT_COUNT (C ESP_BLE_MESH_HEALTH_CLIENT_SET_STATE_EVT macro), 316 (C++ enumerator), 385 ESP_BLE_MESH_GET_TRANSMIT_INTERVAL (C esp_ble_mesh_health_client_set_state_t macro), 316 (C++ union), 378 esp_ble_mesh_health_attention_off_cb_t esp_ble_mesh_health_client_set_state_t::attention (C++ class), 383 (C++ member), 378 esp_ble_mesh_health_attention_off_cb_t:e:smpo_dbelle_mesh_health_client_set_state_t::fault_cle (C++ member), 383 (C++ member), 379 esp_ble_mesh_health_attention_on_cb_t esp_ble_mesh_health_client_set_state_t::fault_tes (C++ class), 383 (C++ member), 379 esp_ble_mesh_health_attention_on_cb_t::emsopd_eblle_mesh_health_client_set_state_t::period_se (C++ member), 383 (C++ member), 378 esp_ble_mesh_health_attention_on_cb_t::EtSiPm_eBLE_MESH_HEALTH_CLIENT_TIMEOUT_EVT (C++ member), 383 (C++ enumerator), 385 esp_ble_mesh_health_attention_set_t esp_ble_mesh_health_current_status_cb_t (C++ class), 380 (C++ class), 381 esp_ble_mesh_health_attention_set_t::atetsepn_tbiloen_mesh_health_current_status_cb_t::company_ (C++ member), 381 (C++ member), 381 esp_ble_mesh_health_attention_status_cbe_stp_ble_mesh_health_current_status_cb_t::fault_ar (C++ class), 382 (C++ member), 381 esp_ble_mesh_health_attention_status_cbe_stp:_:baltet_emnetsiho_nhealth_current_status_cb_t::test_id (C++ member), 382 (C++ member), 381 esp_ble_mesh_health_client_cb_event_t ESP_BLE_MESH_HEALTH_FAULT_ARRAY_SIZE (C++ enum), 385 (C macro), 385 esp_ble_mesh_health_client_cb_param_t esp_ble_mesh_health_fault_clear_cb_t (C++ class), 382 (C++ class), 382 esp_ble_mesh_health_client_cb_param_t::eesrpr_obrl_ec_omdeesh_health_fault_clear_cb_t::company_id (C++ member), 382 (C++ member), 382 esp_ble_mesh_health_client_cb_param_t::epsapr_abmlse_mesh_health_fault_clear_cb_t::model (C++ member), 382 (C++ member), 382 esp_ble_mesh_health_client_cb_param_t::esstpa_tbulse__cmbesh_health_fault_clear_t (C++ member), 382 (C++ class), 381 esp_ble_mesh_health_client_cb_t (C++ esp_ble_mesh_health_fault_clear_t::company_id type), 385 (C++ member), 381 esp_ble_mesh_health_client_common_cb_paersapm__btle_mesh_health_fault_get_t (C++ (C++ union), 379 class), 380 esp_ble_mesh_health_client_common_cb_paersapm__btl:e:_amtetsehn_thieoanl_tsht_aftauuslt_get_t::company_id (C++ member), 379 (C++ member), 380 esp_ble_mesh_health_client_common_cb_paersapm__btl:e:_cmuersrhe_nhte_aslttaht_ufsault_status_cb_t (C++ member), 379 (C++ class), 381 esp_ble_mesh_health_client_common_cb_paersapm__btl:e:_fmaeuslht__hsetaalttuhs_fault_status_cb_t::company_id (C++ member), 379 (C++ member), 381 esp_ble_mesh_health_client_common_cb_paersapm__btl:e:_pmeersiho_dh_esatlatthu_sfault_status_cb_t::fault_arra (C++ member), 379 (C++ member), 381 ESP_BLE_MESH_HEALTH_CLIENT_EVT_MAX esp_ble_mesh_health_fault_status_cb_t::test_id (C++ enumerator), 385 (C++ member), 381 esp_ble_mesh_health_client_get_state esp_ble_mesh_health_fault_test_cb_t (C++ function), 378 (C++ class), 382 Espressif Systems 2098 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_health_fault_test_cb_t::coEmSpPa_nByL_Ei_dMESH_HEALTH_SERVER_FAULT_UPDATE_COMP_EVT (C++ member), 383 (C++ enumerator), 385 esp_ble_mesh_health_fault_test_cb_t::moedsepl_ble_mesh_health_srv_cb_t (C++ class), (C++ member), 383 379 esp_ble_mesh_health_fault_test_cb_t::teesstp__ibdle_mesh_health_srv_cb_t::attention_off (C++ member), 383 (C++ member), 380 esp_ble_mesh_health_fault_test_t (C++ esp_ble_mesh_health_srv_cb_t::attention_on class), 381 (C++ member), 379 esp_ble_mesh_health_fault_test_t::compaensyp__ibdle_mesh_health_srv_cb_t::fault_clear (C++ member), 381 (C++ member), 379 esp_ble_mesh_health_fault_test_t::test_eisdp_ble_mesh_health_srv_cb_t::fault_test (C++ member), 381 (C++ member), 379 esp_ble_mesh_health_fault_update_comp_cebs_pt_ble_mesh_health_srv_t (C++ class), 380 (C++ class), 382 esp_ble_mesh_health_srv_t::attention_timer esp_ble_mesh_health_fault_update_comp_cb_t::el(Ce+m+enmtember), 380 (C++ member), 382 esp_ble_mesh_health_srv_t::attention_timer_start esp_ble_mesh_health_fault_update_comp_cb_t::er(Cr+o+r_mceomdbeer), 380 (C++ member), 382 esp_ble_mesh_health_srv_t::health_cb esp_ble_mesh_health_model_status_t (C++ member), 380 (C++ type), 330 esp_ble_mesh_health_srv_t::health_test esp_ble_mesh_health_period_set_t (C++ (C++ member), 380 class), 381 esp_ble_mesh_health_srv_t::model (C++ esp_ble_mesh_health_period_set_t::fast_period_mdeimvbiers)o, 3r80 (C++ member), 381 ESP_BLE_MESH_HEALTH_STANDARD_TEST (C esp_ble_mesh_health_period_status_cb_t macro), 383 (C++ class), 381 esp_ble_mesh_health_test_t (C++ class), esp_ble_mesh_health_period_status_cb_t::fast_p3e80riod_divisor (C++ member), 382 esp_ble_mesh_health_test_t::company_id ESP_BLE_MESH_HEALTH_PUB_DEFINE (C (C++ member), 380 macro), 383 esp_ble_mesh_health_test_t::current_faults ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_OFF_EVT (C++ member), 380 (C++ enumerator), 386 esp_ble_mesh_health_test_t::id_count ESP_BLE_MESH_HEALTH_SERVER_ATTENTION_ON_EVT (C++ member), 380 (C++ enumerator), 386 esp_ble_mesh_health_test_t::prev_test_id esp_ble_mesh_health_server_cb_event_t (C++ member), 380 (C++ enum), 385 esp_ble_mesh_health_test_t::registered_faults esp_ble_mesh_health_server_cb_param_t (C++ member), 380 (C++ union), 379 esp_ble_mesh_health_test_t::test_ids esp_ble_mesh_health_server_cb_param_t::attenti(Co+n+_omfefmber), 380 (C++ member), 379 ESP_BLE_MESH_HEARTBEAT_FILTER_ACCEPTLIST esp_ble_mesh_health_server_cb_param_t::attenti(Conm_aocrno), 318 (C++ member), 379 ESP_BLE_MESH_HEARTBEAT_FILTER_ADD (C esp_ble_mesh_health_server_cb_param_t::fault_cmlaecraor), 318 (C++ member), 379 esp_ble_mesh_heartbeat_filter_info_t esp_ble_mesh_health_server_cb_param_t::fault_t(Ce+s+t class), 312 (C++ member), 379 esp_ble_mesh_heartbeat_filter_info_t::hb_dst esp_ble_mesh_health_server_cb_param_t::fault_u(Cp+d+atmee_mcboemr)p, 312 (C++ member), 379 esp_ble_mesh_heartbeat_filter_info_t::hb_src esp_ble_mesh_health_server_cb_t (C++ (C++ member), 312 type), 385 ESP_BLE_MESH_HEARTBEAT_FILTER_REJECTLIST ESP_BLE_MESH_HEALTH_SERVER_EVT_MAX (C macro), 318 (C++ enumerator), 386 ESP_BLE_MESH_HEARTBEAT_FILTER_REMOVE ESP_BLE_MESH_HEALTH_SERVER_FAULT_CLEAR_EVT (C macro), 318 (C++ enumerator), 385 ESP_BLE_MESH_HEARTBEAT_MESSAGE_RECV_EVT ESP_BLE_MESH_HEALTH_SERVER_FAULT_TEST_EVT (C++ enumerator), 335 (C++ enumerator), 386 ESP_BLE_MESH_HOUSING_OPENED_ERROR (C esp_ble_mesh_health_server_fault_update macro), 384 (C++ function), 378 ESP_BLE_MESH_HOUSING_OPENED_WARNING (C Espressif Systems 2099 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index macro), 384 ESP_BLE_MESH_LC_RUN (C++ enumerator), 494 esp_ble_mesh_init (C++ function), 337 ESP_BLE_MESH_LC_STANDBY (C++ enumerator), esp_ble_mesh_input_action_t (C++ enum), 494 331 esp_ble_mesh_lc_state_t (C++ enum), 494 ESP_BLE_MESH_INPUT_NO_CHANGE_ERROR (C esp_ble_mesh_light_client_cb_event_t macro), 384 (C++ enum), 494 ESP_BLE_MESH_INPUT_NO_CHANGE_WARNING esp_ble_mesh_light_client_cb_param_t (C macro), 384 (C++ class), 470 ESP_BLE_MESH_INPUT_OOB (C++ enumerator), esp_ble_mesh_light_client_cb_param_t::error_code 331 (C++ member), 471 ESP_BLE_MESH_INPUT_TOO_HIGH_ERROR (C esp_ble_mesh_light_client_cb_param_t::params macro), 384 (C++ member), 471 ESP_BLE_MESH_INPUT_TOO_HIGH_WARNING (C esp_ble_mesh_light_client_cb_param_t::status_cb macro), 384 (C++ member), 471 ESP_BLE_MESH_INPUT_TOO_LOW_ERROR (C esp_ble_mesh_light_client_cb_t (C++ macro), 384 type), 494 ESP_BLE_MESH_INPUT_TOO_LOW_WARNING (C ESP_BLE_MESH_LIGHT_CLIENT_EVT_MAX macro), 384 (C++ enumerator), 494 ESP_BLE_MESH_INTERNAL_BUS_ERROR (C esp_ble_mesh_light_client_get_state macro), 385 (C++ function), 453 ESP_BLE_MESH_INTERNAL_BUS_WARNING (C ESP_BLE_MESH_LIGHT_CLIENT_GET_STATE_EVT macro), 385 (C++ enumerator), 494 ESP_BLE_MESH_INVALID_NODE_INDEX (C esp_ble_mesh_light_client_get_state_t macro), 316 (C++ union), 454 ESP_BLE_MESH_INVALID_SCENE_NUMBER (C esp_ble_mesh_light_client_get_state_t::lc_propert macro), 451 (C++ member), 454 ESP_BLE_MESH_INVALID_SENSOR_PROPERTY_IDESP_BLE_MESH_LIGHT_CLIENT_PUBLISH_EVT (C macro), 428 (C++ enumerator), 494 ESP_BLE_MESH_INVALID_SENSOR_SETTING_PROePsEpR_TbYl_eI_Dmesh_light_client_set_state (C macro), 429 (C++ function), 454 ESP_BLE_MESH_INVALID_SETTINGS_IDX (C ESP_BLE_MESH_LIGHT_CLIENT_SET_STATE_EVT macro), 315 (C++ enumerator), 494 esp_ble_mesh_is_model_subscribed_to_groeuspp_ble_mesh_light_client_set_state_t (C++ function), 338 (C++ union), 454 ESP_BLE_MESH_KEY_ANY (C macro), 315 esp_ble_mesh_light_client_set_state_t::ctl_defaul ESP_BLE_MESH_KEY_DEV (C macro), 315 (C++ member), 455 ESP_BLE_MESH_KEY_PRIMARY (C macro), 315 esp_ble_mesh_light_client_set_state_t::ctl_set ESP_BLE_MESH_KEY_UNUSED (C macro), 315 (C++ member), 454 esp_ble_mesh_last_msg_info_t (C++ class), esp_ble_mesh_light_client_set_state_t::ctl_temper 314 (C++ member), 454 esp_ble_mesh_last_msg_info_t::dst esp_ble_mesh_light_client_set_state_t::ctl_temper (C++ member), 314 (C++ member), 454 esp_ble_mesh_last_msg_info_t::src esp_ble_mesh_light_client_set_state_t::hsl_defaul (C++ member), 314 (C++ member), 455 esp_ble_mesh_last_msg_info_t::tid esp_ble_mesh_light_client_set_state_t::hsl_hue_se (C++ member), 314 (C++ member), 455 esp_ble_mesh_last_msg_info_t::timestampesp_ble_mesh_light_client_set_state_t::hsl_range_ (C++ member), 314 (C++ member), 455 ESP_BLE_MESH_LC_FADE (C++ enumerator), 494 esp_ble_mesh_light_client_set_state_t::hsl_satura ESP_BLE_MESH_LC_FADE_ON (C++ enumerator), (C++ member), 455 494 esp_ble_mesh_light_client_set_state_t::hsl_set ESP_BLE_MESH_LC_FADE_STANDBY_AUTO (C++ member), 455 (C++ enumerator), 494 esp_ble_mesh_light_client_set_state_t::lc_light_o ESP_BLE_MESH_LC_FADE_STANDBY_MANUAL (C++ member), 455 (C++ enumerator), 494 esp_ble_mesh_light_client_set_state_t::lc_mode_se ESP_BLE_MESH_LC_OFF (C++ enumerator), 494 (C++ member), 455 ESP_BLE_MESH_LC_PROLONG (C++ enumerator), esp_ble_mesh_light_client_set_state_t::lc_om_set 494 (C++ member), 455 Espressif Systems 2100 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_light_client_set_state_t::elscp__pbrloep_emretsyh__sleitght_client_status_cb_t::xyl_range_ (C++ member), 455 (C++ member), 456 esp_ble_mesh_light_client_set_state_t::elsipg_hbtlnee_smse_sdhe_flaiuglhtt__sceltient_status_cb_t::xyl_status (C++ member), 454 (C++ member), 456 esp_ble_mesh_light_client_set_state_t::elsipg_hbtlnee_smse_slhi_nleiagrh_ts_ectlient_status_cb_t::xyl_target (C++ member), 454 (C++ member), 456 esp_ble_mesh_light_client_set_state_t::ElSiPg_hBtLnEe_sMsE_SrHa_nLgIeG_HsTe_tCLIENT_TIMEOUT_EVT (C++ member), 454 (C++ enumerator), 494 esp_ble_mesh_light_client_set_state_t::elsipg_hbtlnee_smse_sshe_tlight_control_t (C++ class), (C++ member), 454 479 esp_ble_mesh_light_client_set_state_t::exsypl__bdleef_amuelsth__sleitght_control_t::prop_state (C++ member), 455 (C++ member), 480 esp_ble_mesh_light_client_set_state_t::exsypl__brlaen_gmee_sshe_tlight_control_t::state (C++ member), 455 (C++ member), 480 esp_ble_mesh_light_client_set_state_t::exsypl__bsleet_mesh_light_control_t::state_machine (C++ member), 455 (C++ member), 480 esp_ble_mesh_light_client_status_cb_t esp_ble_mesh_light_ctl_default_set_t (C++ union), 455 (C++ class), 461 esp_ble_mesh_light_client_status_cb_t::ecstpl__bdleef_amuelsth__sltiagthuts_ctl_default_set_t::delta_uv (C++ member), 456 (C++ member), 461 esp_ble_mesh_light_client_status_cb_t::ecstpl__bsltea_tmuessh_light_ctl_default_set_t::lightness (C++ member), 456 (C++ member), 461 esp_ble_mesh_light_client_status_cb_t::ecstpl__btleem_pmeersaht_ulrieg_hrta_ncgtel__sdteaftauuslt_set_t::temperature (C++ member), 456 (C++ member), 461 esp_ble_mesh_light_client_status_cb_t::ecstpl__btleem_pmeersaht_ulrieg_hstt_acttuls_default_status_cb_t (C++ member), 456 (C++ class), 466 esp_ble_mesh_light_client_status_cb_t::ehsspl__bdleef_amuelsth__sltiagthuts_ctl_default_status_cb_t::delta (C++ member), 456 (C++ member), 467 esp_ble_mesh_light_client_status_cb_t::ehsspl__bhluee__msetsaht_ulsight_ctl_default_status_cb_t::light (C++ member), 456 (C++ member), 467 esp_ble_mesh_light_client_status_cb_t::ehsspl__brlaen_gmee_ssht_altiugsht_ctl_default_status_cb_t::tempe (C++ member), 456 (C++ member), 467 esp_ble_mesh_light_client_status_cb_t::EhSsPl__BsLaEt_uMrEaStHi_oLnI_GsHtTa_tCuTsL_LIGHTNESS_STATE (C++ member), 456 (C++ enumerator), 336 esp_ble_mesh_light_client_status_cb_t::ehsspl__bsltea_tmuessh_light_ctl_set_t (C++ class), (C++ member), 456 460 esp_ble_mesh_light_client_status_cb_t::ehsspl__btlaer_gmeets_hs_tlaitguhst_ctl_set_t::ctl_delta_uv (C++ member), 456 (C++ member), 460 esp_ble_mesh_light_client_status_cb_t::elscp__lbilgeh_tm_eosnho_flfi_gshtta_tcutsl_set_t::ctl_lightness (C++ member), 456 (C++ member), 460 esp_ble_mesh_light_client_status_cb_t::elscp__mboldee__msetsaht_ulsight_ctl_set_t::ctl_temperatrue (C++ member), 456 (C++ member), 460 esp_ble_mesh_light_client_status_cb_t::elscp__obml_es_tmaetsuhs_light_ctl_set_t::delay (C++ member), 456 (C++ member), 460 esp_ble_mesh_light_client_status_cb_t::elscp__pbrloep_emretsyh__sltiagthuts_ctl_set_t::op_en (C++ member), 456 (C++ member), 460 esp_ble_mesh_light_client_status_cb_t::elsipg_hbtlnee_smse_sdhe_flaiuglhtt__scttalt_usset_t::tid (C++ member), 455 (C++ member), 460 esp_ble_mesh_light_client_status_cb_t::elsipg_hbtlnee_smse_slha_slti_gshtta_tcutsl_set_t::trans_time (C++ member), 455 (C++ member), 460 esp_ble_mesh_light_client_status_cb_t::elsipg_hbtlnee_smse_slhi_nleiagrh_ts_tcattlu_ssetup_srv_t (C++ member), 455 (C++ class), 473 esp_ble_mesh_light_client_status_cb_t::elsipg_hbtlnee_smse_srha_nlgieg_hstt_acttuls_setup_srv_t::model (C++ member), 456 (C++ member), 473 esp_ble_mesh_light_client_status_cb_t::elsipg_hbtlnee_smse_ssht_altiugsht_ctl_setup_srv_t::rsp_ctrl (C++ member), 455 (C++ member), 473 esp_ble_mesh_light_client_status_cb_t::exsypl__bdleef_amuelsth__sltiagthuts_ctl_setup_srv_t::state (C++ member), 456 (C++ member), 473 Espressif Systems 2101 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_light_ctl_srv_t (C++ class), ESP_BLE_MESH_LIGHT_CTL_TEMP_DELTA_UV_STATE 472 (C++ enumerator), 336 esp_ble_mesh_light_ctl_srv_t::last esp_ble_mesh_light_ctl_temp_srv_t (C++ member), 473 (C++ class), 473 esp_ble_mesh_light_ctl_srv_t::model esp_ble_mesh_light_ctl_temp_srv_t::last (C++ member), 473 (C++ member), 473 esp_ble_mesh_light_ctl_srv_t::rsp_ctrl esp_ble_mesh_light_ctl_temp_srv_t::model (C++ member), 473 (C++ member), 473 esp_ble_mesh_light_ctl_srv_t::state esp_ble_mesh_light_ctl_temp_srv_t::rsp_ctrl (C++ member), 473 (C++ member), 473 esp_ble_mesh_light_ctl_srv_t::transitioensp_ble_mesh_light_ctl_temp_srv_t::state (C++ member), 473 (C++ member), 473 esp_ble_mesh_light_ctl_srv_t::tt_delta_edsepl_tbal_eu_vmesh_light_ctl_temp_srv_t::transition (C++ member), 473 (C++ member), 473 esp_ble_mesh_light_ctl_srv_t::tt_delta_elsipg_hbtlnee_smsesh_light_ctl_temp_srv_t::tt_delta_delta (C++ member), 473 (C++ member), 473 esp_ble_mesh_light_ctl_srv_t::tt_delta_etsepm_pbelrea_tmuerseh_light_ctl_temp_srv_t::tt_delta_tempe (C++ member), 473 (C++ member), 473 esp_ble_mesh_light_ctl_state_t (C++ esp_ble_mesh_light_ctl_temperature_range_set_t class), 472 (C++ class), 461 esp_ble_mesh_light_ctl_state_t::delta_uevsp_ble_mesh_light_ctl_temperature_range_set_t::r (C++ member), 472 (C++ member), 461 esp_ble_mesh_light_ctl_state_t::delta_uevs_pd_ebflaeu_lmtesh_light_ctl_temperature_range_set_t::r (C++ member), 472 (C++ member), 461 esp_ble_mesh_light_ctl_state_t::lightneesssp_ble_mesh_light_ctl_temperature_range_status_c (C++ member), 472 (C++ class), 466 esp_ble_mesh_light_ctl_state_t::lightneesssp__dbelfea_umletsh_light_ctl_temperature_range_status_c (C++ member), 472 (C++ member), 466 esp_ble_mesh_light_ctl_state_t::status_ecsopd_eble_mesh_light_ctl_temperature_range_status_c (C++ member), 472 (C++ member), 466 esp_ble_mesh_light_ctl_state_t::target_edsepl_tbal_eu_vmesh_light_ctl_temperature_range_status_c (C++ member), 472 (C++ member), 466 esp_ble_mesh_light_ctl_state_t::target_elsipg_hbtlnee_smsesh_light_ctl_temperature_set_t (C++ member), 472 (C++ class), 460 esp_ble_mesh_light_ctl_state_t::target_etsepm_pbelrea_tmuerseh_light_ctl_temperature_set_t::ctl_del (C++ member), 472 (C++ member), 460 esp_ble_mesh_light_ctl_state_t::temperaetsupr_eble_mesh_light_ctl_temperature_set_t::ctl_tem (C++ member), 472 (C++ member), 460 esp_ble_mesh_light_ctl_state_t::temperaetsupr_eb_ldee_fmaeuslht_light_ctl_temperature_set_t::delay (C++ member), 472 (C++ member), 461 esp_ble_mesh_light_ctl_state_t::temperaetsupr_eb_lrea_nmgees_hm_alxight_ctl_temperature_set_t::op_en (C++ member), 472 (C++ member), 460 esp_ble_mesh_light_ctl_state_t::temperaetsupr_eb_lrea_nmgees_hm_ilnight_ctl_temperature_set_t::tid (C++ member), 472 (C++ member), 460 esp_ble_mesh_light_ctl_status_cb_t esp_ble_mesh_light_ctl_temperature_set_t::trans_t (C++ class), 465 (C++ member), 461 esp_ble_mesh_light_ctl_status_cb_t::op_eesnp_ble_mesh_light_ctl_temperature_status_cb_t (C++ member), 466 (C++ class), 466 esp_ble_mesh_light_ctl_status_cb_t::preessepn_tb_lcet_lm_elsihg_hltingehsts_ctl_temperature_status_cb_t::o (C++ member), 466 (C++ member), 466 esp_ble_mesh_light_ctl_status_cb_t::preessepn_tb_lcet_lm_etsehm_pleirgahttu_rcetl_temperature_status_cb_t::p (C++ member), 466 (C++ member), 466 esp_ble_mesh_light_ctl_status_cb_t::remeasipn__btliem_emesh_light_ctl_temperature_status_cb_t::p (C++ member), 466 (C++ member), 466 esp_ble_mesh_light_ctl_status_cb_t::taregsept__bcltel__mleisghh_tlniegshst_ctl_temperature_status_cb_t::r (C++ member), 466 (C++ member), 466 esp_ble_mesh_light_ctl_status_cb_t::taregsept__bcltel__mteesmhp_elriagthutr_ectl_temperature_status_cb_t::t (C++ member), 466 (C++ member), 466 Espressif Systems 2102 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_light_ctl_temperature_stateussp__cbbl_et_:m:etsahr_gleitg_hctt_lh_stle_mrpaenrgaet_usreet_t (C++ member), 466 (C++ class), 462 esp_ble_mesh_light_hsl_default_set_t esp_ble_mesh_light_hsl_range_set_t::hue_range_max (C++ class), 462 (C++ member), 462 esp_ble_mesh_light_hsl_default_set_t::heusep_ble_mesh_light_hsl_range_set_t::hue_range_min (C++ member), 462 (C++ member), 462 esp_ble_mesh_light_hsl_default_set_t::leisgph_tbnlees_smesh_light_hsl_range_set_t::saturation_ra (C++ member), 462 (C++ member), 463 esp_ble_mesh_light_hsl_default_set_t::seastpu_rbaltei_omnesh_light_hsl_range_set_t::saturation_ra (C++ member), 462 (C++ member), 462 esp_ble_mesh_light_hsl_default_status_cebs_pt_ble_mesh_light_hsl_range_status_cb_t (C++ class), 468 (C++ class), 468 esp_ble_mesh_light_hsl_default_status_cebs_pt_:b:lheu_emesh_light_hsl_range_status_cb_t::hue_ran (C++ member), 468 (C++ member), 468 esp_ble_mesh_light_hsl_default_status_cebs_pt_:b:llei_gmhetsnhe_slsight_hsl_range_status_cb_t::hue_ran (C++ member), 468 (C++ member), 468 esp_ble_mesh_light_hsl_default_status_cebs_pt_:b:lsea_tmuersaht_iloinght_hsl_range_status_cb_t::saturat (C++ member), 468 (C++ member), 468 esp_ble_mesh_light_hsl_hue_set_t (C++ esp_ble_mesh_light_hsl_range_status_cb_t::saturat class), 461 (C++ member), 468 esp_ble_mesh_light_hsl_hue_set_t::delayesp_ble_mesh_light_hsl_range_status_cb_t::status_ (C++ member), 462 (C++ member), 468 esp_ble_mesh_light_hsl_hue_set_t::hue esp_ble_mesh_light_hsl_sat_srv_t (C++ (C++ member), 462 class), 475 esp_ble_mesh_light_hsl_hue_set_t::op_enesp_ble_mesh_light_hsl_sat_srv_t::last (C++ member), 462 (C++ member), 475 esp_ble_mesh_light_hsl_hue_set_t::tid esp_ble_mesh_light_hsl_sat_srv_t::model (C++ member), 462 (C++ member), 475 esp_ble_mesh_light_hsl_hue_set_t::transe_stpi_mbele_mesh_light_hsl_sat_srv_t::rsp_ctrl (C++ member), 462 (C++ member), 475 esp_ble_mesh_light_hsl_hue_srv_t (C++ esp_ble_mesh_light_hsl_sat_srv_t::state class), 475 (C++ member), 475 esp_ble_mesh_light_hsl_hue_srv_t::last esp_ble_mesh_light_hsl_sat_srv_t::transition (C++ member), 475 (C++ member), 475 esp_ble_mesh_light_hsl_hue_srv_t::modelesp_ble_mesh_light_hsl_sat_srv_t::tt_delta_satura (C++ member), 475 (C++ member), 476 esp_ble_mesh_light_hsl_hue_srv_t::rsp_cetsrpl_ble_mesh_light_hsl_saturation_set_t (C++ member), 475 (C++ class), 462 esp_ble_mesh_light_hsl_hue_srv_t::stateesp_ble_mesh_light_hsl_saturation_set_t::delay (C++ member), 475 (C++ member), 462 esp_ble_mesh_light_hsl_hue_srv_t::transeistpi_obnle_mesh_light_hsl_saturation_set_t::op_en (C++ member), 475 (C++ member), 462 esp_ble_mesh_light_hsl_hue_srv_t::tt_deelstpa__bhluee_mesh_light_hsl_saturation_set_t::saturati (C++ member), 475 (C++ member), 462 ESP_BLE_MESH_LIGHT_HSL_HUE_STATE (C++ esp_ble_mesh_light_hsl_saturation_set_t::tid enumerator), 336 (C++ member), 462 esp_ble_mesh_light_hsl_hue_status_cb_t esp_ble_mesh_light_hsl_saturation_set_t::trans_ti (C++ class), 467 (C++ member), 462 esp_ble_mesh_light_hsl_hue_status_cb_t:E:SoPp__BeLnE_MESH_LIGHT_HSL_SATURATION_STATE (C++ member), 467 (C++ enumerator), 336 esp_ble_mesh_light_hsl_hue_status_cb_t:e:sppr_ebsleen_tm_ehsuhe_light_hsl_saturation_status_cb_t (C++ member), 467 (C++ class), 468 esp_ble_mesh_light_hsl_hue_status_cb_t:e:srpe_mbalien__mteismhe_light_hsl_saturation_status_cb_t::op (C++ member), 468 (C++ member), 468 esp_ble_mesh_light_hsl_hue_status_cb_t:e:stpa_rbgleet__mheuseh_light_hsl_saturation_status_cb_t::pr (C++ member), 467 (C++ member), 468 ESP_BLE_MESH_LIGHT_HSL_LIGHTNESS_STATE esp_ble_mesh_light_hsl_saturation_status_cb_t::re (C++ enumerator), 336 (C++ member), 468 Espressif Systems 2103 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_light_hsl_saturation_statuess_pc_bb_lte:_:mteasrhg_elti_gshatt_uhrsalt_isotnate_t::lightness_default (C++ member), 468 (C++ member), 474 esp_ble_mesh_light_hsl_set_t (C++ class), esp_ble_mesh_light_hsl_state_t::saturation 461 (C++ member), 474 esp_ble_mesh_light_hsl_set_t::delay esp_ble_mesh_light_hsl_state_t::saturation_defaul (C++ member), 461 (C++ member), 474 esp_ble_mesh_light_hsl_set_t::hsl_hue esp_ble_mesh_light_hsl_state_t::saturation_range_ (C++ member), 461 (C++ member), 474 esp_ble_mesh_light_hsl_set_t::hsl_lightenseps_sble_mesh_light_hsl_state_t::saturation_range_ (C++ member), 461 (C++ member), 474 esp_ble_mesh_light_hsl_set_t::hsl_satureastpi_obnle_mesh_light_hsl_state_t::status_code (C++ member), 461 (C++ member), 474 esp_ble_mesh_light_hsl_set_t::op_en esp_ble_mesh_light_hsl_state_t::target_hue (C++ member), 461 (C++ member), 474 esp_ble_mesh_light_hsl_set_t::tid esp_ble_mesh_light_hsl_state_t::target_lightness (C++ member), 461 (C++ member), 474 esp_ble_mesh_light_hsl_set_t::trans_timeesp_ble_mesh_light_hsl_state_t::target_saturation (C++ member), 461 (C++ member), 474 esp_ble_mesh_light_hsl_setup_srv_t esp_ble_mesh_light_hsl_status_cb_t (C++ class), 475 (C++ class), 467 esp_ble_mesh_light_hsl_setup_srv_t::modeeslp_ble_mesh_light_hsl_status_cb_t::hsl_hue (C++ member), 475 (C++ member), 467 esp_ble_mesh_light_hsl_setup_srv_t::rspe_scpt_rblle_mesh_light_hsl_status_cb_t::hsl_lightness (C++ member), 475 (C++ member), 467 esp_ble_mesh_light_hsl_setup_srv_t::staetsep_ble_mesh_light_hsl_status_cb_t::hsl_saturatio (C++ member), 475 (C++ member), 467 esp_ble_mesh_light_hsl_srv_t (C++ class), esp_ble_mesh_light_hsl_status_cb_t::op_en 474 (C++ member), 467 esp_ble_mesh_light_hsl_srv_t::last esp_ble_mesh_light_hsl_status_cb_t::remain_time (C++ member), 474 (C++ member), 467 esp_ble_mesh_light_hsl_srv_t::model esp_ble_mesh_light_hsl_target_status_cb_t (C++ member), 474 (C++ class), 467 esp_ble_mesh_light_hsl_srv_t::rsp_ctrl esp_ble_mesh_light_hsl_target_status_cb_t::hsl_hu (C++ member), 474 (C++ member), 467 esp_ble_mesh_light_hsl_srv_t::state esp_ble_mesh_light_hsl_target_status_cb_t::hsl_li (C++ member), 474 (C++ member), 467 esp_ble_mesh_light_hsl_srv_t::transitioensp_ble_mesh_light_hsl_target_status_cb_t::hsl_sa (C++ member), 474 (C++ member), 467 esp_ble_mesh_light_hsl_srv_t::tt_delta_ehsupe_ble_mesh_light_hsl_target_status_cb_t::op_en (C++ member), 475 (C++ member), 467 esp_ble_mesh_light_hsl_srv_t::tt_delta_elsipg_hbtlnee_smsesh_light_hsl_target_status_cb_t::remain (C++ member), 474 (C++ member), 467 esp_ble_mesh_light_hsl_srv_t::tt_delta_essapt_ubrlaet_imoensh_light_lc_light_onoff_set_t (C++ member), 475 (C++ class), 464 ESP_BLE_MESH_LIGHT_HSL_STATE (C++ enu- esp_ble_mesh_light_lc_light_onoff_set_t::delay merator), 336 (C++ member), 464 esp_ble_mesh_light_hsl_state_t (C++ esp_ble_mesh_light_lc_light_onoff_set_t::light_on class), 473 (C++ member), 464 esp_ble_mesh_light_hsl_state_t::hue esp_ble_mesh_light_lc_light_onoff_set_t::op_en (C++ member), 474 (C++ member), 464 esp_ble_mesh_light_hsl_state_t::hue_defeasupl_tble_mesh_light_lc_light_onoff_set_t::tid (C++ member), 474 (C++ member), 464 esp_ble_mesh_light_hsl_state_t::hue_ranegsep__mbalxe_mesh_light_lc_light_onoff_set_t::trans_ti (C++ member), 474 (C++ member), 464 esp_ble_mesh_light_hsl_state_t::hue_ranEgSeP__mBiLnE_MESH_LIGHT_LC_LIGHT_ONOFF_STATE (C++ member), 474 (C++ enumerator), 336 esp_ble_mesh_light_hsl_state_t::lightneesssp_ble_mesh_light_lc_light_onoff_status_cb_t (C++ member), 474 (C++ class), 470 Espressif Systems 2104 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_light_lc_light_onoff_statuess_pc_bb_lte:_:moeps_he_nlight_lc_property_state_t::set_occup (C++ member), 470 (C++ member), 479 esp_ble_mesh_light_lc_light_onoff_statuess_pc_bb_lte:_:mpersehs_elnitg_hlti_glhct__pornoopfefrty_state_t::time_fade (C++ member), 470 (C++ member), 478 esp_ble_mesh_light_lc_light_onoff_statuess_pc_bb_lte:_:mreesmha_ilni_gthitm_elc_property_state_t::time_fade (C++ member), 470 (C++ member), 478 esp_ble_mesh_light_lc_light_onoff_statuess_pc_bb_lte:_:mteasrhg_elti_glhitg_hltc__opnroofpferty_state_t::time_fade (C++ member), 470 (C++ member), 478 esp_ble_mesh_light_lc_mode_set_t (C++ esp_ble_mesh_light_lc_property_state_t::time_fade class), 463 (C++ member), 478 esp_ble_mesh_light_lc_mode_set_t::mode esp_ble_mesh_light_lc_property_state_t::time_occu (C++ member), 464 (C++ member), 478 esp_ble_mesh_light_lc_mode_status_cb_t esp_ble_mesh_light_lc_property_state_t::time_prol (C++ class), 470 (C++ member), 478 esp_ble_mesh_light_lc_mode_status_cb_t:e:smpo_dbele_mesh_light_lc_property_state_t::time_run_ (C++ member), 470 (C++ member), 478 esp_ble_mesh_light_lc_om_set_t (C++ esp_ble_mesh_light_lc_property_status_cb_t class), 464 (C++ class), 470 esp_ble_mesh_light_lc_om_set_t::mode esp_ble_mesh_light_lc_property_status_cb_t::prope (C++ member), 464 (C++ member), 470 esp_ble_mesh_light_lc_om_status_cb_t esp_ble_mesh_light_lc_property_status_cb_t::prope (C++ class), 470 (C++ member), 470 esp_ble_mesh_light_lc_om_status_cb_t::meosdpe_ble_mesh_light_lc_setup_srv_t (C++ member), 470 (C++ class), 480 esp_ble_mesh_light_lc_property_get_t esp_ble_mesh_light_lc_setup_srv_t::lc (C++ class), 464 (C++ member), 480 esp_ble_mesh_light_lc_property_get_t::persopp_ebrltey__miedsh_light_lc_setup_srv_t::model (C++ member), 464 (C++ member), 480 esp_ble_mesh_light_lc_property_set_t esp_ble_mesh_light_lc_setup_srv_t::rsp_ctrl (C++ class), 464 (C++ member), 480 esp_ble_mesh_light_lc_property_set_t::persopp_ebrltey__miedsh_light_lc_srv_t (C++ class), (C++ member), 464 480 esp_ble_mesh_light_lc_property_set_t::persopp_ebrltey__mveaslhu_elight_lc_srv_t::last (C++ member), 464 (C++ member), 480 esp_ble_mesh_light_lc_property_state_t esp_ble_mesh_light_lc_srv_t::lc (C++ (C++ class), 477 member), 480 esp_ble_mesh_light_lc_property_state_t:e:sapm_bbileen_tm_elsuhx_lleivgehlt__olnc_srv_t::model (C++ member), 478 (C++ member), 480 esp_ble_mesh_light_lc_property_state_t:e:sapm_bbileen_tm_elsuhx_lleivgehlt__plrco_lsornvg_t::rsp_ctrl (C++ member), 478 (C++ member), 480 esp_ble_mesh_light_lc_property_state_t:e:sapm_bbileen_tm_elsuhx_lleivgehlt__sltca_nsdrbvy_t::transition (C++ member), 478 (C++ member), 480 esp_ble_mesh_light_lc_property_state_t:e:slpi_gbhlten_emsess_ho_nlight_lc_state_machine_t (C++ member), 478 (C++ class), 479 esp_ble_mesh_light_lc_property_state_t:e:slpi_gbhlten_emsess_hp_rloilgohntg_lc_state_machine_t::fade (C++ member), 478 (C++ member), 479 esp_ble_mesh_light_lc_property_state_t:e:slpi_gbhlten_emsess_hs_tlaingdhbty_lc_state_machine_t::fade_on (C++ member), 478 (C++ member), 479 esp_ble_mesh_light_lc_property_state_t:e:srpe_gbullea_tmoers_ha_clciugrhatc_ylc_state_machine_t::fade_stand (C++ member), 479 (C++ member), 479 esp_ble_mesh_light_lc_property_state_t:e:srpe_gbullea_tmoers_hk_ildight_lc_state_machine_t::fade_stand (C++ member), 479 (C++ member), 479 esp_ble_mesh_light_lc_property_state_t:e:srpe_gbullea_tmoers_hk_iluight_lc_state_machine_t::state (C++ member), 478 (C++ member), 479 esp_ble_mesh_light_lc_property_state_t:e:srpe_gbullea_tmoers_hk_pldight_lc_state_machine_t::timer (C++ member), 479 (C++ member), 479 esp_ble_mesh_light_lc_property_state_t:e:srpe_gbullea_tmoers_hk_pluight_lc_state_machine_t::trans_time (C++ member), 479 (C++ member), 479 Espressif Systems 2105 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_light_lc_state_t (C++ esp_ble_mesh_light_lightness_range_set_t::range_m class), 477 (C++ member), 460 esp_ble_mesh_light_lc_state_t::ambient_elsupx_lbelvee_lmesh_light_lightness_range_status_cb_t (C++ member), 477 (C++ class), 465 esp_ble_mesh_light_lc_state_t::light_oneosfpf_ble_mesh_light_lightness_range_status_cb_t::r (C++ member), 477 (C++ member), 465 esp_ble_mesh_light_lc_state_t::linear_oeustpp_ubtle_mesh_light_lightness_range_status_cb_t::r (C++ member), 477 (C++ member), 465 esp_ble_mesh_light_lc_state_t::mode esp_ble_mesh_light_lightness_range_status_cb_t::s (C++ member), 477 (C++ member), 465 esp_ble_mesh_light_lc_state_t::occupanceysp_ble_mesh_light_lightness_set_t (C++ member), 477 (C++ class), 459 esp_ble_mesh_light_lc_state_t::occupanceys_pm_obdlee_mesh_light_lightness_set_t::delay (C++ member), 477 (C++ member), 459 esp_ble_mesh_light_lc_state_t::target_leisgph_tb_loen_omfefsh_light_lightness_set_t::lightness (C++ member), 477 (C++ member), 459 ESP_BLE_MESH_LIGHT_LIGHTNESS_ACTUAL_STAeTsEp_ble_mesh_light_lightness_set_t::op_en (C++ enumerator), 336 (C++ member), 459 esp_ble_mesh_light_lightness_default_seets_pt_ble_mesh_light_lightness_set_t::tid (C++ class), 460 (C++ member), 459 esp_ble_mesh_light_lightness_default_seets_pt_:b:llei_gmhetsnhe_slsight_lightness_set_t::trans_time (C++ member), 460 (C++ member), 459 esp_ble_mesh_light_lightness_default_steastpu_sb_lceb__mtesh_light_lightness_setup_srv_t (C++ class), 465 (C++ class), 472 esp_ble_mesh_light_lightness_default_steastpu_sb_lceb__mte:s:hl_ilgihgthnte_slsightness_setup_srv_t::model (C++ member), 465 (C++ member), 472 esp_ble_mesh_light_lightness_last_statuess_pc_bb_lte_mesh_light_lightness_setup_srv_t::rsp_ctr (C++ class), 465 (C++ member), 472 esp_ble_mesh_light_lightness_last_statuess_pc_bb_lte:_:mleisghh_tlniegshst_lightness_setup_srv_t::state (C++ member), 465 (C++ member), 472 esp_ble_mesh_light_lightness_linear_sete_stp_ble_mesh_light_lightness_srv_t (C++ class), 459 (C++ class), 471 esp_ble_mesh_light_lightness_linear_sete_stp:_:bdleel_amyesh_light_lightness_srv_t::actual_transi (C++ member), 459 (C++ member), 471 esp_ble_mesh_light_lightness_linear_sete_stp:_:bllieg_hmtensehs_slight_lightness_srv_t::last (C++ member), 459 (C++ member), 471 esp_ble_mesh_light_lightness_linear_sete_stp:_:bolpe__emnesh_light_lightness_srv_t::linear_transi (C++ member), 459 (C++ member), 471 esp_ble_mesh_light_lightness_linear_sete_stp:_:btlied_mesh_light_lightness_srv_t::model (C++ member), 459 (C++ member), 471 esp_ble_mesh_light_lightness_linear_sete_stp:_:btlrea_nmse_sthi_mleight_lightness_srv_t::rsp_ctrl (C++ member), 459 (C++ member), 471 ESP_BLE_MESH_LIGHT_LIGHTNESS_LINEAR_STAeTsEp_ble_mesh_light_lightness_srv_t::state (C++ enumerator), 336 (C++ member), 471 esp_ble_mesh_light_lightness_linear_staetsups__bclbe__tmesh_light_lightness_srv_t::tt_delta_ligh (C++ class), 465 (C++ member), 471 esp_ble_mesh_light_lightness_linear_staetsups__bclbe__tm:e:sohp__leinght_lightness_srv_t::tt_delta_ligh (C++ member), 465 (C++ member), 472 esp_ble_mesh_light_lightness_linear_staetsups__bclbe__tm:e:sphr_elsiegnhtt__lliigghhttnneessss_state_t (C++ member), 465 (C++ class), 471 esp_ble_mesh_light_lightness_linear_staetsups__bclbe__tm:e:srhe_mlaiignh_tt_ilmieghtness_state_t::lightness_a (C++ member), 465 (C++ member), 471 esp_ble_mesh_light_lightness_linear_staetsups__bclbe__tm:e:stha_rlgiegth_tl_ilgihgthntensesss_state_t::lightness_d (C++ member), 465 (C++ member), 471 esp_ble_mesh_light_lightness_range_set_etsp_ble_mesh_light_lightness_state_t::lightness_l (C++ class), 460 (C++ member), 471 esp_ble_mesh_light_lightness_range_set_ets:p:_rbalneg_em_emsahx_light_lightness_state_t::lightness_l (C++ member), 460 (C++ member), 471 Espressif Systems 2106 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_light_lightness_state_t::leisgph_tbnlees_sm_ersahn_glei_gmhatx_xyl_range_status_cb_t::xyl_y_r (C++ member), 471 (C++ member), 470 esp_ble_mesh_light_lightness_state_t::leisgph_tbnlees_sm_ersahn_glei_gmhitn_xyl_range_status_cb_t::xyl_y_r (C++ member), 471 (C++ member), 470 esp_ble_mesh_light_lightness_state_t::setsapt_ubsl_ec_omdeesh_light_xyl_set_t (C++ class), (C++ member), 471 463 esp_ble_mesh_light_lightness_state_t::teasrpg_ebtl_el_imgehsthn_elsisg_hatc_txuyall_set_t::delay (C++ member), 471 (C++ member), 463 esp_ble_mesh_light_lightness_state_t::teasrpg_ebtl_el_imgehsthn_elsisg_hlti_nxeyalr_set_t::op_en (C++ member), 471 (C++ member), 463 esp_ble_mesh_light_lightness_status_cb_etsp_ble_mesh_light_xyl_set_t::tid (C++ class), 464 (C++ member), 463 esp_ble_mesh_light_lightness_status_cb_ets:p:_obpl_ee_nmesh_light_xyl_set_t::trans_time (C++ member), 465 (C++ member), 463 esp_ble_mesh_light_lightness_status_cb_ets:p:_pbrlees_emnets_hl_ilgihgthnte_sxsyl_set_t::xyl_lightness (C++ member), 465 (C++ member), 463 esp_ble_mesh_light_lightness_status_cb_ets:p:_rbelmea_imne_sthi_mleight_xyl_set_t::xyl_x (C++ member), 465 (C++ member), 463 esp_ble_mesh_light_lightness_status_cb_ets:p:_tbalreg_emte_slhi_glhitgnhets_sxyl_set_t::xyl_y (C++ member), 465 (C++ member), 463 esp_ble_mesh_light_message_opcode_t esp_ble_mesh_light_xyl_setup_srv_t (C++ type), 330 (C++ class), 477 esp_ble_mesh_light_xyl_default_set_t esp_ble_mesh_light_xyl_setup_srv_t::model (C++ class), 463 (C++ member), 477 esp_ble_mesh_light_xyl_default_set_t::leisgph_tbnlees_smesh_light_xyl_setup_srv_t::rsp_ctrl (C++ member), 463 (C++ member), 477 esp_ble_mesh_light_xyl_default_set_t::xeyslp__xble_mesh_light_xyl_setup_srv_t::state (C++ member), 463 (C++ member), 477 esp_ble_mesh_light_xyl_default_set_t::xeyslp__yble_mesh_light_xyl_srv_t (C++ class), (C++ member), 463 476 esp_ble_mesh_light_xyl_default_status_cebs_pt_ble_mesh_light_xyl_srv_t::last (C++ class), 469 (C++ member), 477 esp_ble_mesh_light_xyl_default_status_cebs_pt_:b:llei_gmhetsnhe_slsight_xyl_srv_t::model (C++ member), 469 (C++ member), 476 esp_ble_mesh_light_xyl_default_status_cebs_pt_:b:lxey_lm_exsh_light_xyl_srv_t::rsp_ctrl (C++ member), 469 (C++ member), 476 esp_ble_mesh_light_xyl_default_status_cebs_pt_:b:lxey_lm_eysh_light_xyl_srv_t::state (C++ member), 469 (C++ member), 476 ESP_BLE_MESH_LIGHT_XYL_LIGHTNESS_STATE esp_ble_mesh_light_xyl_srv_t::transition (C++ enumerator), 336 (C++ member), 477 esp_ble_mesh_light_xyl_range_set_t esp_ble_mesh_light_xyl_srv_t::tt_delta_lightness (C++ class), 463 (C++ member), 477 esp_ble_mesh_light_xyl_range_set_t::xyle_sxp__rbalneg_em_emsahx_light_xyl_srv_t::tt_delta_x (C++ member), 463 (C++ member), 477 esp_ble_mesh_light_xyl_range_set_t::xyle_sxp__rbalneg_em_emsihn_light_xyl_srv_t::tt_delta_y (C++ member), 463 (C++ member), 477 esp_ble_mesh_light_xyl_range_set_t::xyle_syp__rbalneg_em_emsahx_light_xyl_state_t (C++ (C++ member), 463 class), 476 esp_ble_mesh_light_xyl_range_set_t::xyle_syp__rbalneg_em_emsihn_light_xyl_state_t::lightness (C++ member), 463 (C++ member), 476 esp_ble_mesh_light_xyl_range_status_cb_etsp_ble_mesh_light_xyl_state_t::lightness_default (C++ class), 469 (C++ member), 476 esp_ble_mesh_light_xyl_range_status_cb_ets:p:_sbtlaet_umse_scho_dleight_xyl_state_t::status_code (C++ member), 469 (C++ member), 476 esp_ble_mesh_light_xyl_range_status_cb_ets:p:_xbylle__xm_ersahn_glei_gmhatx_xyl_state_t::target_lightness (C++ member), 469 (C++ member), 476 esp_ble_mesh_light_xyl_range_status_cb_ets:p:_xbylle__xm_ersahn_glei_gmhitn_xyl_state_t::target_x (C++ member), 469 (C++ member), 476 Espressif Systems 2107 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_light_xyl_state_t::target_eysp_ble_mesh_lighting_server_cb_value_t::set (C++ member), 476 (C++ member), 459 esp_ble_mesh_light_xyl_state_t::x esp_ble_mesh_lighting_server_cb_value_t::state_ch (C++ member), 476 (C++ member), 459 esp_ble_mesh_light_xyl_state_t::x_defauelstp_ble_mesh_lighting_server_cb_value_t::status (C++ member), 476 (C++ member), 459 esp_ble_mesh_light_xyl_state_t::x_rangeE_SmPa_xBLE_MESH_LIGHTING_SERVER_EVT_MAX (C++ member), 476 (C++ enumerator), 495 esp_ble_mesh_light_xyl_state_t::x_rangeE_SmPi_nBLE_MESH_LIGHTING_SERVER_RECV_GET_MSG_EVT (C++ member), 476 (C++ enumerator), 495 esp_ble_mesh_light_xyl_state_t::y esp_ble_mesh_lighting_server_recv_get_msg_t (C++ member), 476 (C++ union), 457 esp_ble_mesh_light_xyl_state_t::y_defauelstp_ble_mesh_lighting_server_recv_get_msg_t::lc_p (C++ member), 476 (C++ member), 457 esp_ble_mesh_light_xyl_state_t::y_rangeE_SmPa_xBLE_MESH_LIGHTING_SERVER_RECV_SET_MSG_EVT (C++ member), 476 (C++ enumerator), 495 esp_ble_mesh_light_xyl_state_t::y_rangee_smpi_nble_mesh_lighting_server_recv_set_msg_t (C++ member), 476 (C++ union), 457 esp_ble_mesh_light_xyl_status_cb_t esp_ble_mesh_lighting_server_recv_set_msg_t::ctl (C++ class), 468 (C++ member), 458 esp_ble_mesh_light_xyl_status_cb_t::op_eesnp_ble_mesh_lighting_server_recv_set_msg_t::ctl_ (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_status_cb_t::remeasipn__btliem_emesh_lighting_server_recv_set_msg_t::ctl_ (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_status_cb_t::xyle_slpi_gbhlten_emsessh_lighting_server_recv_set_msg_t::ctl_ (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_status_cb_t::xyle_sxp_ble_mesh_lighting_server_recv_set_msg_t::hsl (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_status_cb_t::xyle_syp_ble_mesh_lighting_server_recv_set_msg_t::hsl_ (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_target_status_cbe_stp_ble_mesh_lighting_server_recv_set_msg_t::hsl_ (C++ class), 469 (C++ member), 458 esp_ble_mesh_light_xyl_target_status_cbe_stp:_:bolpe__emnesh_lighting_server_recv_set_msg_t::hsl_ (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_target_status_cbe_stp:_:brleem_amiens_ht_ilmieghting_server_recv_set_msg_t::hsl_ (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_target_status_cbe_stp:_:btlaer_gmeets_hx_ylli_glhitgihntgn_essesrver_recv_set_msg_t::lc_l (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_target_status_cbe_stp:_:btlaer_gmeets_hx_ylli_gxhting_server_recv_set_msg_t::lc_m (C++ member), 469 (C++ member), 458 esp_ble_mesh_light_xyl_target_status_cbe_stp:_:btlaer_gmeets_hx_ylli_gyhting_server_recv_set_msg_t::lc_o (C++ member), 469 (C++ member), 458 esp_ble_mesh_lighting_server_cb_event_tesp_ble_mesh_lighting_server_recv_set_msg_t::lc_p (C++ enum), 494 (C++ member), 458 esp_ble_mesh_lighting_server_cb_param_tesp_ble_mesh_lighting_server_recv_set_msg_t::ligh (C++ class), 490 (C++ member), 458 esp_ble_mesh_lighting_server_cb_param_te:s:pc_tbxle_mesh_lighting_server_recv_set_msg_t::ligh (C++ member), 490 (C++ member), 458 esp_ble_mesh_lighting_server_cb_param_te:s:pm_obdleel_mesh_lighting_server_recv_set_msg_t::ligh (C++ member), 490 (C++ member), 458 esp_ble_mesh_lighting_server_cb_param_te:s:pv_ablluee_mesh_lighting_server_recv_set_msg_t::ligh (C++ member), 490 (C++ member), 458 esp_ble_mesh_lighting_server_cb_t esp_ble_mesh_lighting_server_recv_set_msg_t::xyl (C++ type), 494 (C++ member), 458 esp_ble_mesh_lighting_server_cb_value_tesp_ble_mesh_lighting_server_recv_set_msg_t::xyl_ (C++ union), 459 (C++ member), 458 esp_ble_mesh_lighting_server_cb_value_te:s:pg_ebtle_mesh_lighting_server_recv_set_msg_t::xyl_ (C++ member), 459 (C++ member), 458 Espressif Systems 2108 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_LIGHTING_SERVER_RECV_STATUS_MSG_EenVuTmerator), 335 (C++ enumerator), 495 ESP_BLE_MESH_LPN_FRIENDSHIP_ESTABLISH_EVT esp_ble_mesh_lighting_server_recv_status_msg_t(C++ enumerator), 335 (C++ union), 458 ESP_BLE_MESH_LPN_FRIENDSHIP_TERMINATE_EVT esp_ble_mesh_lighting_server_recv_status_msg_t(C:+:+seenusmorer_astotr)a,t3u35s (C++ member), 459 esp_ble_mesh_lpn_poll (C++ function), 340 ESP_BLE_MESH_LIGHTING_SERVER_STATE_CHANEGSEP__EBVLTE_MESH_LPN_POLL_COMP_EVT (C++ (C++ enumerator), 495 enumerator), 335 esp_ble_mesh_lighting_server_state_chanEgSeP__tBLE_MESH_MECHANISM_JAMMED_ERROR (C (C++ union), 456 macro), 385 esp_ble_mesh_lighting_server_state_chanEgSeP__tB:L:Ec_tMlE_SdHe_fMaEuClHtA_NsIeStM_JAMMED_WARNING (C++ member), 457 (C macro), 385 esp_ble_mesh_lighting_server_state_chanEgSeP__tB:L:Ec_tMlE_SsHe_tMEMORY_ERROR (C macro), 384 (C++ member), 457 ESP_BLE_MESH_MEMORY_WARNING (C macro), esp_ble_mesh_lighting_server_state_change_t::c3t84l_temp_range_set (C++ member), 457 ESP_BLE_MESH_MIC_LONG (C macro), 315 esp_ble_mesh_lighting_server_state_chanEgSeP__tB:L:Ec_tMlE_StHe_mMpI_Cs_eStHORT (C macro), 315 (C++ member), 457 esp_ble_mesh_model (C++ class), 308 esp_ble_mesh_lighting_server_state_chanegsep__tb:l:eh_smle_sdhe_fmaoudletl_:s:ectb (C++ member), 309 (C++ member), 457 esp_ble_mesh_model::company_id (C++ esp_ble_mesh_lighting_server_state_change_t::hmselm_bheru)e, 3_0s8et (C++ member), 457 esp_ble_mesh_model::element (C++ mem- esp_ble_mesh_lighting_server_state_change_t::hbserl),_3r0a9nge_set (C++ member), 457 esp_ble_mesh_model::element_idx (C++ esp_ble_mesh_lighting_server_state_change_t::hmselm_bsera)t, 3u0r9ation_set (C++ member), 457 esp_ble_mesh_model::flags (C++ member), esp_ble_mesh_lighting_server_state_change_t::h3s09l_set (C++ member), 457 esp_ble_mesh_model::groups (C++ member), esp_ble_mesh_lighting_server_state_change_t::l3c09_light_onoff_set (C++ member), 457 esp_ble_mesh_model::keys (C++ member), esp_ble_mesh_lighting_server_state_change_t::l3c09_mode_set (C++ member), 457 esp_ble_mesh_model::model_id (C++ mem- esp_ble_mesh_lighting_server_state_change_t::lbcer_),o3m0_8s, e30t9 (C++ member), 457 esp_ble_mesh_model::model_idx (C++ esp_ble_mesh_lighting_server_state_change_t::lmce_mpbrero)p, 3e0r9ty_set (C++ member), 457 esp_ble_mesh_model::op (C++ member), 309 esp_ble_mesh_lighting_server_state_chanegsep__tb:l:el_imgehsthn_emsosd_edle:f:apuulbt(_Cs+e+t member), 309 (C++ member), 457 esp_ble_mesh_model::user_data (C++ esp_ble_mesh_lighting_server_state_change_t::lmiegmhbtern)e, 3s0s9_linear_set (C++ member), 456 esp_ble_mesh_model::vnd (C++ member), 309 esp_ble_mesh_lighting_server_state_chanegsep__tb:l:el_imgehsthn_emsosd_erla:n:g[ea_nsoentymous] (C++ (C++ member), 457 member), 309 esp_ble_mesh_lighting_server_state_chanegsep__tb:l:el_imgehsthn_emsosd_esle_tcb_event_t (C++ (C++ member), 456 enum), 336 esp_ble_mesh_lighting_server_state_chanegsep__tb:l:es_emnessohr__msotdaetlu_scb_param_t (C++ (C++ member), 457 union), 304 esp_ble_mesh_lighting_server_state_chanegsep__tb:l:ex_ymle_sdhe_fmaoudletl__scebt_param_t::ble_mesh_client_mo (C++ member), 457 (C++ class), 305 esp_ble_mesh_lighting_server_state_chanegsep__tb:l:ex_ymle_srha_nmgoed_esle_tcb_param_t::ble_mesh_client_mo (C++ member), 457 (C++ member), 305 esp_ble_mesh_lighting_server_state_chanegsep__tb:l:ex_ymle_sshe_tmodel_cb_param_t::ble_mesh_client_mo (C++ member), 457 (C++ member), 305 esp_ble_mesh_lpn_disable (C++ function), esp_ble_mesh_model_cb_param_t::ble_mesh_client_mo 340 (C++ member), 305 ESP_BLE_MESH_LPN_DISABLE_COMP_EVT esp_ble_mesh_model_cb_param_t::ble_mesh_mod_recv_ (C++ enumerator), 335 (C++ class), 305 esp_ble_mesh_lpn_enable (C++ function), 340 esp_ble_mesh_model_cb_param_t::ble_mesh_mod_recv_ ESP_BLE_MESH_LPN_ENABLE_COMP_EVT (C++ (C++ member), 305 Espressif Systems 2109 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_model_cb_param_t::ble_meshe_smpo_db_lree_cmve_sphu_bmloidsehl__mcsbg__ppaarraamm_:t::l:emnogdtehl_send_comp (C++ member), 305 (C++ member), 304 esp_ble_mesh_model_cb_param_t::ble_meshe_smpo_db_lree_cmve_sphu_bmloidsehl__mcsbg__ppaarraamm_:t::m:osdeerlver_model_updat (C++ member), 305 (C++ member), 305 esp_ble_mesh_model_cb_param_t::ble_meshe_smpo_db_lree_cmve_sphu_bmloidsehl__mcsbg__tp(aCr+a+m:ty:pme)s, g347 (C++ member), 305 esp_ble_mesh_model_cbs_t (C++ class), 308 esp_ble_mesh_model_cb_param_t::ble_meshe_smpo_db_lree_cmve_sphu_bmloidsehl__mcsbgs__pta:r:aimn:i:to_pccbode (C++ member), 305 (C++ member), 308 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__oMpEeSrHa_tMiOoDnE_Le_vCtF_Gp_aCrLaIm(C macro), 376 (C++ class), 305 ESP_BLE_MESH_MODEL_CFG_SRV (C macro), 376 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__oMpEeSrHa_tMiOoDnE_Le_vEtV_Tp_aMrAaXm:(C:+c+txenumera- (C++ member), 305 tor), 337 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__oMpEeSrHa_tMiOoDnE_Le_vGtE_Np_aArDaMmI:N:_lPeRnOgPt_hSRV (C++ member), 306 (C macro), 414 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__oMpEeSrHa_tMiOoDnE_Le_vGtE_Np_aBrAaTmT:E:RmYo_dCeLlI (C (C++ member), 305 macro), 412 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__oMpEeSrHa_tMiOoDnE_Le_vGtE_Np_aBrAaTmT:E:RmYs_gSRV (C (C++ member), 306 macro), 414 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__oMpEeSrHa_tMiOoDnE_Le_vGtE_Np_aCrLaImE:N:To_pPcRoOdPe_SRV (C++ member), 305 (C macro), 415 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__pMuEbSlHi_sMhO_DcEoLm_pG_EpNa_rDaEmF_TRANS_TIME_CLI (C++ class), 306 (C macro), 411 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__pMuEbSlHi_sMhO_DcEoLm_pG_EpNa_rDaEmF:_:TeRrArN_Sc_oTdIeME_SRV (C++ member), 306 (C macro), 413 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__pMuEbSlHi_sMhO_DcEoLm_pG_EpNa_rLaEmV:E:Lm_oCdLeIl (C (C++ member), 306 macro), 411 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__pMuEbSlHi_sMhO_DuEpLd_aGtEeN__eLvEtV_EpLa_rSaRmV (C (C++ class), 306 macro), 413 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__pMuEbSlHi_sMhO_DuEpLd_aGtEeN__eLvOtC_ApTaIrOaNm_:C:LmIo(dCel (C++ member), 306 macro), 412 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__sMeEnSdH__cMoOmDpE_Lp_aGrEaNm_LOCATION_SETUP_SRV (C++ class), 306 (C macro), 414 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__sMeEnSdH__cMoOmDpE_Lp_aGrEaNm_:L:OcCtAxTION_SRV (C (C++ member), 306 macro), 414 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__sMeEnSdH__cMoOmDpE_Lp_aGrEaNm_:M:AeNrUrF_AcCoTdUeRER_PROP_SRV (C++ member), 306 (C macro), 414 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__sMeEnSdH__cMoOmDpE_Lp_aGrEaNm_:O:NmOoFdFe_lCLI (C (C++ member), 306 macro), 411 esp_ble_mesh_model_cb_param_t::ble_meshE_SmPo_dBeLlE__sMeEnSdH__cMoOmDpE_Lp_aGrEaNm_:O:NoOpFcFo_dSeRV (C (C++ member), 306 macro), 412 esp_ble_mesh_model_cb_param_t::ble_meshE_SsPe_rBvLeEr__MmEoSdHe_lM_OuDpEdLa_tGeE_Ns_tPaOtWeE_Rc_oLmEpV_EpLa_rCaLmI (C++ class), 306 (C macro), 412 esp_ble_mesh_model_cb_param_t::ble_meshE_SsPe_rBvLeEr__MmEoSdHe_lM_OuDpEdLa_tGeE_Ns_tPaOtWeE_Rc_oLmEpV_EpLa_rSaEmT:U:Pe_rSrR_Vcode (C++ member), 306 (C macro), 413 esp_ble_mesh_model_cb_param_t::ble_meshE_SsPe_rBvLeEr__MmEoSdHe_lM_OuDpEdLa_tGeE_Ns_tPaOtWeE_Rc_oLmEpV_EpLa_rSaRmV::model (C++ member), 306 (C macro), 413 esp_ble_mesh_model_cb_param_t::ble_meshE_SsPe_rBvLeEr__MmEoSdHe_lM_OuDpEdLa_tGeE_Ns_tPaOtWeE_Rc_oOmNpO_FpFa_rCaLmI::type (C++ member), 306 (C macro), 412 esp_ble_mesh_model_cb_param_t::client_rEeScPv__BpLuEb_lMiEsShH__mMsOgDEL_GEN_POWER_ONOFF_SETUP_SRV (C++ member), 305 (C macro), 413 esp_ble_mesh_model_cb_param_t::client_sEeSnPd__BtLiEm_eMoEuStH_MODEL_GEN_POWER_ONOFF_SRV (C++ member), 305 (C macro), 413 esp_ble_mesh_model_cb_param_t::model_opEeSrPa_tBiLoEn_MESH_MODEL_GEN_PROPERTY_CLI (C (C++ member), 304 macro), 412 esp_ble_mesh_model_cb_param_t::model_puEbSlPi_sBhL_Ec_oMmEpSH_MODEL_GEN_USER_PROP_SRV (C++ member), 305 (C macro), 414 esp_ble_mesh_model_cb_param_t::model_puEbSlPi_sBhL_Eu_pMdEaStHe_MODEL_HEALTH_CLI (C macro), (C++ member), 305 383 Espressif Systems 2110 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_MODEL_HEALTH_SRV (C macro), ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_SRV (C 383 macro), 319 ESP_BLE_MESH_MODEL_ID_CONFIG_CLI (C ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_TEMP_SRV macro), 318 (C macro), 319 ESP_BLE_MESH_MODEL_ID_CONFIG_SRV (C ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_CLI (C macro), 318 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_ADMIN_PROP_SREVSP_BLE_MESH_MODEL_ID_LIGHT_HSL_HUE_SRV (C macro), 319 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_BATTERY_CLI ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SAT_SRV (C macro), 319 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_BATTERY_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_HSL_SETUP_SRV (C macro), 319 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_CLIENT_PROP_SERSVP_BLE_MESH_MODEL_ID_LIGHT_HSL_SRV (C (C macro), 319 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_DEF_TRANS_TIMEES_PC_LBILE_MESH_MODEL_ID_LIGHT_LC_CLI (C (C macro), 318 macro), 320 ESP_BLE_MESH_MODEL_ID_GEN_DEF_TRANS_TIMEES_PS_RBVLE_MESH_MODEL_ID_LIGHT_LC_SETUP_SRV (C macro), 318 (C macro), 320 ESP_BLE_MESH_MODEL_ID_GEN_LEVEL_CLI (C ESP_BLE_MESH_MODEL_ID_LIGHT_LC_SRV (C macro), 318 macro), 320 ESP_BLE_MESH_MODEL_ID_GEN_LEVEL_SRV (C ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_CLI macro), 318 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_CLI ESP_BLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_SETUP_SRV (C macro), 319 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_SETUEPS_PS_RBVLE_MESH_MODEL_ID_LIGHT_LIGHTNESS_SRV (C macro), 319 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_LOCATION_SRV ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_CLI (C (C macro), 319 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_MANUFACTURER_EPSRPO_PB_LSER_VMESH_MODEL_ID_LIGHT_XYL_SETUP_SRV (C macro), 319 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_ONOFF_CLI (C ESP_BLE_MESH_MODEL_ID_LIGHT_XYL_SRV (C macro), 318 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_ONOFF_SRV (C ESP_BLE_MESH_MODEL_ID_SCENE_CLI (C macro), 318 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_CELSIP_BLE_MESH_MODEL_ID_SCENE_SETUP_SRV (C macro), 319 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_SEESTPU_PB_LSER_VMESH_MODEL_ID_SCENE_SRV (C (C macro), 319 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_POWER_LEVEL_SERSVP_BLE_MESH_MODEL_ID_SCHEDULER_CLI (C (C macro), 318 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_CELSIP_BLE_MESH_MODEL_ID_SCHEDULER_SETUP_SRV (C macro), 318 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_SEESTPU_PB_LSER_VMESH_MODEL_ID_SCHEDULER_SRV (C (C macro), 318 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_POWER_ONOFF_SERSVP_BLE_MESH_MODEL_ID_SENSOR_CLI (C (C macro), 318 macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_PROP_CLI (C ESP_BLE_MESH_MODEL_ID_SENSOR_SETUP_SRV macro), 319 (C macro), 319 ESP_BLE_MESH_MODEL_ID_GEN_USER_PROP_SRVESP_BLE_MESH_MODEL_ID_SENSOR_SRV (C (C macro), 319 macro), 319 ESP_BLE_MESH_MODEL_ID_HEALTH_CLI (C ESP_BLE_MESH_MODEL_ID_TIME_CLI (C macro), 318 macro), 319 ESP_BLE_MESH_MODEL_ID_HEALTH_SRV (C ESP_BLE_MESH_MODEL_ID_TIME_SETUP_SRV macro), 318 (C macro), 319 ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_CLI (C ESP_BLE_MESH_MODEL_ID_TIME_SRV (C macro), 319 macro), 319 ESP_BLE_MESH_MODEL_ID_LIGHT_CTL_SETUP_SERSVP_BLE_MESH_MODEL_LIGHT_CTL_CLI (C (C macro), 319 macro), 491 Espressif Systems 2111 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_MODEL_LIGHT_CTL_SETUP_SRV (C macro), 323 (C macro), 492 ESP_BLE_MESH_MODEL_OP_ATTENTION_STATUS ESP_BLE_MESH_MODEL_LIGHT_CTL_SRV (C (C macro), 323 macro), 491 ESP_BLE_MESH_MODEL_OP_BEACON_GET (C ESP_BLE_MESH_MODEL_LIGHT_CTL_TEMP_SRV macro), 320 (C macro), 492 ESP_BLE_MESH_MODEL_OP_BEACON_SET (C ESP_BLE_MESH_MODEL_LIGHT_HSL_CLI (C macro), 320 macro), 491 ESP_BLE_MESH_MODEL_OP_BEACON_STATUS (C ESP_BLE_MESH_MODEL_LIGHT_HSL_HUE_SRV macro), 322 (C macro), 493 ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_GET ESP_BLE_MESH_MODEL_LIGHT_HSL_SAT_SRV (C macro), 320 (C macro), 493 ESP_BLE_MESH_MODEL_OP_COMPOSITION_DATA_STATUS ESP_BLE_MESH_MODEL_LIGHT_HSL_SETUP_SRV (C macro), 322 (C macro), 492 ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_GET ESP_BLE_MESH_MODEL_LIGHT_HSL_SRV (C (C macro), 320 macro), 492 ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_SET ESP_BLE_MESH_MODEL_LIGHT_LC_CLI (C (C macro), 320 macro), 491 ESP_BLE_MESH_MODEL_OP_DEFAULT_TTL_STATUS ESP_BLE_MESH_MODEL_LIGHT_LC_SETUP_SRV (C macro), 322 (C macro), 493 ESP_BLE_MESH_MODEL_OP_END (C macro), 318 ESP_BLE_MESH_MODEL_LIGHT_LC_SRV (C ESP_BLE_MESH_MODEL_OP_FRIEND_GET (C macro), 493 macro), 320 ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_CLI ESP_BLE_MESH_MODEL_OP_FRIEND_SET (C (C macro), 490 macro), 321 ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_SETUEPS_PS_RBVLE_MESH_MODEL_OP_FRIEND_STATUS (C (C macro), 491 macro), 322 ESP_BLE_MESH_MODEL_LIGHT_LIGHTNESS_SRV ESP_BLE_MESH_MODEL_OP_GATT_PROXY_GET (C macro), 491 (C macro), 320 ESP_BLE_MESH_MODEL_LIGHT_XYL_CLI (C ESP_BLE_MESH_MODEL_OP_GATT_PROXY_SET macro), 491 (C macro), 320 ESP_BLE_MESH_MODEL_LIGHT_XYL_SETUP_SRV ESP_BLE_MESH_MODEL_OP_GATT_PROXY_STATUS (C macro), 493 (C macro), 322 ESP_BLE_MESH_MODEL_LIGHT_XYL_SRV (C ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_GET macro), 493 (C macro), 325 esp_ble_mesh_model_msg_opcode_init ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTIES_STATUS (C++ function), 341 (C macro), 325 ESP_BLE_MESH_MODEL_NONE (C macro), 318 ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_GET ESP_BLE_MESH_MODEL_OP (C macro), 317 (C macro), 325 ESP_BLE_MESH_MODEL_OP_1 (C macro), 317 ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET ESP_BLE_MESH_MODEL_OP_2 (C macro), 317 (C macro), 325 ESP_BLE_MESH_MODEL_OP_3 (C macro), 317 ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_SET_UNAC ESP_BLE_MESH_MODEL_OP_APP_KEY_ADD (C (C macro), 325 macro), 321 ESP_BLE_MESH_MODEL_OP_GEN_ADMIN_PROPERTY_STATUS ESP_BLE_MESH_MODEL_OP_APP_KEY_DELETE (C macro), 325 (C macro), 321 ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_GET ESP_BLE_MESH_MODEL_OP_APP_KEY_GET (C (C macro), 324 macro), 320 ESP_BLE_MESH_MODEL_OP_GEN_BATTERY_STATUS ESP_BLE_MESH_MODEL_OP_APP_KEY_LIST (C (C macro), 324 macro), 322 ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_GET ESP_BLE_MESH_MODEL_OP_APP_KEY_STATUS (C macro), 325 (C macro), 322 ESP_BLE_MESH_MODEL_OP_GEN_CLIENT_PROPERTIES_STATU ESP_BLE_MESH_MODEL_OP_APP_KEY_UPDATE (C macro), 325 (C macro), 321 ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_GET ESP_BLE_MESH_MODEL_OP_ATTENTION_GET (C (C macro), 324 macro), 323 ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET ESP_BLE_MESH_MODEL_OP_ATTENTION_SET (C (C macro), 324 macro), 323 ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIME_SET_UNAC ESP_BLE_MESH_MODEL_OP_ATTENTION_SET_UNACK (C macro), 324 Espressif Systems 2112 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_MODEL_OP_GEN_DEF_TRANS_TIMEES_PS_TBALTEU_SMESH_MODEL_OP_GEN_ONPOWERUP_SET_UNACK (C macro), 324 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET (C ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_STATUS macro), 323 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET_UNAECSKP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_GET (C macro), 324 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_GET (C ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET macro), 323 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET (C ESP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_SET_UNACK macro), 323 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET_UNAECSKP_BLE_MESH_MODEL_OP_GEN_POWER_DEFAULT_STATUS (C macro), 323 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_STATUS ESP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_GET (C macro), 323 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_GEETSP_BLE_MESH_MODEL_OP_GEN_POWER_LAST_STATUS (C macro), 324 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SEETSP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_GET (C macro), 324 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_SEETS_PU_NBALCEK_MESH_MODEL_OP_GEN_POWER_LEVEL_SET (C macro), 324 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LOC_GLOBAL_STEASTPU_SBLE_MESH_MODEL_OP_GEN_POWER_LEVEL_SET_UNACK (C macro), 324 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_GETESP_BLE_MESH_MODEL_OP_GEN_POWER_LEVEL_STATUS (C macro), 324 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SETESP_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_GET (C macro), 325 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_SETE_SUPN_ABCLKE_MESH_MODEL_OP_GEN_POWER_RANGE_SET (C macro), 325 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_LOC_LOCAL_STAETSUPS_BLE_MESH_MODEL_OP_GEN_POWER_RANGE_SET_UNACK (C macro), 324 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_EPSRPO_PBELRET_IMEESS_HG_EMTODEL_OP_GEN_POWER_RANGE_STATUS (C macro), 325 (C macro), 324 ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_EPSRPO_PBELRET_IMEESS_HS_TMAOTDUESL_OP_GEN_USER_PROPERTIES_GET (C macro), 325 (C macro), 325 ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_EPSRPO_PBELRET_YM_EGSEHT_MODEL_OP_GEN_USER_PROPERTIES_STATUS (C macro), 325 (C macro), 325 ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_EPSRPO_PBELRET_YM_ESSEHT_MODEL_OP_GEN_USER_PROPERTY_GET (C macro), 325 (C macro), 325 ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_EPSRPO_PBELRET_YM_ESSEHT__MUONDAECLK_OP_GEN_USER_PROPERTY_SET (C macro), 325 (C macro), 325 ESP_BLE_MESH_MODEL_OP_GEN_MANUFACTURER_EPSRPO_PBELRET_YM_ESSTHA_TMUOSDEL_OP_GEN_USER_PROPERTY_SET_UNACK (C macro), 325 (C macro), 325 ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET (C ESP_BLE_MESH_MODEL_OP_GEN_USER_PROPERTY_STATUS macro), 324 (C macro), 325 ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET_UNACEKSP_BLE_MESH_MODEL_OP_HEALTH_CURRENT_STATUS (C macro), 324 (C macro), 323 ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_GET (C ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR macro), 323 (C macro), 323 ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET (C ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_CLEAR_UNACK macro), 323 (C macro), 323 ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET_UNAECSKP_BLE_MESH_MODEL_OP_HEALTH_FAULT_GET (C macro), 323 (C macro), 323 ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_STATUS ESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_STATUS (C macro), 323 (C macro), 323 ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_GETESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST (C macro), 324 (C macro), 323 ESP_BLE_MESH_MODEL_OP_GEN_ONPOWERUP_SETESP_BLE_MESH_MODEL_OP_HEALTH_FAULT_TEST_UNACK (C macro), 324 (C macro), 323 Espressif Systems 2113 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_GETESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_GET (C macro), 323 (C macro), 328 ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SETESP_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET (C macro), 323 (C macro), 328 ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_SETE_SUPN_ABCLKE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_SET_UNACK (C macro), 323 (C macro), 328 ESP_BLE_MESH_MODEL_OP_HEALTH_PERIOD_STAETSUPS_BLE_MESH_MODEL_OP_LIGHT_HSL_DEFAULT_STATUS (C macro), 323 (C macro), 328 ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_GETESP_BLE_MESH_MODEL_OP_LIGHT_HSL_GET (C (C macro), 320 macro), 327 ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_SETESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_GET (C macro), 321 (C macro), 327 ESP_BLE_MESH_MODEL_OP_HEARTBEAT_PUB_STAETSUPS_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET (C macro), 322 (C macro), 327 ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_GETESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_SET_UNACK (C macro), 320 (C macro), 327 ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_SETESP_BLE_MESH_MODEL_OP_LIGHT_HSL_HUE_STATUS (C macro), 321 (C macro), 327 ESP_BLE_MESH_MODEL_OP_HEARTBEAT_SUB_STAETSUPS_BLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_GET (C macro), 322 (C macro), 328 ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASEE_SGPE_TBLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET (C macro), 320 (C macro), 328 ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASEE_SSPE_TBLE_MESH_MODEL_OP_LIGHT_HSL_RANGE_SET_UNACK (C macro), 321 (C macro), 328 ESP_BLE_MESH_MODEL_OP_KEY_REFRESH_PHASEE_SSPT_ABTLUES_MESH_MODEL_OP_LIGHT_HSL_RANGE_STATUS (C macro), 322 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULTE_SGPE_TBLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_GET (C macro), 327 (C macro), 327 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULTE_SSPE_TBLE_MESH_MODEL_OP_LIGHT_HSL_SATURATION_SET (C macro), 327 (C macro), 327 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULTE_SSPE_TB_LUEN_AMCEKSH_MODEL_OP_LIGHT_HSL_SATURATION_SET_UN (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_DEFAULTE_SSPT_ABTLUES_MESH_MODEL_OP_LIGHT_HSL_SATURATION_STATUS (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_GET (C ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET (C macro), 327 macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET (C ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_SET_UNACK macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_SET_UNAECSKP_BLE_MESH_MODEL_OP_LIGHT_HSL_STATUS (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_STATUS ESP_BLE_MESH_MODEL_OP_LIGHT_HSL_TARGET_GET (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERAETSUPR_EB_LGEE_TMESH_MODEL_OP_LIGHT_HSL_TARGET_STATUS (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERAETSUPR_EB_LREA_NMGEES_HG_EMTODEL_OP_LIGHT_LC_LIGHT_ONOFF_GET (C macro), 327 (C macro), 329 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERAETSUPR_EB_LREA_NMGEES_HS_EMTODEL_OP_LIGHT_LC_LIGHT_ONOFF_SET (C macro), 327 (C macro), 329 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERAETSUPR_EB_LREA_NMGEES_HS_EMTO_DUENLA_COKP_LIGHT_LC_LIGHT_ONOFF_SET_UN (C macro), 327 (C macro), 329 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERAETSUPR_EB_LREA_NMGEES_HS_TMAOTDUESL_OP_LIGHT_LC_LIGHT_ONOFF_STATUS (C macro), 327 (C macro), 329 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERAETSUPR_EB_LSEE_TMESH_MODEL_OP_LIGHT_LC_MODE_GET (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERAETSUPR_EB_LSEE_TM_EUSNHA_CMKODEL_OP_LIGHT_LC_MODE_SET (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_CTL_TEMPERAETSUPR_EB_LSET_AMTEUSSH_MODEL_OP_LIGHT_LC_MODE_SET_UNACK (C macro), 327 (C macro), 328 Espressif Systems 2114 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_MODEL_OP_LIGHT_LC_MODE_STAETSUPS_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_SET_UNACK (C macro), 328 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_GET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULT_STATUS (C macro), 328 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_GET (C (C macro), 328 macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_SET_UENSAPC_KBLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_GET (C macro), 328 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LC_OM_STATUESSP_BLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET (C macro), 329 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTYE_SGPE_TBLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_SET_UNACK (C macro), 329 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTYE_SSPE_TBLE_MESH_MODEL_OP_LIGHT_XYL_RANGE_STATUS (C macro), 329 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTYE_SSPE_TB_LUEN_AMCEKSH_MODEL_OP_LIGHT_XYL_SET (C (C macro), 329 macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LC_PROPERTYE_SSPT_ABTLUES_MESH_MODEL_OP_LIGHT_XYL_SET_UNACK (C macro), 329 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEESFPA_UBLLTE__GMEETSH_MODEL_OP_LIGHT_XYL_STATUS (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEESFPA_UBLLTE__SMEETSH_MODEL_OP_LIGHT_XYL_TARGET_GET (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEESFPA_UBLLTE__SMEETS_HU_NMAOCDKEL_OP_LIGHT_XYL_TARGET_STATUS (C macro), 327 (C macro), 328 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_DEESFPA_UBLLTE__SMTEASTHU_SMODEL_OP_LPN_POLLTIMEOUT_GET (C macro), 327 (C macro), 320 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_GEESTP_BLE_MESH_MODEL_OP_LPN_POLLTIMEOUT_STATUS (C macro), 326 (C macro), 322 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LEASSPT__BGLEET_MESH_MODEL_OP_MODEL_APP_BIND (C macro), 327 (C macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LEASSPT__BSLTEA_TMUESSH_MODEL_OP_MODEL_APP_STATUS (C macro), 327 (C macro), 322 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LEISNPE_ABRL_EG_EMTESH_MODEL_OP_MODEL_APP_UNBIND (C macro), 326 (C macro), 322 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LEISNPE_ABRL_ES_EMTESH_MODEL_OP_MODEL_PUB_GET (C (C macro), 327 macro), 320 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LEISNPE_ABRL_ES_EMTE_SUHN_AMCOKDEL_OP_MODEL_PUB_SET (C (C macro), 327 macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_LEISNPE_ABRL_ES_TMAETSUHS_MODEL_OP_MODEL_PUB_STATUS (C macro), 327 (C macro), 322 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_REASNPG_EB_LGEE_TMESH_MODEL_OP_MODEL_PUB_VIRTUAL_ADDR_SET (C macro), 327 (C macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_REASNPG_EB_LSEE_TMESH_MODEL_OP_MODEL_SUB_ADD (C (C macro), 327 macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_REASNPG_EB_LSEE_TM_EUSNHA_CMKODEL_OP_MODEL_SUB_DELETE (C macro), 327 (C macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_REASNPG_EB_LSET_AMTEUSSH_MODEL_OP_MODEL_SUB_DELETE_ALL (C macro), 327 (C macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SEESTP_BLE_MESH_MODEL_OP_MODEL_SUB_OVERWRITE (C macro), 326 (C macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SEESTP__UBNLAEC_KMESH_MODEL_OP_MODEL_SUB_STATUS (C macro), 326 (C macro), 322 ESP_BLE_MESH_MODEL_OP_LIGHT_LIGHTNESS_SETSAPT_UBSLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_ADD (C macro), 326 (C macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULTE_SGPE_TBLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_DELE (C macro), 328 (C macro), 321 ESP_BLE_MESH_MODEL_OP_LIGHT_XYL_DEFAULTE_SSPE_TBLE_MESH_MODEL_OP_MODEL_SUB_VIRTUAL_ADDR_OVER (C macro), 328 (C macro), 321 Espressif Systems 2115 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_MODEL_OP_NET_KEY_ADD (C ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET_UNACK macro), 321 (C macro), 326 ESP_BLE_MESH_MODEL_OP_NET_KEY_DELETE ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_STATUS (C macro), 321 (C macro), 326 ESP_BLE_MESH_MODEL_OP_NET_KEY_GET (C ESP_BLE_MESH_MODEL_OP_SCHEDULER_GET (C macro), 320 macro), 326 ESP_BLE_MESH_MODEL_OP_NET_KEY_LIST (C ESP_BLE_MESH_MODEL_OP_SCHEDULER_STATUS macro), 322 (C macro), 326 ESP_BLE_MESH_MODEL_OP_NET_KEY_STATUS ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_GET (C macro), 322 (C macro), 325 ESP_BLE_MESH_MODEL_OP_NET_KEY_UPDATE ESP_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET (C macro), 321 (C macro), 325 ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_EGSEPT_BLE_MESH_MODEL_OP_SENSOR_CADENCE_SET_UNACK (C macro), 320 (C macro), 325 ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_ESSEPT_BLE_MESH_MODEL_OP_SENSOR_CADENCE_STATUS (C macro), 322 (C macro), 325 ESP_BLE_MESH_MODEL_OP_NETWORK_TRANSMIT_ESSTPA_TBULSE_MESH_MODEL_OP_SENSOR_COLUMN_GET (C macro), 322 (C macro), 325 ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_GETESP_BLE_MESH_MODEL_OP_SENSOR_COLUMN_STATUS (C macro), 320 (C macro), 325 ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_SETESP_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_GET (C macro), 321 (C macro), 325 ESP_BLE_MESH_MODEL_OP_NODE_IDENTITY_STAETSUPS_BLE_MESH_MODEL_OP_SENSOR_DESCRIPTOR_STATUS (C macro), 322 (C macro), 325 ESP_BLE_MESH_MODEL_OP_NODE_RESET (C ESP_BLE_MESH_MODEL_OP_SENSOR_GET (C macro), 321 macro), 325 ESP_BLE_MESH_MODEL_OP_NODE_RESET_STATUSESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_GET (C macro), 322 (C macro), 325 ESP_BLE_MESH_MODEL_OP_RELAY_GET (C ESP_BLE_MESH_MODEL_OP_SENSOR_SERIES_STATUS macro), 320 (C macro), 325 ESP_BLE_MESH_MODEL_OP_RELAY_SET (C ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_GET macro), 321 (C macro), 326 ESP_BLE_MESH_MODEL_OP_RELAY_STATUS (C ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET macro), 322 (C macro), 326 ESP_BLE_MESH_MODEL_OP_SCENE_DELETE (C ESP_BLE_MESH_MODEL_OP_SENSOR_SETTING_SET_UNACK macro), 326 (C macro), 326 ESP_BLE_MESH_MODEL_OP_SCENE_DELETE_UNACEKSP_BLE_MESH_MODEL_OP_SENSOR_SETTING_STATUS (C macro), 326 (C macro), 326 ESP_BLE_MESH_MODEL_OP_SCENE_GET (C ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_GET macro), 326 (C macro), 325 ESP_BLE_MESH_MODEL_OP_SCENE_RECALL (C ESP_BLE_MESH_MODEL_OP_SENSOR_SETTINGS_STATUS macro), 326 (C macro), 325 ESP_BLE_MESH_MODEL_OP_SCENE_RECALL_UNACEKSP_BLE_MESH_MODEL_OP_SENSOR_STATUS (C (C macro), 326 macro), 325 ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_GEETSP_BLE_MESH_MODEL_OP_SIG_MODEL_APP_GET (C macro), 326 (C macro), 320 ESP_BLE_MESH_MODEL_OP_SCENE_REGISTER_STEASTPU_SBLE_MESH_MODEL_OP_SIG_MODEL_APP_LIST (C macro), 326 (C macro), 322 ESP_BLE_MESH_MODEL_OP_SCENE_STATUS (C ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_GET macro), 326 (C macro), 320 ESP_BLE_MESH_MODEL_OP_SCENE_STORE (C ESP_BLE_MESH_MODEL_OP_SIG_MODEL_SUB_LIST macro), 326 (C macro), 322 ESP_BLE_MESH_MODEL_OP_SCENE_STORE_UNACKesp_ble_mesh_model_op_t (C++ class), 308 (C macro), 326 esp_ble_mesh_model_op_t::min_len (C++ ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_GET member), 308 (C macro), 326 esp_ble_mesh_model_op_t::opcode (C++ ESP_BLE_MESH_MODEL_OP_SCHEDULER_ACT_SET member), 308 (C macro), 326 esp_ble_mesh_model_op_t::param_cb Espressif Systems 2116 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 308 esp_ble_mesh_model_pub_t::publish_addr ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_GET (C++ member), 307 (C macro), 326 esp_ble_mesh_model_pub_t::retransmit ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_SET (C++ member), 307 (C macro), 326 esp_ble_mesh_model_pub_t::send_rel ESP_BLE_MESH_MODEL_OP_TAI_UTC_DELTA_STATUS (C++ member), 307 (C macro), 326 esp_ble_mesh_model_pub_t::timer (C++ ESP_BLE_MESH_MODEL_OP_TIME_GET (C member), 308 macro), 326 esp_ble_mesh_model_pub_t::ttl (C++ ESP_BLE_MESH_MODEL_OP_TIME_ROLE_GET (C member), 307 macro), 326 esp_ble_mesh_model_pub_t::update (C++ ESP_BLE_MESH_MODEL_OP_TIME_ROLE_SET (C member), 308 macro), 326 esp_ble_mesh_model_publish (C++ function), ESP_BLE_MESH_MODEL_OP_TIME_ROLE_STATUS 342 (C macro), 326 ESP_BLE_MESH_MODEL_PUBLISH_COMP_EVT ESP_BLE_MESH_MODEL_OP_TIME_SET (C (C++ enumerator), 336 macro), 326 ESP_BLE_MESH_MODEL_PUBLISH_UPDATE_EVT ESP_BLE_MESH_MODEL_OP_TIME_STATUS (C (C++ enumerator), 336 macro), 326 ESP_BLE_MESH_MODEL_SCENE_CLI (C macro), ESP_BLE_MESH_MODEL_OP_TIME_ZONE_GET (C 449 macro), 326 ESP_BLE_MESH_MODEL_SCENE_SETUP_SRV (C ESP_BLE_MESH_MODEL_OP_TIME_ZONE_SET (C macro), 450 macro), 326 ESP_BLE_MESH_MODEL_SCENE_SRV (C macro), ESP_BLE_MESH_MODEL_OP_TIME_ZONE_STATUS 450 (C macro), 326 ESP_BLE_MESH_MODEL_SCHEDULER_CLI (C ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_GET macro), 449 (C macro), 320 ESP_BLE_MESH_MODEL_SCHEDULER_SETUP_SRV ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_APP_LIST (C macro), 450 (C macro), 322 ESP_BLE_MESH_MODEL_SCHEDULER_SRV (C ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_GET macro), 450 (C macro), 320 ESP_BLE_MESH_MODEL_SEND_COMP_EVT (C++ ESP_BLE_MESH_MODEL_OP_VENDOR_MODEL_SUB_LIST enumerator), 336 (C macro), 322 ESP_BLE_MESH_MODEL_SENSOR_CLI (C macro), ESP_BLE_MESH_MODEL_OPERATION_EVT (C++ 428 enumerator), 336 ESP_BLE_MESH_MODEL_SENSOR_SETUP_SRV (C ESP_BLE_MESH_MODEL_PUB_DEFINE (C macro), macro), 428 317 ESP_BLE_MESH_MODEL_SENSOR_SRV (C macro), esp_ble_mesh_model_pub_t (C++ class), 307 428 esp_ble_mesh_model_pub_t::app_idx ESP_BLE_MESH_MODEL_STATUS_CANNOT_SET_RANGE_MAX (C++ member), 307 (C macro), 329 esp_ble_mesh_model_pub_t::count (C++ ESP_BLE_MESH_MODEL_STATUS_CANNOT_SET_RANGE_MIN member), 308 (C macro), 329 esp_ble_mesh_model_pub_t::cred (C++ ESP_BLE_MESH_MODEL_STATUS_SUCCESS (C member), 307 macro), 329 esp_ble_mesh_model_pub_t::dev_role esp_ble_mesh_model_status_t (C++ type), (C++ member), 308 330 esp_ble_mesh_model_pub_t::fast_period esp_ble_mesh_model_subscribe_group_addr (C++ member), 308 (C++ function), 338 esp_ble_mesh_model_pub_t::model (C++ ESP_BLE_MESH_MODEL_SUBSCRIBE_GROUP_ADDR_COMP_EVT member), 307 (C++ enumerator), 335 esp_ble_mesh_model_pub_t::msg (C++ esp_ble_mesh_model_t (C++ type), 329 member), 308 ESP_BLE_MESH_MODEL_TIME_CLI (C macro), esp_ble_mesh_model_pub_t::period (C++ 449 member), 307 ESP_BLE_MESH_MODEL_TIME_SETUP_SRV (C esp_ble_mesh_model_pub_t::period_div macro), 450 (C++ member), 307 ESP_BLE_MESH_MODEL_TIME_SRV (C macro), esp_ble_mesh_model_pub_t::period_start 450 (C++ member), 308 esp_ble_mesh_model_unsubscribe_group_addr Espressif Systems 2117 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ function), 339 function), 348 ESP_BLE_MESH_MODEL_UNSUBSCRIBE_GROUP_ADeDsRp__CbOlMeP__mEeVsTh_node_input_string (C++ (C++ enumerator), 335 function), 348 esp_ble_mesh_msg_ctx_t (C++ class), 309 esp_ble_mesh_node_is_provisioned (C++ esp_ble_mesh_msg_ctx_t::addr (C++ mem- function), 348 ber), 309 esp_ble_mesh_node_local_reset (C++ func- esp_ble_mesh_msg_ctx_t::app_idx (C++ tion), 342 member), 309 ESP_BLE_MESH_NODE_NAME_MAX_LEN (C esp_ble_mesh_msg_ctx_t::model (C++ macro), 315 member), 310 ESP_BLE_MESH_NODE_PROV_COMPLETE_EVT esp_ble_mesh_msg_ctx_t::net_idx (C++ (C++ enumerator), 332 member), 309 esp_ble_mesh_node_prov_disable (C++ esp_ble_mesh_msg_ctx_t::recv_dst (C++ function), 348 member), 309 ESP_BLE_MESH_NODE_PROV_DISABLE_COMP_EVT esp_ble_mesh_msg_ctx_t::recv_op (C++ (C++ enumerator), 332 member), 310 esp_ble_mesh_node_prov_enable (C++ func- esp_ble_mesh_msg_ctx_t::recv_rssi tion), 348 (C++ member), 309 ESP_BLE_MESH_NODE_PROV_ENABLE_COMP_EVT esp_ble_mesh_msg_ctx_t::recv_ttl (C++ (C++ enumerator), 332 member), 309 ESP_BLE_MESH_NODE_PROV_INPUT_EVT (C++ esp_ble_mesh_msg_ctx_t::send_rel (C++ enumerator), 332 member), 309 ESP_BLE_MESH_NODE_PROV_INPUT_NUMBER_COMP_EVT esp_ble_mesh_msg_ctx_t::send_ttl (C++ (C++ enumerator), 333 member), 309 ESP_BLE_MESH_NODE_PROV_INPUT_STRING_COMP_EVT esp_ble_mesh_msg_ctx_t::srv_send (C++ (C++ enumerator), 333 member), 310 ESP_BLE_MESH_NODE_PROV_LINK_CLOSE_EVT ESP_BLE_MESH_NET_PRIMARY (C macro), 315 (C++ enumerator), 332 ESP_BLE_MESH_NO_FAULT (C macro), 383 ESP_BLE_MESH_NODE_PROV_LINK_OPEN_EVT ESP_BLE_MESH_NO_INPUT (C++ enumerator), 331 (C++ enumerator), 332 ESP_BLE_MESH_NO_LOAD_ERROR (C macro), 384 ESP_BLE_MESH_NODE_PROV_OOB_PUB_KEY_EVT ESP_BLE_MESH_NO_LOAD_WARNING (C macro), (C++ enumerator), 332 384 ESP_BLE_MESH_NODE_PROV_OUTPUT_NUMBER_EVT ESP_BLE_MESH_NO_OOB (C++ enumerator), 331 (C++ enumerator), 332 ESP_BLE_MESH_NO_OUTPUT (C++ enumerator), ESP_BLE_MESH_NODE_PROV_OUTPUT_STRING_EVT 331 (C++ enumerator), 332 esp_ble_mesh_node_add_local_app_key ESP_BLE_MESH_NODE_PROV_RESET_EVT (C++ (C++ function), 339 enumerator), 332 ESP_BLE_MESH_NODE_ADD_LOCAL_APP_KEY_COMEPS_PE_VBTLE_MESH_NODE_PROV_SET_OOB_PUB_KEY_COMP_EVT (C++ enumerator), 333 (C++ enumerator), 332 esp_ble_mesh_node_add_local_net_key ESP_BLE_MESH_NODE_PROXY_GATT_DISABLE_COMP_EVT (C++ function), 339 (C++ enumerator), 333 ESP_BLE_MESH_NODE_ADD_LOCAL_NET_KEY_COMEPS_PE_VBTLE_MESH_NODE_PROXY_GATT_ENABLE_COMP_EVT (C++ enumerator), 333 (C++ enumerator), 333 esp_ble_mesh_node_bind_app_key_to_localE_SmPo_dBeLlE_MESH_NODE_PROXY_IDENTITY_ENABLE_COMP_EVT (C++ function), 339 (C++ enumerator), 333 ESP_BLE_MESH_NODE_BIND_APP_KEY_TO_MODELe_sCpO_MbPl_eE_VmTesh_node_set_oob_pub_key (C++ enumerator), 333 (C++ function), 348 esp_ble_mesh_node_get_local_app_key ESP_BLE_MESH_NODE_SET_UNPROV_DEV_NAME_COMP_EVT (C++ function), 339 (C++ enumerator), 332 esp_ble_mesh_node_get_local_net_key esp_ble_mesh_node_t (C++ class), 311 (C++ function), 339 esp_ble_mesh_node_t::addr (C++ member), ESP_BLE_MESH_NODE_IDENTITY_NOT_SUPPORTED 311 (C macro), 316 esp_ble_mesh_node_t::addr_type (C++ ESP_BLE_MESH_NODE_IDENTITY_RUNNING (C member), 311 macro), 316 esp_ble_mesh_node_t::comp_data (C++ ESP_BLE_MESH_NODE_IDENTITY_STOPPED (C member), 312 macro), 316 esp_ble_mesh_node_t::comp_length (C++ esp_ble_mesh_node_input_number (C++ member), 311 Espressif Systems 2118 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_node_t::dev_key (C++ mem- 331 ber), 311 esp_ble_mesh_prov_cb_event_t (C++ enum), esp_ble_mesh_node_t::dev_uuid (C++ 332 member), 311 esp_ble_mesh_prov_cb_param_t (C++ esp_ble_mesh_node_t::element_num (C++ union), 284 member), 311 esp_ble_mesh_prov_cb_param_t::ble_mesh_deinit_mes esp_ble_mesh_node_t::flags (C++ member), (C++ class), 289 311 esp_ble_mesh_prov_cb_param_t::ble_mesh_deinit_mes esp_ble_mesh_node_t::iv_index (C++ (C++ member), 289 member), 311 esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_fri esp_ble_mesh_node_t::name (C++ member), (C++ class), 289 311 esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_fri esp_ble_mesh_node_t::net_idx (C++ mem- (C++ member), 289 ber), 311 esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_fri esp_ble_mesh_node_t::oob_info (C++ (C++ class), 289 member), 311 esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_fri esp_ble_mesh_node_t::unicast_addr (C++ member), 289 (C++ member), 311 esp_ble_mesh_prov_cb_param_t::ble_mesh_friend_fri ESP_BLE_MESH_OCTET16_LEN (C macro), 315 (C++ member), 289 esp_ble_mesh_octet16_t (C++ type), 329 esp_ble_mesh_prov_cb_param_t::ble_mesh_heartbeat_ ESP_BLE_MESH_OCTET8_LEN (C macro), 315 (C++ class), 289 esp_ble_mesh_octet8_t (C++ type), 329 esp_ble_mesh_prov_cb_param_t::ble_mesh_heartbeat_ esp_ble_mesh_oob_method_t (C++ enum), 331 (C++ member), 290 esp_ble_mesh_opcode_config_client_get_tesp_ble_mesh_prov_cb_param_t::ble_mesh_heartbeat_ (C++ type), 329 (C++ member), 290 esp_ble_mesh_opcode_config_client_set_tesp_ble_mesh_prov_cb_param_t::ble_mesh_input_evt_ (C++ type), 329 (C++ class), 290 esp_ble_mesh_opcode_config_status_t esp_ble_mesh_prov_cb_param_t::ble_mesh_input_evt_ (C++ type), 329 (C++ member), 290 esp_ble_mesh_opcode_health_client_get_tesp_ble_mesh_prov_cb_param_t::ble_mesh_input_evt_ (C++ type), 330 (C++ member), 290 esp_ble_mesh_opcode_health_client_set_tesp_ble_mesh_prov_cb_param_t::ble_mesh_input_numb (C++ type), 330 (C++ class), 290 esp_ble_mesh_opcode_t (C++ type), 330 esp_ble_mesh_prov_cb_param_t::ble_mesh_input_numb esp_ble_mesh_output_action_t (C++ enum), (C++ member), 290 331 esp_ble_mesh_prov_cb_param_t::ble_mesh_input_stri ESP_BLE_MESH_OUTPUT_OOB (C++ enumerator), (C++ class), 290 331 esp_ble_mesh_prov_cb_param_t::ble_mesh_input_stri ESP_BLE_MESH_OVERFLOW_ERROR (C macro), (C++ member), 290 385 esp_ble_mesh_prov_cb_param_t::ble_mesh_link_close ESP_BLE_MESH_OVERFLOW_WARNING (C macro), (C++ class), 290 385 esp_ble_mesh_prov_cb_param_t::ble_mesh_link_close ESP_BLE_MESH_OVERHEAT_ERROR (C macro), (C++ member), 290 384 esp_ble_mesh_prov_cb_param_t::ble_mesh_link_open_ ESP_BLE_MESH_OVERHEAT_WARNING (C macro), (C++ class), 290 384 esp_ble_mesh_prov_cb_param_t::ble_mesh_link_open_ ESP_BLE_MESH_OVERLOAD_ERROR (C macro), (C++ member), 290 384 esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_disabl ESP_BLE_MESH_OVERLOAD_WARNING (C macro), (C++ class), 290 384 esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_disabl ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_ERROR (C++ member), 291 (C macro), 384 esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_enable ESP_BLE_MESH_POWER_SUPPLY_INTERRUPTED_WARNING (C++ class), 291 (C macro), 384 esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_enable ESP_BLE_MESH_PROV (C macro), 317 (C++ member), 291 ESP_BLE_MESH_PROV_ADV (C++ enumerator), 331 esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friend esp_ble_mesh_prov_adv_cb_t (C++ type), 352 (C++ class), 291 esp_ble_mesh_prov_bearer_t (C++ enum), esp_ble_mesh_prov_cb_param_t::ble_mesh_lpn_friend Espressif Systems 2119 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 291 (C++ member), 292 esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__bflrei_emnedsshh_ippr_otve_rcmbi_npaatrea_mp_atr:a:mble_mesh_output_num (C++ class), 291 (C++ class), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__bflrei_emnedsshh_ippr_otve_rcmbi_npaatrea_mp_atr:a:mb:l:ef_rmieesnhd__oaudtdprut_num (C++ member), 291 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__bploel_lm_ecsohm_pp_rpoavr_acmb_param_t::ble_mesh_output_num (C++ class), 291 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_elsppn__bploel_lm_ecsohm_pp_rpoavr_acmb:_:pearrra_mc_otd:e:ble_mesh_output_str (C++ member), 291 (C++ class), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_es_umbe_sghr_opurpo_va_dcdbr__pcaormapm__pta:r:abmle_mesh_output_str (C++ class), 291 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_es_umbe_sghr_opurpo_va_dcdbr__pcaormapm__pta:r:abml:e:_cmoemspha_npyr_oivd_disab (C++ member), 291 (C++ class), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_es_umbe_sghr_opurpo_va_dcdbr__pcaormapm__pta:r:abml:e:_emleesmhe_nptr_oavd_ddrisab (C++ member), 291 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_es_umbe_sghr_opurpo_va_dcdbr__pcaormapm__pta:r:abml:e:_emrers_hc_opdreov_enabl (C++ member), 291 (C++ class), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_es_umbe_sghr_opurpo_va_dcdbr__pcaormapm__pta:r:abml:e:_gmreosuhp__pardodvr_enabl (C++ member), 291 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_es_umbe_sghr_opurpo_va_dcdbr__pcaormapm__pta:r:abml:e:_mmoedsehl__pirdov_regis (C++ member), 291 (C++ class), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_eu_nmseusbh__gprroouvp__cabd_dpra_rcaomm_pt_:p:abrlaem_mesh_prov_regis (C++ class), 291 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_eu_nmseusbh__gprroouvp__cabd_dpra_rcaomm_pt_:p:abrlaem_:m:ecsohm_pparnoyv_iisdion_ (C++ member), 292 (C++ class), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_eu_nmseusbh__gprroouvp__cabd_dpra_rcaomm_pt_:p:abrlaem_:m:eeslhe_mpernotv_iasdidorn_ (C++ member), 292 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_eu_nmseusbh__gprroouvp__cabd_dpra_rcaomm_pt_:p:abrlaem_:m:eesrhr__pcroodveision_ (C++ member), 292 (C++ member), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_eu_nmseusbh__gprroouvp__cabd_dpra_rcaomm_pt_:p:abrlaem_:m:egsrho_uppr_oavdidsrion_ (C++ member), 292 (C++ member), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_emsopd_ebll_eu_nmseusbh__gprroouvp__cabd_dpra_rcaomm_pt_:p:abrlaem_:m:emsohd_eplr_oivdision_ (C++ member), 292 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_laed_dm_elsohc_aplr_oavp_pc_bk_epya_rcaomm_pt_:p:abrlaem_mesh_provision_ (C++ class), 292 (C++ member), 293 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_laed_dm_elsohc_aplr_oavp_pc_bk_epya_rcaomm_pt_:p:abrlaem_:m:easphp__pirdoxvision_ (C++ member), 292 (C++ class), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_laed_dm_elsohc_aplr_oavp_pc_bk_epya_rcaomm_pt_:p:abrlaem_:m:eesrhr__pcroodveisione (C++ member), 292 (C++ class), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_laed_dm_elsohc_aplr_oavp_pc_bk_epya_rcaomm_pt_:p:abrlaem_:m:enseht__pirdoxvisione (C++ member), 292 (C++ member), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_laed_dm_elsohc_aplr_onve_tc_bk_epya_rcaomm_pt_:p:abrlaem_mesh_provisione (C++ class), 292 (C++ member), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_laed_dm_elsohc_aplr_onve_tc_bk_epya_rcaomm_pt_:p:abrlaem_:m:eesrhr__pcroodveisione (C++ member), 292 (C++ member), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_laed_dm_elsohc_aplr_onve_tc_bk_epya_rcaomm_pt_:p:abrlaem_:m:enseht__pirdoxvisione (C++ member), 292 (C++ class), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_lbei_nmde_slho_cparlo_vm_ocdb__appapr_acmo_mtp:_:pbalrea_mmesh_provisione (C++ class), 292 (C++ member), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_lbei_nmde_slho_cparlo_vm_ocdb__appapr_acmo_mtp:_:pbalrea_mm:e:sahp_pp_riodvxisione (C++ member), 292 (C++ member), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_lbei_nmde_slho_cparlo_vm_ocdb__appapr_acmo_mtp:_:pbalrea_mm:e:scho_mppraonvyi_siidone (C++ member), 292 (C++ class), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_lbei_nmde_slho_cparlo_vm_ocdb__appapr_acmo_mtp:_:pbalrea_mm:e:sehl_epmreonvti_saidodnre (C++ member), 292 (C++ member), 294 esp_ble_mesh_prov_cb_param_t::ble_mesh_ensopd_eb_lbei_nmde_slho_cparlo_vm_ocdb__appapr_acmo_mtp:_:pbalrea_mm:e:sehr_rp_rcoovdiesione (C++ member), 292 (C++ class), 294 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 Espressif Systems 2120 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 294 (C++ member), 296 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__bpirnodv__lcobc_apla_rmaomd__ta:p:pb_lceo_mmpe_spha_rparmo:v:icsoimopnaen (C++ member), 294 (C++ class), 296 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__bpirnodv__lcobc_apla_rmaomd__ta:p:pb_lceo_mmpe_spha_rparmo:v:ieslieomneen (C++ member), 294 (C++ member), 296 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__bpirnodv__lcobc_apla_rmaomd__ta:p:pb_lceo_mmpe_spha_rparmo:v:iesriro_nceo (C++ member), 294 (C++ member), 296 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__bpirnodv__lcobc_apla_rmaomd__ta:p:pb_lceo_mmpe_spha_rparmo:v:imsoidoenle_ (C++ member), 295 (C++ member), 296 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__dperloevt_ec_bd_epva_rcaomm_pt_:p:abrlaem_mesh_provisione (C++ class), 295 (C++ member), 296 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__dperloevt_ec_bd_epva_rcaomm_pt_:p:abrlaem_:m:eesrhr__pcroodveisione (C++ member), 295 (C++ class), 296 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__dperloevt_ec_bn_opdaer_awmi_tth:_:abdlder__mceosmhp__ppraorvaimsione (C++ class), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__dperloevt_ec_bn_opdaer_awmi_tth:_:abdlder__mceosmhp__ppraorvaims:i:oenrer (C++ member), 295 (C++ class), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__dperloevt_ec_bn_opdaer_awmi_tth:_:abdlder__mceosmhp__ppraorvaims:i:ounnei (C++ member), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__dperloevt_ec_bn_opdaer_awmi_tth:_:ubulied__mceosmhp__ppraorvaimsione (C++ class), 295 (C++ class), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__dperloevt_ec_bn_opdaer_awmi_tth:_:ubulied__mceosmhp__ppraorvaims:i:oenrer (C++ member), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__dperloevt_ec_bn_opdaer_awmi_tth:_:ubulied__mceosmhp__ppraorvaims:i:ounuei (C++ member), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__lpirnokv__cclbo_spea_reavmt__tp:a:rbalme_mesh_provisione (C++ class), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__lpirnokv__cclbo_spea_reavmt__tp:a:rbalme:_:mbeesahr_eprrovisione (C++ member), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__lpirnokv__cclbo_spea_reavmt__tp:a:rbalme:_:mreesahs_opnrovisione (C++ member), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__lpirnokv__ocpbe_np_aervatm__pta:r:abmle_mesh_provisione (C++ class), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__lpirnokv__ocpbe_np_aervatm__pta:r:abml:e:_bmeeasrhe_rprovisione (C++ member), 295 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ccobm_pp_apraarma_mt::ble_mesh_provisione (C++ class), 295 (C++ class), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ccobm_pp_apraarma_mt::::dbelvei_cmee_suhu_ipdrovisione (C++ member), 296 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ccobm_pp_apraarma_mt::::eblleem_emnets_hn_upmrovisione (C++ member), 296 (C++ class), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ccobm_pp_apraarma_mt::::nbeltek_emye_sihd_xprovisione (C++ member), 296 (C++ member), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ccobm_pp_apraarma_mt::::nboldee__miedsxh_provisione (C++ member), 296 (C++ class), 297 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ccobm_pp_apraarma_mt::::ubnliec_amsets_ha_dpdrrovisione (C++ member), 296 (C++ member), 298 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__dcebv__pwairtahm__atd:d:rb_lceo_mmpe_spha_rparmovisione (C++ class), 296 (C++ member), 298 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__dcebv__pwairtahm__atd:d:rb_lceo_mmpe_spha_rparmo:v:iesriro_nceo (C++ member), 296 (C++ member), 298 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__dcibs_apbalrea_mc_otm:p:_bplaer_ammesh_provisione (C++ class), 296 (C++ member), 298 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__dcibs_apbalrea_mc_otm:p:_bplaer_amme:s:he_rprr_ocvoidseione (C++ member), 296 (C++ member), 298 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ecnba_bplaer_acmo_mtp:_:pbalrea_mmesh_provisione (C++ class), 296 (C++ member), 298 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__pprroovv__ecnba_bplaer_acmo_mtp:_:pbalrea_mm:e:sehr_rp_rcoovdiesione Espressif Systems 2121 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 298 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vd_ecvb__upuairda_mm_att:c:hb_lceo_mmpe_spha_rparmoxy_clie (C++ class), 298 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vd_ecvb__upuairda_mm_att:c:hb_lceo_mmpe_spha_rparmo:x:ye_rcrl_iceo (C++ member), 298 (C++ class), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vn_ocdbe__pnaarmaem__cto:m:pb_lpea_rmaemsh_proxy_clie (C++ class), 298 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vn_ocdbe__pnaarmaem__cto:m:pb_lpea_rmaems:h:_eprrro_xcyo_dcelie (C++ member), 298 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vn_ocdbe__pnaarmaem__cto:m:pb_lpea_rmaems:h:_npordoex_yi_ncdleixe (C++ member), 298 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vp_rcibm_aprayr_aeml_etm:_:abdlder__mceosmhp__ppraorxaym_clie (C++ class), 298 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vp_rcibm_aprayr_aeml_etm:_:abdlder__mceosmhp__ppraorxaym_:c:leirer (C++ member), 298 (C++ class), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vp_rcobv__pdaartaam__itn:f:ob_lceo_mmpe_spha_rparmoxy_clie (C++ class), 298 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vp_rcobv__pdaartaam__itn:f:ob_lceo_mmpe_spha_rparmo:x:ye_rcrl_iceo (C++ member), 298 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vs_tcabt_ipca_roaomb__tv:a:lb_lceo_mmpe_spha_rparmoxy_clie (C++ class), 298 (C++ class), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sperto_vs_tcabt_ipca_roaomb__tv:a:lb_lceo_mmpe_spha_rparmo:x:ye_rcrl_iceo (C++ member), 299 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sptroorve__cnbo_dpea_rcaomm_pt_:d:abtlae__cmoemsph__pparroaxmy_clie (C++ class), 299 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sptroorve__cnbo_dpea_rcaomm_pt_:d:abtlae__cmoemsph__pparroaxmy:_:caldider (C++ member), 299 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__sptroorve__cnbo_dpea_rcaomm_pt_:d:abtlae__cmoemsph__pparroaxmy:_:celrire_ (C++ member), 299 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__upprdoavt_ec_bl_opcaarla_ma_ptp:_:kbelye__cmoemsph__pparroaxmy_clie (C++ class), 299 (C++ member), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__upprdoavt_ec_bl_opcaarla_ma_ptp:_:kbelye__cmoemsph__pparroaxmy:_:calpipe_ (C++ member), 299 (C++ class), 300 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__upprdoavt_ec_bl_opcaarla_ma_ptp:_:kbelye__cmoemsph__pparroaxmy:_:celrire_ (C++ member), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__upprdoavt_ec_bl_opcaarla_ma_ptp:_:kbelye__cmoemsph__pparroaxmy:_:cnleite_ (C++ member), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__upprdoavt_ec_bl_opcaarla_mn_ett:_:kbelye__cmoemsph__pparroaxmy_clie (C++ class), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__upprdoavt_ec_bl_opcaarla_mn_ett:_:kbelye__cmoemsph__pparroaxmy:_:celrire_ (C++ member), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_vbilsei_omneesrh__upprdoavt_ec_bl_opcaarla_mn_ett:_:kbelye__cmoemsph__pparroaxmy:_:cnleite_ (C++ member), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pardodv__fcibl_tpearr_aamd_dtr:_:cbolmep__mpeasrha_mproxy_clie (C++ class), 299 (C++ class), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pardodv__fcibl_tpearr_aamd_dtr:_:cbolmep__mpeasrha_mp:r:ocxoyn_nc_lhiaen (C++ member), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pardodv__fcibl_tpearr_aamd_dtr:_:cbolmep__mpeasrha_mp:r:oexryr__ccloidee (C++ member), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pardodv__fcibl_tpearr_aamd_dtr:_:cbolmep__mpeasrha_mp:r:onxeyt__cildixe (C++ member), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt__pcaormapm__pta:r:abmle_mesh_proxy_clie (C++ class), 299 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt__pcaormapm__pta:r:abml:e:_amdedsrh_proxy_clie (C++ member), 300 (C++ member), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt__pcaormapm__pta:r:abml:e:_amdedsrh__tpyrpoexy_clie (C++ member), 300 (C++ class), 301 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__pcroonvn_eccbt__pcaormapm__pta:r:abml:e:_emrers_hc_opdreoxy_clie Espressif Systems 2122 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 301 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreomvo_vceb__fpialrtaemr__ta:d:derr_rc_ocmopd_eparam::err_c (C++ member), 301 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__prreomvo_vceb__fpialrtaemr__ta:d:dErS_Pc_oBmLpE__pMaErSaHm_:F:RnNeDt__Fi (C++ member), 301 (C++ enumerator), 289 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__psreotv__fcibl_tpearr_atmy_pte:_:cEoSmPp__BpLaEr_aMmESH_FRND_F (C++ class), 301 (C++ enumerator), 289 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__psreotv__fcibl_tpearr_atmy_pte:_:cEoSmPp__BpLaEr_aMmE:S:Hc_oFnRnN_Dh_aFn (C++ member), 302 (C++ enumerator), 289 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__psreotv__fcibl_tpearr_atmy_pte:_:cEoSmPp__BpLaEr_aMmE:S:He_rFrR_NcDo_dFe (C++ member), 302 (C++ enumerator), 289 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ec_lmieesnht__psreotv__fcibl_tpearr_atmy_pte:_:cEoSmPp__BpLaEr_aMmE:S:Hn_eFtR_NiDd_xF (C++ member), 302 (C++ enumerator), 289 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_eg_amtets_hd_ipsraobvl_ec_bc_opmapr_apma_rta:m:feature (C++ class), 302 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_eg_amtets_hd_ipsraobvl_ec_bc_opmapr_apma_rta:m::f:renrdr__fcroideendship_est (C++ member), 302 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_eg_amtets_he_nparbolve__ccbo_mppa_rpaamr_atm::frnd_friendship_ter (C++ class), 302 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_eg_amtets_he_nparbolve__ccbo_mppa_rpaamr_atm::::hebr_rd_sctode (C++ member), 302 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ei_dmeensthi_tpyr_oevn_acbbl_ep_acroammp__tp:a:rhabm_src (C++ class), 302 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_ei_dmeensthi_tpyr_oevn_acbbl_ep_acroammp__tp:a:rhaema:r:tebrera_tc_omdseg_recv (C++ member), 302 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_es_emrevsehr__pcroonvn_eccbt_epda_rpaamr_atm::hops (C++ class), 302 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_es_emrevsehr__pcroonvn_eccbt_epda_rpaamr_atm::::icnodnenx_handle (C++ member), 302 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_es_emrevsehr__pdriosvc_ocnbn_epcatreadm__pta:r:aimnit_ttl (C++ class), 302 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_es_emrevsehr__pdriosvc_ocnbn_epcatreadm__pta:r:almp:n:_cdoinsna_bhlaen_dcloemp (C++ member), 302 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_epsrpo_xbyl_es_emrevsehr__pdriosvc_ocnbn_epcatreadm__pta:r:almp:n:_reenaasbolne_comp (C++ member), 302 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__bflaes_tm_epsrho_vp_raocvt_icobn__pcaormapm__pta:r:almpn_friendship_esta (C++ class), 302 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__bflaes_tm_epsrho_vp_raocvt_icobn__pcaormapm__pta:r:almp:n:_sftraiteunsd_sahcitpi_otnerm (C++ member), 303 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__bflaes_tm_epsrho_vp_rionvf_oc_bc_opmapr_apma_rta:m:lpn_poll_comp (C++ class), 303 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__bflaes_tm_epsrho_vp_rionvf_oc_bc_opmapr_apma_rta:m::m:osdtealt_ussu_bm_agtrcohup_add (C++ member), 303 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__bflaes_tm_epsrho_vp_rionvf_oc_bc_opmapr_apma_rta:m::m:osdtealt_uusn_snuebt__girdoxup_a (C++ member), 303 (C++ member), 289 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__bflaes_tm_epsrho_vp_rionvf_oc_bc_opmapr_apma_rta:m::n:osdtea_taudsd__uanpipc_aksety_co (C++ member), 303 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__boloeb__mpeusbh__kperyo_vc_ocmbp__ppaarraamm_t::node_add_net_key_co (C++ class), 303 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__boloeb__mpeusbh__kperyo_vc_ocmbp__ppaarraamm_:t::e:rnro_dceo_dbeind_app_key_t (C++ member), 303 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__bulnep_rmoevs_hd_epvr_onva_mceb__cpoamrpa_mp_atr:a:mnode_prov_complete (C++ class), 303 (C++ member), 284 esp_ble_mesh_prov_cb_param_t::ble_mesh_essept__bulnep_rmoevs_hd_epvr_onva_mceb__cpoamrpa_mp_atr:a:mn:o:deer_rp_rcoovd_edisable_c (C++ member), 303 (C++ member), 284 esp_ble_mesh_prov_cb_param_t::deinit_meesshp__cbolmep_mesh_prov_cb_param_t::node_prov_enable_co (C++ member), 289 (C++ member), 284 esp_ble_mesh_prov_cb_param_t::enable esp_ble_mesh_prov_cb_param_t::node_prov_input Espressif Systems 2123 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 284 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::node_prove_sipn_pbulte__nmuems_hc_opmrpov_cb_param_t::provisioner_prov_co (C++ member), 284 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_prove_sipn_pbulte__smters_hc_opmrpov_cb_param_t::provisioner_prov_de (C++ member), 284 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_prove_slpi_nbkl_ec_lmoesseh_prov_cb_param_t::provisioner_prov_di (C++ member), 284 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_prove_slpi_nbkl_eo_pmeensh_prov_cb_param_t::provisioner_prov_en (C++ member), 284 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_prove_sopu_tbpluet__mneusmh_prov_cb_param_t::provisioner_prov_in (C++ member), 284 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_prove_sopu_tbpluet__msetsrh_prov_cb_param_t::provisioner_prov_in (C++ member), 284 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::node_prove_srpe_sbelte_mesh_prov_cb_param_t::provisioner_prov_in (C++ member), 284 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::node_prove_sspe_tb_loeo_bm_epsuhb__pkreoyv__ccobm_pparam_t::provisioner_prov_li (C++ member), 284 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_proxeys_pg_abtlte__dmiessahb_lper_ocvo_mcpb_param_t::provisioner_prov_li (C++ member), 285 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_proxeys_pg_abtlte__emneasbhl_ep_rcoovm_pcb_param_t::provisioner_prov_ou (C++ member), 285 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_proxeys_pi_dbelnet_imteys_he_nparbolve__ccbo_mpparam_t::provisioner_prov_re (C++ member), 285 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::node_set_eusnpp_rbolve__dmeevs_hn_apmreo_vc_ocmbp_param_t::provisioner_prov_re (C++ member), 284 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::op (C++ esp_ble_mesh_prov_cb_param_t::provisioner_recv_he member), 287 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::prov_regiesstpe_rb_lceo_mmpesh_prov_cb_param_t::provisioner_recv_un (C++ member), 284 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::provisioneesrp__abdlde__ampeps_hk_epyr_ocvo_mcpb_param_t::provisioner_set_dev (C++ member), 286 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::provisioneesrp__abdlde__nmeets_hk_epyr_ocvo_mcpb_param_t::provisioner_set_hea (C++ member), 286 (C++ member), 287 esp_ble_mesh_prov_cb_param_t::provisioneesrp__abdlde__umnepsrho_vp_rdoevv__ccbo_mpparam_t::provisioner_set_hea (C++ member), 285 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::provisioneesrp__bbilned__maepsph__kperyo_vt_oc_bm_opdaerla_mc_otm:p:provisioner_set_nod (C++ member), 286 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::provisioneesrp__cblloes_em_esseht_tpirnogvs__cwbi_tpha_rianmd_etx:_:cpormopvisioner_set_pri (C++ member), 287 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::provisioneesrp__cblloes_em_esseht_tpirnogvs__cwbi_tpha_ruaimd__tc:o:mpprovisioner_set_pro (C++ member), 287 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::provisioneesrp__dbellee_tmee_sdhe_vp_rcoovm_pcb_param_t::provisioner_set_sta (C++ member), 285 (C++ member), 285 esp_ble_mesh_prov_cb_param_t::provisioneesrp__dbellee_tmee_snho_dper_owvi_tchb__apdadrra_mc_otm:p:provisioner_store_n (C++ member), 286 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::provisioneesrp__dbellee_tmee_snho_dper_owvi_tchb__upuairda_mc_otm:p:provisioner_update_ (C++ member), 286 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::provisioneesrp__dbellee_tmee_sshe_tptrionvg_sc_bw_iptahr_aimn_dte:x:_pcroomvpisioner_update_ (C++ member), 287 (C++ member), 286 esp_ble_mesh_prov_cb_param_t::provisioneesrp__dbellee_tmee_sshe_tptrionvg_sc_bw_iptahr_aumi_dt_:c:opmrpoxy_client_add_fi (C++ member), 287 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::provisioneesrp__dbilree_cmte_sehr_apsreo_vs_ectbt_ipnagrsa_mc_otm:p:proxy_client_connec (C++ member), 287 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::provisioneesrp__ebnlaeb_lmee_shhe_aprrtobve_actb__rpeacrva_mc_otm:p:proxy_client_connec (C++ member), 286 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::provisioneesrp__obpleen__mseestht_ipnrgosv__wcibt_hp_airnadme_xt_:c:opmrpoxy_client_discon (C++ member), 287 (C++ member), 288 esp_ble_mesh_prov_cb_param_t::provisioneesrp__obpleen__mseestht_ipnrgosv__wcibt_hp_auriadm__cto:m:pproxy_client_discon Espressif Systems 2124 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 288 ESP_BLE_MESH_PROV_OOB_ON_BOX (C++ enu- esp_ble_mesh_prov_cb_param_t::proxy_client_recmve_raatodrv),_3p3k1t (C++ member), 288 ESP_BLE_MESH_PROV_OOB_ON_DEV (C++ enu- esp_ble_mesh_prov_cb_param_t::proxy_client_recmve_raftoirl),t3e3r1_status (C++ member), 288 ESP_BLE_MESH_PROV_OOB_ON_PAPER (C++ esp_ble_mesh_prov_cb_param_t::proxy_client_remenouvmee_rfatiolr)t, e33r1_addr_comp (C++ member), 288 ESP_BLE_MESH_PROV_OOB_OTHER (C++ enumer- esp_ble_mesh_prov_cb_param_t::proxy_client_seta_tofr)i, l3t31er_type_comp (C++ member), 288 ESP_BLE_MESH_PROV_OOB_STRING (C++ enu- esp_ble_mesh_prov_cb_param_t::proxy_server_conmneeractotre),d331 (C++ member), 288 ESP_BLE_MESH_PROV_OOB_URI (C++ enumera- esp_ble_mesh_prov_cb_param_t::proxy_server_distocro),n3n3e1cted (C++ member), 288 ESP_BLE_MESH_PROV_OUTPUT_OOB_MAX_LEN esp_ble_mesh_prov_cb_param_t::rssi (C macro), 317 (C++ member), 287 ESP_BLE_MESH_PROV_REGISTER_COMP_EVT esp_ble_mesh_prov_cb_param_t::rx_ttl (C++ enumerator), 332 (C++ member), 287 ESP_BLE_MESH_PROV_STATIC_OOB_MAX_LEN esp_ble_mesh_prov_cb_param_t::set_fast_prov_ac(Ctimoancr_oc),o3m1p7 (C++ member), 288 esp_ble_mesh_prov_t (C++ class), 310 esp_ble_mesh_prov_cb_param_t::set_fast_epsrpo_vb_lien_fmoe_scho_mpprovisioner_add_local_app_key (C++ member), 288 (C++ function), 344 esp_ble_mesh_prov_cb_param_t::type ESP_BLE_MESH_PROVISIONER_ADD_LOCAL_APP_KEY_COMP_E (C++ member), 286 (C++ enumerator), 334 esp_ble_mesh_prov_cb_param_t::uid esp_ble_mesh_provisioner_add_local_net_key (C++ member), 287 (C++ function), 344 esp_ble_mesh_prov_cb_param_t::[anonymouEsS]P_BLE_MESH_PROVISIONER_ADD_LOCAL_NET_KEY_COMP_E (C++ enum), 289 (C++ enumerator), 334 esp_ble_mesh_prov_cb_t (C++ type), 352 esp_ble_mesh_provisioner_add_unprov_dev esp_ble_mesh_prov_data_info_t (C++ (C++ function), 349 class), 311 ESP_BLE_MESH_PROVISIONER_ADD_UNPROV_DEV_COMP_EVT esp_ble_mesh_prov_data_info_t::flag (C++ enumerator), 333 (C++ member), 311 esp_ble_mesh_provisioner_bind_app_key_to_local_mo esp_ble_mesh_prov_data_info_t::flags (C++ function), 344 (C++ member), 311 ESP_BLE_MESH_PROVISIONER_BIND_APP_KEY_TO_MODEL_CO esp_ble_mesh_prov_data_info_t::iv_index (C++ enumerator), 334 (C++ member), 311 esp_ble_mesh_provisioner_close_settings_with_inde esp_ble_mesh_prov_data_info_t::net_idx (C++ function), 346 (C++ member), 311 ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_INDE ESP_BLE_MESH_PROV_EVT_MAX (C++ enumera- (C++ enumerator), 334 tor), 336 esp_ble_mesh_provisioner_close_settings_with_uid ESP_BLE_MESH_PROV_GATT (C++ enumerator), (C++ function), 346 331 ESP_BLE_MESH_PROVISIONER_CLOSE_SETTINGS_WITH_UID_ ESP_BLE_MESH_PROV_INPUT_OOB_MAX_LEN (C (C++ enumerator), 334 macro), 317 esp_ble_mesh_provisioner_delete_dev ESP_BLE_MESH_PROV_OOB_2D_CODE (C++ enu- (C++ function), 351 merator), 331 ESP_BLE_MESH_PROVISIONER_DELETE_DEV_COMP_EVT ESP_BLE_MESH_PROV_OOB_BAR_CODE (C++ (C++ enumerator), 333 enumerator), 331 esp_ble_mesh_provisioner_delete_node_with_addr ESP_BLE_MESH_PROV_OOB_IN_BOX (C++ enu- (C++ function), 343 merator), 331 ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_ADDR_CO ESP_BLE_MESH_PROV_OOB_IN_MANUAL (C++ (C++ enumerator), 334 enumerator), 331 esp_ble_mesh_provisioner_delete_node_with_uuid esp_ble_mesh_prov_oob_info_t (C++ enum), (C++ function), 343 331 ESP_BLE_MESH_PROVISIONER_DELETE_NODE_WITH_UUID_CO ESP_BLE_MESH_PROV_OOB_NFC (C++ enumera- (C++ enumerator), 334 tor), 331 esp_ble_mesh_provisioner_delete_settings_with_ind ESP_BLE_MESH_PROV_OOB_NUMBER (C++ enu- (C++ function), 347 merator), 331 ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGS_WITH_IND Espressif Systems 2125 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ enumerator), 334 (C++ function), 349 esp_ble_mesh_provisioner_delete_settingEsS_Pw_iBtLhE__uMiEdSH_PROVISIONER_PROV_ENABLE_COMP_EVT (C++ function), 347 (C++ enumerator), 333 ESP_BLE_MESH_PROVISIONER_DELETE_SETTINGESS_PW_IBTLHE__UMIEDS_HC_OPMRPO_VEIVSTIONER_PROV_INPUT_EVT (C++ enumerator), 334 (C++ enumerator), 333 esp_ble_mesh_provisioner_direct_erase_sEeStPt_iBnLgEs_MESH_PROVISIONER_PROV_INPUT_NUMBER_COMP_E (C++ function), 346 (C++ enumerator), 334 ESP_BLE_MESH_PROVISIONER_DRIECT_ERASE_SEESTPT_IBNLGES__MCEOSMHP__PERVOTVISIONER_PROV_INPUT_STRING_COMP_E (C++ enumerator), 334 (C++ enumerator), 334 ESP_BLE_MESH_PROVISIONER_ENABLE_HEARTBEEASTP__RBELCEV__MCEOSMHP__PERVOTVISIONER_PROV_LINK_CLOSE_EVT (C++ enumerator), 334 (C++ enumerator), 333 esp_ble_mesh_provisioner_get_free_settiEnSgPs__BcLoEu_nMtESH_PROVISIONER_PROV_LINK_OPEN_EVT (C++ function), 347 (C++ enumerator), 333 esp_ble_mesh_provisioner_get_local_app_EkSePy_BLE_MESH_PROVISIONER_PROV_OUTPUT_EVT (C++ function), 344 (C++ enumerator), 333 esp_ble_mesh_provisioner_get_local_net_EkSePy_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_CO (C++ function), 345 (C++ enumerator), 334 esp_ble_mesh_provisioner_get_node_indexESP_BLE_MESH_PROVISIONER_PROV_READ_OOB_PUB_KEY_EV (C++ function), 342 (C++ enumerator), 333 esp_ble_mesh_provisioner_get_node_name esp_ble_mesh_provisioner_read_oob_pub_key (C++ function), 342 (C++ function), 348 esp_ble_mesh_provisioner_get_node_tablee_sepn_tbrlye_mesh_provisioner_recv_heartbeat (C++ function), 343 (C++ function), 345 esp_ble_mesh_provisioner_get_node_with_EaSdPd_rBLE_MESH_PROVISIONER_RECV_HEARTBEAT_MESSAGE_E (C++ function), 343 (C++ enumerator), 334 esp_ble_mesh_provisioner_get_node_with_EnSaPm_eBLE_MESH_PROVISIONER_RECV_UNPROV_ADV_PKT_EVT (C++ function), 343 (C++ enumerator), 333 esp_ble_mesh_provisioner_get_node_with_eusupi_dble_mesh_provisioner_set_dev_uuid_match (C++ function), 343 (C++ function), 351 esp_ble_mesh_provisioner_get_prov_node_EcSoPu_nBtLE_MESH_PROVISIONER_SET_DEV_UUID_MATCH_COMP_ (C++ function), 343 (C++ enumerator), 333 esp_ble_mesh_provisioner_get_settings_iensdpe_xble_mesh_provisioner_set_heartbeat_filter_inf (C++ function), 347 (C++ function), 345 esp_ble_mesh_provisioner_get_settings_uEiSdP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_INF (C++ function), 347 (C++ enumerator), 334 esp_ble_mesh_provisioner_input_number esp_ble_mesh_provisioner_set_heartbeat_filter_typ (C++ function), 349 (C++ function), 345 esp_ble_mesh_provisioner_input_string ESP_BLE_MESH_PROVISIONER_SET_HEARTBEAT_FILTER_TYP (C++ function), 349 (C++ enumerator), 334 esp_ble_mesh_provisioner_open_settings_ewsipt_hb_lien_dmeexsh_provisioner_set_node_name (C++ function), 346 (C++ function), 342 ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_EWSIPT_HB_LIEN_DMEEXS_HC_OPMRPO_VEIVSTIONER_SET_NODE_NAME_COMP_EVT (C++ enumerator), 334 (C++ enumerator), 334 esp_ble_mesh_provisioner_open_settings_ewsipt_hb_luei_dmesh_provisioner_set_primary_elem_addr (C++ function), 346 (C++ function), 351 ESP_BLE_MESH_PROVISIONER_OPEN_SETTINGS_EWSIPT_HB_LUEI_DM_ECSOHM_PP_REOVVTISIONER_SET_PRIMARY_ELEM_ADDR_CO (C++ enumerator), 334 (C++ enumerator), 333 ESP_BLE_MESH_PROVISIONER_PROV_COMPLETE_eEsVpT_ble_mesh_provisioner_set_prov_data_info (C++ enumerator), 333 (C++ function), 351 ESP_BLE_MESH_PROVISIONER_PROV_DEV_WITH_EASDPD_RB_LCEO_MMPE_SEHV_TPROVISIONER_SET_PROV_DATA_INFO_COMP_ (C++ enumerator), 333 (C++ enumerator), 333 esp_ble_mesh_provisioner_prov_device_wietshp__abdlder_mesh_provisioner_set_static_oob_value (C++ function), 350 (C++ function), 351 esp_ble_mesh_provisioner_prov_disable ESP_BLE_MESH_PROVISIONER_SET_STATIC_OOB_VALUE_COM (C++ function), 349 (C++ enumerator), 333 ESP_BLE_MESH_PROVISIONER_PROV_DISABLE_CeOsMpP__bElVeT_mesh_provisioner_store_node_comp_data (C++ enumerator), 333 (C++ function), 343 esp_ble_mesh_provisioner_prov_enable ESP_BLE_MESH_PROVISIONER_STORE_NODE_COMP_DATA_COM Espressif Systems 2126 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ enumerator), 334 esp_ble_mesh_register_generic_client_callback esp_ble_mesh_provisioner_update_local_app_key (C++ function), 386 (C++ function), 344 esp_ble_mesh_register_generic_server_callback ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_APP_KEY_(CC+O+MPf_unEcVtiTon), 386 (C++ enumerator), 334 esp_ble_mesh_register_health_client_callback esp_ble_mesh_provisioner_update_local_net_key (C++ function), 377 (C++ function), 345 esp_ble_mesh_register_health_server_callback ESP_BLE_MESH_PROVISIONER_UPDATE_LOCAL_NET_KEY_(CC+O+MPf_unEcVtiTon), 377 (C++ enumerator), 334 esp_ble_mesh_register_light_client_callback esp_ble_mesh_proxy_client_add_filter_addr (C++ function), 453 (C++ function), 353 esp_ble_mesh_register_lighting_server_callback ESP_BLE_MESH_PROXY_CLIENT_ADD_FILTER_ADDR_COMP(C_+E+VTfunction), 454 (C++ enumerator), 335 esp_ble_mesh_register_prov_callback esp_ble_mesh_proxy_client_connect (C++ function), 347 (C++ function), 353 esp_ble_mesh_register_sensor_client_callback ESP_BLE_MESH_PROXY_CLIENT_CONNECT_COMP_EVT (C++ function), 416 (C++ enumerator), 335 esp_ble_mesh_register_sensor_server_callback ESP_BLE_MESH_PROXY_CLIENT_CONNECTED_EVT (C++ function), 417 (C++ enumerator), 335 esp_ble_mesh_register_time_scene_client_callback esp_ble_mesh_proxy_client_disconnect (C++ function), 432 (C++ function), 353 esp_ble_mesh_register_time_scene_server_callback ESP_BLE_MESH_PROXY_CLIENT_DISCONNECT_COMP_EVT (C++ function), 432 (C++ enumerator), 335 ESP_BLE_MESH_RELAY_DISABLED (C macro), ESP_BLE_MESH_PROXY_CLIENT_DISCONNECTED_EVT 315 (C++ enumerator), 335 ESP_BLE_MESH_RELAY_ENABLED (C macro), 315 ESP_BLE_MESH_PROXY_CLIENT_RECV_ADV_PKT_EESVPT_BLE_MESH_RELAY_NOT_SUPPORTED (C (C++ enumerator), 335 macro), 315 ESP_BLE_MESH_PROXY_CLIENT_RECV_FILTER_SETSAPT_UBSL_EE_VMTESH_SAMPLE_FUNC_ACCUMULATED (C++ enumerator), 335 (C++ enumerator), 431 esp_ble_mesh_proxy_client_remove_filterE_SaPd_dBrLE_MESH_SAMPLE_FUNC_ARITHMETIC_MEAN (C++ function), 353 (C++ enumerator), 431 ESP_BLE_MESH_PROXY_CLIENT_REMOVE_FILTERE_SAPD_DBRL_EC_OMMEPS_HE_VSTAMPLE_FUNC_COUNT (C++ (C++ enumerator), 335 enumerator), 431 esp_ble_mesh_proxy_client_set_filter_tyEpSeP_BLE_MESH_SAMPLE_FUNC_INSTANTANEOUS (C++ function), 353 (C++ enumerator), 431 ESP_BLE_MESH_PROXY_CLIENT_SET_FILTER_TYEPSEP__CBOLMEP__MEEVSTH_SAMPLE_FUNC_MAXIMUM (C++ (C++ enumerator), 335 enumerator), 431 esp_ble_mesh_proxy_filter_type_t (C++ ESP_BLE_MESH_SAMPLE_FUNC_MINIMUM (C++ enum), 332 enumerator), 431 esp_ble_mesh_proxy_gatt_disable (C++ ESP_BLE_MESH_SAMPLE_FUNC_RMS (C++ enu- function), 353 merator), 431 esp_ble_mesh_proxy_gatt_enable (C++ ESP_BLE_MESH_SAMPLE_FUNC_UNSPECIFIED function), 352 (C++ enumerator), 431 esp_ble_mesh_proxy_identity_enable esp_ble_mesh_scene_delete_t (C++ class), (C++ function), 352 436 ESP_BLE_MESH_PROXY_SERVER_CONNECTED_EVTesp_ble_mesh_scene_delete_t::scene_number (C++ enumerator), 335 (C++ member), 436 ESP_BLE_MESH_PROXY_SERVER_DISCONNECTED_EESVPT_BLE_MESH_SCENE_NOT_FOUND (C macro), (C++ enumerator), 335 452 ESP_BLE_MESH_PUBLISH_TRANSMIT (C macro), ESP_BLE_MESH_SCENE_NUMBER_LEN (C macro), 316 451 ESP_BLE_MESH_PUSH (C++ enumerator), 331 esp_ble_mesh_scene_recall_t (C++ class), esp_ble_mesh_register_config_client_callback 436 (C++ function), 354 esp_ble_mesh_scene_recall_t::delay esp_ble_mesh_register_config_server_callback (C++ member), 436 (C++ function), 354 esp_ble_mesh_scene_recall_t::op_en esp_ble_mesh_register_custom_model_callback (C++ member), 436 (C++ function), 340 esp_ble_mesh_scene_recall_t::scene_number Espressif Systems 2127 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 436 ESP_BLE_MESH_SCENE_SUCCESS (C macro), 452 esp_ble_mesh_scene_recall_t::tid (C++ esp_ble_mesh_scenes_state_t (C++ class), member), 436 441 esp_ble_mesh_scene_recall_t::trans_timeesp_ble_mesh_scenes_state_t::current_scene (C++ member), 436 (C++ member), 442 ESP_BLE_MESH_SCENE_REG_FULL (C macro), esp_ble_mesh_scenes_state_t::in_progress 452 (C++ member), 442 esp_ble_mesh_scene_register_status_cb_tesp_ble_mesh_scenes_state_t::scene_count (C++ class), 439 (C++ member), 442 esp_ble_mesh_scene_register_status_cb_te:s:pc_ubrlree_nmte_sshc_esnceenes_state_t::scenes (C++ member), 439 (C++ member), 442 esp_ble_mesh_scene_register_status_cb_te:s:ps_cbelnee_smesh_scenes_state_t::status_code (C++ member), 439 (C++ member), 442 esp_ble_mesh_scene_register_status_cb_te:s:ps_tbalteu_sm_ecsohd_escenes_state_t::target_scene (C++ member), 439 (C++ member), 442 esp_ble_mesh_scene_register_t (C++ ESP_BLE_MESH_SCHEDULE_ACT_NO_ACTION (C class), 441 macro), 452 esp_ble_mesh_scene_register_t::scene_nuEmSbPe_rBLE_MESH_SCHEDULE_ACT_SCENE_RECALL (C++ member), 441 (C macro), 452 esp_ble_mesh_scene_register_t::scene_tyEpSeP_BLE_MESH_SCHEDULE_ACT_TURN_OFF (C (C++ member), 441 macro), 452 esp_ble_mesh_scene_register_t::scene_vaElSuPe_BLE_MESH_SCHEDULE_ACT_TURN_ON (C (C++ member), 441 macro), 452 esp_ble_mesh_scene_setup_srv_t (C++ ESP_BLE_MESH_SCHEDULE_DAY_ANY_DAY (C class), 442 macro), 451 esp_ble_mesh_scene_setup_srv_t::model ESP_BLE_MESH_SCHEDULE_ENTRY_MAX_INDEX (C++ member), 443 (C macro), 452 esp_ble_mesh_scene_setup_srv_t::rsp_ctrElSP_BLE_MESH_SCHEDULE_HOUR_ANY_HOUR (C (C++ member), 443 macro), 451 esp_ble_mesh_scene_setup_srv_t::state ESP_BLE_MESH_SCHEDULE_HOUR_ONCE_A_DAY (C++ member), 443 (C macro), 451 esp_ble_mesh_scene_srv_t (C++ class), 442 esp_ble_mesh_schedule_register_t (C++ esp_ble_mesh_scene_srv_t::last (C++ class), 443 member), 442 esp_ble_mesh_schedule_register_t::action esp_ble_mesh_scene_srv_t::model (C++ (C++ member), 443 member), 442 esp_ble_mesh_schedule_register_t::day esp_ble_mesh_scene_srv_t::rsp_ctrl (C++ member), 443 (C++ member), 442 esp_ble_mesh_schedule_register_t::day_of_week esp_ble_mesh_scene_srv_t::state (C++ (C++ member), 443 member), 442 esp_ble_mesh_schedule_register_t::hour esp_ble_mesh_scene_srv_t::transition (C++ member), 443 (C++ member), 442 esp_ble_mesh_schedule_register_t::in_use esp_ble_mesh_scene_status_cb_t (C++ (C++ member), 443 class), 438 esp_ble_mesh_schedule_register_t::minute esp_ble_mesh_scene_status_cb_t::current_scene (C++ member), 443 (C++ member), 438 esp_ble_mesh_schedule_register_t::month esp_ble_mesh_scene_status_cb_t::op_en (C++ member), 443 (C++ member), 438 esp_ble_mesh_schedule_register_t::scene_number esp_ble_mesh_scene_status_cb_t::remain_time (C++ member), 443 (C++ member), 438 esp_ble_mesh_schedule_register_t::second esp_ble_mesh_scene_status_cb_t::status_code (C++ member), 443 (C++ member), 438 esp_ble_mesh_schedule_register_t::trans_time esp_ble_mesh_scene_status_cb_t::target_scene (C++ member), 443 (C++ member), 438 esp_ble_mesh_schedule_register_t::year esp_ble_mesh_scene_store_t (C++ class), (C++ member), 443 436 ESP_BLE_MESH_SCHEDULE_SCENE_NO_SCENE esp_ble_mesh_scene_store_t::scene_number (C macro), 452 (C++ member), 436 ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_HOUR Espressif Systems 2128 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C macro), 451 (C++ member), 439 ESP_BLE_MESH_SCHEDULE_SEC_ANY_OF_MIN esp_ble_mesh_scheduler_act_status_cb_t::month (C macro), 451 (C++ member), 439 ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_MIN esp_ble_mesh_scheduler_act_status_cb_t::scene_num (C macro), 451 (C++ member), 439 ESP_BLE_MESH_SCHEDULE_SEC_EVERY_15_SEC esp_ble_mesh_scheduler_act_status_cb_t::second (C macro), 451 (C++ member), 439 ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_MIN esp_ble_mesh_scheduler_act_status_cb_t::trans_tim (C macro), 451 (C++ member), 439 ESP_BLE_MESH_SCHEDULE_SEC_EVERY_20_SEC esp_ble_mesh_scheduler_act_status_cb_t::year (C macro), 451 (C++ member), 439 ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_HOUR esp_ble_mesh_scheduler_setup_srv_t (C macro), 451 (C++ class), 444 ESP_BLE_MESH_SCHEDULE_SEC_ONCE_AN_MIN esp_ble_mesh_scheduler_setup_srv_t::model (C macro), 452 (C++ member), 444 ESP_BLE_MESH_SCHEDULE_YEAR_ANY_YEAR (C esp_ble_mesh_scheduler_setup_srv_t::rsp_ctrl macro), 451 (C++ member), 444 esp_ble_mesh_scheduler_act_get_t (C++ esp_ble_mesh_scheduler_setup_srv_t::state class), 436 (C++ member), 444 esp_ble_mesh_scheduler_act_get_t::indexesp_ble_mesh_scheduler_srv_t (C++ class), (C++ member), 437 443 esp_ble_mesh_scheduler_act_set_t (C++ esp_ble_mesh_scheduler_srv_t::model class), 437 (C++ member), 444 esp_ble_mesh_scheduler_act_set_t::actioensp_ble_mesh_scheduler_srv_t::rsp_ctrl (C++ member), 437 (C++ member), 444 esp_ble_mesh_scheduler_act_set_t::day esp_ble_mesh_scheduler_srv_t::state (C++ member), 437 (C++ member), 444 esp_ble_mesh_scheduler_act_set_t::day_oefs_pw_ebelke_mesh_scheduler_state_t (C++ (C++ member), 437 class), 443 esp_ble_mesh_scheduler_act_set_t::hour esp_ble_mesh_scheduler_state_t::schedule_count (C++ member), 437 (C++ member), 443 esp_ble_mesh_scheduler_act_set_t::indexesp_ble_mesh_scheduler_state_t::schedules (C++ member), 437 (C++ member), 443 esp_ble_mesh_scheduler_act_set_t::minuteesp_ble_mesh_scheduler_status_cb_t (C++ member), 437 (C++ class), 439 esp_ble_mesh_scheduler_act_set_t::monthesp_ble_mesh_scheduler_status_cb_t::schedules (C++ member), 437 (C++ member), 439 esp_ble_mesh_scheduler_act_set_t::sceneE_SnPu_mBbLeEr_MESH_SDU_MAX_LEN (C macro), 315 (C++ member), 437 ESP_BLE_MESH_SELF_TEST_ERROR (C macro), esp_ble_mesh_scheduler_act_set_t::second 384 (C++ member), 437 ESP_BLE_MESH_SELF_TEST_WARNING (C esp_ble_mesh_scheduler_act_set_t::trans_time macro), 384 (C++ member), 437 esp_ble_mesh_sensor_cadence_get_t esp_ble_mesh_scheduler_act_set_t::year (C++ class), 419 (C++ member), 437 esp_ble_mesh_sensor_cadence_get_t::property_id esp_ble_mesh_scheduler_act_status_cb_t (C++ member), 419 (C++ class), 439 esp_ble_mesh_sensor_cadence_set_t esp_ble_mesh_scheduler_act_status_cb_t::action(C++ class), 419 (C++ member), 439 esp_ble_mesh_sensor_cadence_set_t::fast_cadence_h esp_ble_mesh_scheduler_act_status_cb_t::day (C++ member), 420 (C++ member), 439 esp_ble_mesh_sensor_cadence_set_t::fast_cadence_l esp_ble_mesh_scheduler_act_status_cb_t::day_of(C_+w+eemkember), 420 (C++ member), 439 esp_ble_mesh_sensor_cadence_set_t::fast_cadence_p esp_ble_mesh_scheduler_act_status_cb_t::hour (C++ member), 420 (C++ member), 439 esp_ble_mesh_sensor_cadence_set_t::property_id esp_ble_mesh_scheduler_act_status_cb_t::index (C++ member), 420 (C++ member), 439 esp_ble_mesh_sensor_cadence_set_t::status_min_int esp_ble_mesh_scheduler_act_status_cb_t::minute(C++ member), 420 Espressif Systems 2129 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_sensor_cadence_set_t::stateussp__tbrlieg_gmeers_hd_esletnas_odro_wcnlient_get_state_t::setting_g (C++ member), 420 (C++ member), 417 esp_ble_mesh_sensor_cadence_set_t::stateussp__tbrlieg_gmeers_hd_esletnas_ourp_client_get_state_t::settings_ (C++ member), 420 (C++ member), 417 esp_ble_mesh_sensor_cadence_set_t::statEuSsP__tBrLiEg_gMeErS_Ht_ySpEeNSOR_CLIENT_PUBLISH_EVT (C++ member), 420 (C++ enumerator), 431 esp_ble_mesh_sensor_cadence_status_cb_tesp_ble_mesh_sensor_client_set_state (C++ class), 421 (C++ function), 417 esp_ble_mesh_sensor_cadence_status_cb_tE:S:Pp_rBoLpEe_rMtEyS_Hi_dSENSOR_CLIENT_SET_STATE_EVT (C++ member), 421 (C++ enumerator), 431 esp_ble_mesh_sensor_cadence_status_cb_te:s:ps_ebnlseo_rm_ecsahd_esnecnes_ovra_lculeient_set_state_t (C++ member), 421 (C++ union), 417 esp_ble_mesh_sensor_cadence_t (C++ esp_ble_mesh_sensor_client_set_state_t::cadence_s class), 423 (C++ member), 418 esp_ble_mesh_sensor_cadence_t::fast_cadeesnpc_eb_lhei_gmhesh_sensor_client_set_state_t::setting_s (C++ member), 424 (C++ member), 418 esp_ble_mesh_sensor_cadence_t::fast_cadeesnpc_eb_lleo_wmesh_sensor_client_status_cb_t (C++ member), 424 (C++ union), 418 esp_ble_mesh_sensor_cadence_t::min_inteersvpa_lble_mesh_sensor_client_status_cb_t::cadence_s (C++ member), 424 (C++ member), 418 esp_ble_mesh_sensor_cadence_t::period_deisvpi_sbolre_mesh_sensor_client_status_cb_t::column_st (C++ member), 423 (C++ member), 418 esp_ble_mesh_sensor_cadence_t::trigger_edsepl_tbal_ed_omwensh_sensor_client_status_cb_t::descripto (C++ member), 423 (C++ member), 418 esp_ble_mesh_sensor_cadence_t::trigger_edsepl_tbal_eu_pmesh_sensor_client_status_cb_t::sensor_st (C++ member), 423 (C++ member), 418 esp_ble_mesh_sensor_cadence_t::trigger_etsypp_eble_mesh_sensor_client_status_cb_t::series_st (C++ member), 423 (C++ member), 418 esp_ble_mesh_sensor_client_cb_event_t esp_ble_mesh_sensor_client_status_cb_t::setting_s (C++ enum), 431 (C++ member), 418 esp_ble_mesh_sensor_client_cb_param_t esp_ble_mesh_sensor_client_status_cb_t::settings_ (C++ class), 422 (C++ member), 418 esp_ble_mesh_sensor_client_cb_param_t::EeSrPr_oBrL_Ec_oMdEeSH_SENSOR_CLIENT_TIMEOUT_EVT (C++ member), 423 (C++ enumerator), 431 esp_ble_mesh_sensor_client_cb_param_t::epsapr_abmlse_mesh_sensor_column_get_t (C++ (C++ member), 423 class), 421 esp_ble_mesh_sensor_client_cb_param_t::esstpa_tbulse__cmbesh_sensor_column_get_t::property_id (C++ member), 423 (C++ member), 421 esp_ble_mesh_sensor_client_cb_t (C++ esp_ble_mesh_sensor_column_get_t::raw_value_x type), 430 (C++ member), 421 ESP_BLE_MESH_SENSOR_CLIENT_EVT_MAX esp_ble_mesh_sensor_column_status_cb_t (C++ enumerator), 431 (C++ class), 422 esp_ble_mesh_sensor_client_get_state esp_ble_mesh_sensor_column_status_cb_t::property_ (C++ function), 417 (C++ member), 422 ESP_BLE_MESH_SENSOR_CLIENT_GET_STATE_EVeTsp_ble_mesh_sensor_column_status_cb_t::sensor_co (C++ enumerator), 431 (C++ member), 422 esp_ble_mesh_sensor_client_get_state_t ESP_BLE_MESH_SENSOR_DATA_FORMAT_A (C (C++ union), 417 macro), 429 esp_ble_mesh_sensor_client_get_state_t:E:ScPa_dBeLnEc_eM_EgSeHt_SENSOR_DATA_FORMAT_A_MPID (C++ member), 417 (C macro), 430 esp_ble_mesh_sensor_client_get_state_t:E:ScPo_lBuLmEn__MgEeStH_SENSOR_DATA_FORMAT_A_MPID_LEN (C++ member), 417 (C macro), 429 esp_ble_mesh_sensor_client_get_state_t:E:SdPe_sBcLrEi_pMtEoSrH__gSeEtNSOR_DATA_FORMAT_B (C (C++ member), 417 macro), 429 esp_ble_mesh_sensor_client_get_state_t:E:SsPe_nBsLoEr__MgEeStH_SENSOR_DATA_FORMAT_B_MPID (C++ member), 417 (C macro), 430 esp_ble_mesh_sensor_client_get_state_t:E:SsPe_rBiLeEs__MgEeStH_SENSOR_DATA_FORMAT_B_MPID_LEN (C++ member), 417 (C macro), 429 Espressif Systems 2130 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_sensor_data_t (C++ class), (C++ member), 424 424 esp_ble_mesh_sensor_series_column_t::raw_value_y esp_ble_mesh_sensor_data_t::format (C++ member), 424 (C++ member), 424 esp_ble_mesh_sensor_series_get_t (C++ esp_ble_mesh_sensor_data_t::length class), 421 (C++ member), 424 esp_ble_mesh_sensor_series_get_t::op_en esp_ble_mesh_sensor_data_t::raw_value (C++ member), 421 (C++ member), 424 esp_ble_mesh_sensor_series_get_t::property_id ESP_BLE_MESH_SENSOR_DATA_ZERO_LEN (C (C++ member), 421 macro), 429 esp_ble_mesh_sensor_series_get_t::raw_value_x1 esp_ble_mesh_sensor_descriptor_get_t (C++ member), 421 (C++ class), 419 esp_ble_mesh_sensor_series_get_t::raw_value_x2 esp_ble_mesh_sensor_descriptor_get_t::op_en (C++ member), 421 (C++ member), 419 esp_ble_mesh_sensor_series_status_cb_t esp_ble_mesh_sensor_descriptor_get_t::property(C_+i+d class), 422 (C++ member), 419 esp_ble_mesh_sensor_series_status_cb_t::property_ ESP_BLE_MESH_SENSOR_DESCRIPTOR_LEN (C (C++ member), 422 macro), 429 esp_ble_mesh_sensor_series_status_cb_t::sensor_se esp_ble_mesh_sensor_descriptor_status_cb_t (C++ member), 422 (C++ class), 421 esp_ble_mesh_sensor_server_cb_event_t esp_ble_mesh_sensor_descriptor_status_cb_t::de(Cs+c+riepnutmor), 431 (C++ member), 421 esp_ble_mesh_sensor_server_cb_param_t esp_ble_mesh_sensor_descriptor_t (C++ (C++ class), 428 class), 423 esp_ble_mesh_sensor_server_cb_param_t::ctx esp_ble_mesh_sensor_descriptor_t::measure_peri(Co+d+ member), 428 (C++ member), 423 esp_ble_mesh_sensor_server_cb_param_t::model esp_ble_mesh_sensor_descriptor_t::negative_tol(Ce+r+anmceember), 428 (C++ member), 423 esp_ble_mesh_sensor_server_cb_param_t::value esp_ble_mesh_sensor_descriptor_t::positive_tol(Ce+r+anmceember), 428 (C++ member), 423 esp_ble_mesh_sensor_server_cb_t (C++ esp_ble_mesh_sensor_descriptor_t::sampling_funtycpte)i, o4n31 (C++ member), 423 esp_ble_mesh_sensor_server_cb_value_t esp_ble_mesh_sensor_descriptor_t::update_inter(Cv+a+l union), 419 (C++ member), 423 esp_ble_mesh_sensor_server_cb_value_t::get ESP_BLE_MESH_SENSOR_DIVISOR_TRIGGER_TYPE_LEN (C++ member), 419 (C macro), 429 esp_ble_mesh_sensor_server_cb_value_t::set esp_ble_mesh_sensor_get_t (C++ class), 420 (C++ member), 419 esp_ble_mesh_sensor_get_t::op_en (C++ esp_ble_mesh_sensor_server_cb_value_t::state_chan member), 421 (C++ member), 419 esp_ble_mesh_sensor_get_t::property_id ESP_BLE_MESH_SENSOR_SERVER_EVT_MAX (C++ member), 421 (C++ enumerator), 431 esp_ble_mesh_sensor_message_opcode_t ESP_BLE_MESH_SENSOR_SERVER_RECV_GET_MSG_EVT (C++ type), 330 (C++ enumerator), 431 ESP_BLE_MESH_SENSOR_NOT_APPL_MEASURE_PEeRsIpO_Dble_mesh_sensor_server_recv_get_msg_t (C macro), 429 (C++ union), 418 ESP_BLE_MESH_SENSOR_NOT_APPL_UPDATE_INTeEsRpV_AbLle_mesh_sensor_server_recv_get_msg_t::sensor (C macro), 429 (C++ member), 418 ESP_BLE_MESH_SENSOR_PERIOD_DIVISOR_MAX_eVsApL_UbEle_mesh_sensor_server_recv_get_msg_t::sensor (C macro), 429 (C++ member), 419 ESP_BLE_MESH_SENSOR_PROPERTY_ID_LEN (C esp_ble_mesh_sensor_server_recv_get_msg_t::sensor macro), 428 (C++ member), 418 esp_ble_mesh_sensor_sample_func (C++ esp_ble_mesh_sensor_server_recv_get_msg_t::sensor enum), 431 (C++ member), 418 esp_ble_mesh_sensor_series_column_t esp_ble_mesh_sensor_server_recv_get_msg_t::sensor (C++ class), 424 (C++ member), 419 esp_ble_mesh_sensor_series_column_t::coelsupm_nb_lwei_dmtehsh_sensor_server_recv_get_msg_t::sensor (C++ member), 424 (C++ member), 418 esp_ble_mesh_sensor_series_column_t::raews_pv_ablluee__mxesh_sensor_server_recv_get_msg_t::sensor Espressif Systems 2131 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 418 (C++ member), 423 ESP_BLE_MESH_SENSOR_SERVER_RECV_SET_MSGe_sEpV_Tble_mesh_sensor_settings_get_t (C++ enumerator), 431 (C++ class), 420 esp_ble_mesh_sensor_server_recv_set_msge_stp_ble_mesh_sensor_settings_get_t::sensor_proper (C++ union), 419 (C++ member), 420 esp_ble_mesh_sensor_server_recv_set_msge_stp:_:bsleen_smoers_hc_asdeennscoer_settings_status_cb_t (C++ member), 419 (C++ class), 421 esp_ble_mesh_sensor_server_recv_set_msge_stp:_:bsleen_smoers_hs_estetnisnogr_settings_status_cb_t::sensor_ (C++ member), 419 (C++ member), 422 ESP_BLE_MESH_SENSOR_SERVER_STATE_CHANGEe_sEpV_Tble_mesh_sensor_settings_status_cb_t::sensor_ (C++ enumerator), 431 (C++ member), 422 esp_ble_mesh_sensor_server_state_changee_stp_ble_mesh_sensor_setup_srv_t (C++ (C++ union), 418 class), 425 esp_ble_mesh_sensor_server_state_changee_stp:_:bsleen_smoers_hc_asdeennscoer__sseettup_srv_t::model (C++ member), 418 (C++ member), 425 esp_ble_mesh_sensor_server_state_changee_stp:_:bsleen_smoers_hs_estetnisnogr__sseettup_srv_t::rsp_ctrl (C++ member), 418 (C++ member), 425 ESP_BLE_MESH_SENSOR_SETTING_ACCESS_LEN esp_ble_mesh_sensor_setup_srv_t::state_count (C macro), 429 (C++ member), 425 ESP_BLE_MESH_SENSOR_SETTING_ACCESS_READesp_ble_mesh_sensor_setup_srv_t::states (C macro), 429 (C++ member), 425 ESP_BLE_MESH_SENSOR_SETTING_ACCESS_READe_sWpR_IbTlEe_mesh_sensor_srv_t (C++ class), 425 (C macro), 429 esp_ble_mesh_sensor_srv_t::model (C++ esp_ble_mesh_sensor_setting_get_t member), 425 (C++ class), 420 esp_ble_mesh_sensor_srv_t::rsp_ctrl esp_ble_mesh_sensor_setting_get_t::sensor_prop(Ce+r+tym_eimdber), 425 (C++ member), 420 esp_ble_mesh_sensor_srv_t::state_count esp_ble_mesh_sensor_setting_get_t::sensor_sett(Ci+n+g_mpermobpeer)r, t42y5_id (C++ member), 420 esp_ble_mesh_sensor_srv_t::states ESP_BLE_MESH_SENSOR_SETTING_PROPERTY_ID_LEN (C++ member), 425 (C macro), 429 esp_ble_mesh_sensor_state_t (C++ class), esp_ble_mesh_sensor_setting_set_t 424 (C++ class), 420 esp_ble_mesh_sensor_state_t::cadence esp_ble_mesh_sensor_setting_set_t::sensor_prop(Ce+r+tym_eimdber), 424 (C++ member), 420 esp_ble_mesh_sensor_state_t::descriptor esp_ble_mesh_sensor_setting_set_t::sensor_sett(Ci+n+g_mpermobpeer)r, t42y4_id (C++ member), 420 esp_ble_mesh_sensor_state_t::sensor_data esp_ble_mesh_sensor_setting_set_t::sensor_sett(Ci+n+g_mreamwber), 425 (C++ member), 420 esp_ble_mesh_sensor_state_t::sensor_property_id esp_ble_mesh_sensor_setting_status_cb_t (C++ member), 424 (C++ class), 422 esp_ble_mesh_sensor_state_t::series_column esp_ble_mesh_sensor_setting_status_cb_t::op_en(C++ member), 425 (C++ member), 422 esp_ble_mesh_sensor_state_t::setting_count esp_ble_mesh_sensor_setting_status_cb_t::senso(Cr+_+prmoepmebretr)y, _42i4d (C++ member), 422 esp_ble_mesh_sensor_state_t::settings esp_ble_mesh_sensor_setting_status_cb_t::senso(Cr+_+semtetmibnegr)_, a42c4cess (C++ member), 422 esp_ble_mesh_sensor_status_cb_t (C++ esp_ble_mesh_sensor_setting_status_cb_t::sensoclra_sss),e4t2t2ing_property_id (C++ member), 422 esp_ble_mesh_sensor_status_cb_t::marshalled_senso esp_ble_mesh_sensor_setting_status_cb_t::senso(Cr+_+semtetmibnegr)_, r42a2w (C++ member), 422 ESP_BLE_MESH_SENSOR_STATUS_MIN_INTERVAL_LEN esp_ble_mesh_sensor_setting_t (C++ (C macro), 429 class), 423 ESP_BLE_MESH_SENSOR_STATUS_MIN_INTERVAL_MAX esp_ble_mesh_sensor_setting_t::access (C macro), 429 (C++ member), 423 ESP_BLE_MESH_SENSOR_STATUS_TRIGGER_TYPE_CHAR esp_ble_mesh_sensor_setting_t::property_id (C macro), 429 (C++ member), 423 ESP_BLE_MESH_SENSOR_STATUS_TRIGGER_TYPE_UINT16 esp_ble_mesh_sensor_setting_t::raw (C macro), 429 Espressif Systems 2132 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_MESH_SENSOR_UNSPECIFIED_NEG_TOLeEsRpA_NbClEe_mesh_server_recv_gen_level_set_t::trans_t (C macro), 429 (C++ member), 408 ESP_BLE_MESH_SENSOR_UNSPECIFIED_POS_TOLeEsRpA_NbClEe_mesh_server_recv_gen_loc_global_set_t (C macro), 429 (C++ class), 410 ESP_BLE_MESH_SERVER_AUTO_RSP (C macro), esp_ble_mesh_server_recv_gen_loc_global_set_t::gl 329 (C++ member), 410 ESP_BLE_MESH_SERVER_FLAG_MAX (C++ enu- esp_ble_mesh_server_recv_gen_loc_global_set_t::gl merator), 336 (C++ member), 410 esp_ble_mesh_server_model_send_msg esp_ble_mesh_server_recv_gen_loc_global_set_t::gl (C++ function), 341 (C++ member), 410 ESP_BLE_MESH_SERVER_MODEL_STATE_MAX esp_ble_mesh_server_recv_gen_loc_local_set_t (C++ enumerator), 336 (C++ class), 410 esp_ble_mesh_server_model_update_state esp_ble_mesh_server_recv_gen_loc_local_set_t::flo (C++ function), 342 (C++ member), 410 ESP_BLE_MESH_SERVER_MODEL_UPDATE_STATE_eCsOpM_Pb_lEeV_Tmesh_server_recv_gen_loc_local_set_t::loc (C++ enumerator), 337 (C++ member), 410 esp_ble_mesh_server_recv_gen_admin_propeesrpt_yb_lgee_tm_etsh_server_recv_gen_loc_local_set_t::loc (C++ class), 407 (C++ member), 410 esp_ble_mesh_server_recv_gen_admin_propeesrpt_yb_lgee_tm_ets:h:_psreorpveerrt_yr_eicdv_gen_loc_local_set_t::loc (C++ member), 407 (C++ member), 410 esp_ble_mesh_server_recv_gen_admin_propeesrpt_yb_lsee_tm_etsh_server_recv_gen_loc_local_set_t::unc (C++ class), 410 (C++ member), 410 esp_ble_mesh_server_recv_gen_admin_propeesrpt_yb_lsee_tm_ets:h:_psreorpveerrt_yr_eicdv_gen_manufacturer_propert (C++ member), 411 (C++ class), 407 esp_ble_mesh_server_recv_gen_admin_propeesrpt_yb_lsee_tm_ets:h:_psreorpveerrt_yr_evcavl_ugeen_manufacturer_propert (C++ member), 411 (C++ member), 407 esp_ble_mesh_server_recv_gen_admin_propeesrpt_yb_lsee_tm_ets:h:_usseerrv_earc_creescsv_gen_manufacturer_propert (C++ member), 411 (C++ class), 411 esp_ble_mesh_server_recv_gen_client_proepsepr_tbilees__mgeesth__tserver_recv_gen_manufacturer_propert (C++ class), 407 (C++ member), 411 esp_ble_mesh_server_recv_gen_client_proepsepr_tbilees__mgeesth__ts:e:rpvreorp_erretcyv__igden_manufacturer_propert (C++ member), 408 (C++ member), 411 esp_ble_mesh_server_recv_gen_def_trans_etsipm_eb_lsee_tm_etsh_server_recv_gen_move_set_t (C++ class), 409 (C++ class), 409 esp_ble_mesh_server_recv_gen_def_trans_etsipm_eb_lsee_tm_ets:h:_tsrearnvse_rt_irmeecv_gen_move_set_t::delay (C++ member), 409 (C++ member), 409 esp_ble_mesh_server_recv_gen_delta_set_etsp_ble_mesh_server_recv_gen_move_set_t::delta_le (C++ class), 408 (C++ member), 409 esp_ble_mesh_server_recv_gen_delta_set_ets:p:_dbellea_ymesh_server_recv_gen_move_set_t::op_en (C++ member), 408 (C++ member), 409 esp_ble_mesh_server_recv_gen_delta_set_ets:p:_dbellet_am_elsehv_eslerver_recv_gen_move_set_t::tid (C++ member), 408 (C++ member), 409 esp_ble_mesh_server_recv_gen_delta_set_ets:p:_obpl_ee_nmesh_server_recv_gen_move_set_t::trans_ti (C++ member), 408 (C++ member), 409 esp_ble_mesh_server_recv_gen_delta_set_ets:p:_tbilde_mesh_server_recv_gen_onoff_set_t (C++ member), 408 (C++ class), 408 esp_ble_mesh_server_recv_gen_delta_set_ets:p:_tbrlaen_sm_etsihm_eserver_recv_gen_onoff_set_t::delay (C++ member), 408 (C++ member), 408 esp_ble_mesh_server_recv_gen_level_set_etsp_ble_mesh_server_recv_gen_onoff_set_t::onoff (C++ class), 408 (C++ member), 408 esp_ble_mesh_server_recv_gen_level_set_ets:p:_dbellea_ymesh_server_recv_gen_onoff_set_t::op_en (C++ member), 408 (C++ member), 408 esp_ble_mesh_server_recv_gen_level_set_ets:p:_lbelvee_lmesh_server_recv_gen_onoff_set_t::tid (C++ member), 408 (C++ member), 408 esp_ble_mesh_server_recv_gen_level_set_ets:p:_obpl_ee_nmesh_server_recv_gen_onoff_set_t::trans_t (C++ member), 408 (C++ member), 408 esp_ble_mesh_server_recv_gen_level_set_ets:p:_tbilde_mesh_server_recv_gen_onpowerup_set_t (C++ member), 408 (C++ class), 409 Espressif Systems 2133 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_server_recv_gen_onpowerup_essept__btl:e:_omnepsohw_esreurpver_recv_light_ctl_temperature_ra (C++ member), 409 (C++ class), 486 esp_ble_mesh_server_recv_gen_power_defaeuslpt__bsleet__mtesh_server_recv_light_ctl_temperature_ra (C++ class), 409 (C++ member), 486 esp_ble_mesh_server_recv_gen_power_defaeuslpt__bsleet__mte:s:hp_osweerrver_recv_light_ctl_temperature_ra (C++ member), 410 (C++ member), 486 esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_mesh_server_recv_light_ctl_temperature_se (C++ class), 409 (C++ class), 486 esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:edsehl_asyerver_recv_light_ctl_temperature_se (C++ member), 409 (C++ member), 486 esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:eosph__esnerver_recv_light_ctl_temperature_se (C++ member), 409 (C++ member), 486 esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:epsohw_esrerver_recv_light_ctl_temperature_se (C++ member), 409 (C++ member), 486 esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:etsihd_server_recv_light_ctl_temperature_se (C++ member), 409 (C++ member), 486 esp_ble_mesh_server_recv_gen_power_leveels_ps_ebtl_et_:m:etsrha_nsse_rtviemre_recv_light_ctl_temperature_se (C++ member), 409 (C++ member), 486 esp_ble_mesh_server_recv_gen_power_rangees_ps_ebtl_et_mesh_server_recv_light_ctl_temperature_se (C++ class), 410 (C++ member), 486 esp_ble_mesh_server_recv_gen_power_rangees_ps_ebtl_et_:m:ersahn_gsee_rmvaexr_recv_light_hsl_default_set_t (C++ member), 410 (C++ class), 488 esp_ble_mesh_server_recv_gen_power_rangees_ps_ebtl_et_:m:ersahn_gsee_rmvienr_recv_light_hsl_default_set_t: (C++ member), 410 (C++ member), 488 esp_ble_mesh_server_recv_gen_user_propeerstpy__bgleet__mtesh_server_recv_light_hsl_default_set_t: (C++ class), 407 (C++ member), 488 esp_ble_mesh_server_recv_gen_user_propeerstpy__bgleet__mte:s:hp_rsoeprevretry__riedcv_light_hsl_default_set_t: (C++ member), 407 (C++ member), 488 esp_ble_mesh_server_recv_gen_user_propeerstpy__bsleet__mtesh_server_recv_light_hsl_hue_set_t (C++ class), 410 (C++ class), 487 esp_ble_mesh_server_recv_gen_user_propeerstpy__bsleet__mte:s:hp_rsoeprevretry__riedcv_light_hsl_hue_set_t::del (C++ member), 410 (C++ member), 487 esp_ble_mesh_server_recv_gen_user_propeerstpy__bsleet__mte:s:hp_rsoeprevretry__rveaclvu_elight_hsl_hue_set_t::hue (C++ member), 410 (C++ member), 487 esp_ble_mesh_server_recv_light_ctl_defaeuslpt__bsleet__mtesh_server_recv_light_hsl_hue_set_t::op_ (C++ class), 486 (C++ member), 487 esp_ble_mesh_server_recv_light_ctl_defaeuslpt__bsleet__mte:s:hd_esletrav_eurv_recv_light_hsl_hue_set_t::tid (C++ member), 487 (C++ member), 487 esp_ble_mesh_server_recv_light_ctl_defaeuslpt__bsleet__mte:s:hl_isgehrtvneers_srecv_light_hsl_hue_set_t::tra (C++ member), 487 (C++ member), 487 esp_ble_mesh_server_recv_light_ctl_defaeuslpt__bsleet__mte:s:ht_esmeprevreart_urreecv_light_hsl_range_set_t (C++ member), 487 (C++ class), 488 esp_ble_mesh_server_recv_light_ctl_set_etsp_ble_mesh_server_recv_light_hsl_range_set_t::h (C++ class), 486 (C++ member), 488 esp_ble_mesh_server_recv_light_ctl_set_ets:p:_dbellea_ymesh_server_recv_light_hsl_range_set_t::h (C++ member), 486 (C++ member), 488 esp_ble_mesh_server_recv_light_ctl_set_ets:p:_dbellet_am_eusvh_server_recv_light_hsl_range_set_t::s (C++ member), 486 (C++ member), 488 esp_ble_mesh_server_recv_light_ctl_set_ets:p:_lbilgeh_tmneesshs_server_recv_light_hsl_range_set_t::s (C++ member), 486 (C++ member), 488 esp_ble_mesh_server_recv_light_ctl_set_ets:p:_obpl_ee_nmesh_server_recv_light_hsl_saturation_set (C++ member), 486 (C++ class), 487 esp_ble_mesh_server_recv_light_ctl_set_ets:p:_tbelmep_emreasthu_rseerver_recv_light_hsl_saturation_set (C++ member), 486 (C++ member), 488 esp_ble_mesh_server_recv_light_ctl_set_ets:p:_tbilde_mesh_server_recv_light_hsl_saturation_set (C++ member), 486 (C++ member), 488 esp_ble_mesh_server_recv_light_ctl_set_ets:p:_tbrlaen_sm_etsihm_eserver_recv_light_hsl_saturation_set (C++ member), 486 (C++ member), 488 Espressif Systems 2134 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_server_recv_light_hsl_satuersapt_ibolne__smeets_ht_:s:etrivder_recv_light_lightness_linear_s (C++ member), 488 (C++ member), 485 esp_ble_mesh_server_recv_light_hsl_satuersapt_ibolne__smeets_ht_:s:etrrvaenrs__rteicmve_light_lightness_linear_s (C++ member), 488 (C++ member), 485 esp_ble_mesh_server_recv_light_hsl_set_etsp_ble_mesh_server_recv_light_lightness_linear_s (C++ class), 487 (C++ member), 485 esp_ble_mesh_server_recv_light_hsl_set_ets:p:_dbellea_ymesh_server_recv_light_lightness_linear_s (C++ member), 487 (C++ member), 485 esp_ble_mesh_server_recv_light_hsl_set_ets:p:_hbulee_mesh_server_recv_light_lightness_range_se (C++ member), 487 (C++ class), 485 esp_ble_mesh_server_recv_light_hsl_set_ets:p:_lbilgeh_tmneesshs_server_recv_light_lightness_range_se (C++ member), 487 (C++ member), 485 esp_ble_mesh_server_recv_light_hsl_set_ets:p:_obpl_ee_nmesh_server_recv_light_lightness_range_se (C++ member), 487 (C++ member), 485 esp_ble_mesh_server_recv_light_hsl_set_ets:p:_sbalteu_rmaetsiho_nserver_recv_light_lightness_set_t (C++ member), 487 (C++ class), 485 esp_ble_mesh_server_recv_light_hsl_set_ets:p:_tbilde_mesh_server_recv_light_lightness_set_t::d (C++ member), 487 (C++ member), 485 esp_ble_mesh_server_recv_light_hsl_set_ets:p:_tbrlaen_sm_etsihm_eserver_recv_light_lightness_set_t::l (C++ member), 487 (C++ member), 485 esp_ble_mesh_server_recv_light_lc_lighte_sopn_obflfe__smeets_ht_server_recv_light_lightness_set_t::o (C++ class), 489 (C++ member), 485 esp_ble_mesh_server_recv_light_lc_lighte_sopn_obflfe__smeets_ht_:s:edrevleary_recv_light_lightness_set_t::t (C++ member), 490 (C++ member), 485 esp_ble_mesh_server_recv_light_lc_lighte_sopn_obflfe__smeets_ht_:s:elrivgehrt__roencovf_flight_lightness_set_t::t (C++ member), 490 (C++ member), 485 esp_ble_mesh_server_recv_light_lc_lighte_sopn_obflfe__smeets_ht_:s:eorpv_eern_recv_light_xyl_default_set_t (C++ member), 490 (C++ class), 489 esp_ble_mesh_server_recv_light_lc_lighte_sopn_obflfe__smeets_ht_:s:etrivder_recv_light_xyl_default_set_t: (C++ member), 490 (C++ member), 489 esp_ble_mesh_server_recv_light_lc_lighte_sopn_obflfe__smeets_ht_:s:etrrvaenrs__rteicmve_light_xyl_default_set_t: (C++ member), 490 (C++ member), 489 esp_ble_mesh_server_recv_light_lc_mode_essept__btle_mesh_server_recv_light_xyl_default_set_t: (C++ class), 489 (C++ member), 489 esp_ble_mesh_server_recv_light_lc_mode_essept__btl:e:_mmoedseh_server_recv_light_xyl_range_set_t (C++ member), 489 (C++ class), 489 esp_ble_mesh_server_recv_light_lc_om_seets_pt_ble_mesh_server_recv_light_xyl_range_set_t::x (C++ class), 489 (C++ member), 489 esp_ble_mesh_server_recv_light_lc_om_seets_pt_:b:lmeo_dmeesh_server_recv_light_xyl_range_set_t::x (C++ member), 489 (C++ member), 489 esp_ble_mesh_server_recv_light_lc_propeerstpy__bgleet__mtesh_server_recv_light_xyl_range_set_t::y (C++ class), 484 (C++ member), 489 esp_ble_mesh_server_recv_light_lc_propeerstpy__bgleet__mte:s:hp_rsoeprevretry__riedcv_light_xyl_range_set_t::y (C++ member), 485 (C++ member), 489 esp_ble_mesh_server_recv_light_lc_propeerstpy__bsleet__mtesh_server_recv_light_xyl_set_t (C++ class), 490 (C++ class), 488 esp_ble_mesh_server_recv_light_lc_propeerstpy__bsleet__mte:s:hp_rsoeprevretry__riedcv_light_xyl_set_t::delay (C++ member), 490 (C++ member), 489 esp_ble_mesh_server_recv_light_lc_propeerstpy__bsleet__mte:s:hp_rsoeprevretry__rveaclvu_elight_xyl_set_t::lightne (C++ member), 490 (C++ member), 488 esp_ble_mesh_server_recv_light_lightnesess_pd_ebflaeu_lmte_sshe_ts_etrver_recv_light_xyl_set_t::op_en (C++ class), 485 (C++ member), 488 esp_ble_mesh_server_recv_light_lightnesess_pd_ebflaeu_lmte_sshe_ts_etr:v:elri_grhetcnve_slsight_xyl_set_t::tid (C++ member), 485 (C++ member), 489 esp_ble_mesh_server_recv_light_lightnesess_pl_ibnleea_rm_esseht__sterver_recv_light_xyl_set_t::trans_t (C++ class), 485 (C++ member), 489 esp_ble_mesh_server_recv_light_lightnesess_pl_ibnleea_rm_esseht__ste:r:vdeerl_aryecv_light_xyl_set_t::x (C++ member), 485 (C++ member), 488 Espressif Systems 2135 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_server_recv_light_xyl_set_ets:p:_yble_mesh_server_recv_sensor_cadence_set_t::pr (C++ member), 488 (C++ member), 427 esp_ble_mesh_server_recv_scene_delete_tesp_ble_mesh_server_recv_sensor_column_get_t (C++ class), 448 (C++ class), 427 esp_ble_mesh_server_recv_scene_delete_te:s:ps_cbelnee__mneusmhb_esrerver_recv_sensor_column_get_t::pro (C++ member), 448 (C++ member), 427 esp_ble_mesh_server_recv_scene_recall_tesp_ble_mesh_server_recv_sensor_column_get_t::raw (C++ class), 447 (C++ member), 427 esp_ble_mesh_server_recv_scene_recall_te:s:pd_ebllaey_mesh_server_recv_sensor_descriptor_get_t (C++ member), 448 (C++ class), 426 esp_ble_mesh_server_recv_scene_recall_te:s:po_pb_leen_mesh_server_recv_sensor_descriptor_get_t: (C++ member), 448 (C++ member), 426 esp_ble_mesh_server_recv_scene_recall_te:s:ps_cbelnee__mneusmhb_esrerver_recv_sensor_descriptor_get_t: (C++ member), 448 (C++ member), 426 esp_ble_mesh_server_recv_scene_recall_te:s:pt_ibdle_mesh_server_recv_sensor_get_t (C++ member), 448 (C++ class), 427 esp_ble_mesh_server_recv_scene_recall_te:s:pt_rbalnes__mteismhe_server_recv_sensor_get_t::op_en (C++ member), 448 (C++ member), 427 esp_ble_mesh_server_recv_scene_store_t esp_ble_mesh_server_recv_sensor_get_t::property_i (C++ class), 447 (C++ member), 427 esp_ble_mesh_server_recv_scene_store_t:e:sspc_ebnlee__nmuemsbhe_rserver_recv_sensor_series_get_t (C++ member), 447 (C++ class), 427 esp_ble_mesh_server_recv_scheduler_act_egsept__btle_mesh_server_recv_sensor_series_get_t::op_ (C++ class), 446 (C++ member), 427 esp_ble_mesh_server_recv_scheduler_act_egsept__btl:e:_imnedsehx_server_recv_sensor_series_get_t::pro (C++ member), 446 (C++ member), 427 esp_ble_mesh_server_recv_scheduler_act_essept__btle_mesh_server_recv_sensor_series_get_t::raw (C++ class), 448 (C++ member), 427 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_amcetsiho_nserver_recv_sensor_setting_get_t (C++ member), 448 (C++ class), 426 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_dmaeysh_server_recv_sensor_setting_get_t::pr (C++ member), 448 (C++ member), 427 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_dmaeys_ho_fs_ewreveekr_recv_sensor_setting_get_t::se (C++ member), 448 (C++ member), 427 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_hmoeusrh_server_recv_sensor_setting_set_t (C++ member), 448 (C++ class), 427 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_imnedsehx_server_recv_sensor_setting_set_t::pr (C++ member), 448 (C++ member), 428 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_mmiensuht_eserver_recv_sensor_setting_set_t::se (C++ member), 448 (C++ member), 428 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_mmoensthh_server_recv_sensor_setting_set_t::se (C++ member), 448 (C++ member), 428 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_smceesnhe__sneurmvbeerr_recv_sensor_settings_get_t (C++ member), 448 (C++ class), 426 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_smeecsohn_dserver_recv_sensor_settings_get_t::p (C++ member), 448 (C++ member), 426 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_tmreasnhs__steirmveer_recv_sensor_status_t (C++ member), 448 (C++ class), 490 esp_ble_mesh_server_recv_scheduler_act_essept__btl:e:_ymeeasrh_server_recv_sensor_status_t::data (C++ member), 448 (C++ member), 490 esp_ble_mesh_server_recv_sensor_cadencee_sgpe_tb_lte_mesh_server_recv_tai_utc_delta_set_t (C++ class), 426 (C++ class), 447 esp_ble_mesh_server_recv_sensor_cadencee_sgpe_tb_lte:_:mpersohp_esretryv_eird_recv_tai_utc_delta_set_t::pad (C++ member), 426 (C++ member), 447 esp_ble_mesh_server_recv_sensor_cadencee_sspe_tb_lte_mesh_server_recv_tai_utc_delta_set_t::tai (C++ class), 427 (C++ member), 447 esp_ble_mesh_server_recv_sensor_cadencee_sspe_tb_lte:_:mceasdhe_nsceerver_recv_tai_utc_delta_set_t::tai (C++ member), 427 (C++ member), 447 Espressif Systems 2136 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_server_recv_time_role_set_etsp_ble_mesh_server_state_value_t::gen_onpowerup (C++ class), 447 (C++ member), 303 esp_ble_mesh_server_recv_time_role_set_ets:p:_tbilmee__mreoslhe_server_state_value_t::gen_power_actu (C++ member), 447 (C++ member), 304 esp_ble_mesh_server_recv_time_set_t esp_ble_mesh_server_state_value_t::hue (C++ class), 446 (C++ member), 304 esp_ble_mesh_server_recv_time_set_t::suebsspe_cbolned_mesh_server_state_value_t::level (C++ member), 446 (C++ member), 303 esp_ble_mesh_server_recv_time_set_t::taeis_ps_ebcloen_dmsesh_server_state_value_t::light_ctl_ligh (C++ member), 446 (C++ member), 304 esp_ble_mesh_server_recv_time_set_t::taeis_pu_tbcl_ed_emletsah_server_state_value_t::light_ctl_temp (C++ member), 447 (C++ member), 304 esp_ble_mesh_server_recv_time_set_t::tiemsep__abulteh_omreisthy_server_state_value_t::light_hsl (C++ member), 447 (C++ member), 304 esp_ble_mesh_server_recv_time_set_t::tiemsep__zbolnee__moefsfhs_esterver_state_value_t::light_hsl_hue (C++ member), 447 (C++ member), 304 esp_ble_mesh_server_recv_time_set_t::unecsepr_tbalien_tmyesh_server_state_value_t::light_hsl_ligh (C++ member), 446 (C++ member), 304 esp_ble_mesh_server_recv_time_status_t esp_ble_mesh_server_state_value_t::light_hsl_satu (C++ class), 448 (C++ member), 304 esp_ble_mesh_server_recv_time_status_t:e:sspu_bbsleec_omnedsh_server_state_value_t::light_lc_light (C++ member), 449 (C++ member), 304 esp_ble_mesh_server_recv_time_status_t:e:stpa_ib_lsee_cmoensdhs_server_state_value_t::light_lightnes (C++ member), 449 (C++ member), 304 esp_ble_mesh_server_recv_time_status_t:e:stpa_ib_luet_cm_edsehl_tsaerver_state_value_t::light_lightnes (C++ member), 449 (C++ member), 304 esp_ble_mesh_server_recv_time_status_t:e:stpi_mbel_ea_umtehsohr_isteyrver_state_value_t::light_xyl_ligh (C++ member), 449 (C++ member), 304 esp_ble_mesh_server_recv_time_status_t:e:stpi_mbel_ez_omnees_ho_fsfesrevter_state_value_t::lightness (C++ member), 449 (C++ member), 304 esp_ble_mesh_server_recv_time_status_t:e:supn_cbelret_amiensthy_server_state_value_t::onoff (C++ member), 449 (C++ member), 303 esp_ble_mesh_server_recv_time_zone_set_etsp_ble_mesh_server_state_value_t::onpowerup (C++ class), 447 (C++ member), 303 esp_ble_mesh_server_recv_time_zone_set_ets:p:_tbalie__zmoenseh__cshearnvgeer_state_value_t::power (C++ member), 447 (C++ member), 303 esp_ble_mesh_server_recv_time_zone_set_ets:p:_tbilmee__mzeosnhe__soefrfvseert__snteawte_value_t::saturation (C++ member), 447 (C++ member), 304 ESP_BLE_MESH_SERVER_RSP_BY_APP (C esp_ble_mesh_server_state_value_t::temperature macro), 329 (C++ member), 304 esp_ble_mesh_server_rsp_ctrl_t (C++ ESP_BLE_MESH_SERVER_TRANS_TIMER_START class), 314 (C++ enumerator), 336 esp_ble_mesh_server_rsp_ctrl_t::get_auteos_pr_sbple_mesh_set_fast_prov_action (C++ member), 314 (C++ function), 352 esp_ble_mesh_server_rsp_ctrl_t::set_autEoS_Pr_sBpLE_MESH_SET_FAST_PROV_ACTION_COMP_EVT (C++ member), 314 (C++ enumerator), 335 esp_ble_mesh_server_rsp_ctrl_t::status_easupt_ob_lres_pmesh_set_fast_prov_info (C++ (C++ member), 314 function), 352 esp_ble_mesh_server_state_type_t (C++ ESP_BLE_MESH_SET_FAST_PROV_INFO_COMP_EVT enum), 336 (C++ enumerator), 335 esp_ble_mesh_server_state_value_t esp_ble_mesh_set_unprovisioned_device_name (C++ union), 303 (C++ function), 348 esp_ble_mesh_server_state_value_t::deltEaS_Pu_vBLE_MESH_SETTINGS_UID_SIZE (C (C++ member), 304 macro), 315 esp_ble_mesh_server_state_value_t::gen_ElSePv_eBlLE_MESH_SIG_MODEL (C macro), 317 (C++ member), 303 esp_ble_mesh_state_change_cfg_appkey_add_t esp_ble_mesh_server_state_value_t::gen_onoff (C++ class), 375 (C++ member), 303 esp_ble_mesh_state_change_cfg_appkey_add_t::app_i Espressif Systems 2137 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 375 (C++ member), 376 esp_ble_mesh_state_change_cfg_appkey_adeds_pt_:b:laep_pm_eksehy_state_change_cfg_model_app_unbind_t: (C++ member), 375 (C++ member), 376 esp_ble_mesh_state_change_cfg_appkey_adeds_pt_:b:lnee_tm_eisdhx_state_change_cfg_model_app_unbind_t: (C++ member), 375 (C++ member), 376 esp_ble_mesh_state_change_cfg_appkey_deelsept_eb_lte_mesh_state_change_cfg_model_app_unbind_t: (C++ class), 375 (C++ member), 376 esp_ble_mesh_state_change_cfg_appkey_deelsept_eb_lte:_:maepsph__isdtxate_change_cfg_model_sub_add_t (C++ member), 375 (C++ class), 374 esp_ble_mesh_state_change_cfg_appkey_deelsept_eb_lte:_:mneesth__isdtxate_change_cfg_model_sub_add_t::co (C++ member), 375 (C++ member), 374 esp_ble_mesh_state_change_cfg_appkey_upedsapt_eb_lte_mesh_state_change_cfg_model_sub_add_t::el (C++ class), 375 (C++ member), 374 esp_ble_mesh_state_change_cfg_appkey_upedsapt_eb_lte:_:maepsph__isdtxate_change_cfg_model_sub_add_t::mo (C++ member), 375 (C++ member), 374 esp_ble_mesh_state_change_cfg_appkey_upedsapt_eb_lte:_:maepsph__ksetyate_change_cfg_model_sub_add_t::su (C++ member), 375 (C++ member), 374 esp_ble_mesh_state_change_cfg_appkey_upedsapt_eb_lte:_:mneesth__isdtxate_change_cfg_model_sub_delete_t (C++ member), 375 (C++ class), 374 esp_ble_mesh_state_change_cfg_kr_phase_essept__btle_mesh_state_change_cfg_model_sub_delete_t: (C++ class), 376 (C++ member), 374 esp_ble_mesh_state_change_cfg_kr_phase_essept__btl:e:_kmre_sphh_assteate_change_cfg_model_sub_delete_t: (C++ member), 376 (C++ member), 374 esp_ble_mesh_state_change_cfg_kr_phase_essept__btl:e:_nmeets_hi_dsxtate_change_cfg_model_sub_delete_t: (C++ member), 376 (C++ member), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tble_mesh_state_change_cfg_model_sub_delete_t: (C++ class), 373 (C++ member), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:ea_pmpe_sihd_xstate_change_cfg_netkey_add_t (C++ member), 373 (C++ class), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:ec_ommepsahn_ys_tiadte_change_cfg_netkey_add_t::net_i (C++ member), 373 (C++ member), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:ec_rmeeds_hf_lsatgate_change_cfg_netkey_add_t::net_k (C++ member), 373 (C++ member), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:ee_lmeemsehn_ts_taadtder_change_cfg_netkey_delete_t (C++ member), 373 (C++ class), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:em_omdeeslh__isdtate_change_cfg_netkey_delete_t::ne (C++ member), 374 (C++ member), 375 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:ep_umbe_sahd_dsrtate_change_cfg_netkey_update_t (C++ member), 373 (C++ class), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:ep_umbe_sphe_rsitoadte_change_cfg_netkey_update_t::ne (C++ member), 373 (C++ member), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:ep_umbe_srhe_tsrtaantsem_icthange_cfg_netkey_update_t::ne (C++ member), 373 (C++ member), 374 esp_ble_mesh_state_change_cfg_mod_pub_seestp__tb:l:ep_umbe_stht_lstate_change_gen_admin_property_set_ (C++ member), 373 (C++ class), 407 esp_ble_mesh_state_change_cfg_model_appe_sbpi_nbdl_et_mesh_state_change_gen_admin_property_set_ (C++ class), 375 (C++ member), 407 esp_ble_mesh_state_change_cfg_model_appe_sbpi_nbdl_et_:m:easphp__sitdaxte_change_gen_admin_property_set_ (C++ member), 375 (C++ member), 407 esp_ble_mesh_state_change_cfg_model_appe_sbpi_nbdl_et_:m:ecsohm_psatnayt_ei_dchange_gen_admin_property_set_ (C++ member), 375 (C++ member), 407 esp_ble_mesh_state_change_cfg_model_appe_sbpi_nbdl_et_:m:eeslhe_msetnatt_ea_dcdhrange_gen_def_trans_time_set_ (C++ member), 375 (C++ class), 405 esp_ble_mesh_state_change_cfg_model_appe_sbpi_nbdl_et_:m:emsohd_eslt_aitde_change_gen_def_trans_time_set_ (C++ member), 375 (C++ member), 405 esp_ble_mesh_state_change_cfg_model_appe_supn_bbilned__mtesh_state_change_gen_delta_set_t (C++ class), 376 (C++ class), 405 esp_ble_mesh_state_change_cfg_model_appe_supn_bbilned__mte:s:ha_pspt_aitdex_change_gen_delta_set_t::level Espressif Systems 2138 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 405 (C++ class), 406 esp_ble_mesh_state_change_gen_level_sete_stp_ble_mesh_state_change_gen_user_property_set_t (C++ class), 405 (C++ member), 407 esp_ble_mesh_state_change_gen_level_sete_stp:_:blleev_emlesh_state_change_gen_user_property_set_t (C++ member), 405 (C++ member), 407 esp_ble_mesh_state_change_gen_loc_globaels_ps_ebtl_et_mesh_state_change_light_ctl_default_set_t (C++ class), 406 (C++ class), 481 esp_ble_mesh_state_change_gen_loc_globaels_ps_ebtl_et_:m:easlht_isttuadtee_change_light_ctl_default_set_t (C++ member), 406 (C++ member), 482 esp_ble_mesh_state_change_gen_loc_globaels_ps_ebtl_et_:m:elsaht_isttuadtee_change_light_ctl_default_set_t (C++ member), 406 (C++ member), 482 esp_ble_mesh_state_change_gen_loc_globaels_ps_ebtl_et_:m:elsohn_gsittautdee_change_light_ctl_default_set_t (C++ member), 406 (C++ member), 482 esp_ble_mesh_state_change_gen_loc_locale_sspe_tb_lte_mesh_state_change_light_ctl_set_t (C++ class), 406 (C++ class), 481 esp_ble_mesh_state_change_gen_loc_locale_sspe_tb_lte:_:maelsthi_tsutdaete_change_light_ctl_set_t::delta_ (C++ member), 406 (C++ member), 481 esp_ble_mesh_state_change_gen_loc_locale_sspe_tb_lte:_:meeassht_state_change_light_ctl_set_t::lightn (C++ member), 406 (C++ member), 481 esp_ble_mesh_state_change_gen_loc_locale_sspe_tb_lte:_:mfelsoho_rs_tnautmeb_ecrhange_light_ctl_set_t::temper (C++ member), 406 (C++ member), 481 esp_ble_mesh_state_change_gen_loc_locale_sspe_tb_lte:_:mneosrht_hstate_change_light_ctl_temperature_r (C++ member), 406 (C++ class), 481 esp_ble_mesh_state_change_gen_loc_locale_sspe_tb_lte:_:muensche_rsttaaitnet_ychange_light_ctl_temperature_r (C++ member), 406 (C++ member), 481 esp_ble_mesh_state_change_gen_manu_propeesrpt_yb_lsee_tm_etsh_state_change_light_ctl_temperature_r (C++ class), 407 (C++ member), 481 esp_ble_mesh_state_change_gen_manu_propeesrpt_yb_lsee_tm_ets:h:_asctcaetses_change_light_ctl_temperature_s (C++ member), 407 (C++ class), 481 esp_ble_mesh_state_change_gen_manu_propeesrpt_yb_lsee_tm_ets:h:_isdtate_change_light_ctl_temperature_s (C++ member), 407 (C++ member), 481 esp_ble_mesh_state_change_gen_move_set_etsp_ble_mesh_state_change_light_ctl_temperature_s (C++ class), 405 (C++ member), 481 esp_ble_mesh_state_change_gen_move_set_ets:p:_lbelvee_lmesh_state_change_light_hsl_default_set_t (C++ member), 405 (C++ class), 482 esp_ble_mesh_state_change_gen_onoff_sete_stp_ble_mesh_state_change_light_hsl_default_set_t (C++ class), 405 (C++ member), 482 esp_ble_mesh_state_change_gen_onoff_sete_stp:_:bolneo_fmfesh_state_change_light_hsl_default_set_t (C++ member), 405 (C++ member), 482 esp_ble_mesh_state_change_gen_onpowerupe_sspe_tb_lte_mesh_state_change_light_hsl_default_set_t (C++ class), 405 (C++ member), 482 esp_ble_mesh_state_change_gen_onpowerupe_sspe_tb_lte:_:moenspho_wsetrautpe_change_light_hsl_hue_set_t (C++ member), 405 (C++ class), 482 esp_ble_mesh_state_change_gen_power_defeasupl_tb_lsee_tm_etsh_state_change_light_hsl_hue_set_t::hu (C++ class), 406 (C++ member), 482 esp_ble_mesh_state_change_gen_power_defeasupl_tb_lsee_tm_ets:h:_psotwaetre_change_light_hsl_range_set_t (C++ member), 406 (C++ class), 482 esp_ble_mesh_state_change_gen_power_leveeslp__sbelte__tmesh_state_change_light_hsl_range_set_t:: (C++ class), 405 (C++ member), 483 esp_ble_mesh_state_change_gen_power_leveeslp__sbelte__tm:e:spho_wsetrate_change_light_hsl_range_set_t:: (C++ member), 406 (C++ member), 483 esp_ble_mesh_state_change_gen_power_ranegsep__sbelte__tmesh_state_change_light_hsl_range_set_t:: (C++ class), 406 (C++ member), 483 esp_ble_mesh_state_change_gen_power_ranegsep__sbelte__tm:e:srha_nsgtea_tmea_xchange_light_hsl_range_set_t:: (C++ member), 406 (C++ member), 483 esp_ble_mesh_state_change_gen_power_ranegsep__sbelte__tm:e:srha_nsgtea_tmei_nchange_light_hsl_saturation_se (C++ member), 406 (C++ class), 482 esp_ble_mesh_state_change_gen_user_propeesrpt_yb_lsee_tm_etsh_state_change_light_hsl_saturation_se Espressif Systems 2139 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 482 (C++ member), 483 esp_ble_mesh_state_change_light_hsl_sete_stp_ble_mesh_state_change_light_xyl_range_set_t:: (C++ class), 482 (C++ member), 483 esp_ble_mesh_state_change_light_hsl_sete_stp:_:bhluee_mesh_state_change_light_xyl_range_set_t:: (C++ member), 482 (C++ member), 483 esp_ble_mesh_state_change_light_hsl_sete_stp:_:bllieg_hmtensehs_sstate_change_light_xyl_set_t (C++ member), 482 (C++ class), 483 esp_ble_mesh_state_change_light_hsl_sete_stp:_:bslaet_umreasthi_osntate_change_light_xyl_set_t::lightn (C++ member), 482 (C++ member), 483 esp_ble_mesh_state_change_light_lc_lighets_po_nbolfef__mseesth__tstate_change_light_xyl_set_t::x (C++ class), 484 (C++ member), 483 esp_ble_mesh_state_change_light_lc_lighets_po_nbolfef__mseesth__ts:t:aotneo_fcfhange_light_xyl_set_t::y (C++ member), 484 (C++ member), 483 esp_ble_mesh_state_change_light_lc_modee_sspe_tb_lte_mesh_state_change_scene_delete_t (C++ class), 483 (C++ class), 445 esp_ble_mesh_state_change_light_lc_modee_sspe_tb_lte:_:mmeosdhe_state_change_scene_delete_t::scene_n (C++ member), 484 (C++ member), 446 esp_ble_mesh_state_change_light_lc_om_seestp__tble_mesh_state_change_scene_recall_t (C++ class), 484 (C++ class), 445 esp_ble_mesh_state_change_light_lc_om_seestp__tb:l:em_omdeesh_state_change_scene_recall_t::scene_n (C++ member), 484 (C++ member), 445 esp_ble_mesh_state_change_light_lc_propeesrpt_yb_lsee_tm_etsh_state_change_scene_store_t (C++ class), 484 (C++ class), 445 esp_ble_mesh_state_change_light_lc_propeesrpt_yb_lsee_tm_ets:h:_psrtoapteer_tcyh_aindge_scene_store_t::scene_nu (C++ member), 484 (C++ member), 445 esp_ble_mesh_state_change_light_lc_propeesrpt_yb_lsee_tm_ets:h:_psrtoapteer_tcyh_avnagleu_escheduler_act_set_t (C++ member), 484 (C++ class), 446 esp_ble_mesh_state_change_light_lightneesssp__dbelfea_umlets_hs_estt_atte_change_scheduler_act_set_t::ac (C++ class), 481 (C++ member), 446 esp_ble_mesh_state_change_light_lightneesssp__dbelfea_umlets_hs_estt_att:e:_lcihgahntgnee_ssscheduler_act_set_t::da (C++ member), 481 (C++ member), 446 esp_ble_mesh_state_change_light_lightneesssp__lbilnee_amre_sshe_ts_ttate_change_scheduler_act_set_t::da (C++ class), 480 (C++ member), 446 esp_ble_mesh_state_change_light_lightneesssp__lbilnee_amre_sshe_ts_tta:t:el_icghhatnngees_sscheduler_act_set_t::ho (C++ member), 481 (C++ member), 446 esp_ble_mesh_state_change_light_lightneesssp__rbalneg_em_esseht__sttate_change_scheduler_act_set_t::in (C++ class), 481 (C++ member), 446 esp_ble_mesh_state_change_light_lightneesssp__rbalneg_em_esseht__stt:a:trea_ncghea_nmgaex_scheduler_act_set_t::mi (C++ member), 481 (C++ member), 446 esp_ble_mesh_state_change_light_lightneesssp__rbalneg_em_esseht__stt:a:trea_ncghea_nmgien_scheduler_act_set_t::mo (C++ member), 481 (C++ member), 446 esp_ble_mesh_state_change_light_lightneesssp__sbelte__tmesh_state_change_scheduler_act_set_t::sc (C++ class), 480 (C++ member), 446 esp_ble_mesh_state_change_light_lightneesssp__sbelte__tm:e:slhi_gshttantees_schange_scheduler_act_set_t::se (C++ member), 480 (C++ member), 446 esp_ble_mesh_state_change_light_xyl_defeasupl_tb_lsee_tm_etsh_state_change_scheduler_act_set_t::tr (C++ class), 483 (C++ member), 446 esp_ble_mesh_state_change_light_xyl_defeasupl_tb_lsee_tm_ets:h:_lsitgahtten_ecshsange_scheduler_act_set_t::ye (C++ member), 483 (C++ member), 446 esp_ble_mesh_state_change_light_xyl_defeasupl_tb_lsee_tm_ets:h:_xstate_change_sensor_cadence_set_t (C++ member), 483 (C++ class), 425 esp_ble_mesh_state_change_light_xyl_defeasupl_tb_lsee_tm_ets:h:_ystate_change_sensor_cadence_set_t::f (C++ member), 483 (C++ member), 426 esp_ble_mesh_state_change_light_xyl_ranegsep__sbelte__tmesh_state_change_sensor_cadence_set_t::f (C++ class), 483 (C++ member), 426 esp_ble_mesh_state_change_light_xyl_ranegsep__sbelte__tm:e:sxh__rsatnagtee__mcahxange_sensor_cadence_set_t::m (C++ member), 483 (C++ member), 426 esp_ble_mesh_state_change_light_xyl_ranegsep__sbelte__tm:e:sxh__rsatnagtee__mcihnange_sensor_cadence_set_t::p Espressif Systems 2140 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 425 (C++ member), 444 esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:epsrho_psetrattye__icdhange_time_status_t::tai_utc_ (C++ member), 425 (C++ member), 445 esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:etsrhi_gsgteart_ed_eclhtaan_gdeo_wtnime_status_t::time_aut (C++ member), 425 (C++ member), 444 esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:etsrhi_gsgteart_ed_eclhtaan_guep_time_status_t::time_zon (C++ member), 425 (C++ member), 445 esp_ble_mesh_state_change_sensor_cadencees_ps_ebtl_et_:m:etsrhi_gsgteart_et_ycpheange_time_status_t::uncertai (C++ member), 425 (C++ member), 444 esp_ble_mesh_state_change_sensor_settinegs_ps_ebtl_et_mesh_state_change_time_zone_set_t (C++ class), 426 (C++ class), 445 esp_ble_mesh_state_change_sensor_settinegs_ps_ebtl_et_:m:epsrho_psetrattye__icdhange_time_zone_set_t::tai_zo (C++ member), 426 (C++ member), 445 esp_ble_mesh_state_change_sensor_settinegs_ps_ebtl_et_:m:esseht_tsitnagt_ep_rcohpaenrgtey__tiidme_zone_set_t::time_z (C++ member), 426 (C++ member), 445 esp_ble_mesh_state_change_sensor_settinegs_ps_ebtl_et_:m:esseht_tsitnagt_ev_atlruaensition_t (C++ (C++ member), 426 class), 313 esp_ble_mesh_state_change_sensor_statuse_stp_ble_mesh_state_transition_t::BLE_MESH_ATOMIC_ (C++ class), 484 (C++ function), 313 esp_ble_mesh_state_change_sensor_statuse_stp:_:balmeb_imeensth__lsutxalteev_etlransition_t::counter (C++ member), 484 (C++ member), 314 esp_ble_mesh_state_change_sensor_statuse_stp:_:bolcec_umpeasnhc_ystate_transition_t::delay (C++ member), 484 (C++ member), 314 esp_ble_mesh_state_change_sensor_statuse_stp:_:bplreo_pmeersthy__sitdate_transition_t::just_started (C++ member), 484 (C++ member), 313 esp_ble_mesh_state_change_sensor_statuse_stp:_:bsleet__moecschu_psatnactye__ttor_a1n_sdietliaoyn_t::quo_tt (C++ member), 484 (C++ member), 314 esp_ble_mesh_state_change_sensor_statuse_stp:_:bsltea_tmeesh_state_transition_t::remain_time (C++ member), 484 (C++ member), 313 esp_ble_mesh_state_change_tai_utc_deltae_sspe_tb_lte_mesh_state_transition_t::start_timestamp (C++ class), 445 (C++ member), 314 esp_ble_mesh_state_change_tai_utc_deltae_sspe_tb_lte:_:mteasih__dsetlattae__cthraanngseition_t::timer (C++ member), 445 (C++ member), 314 esp_ble_mesh_state_change_tai_utc_deltae_sspe_tb_lte:_:mteasih__usttca_tdee_lttraa_nnseiwtion_t::total_duration (C++ member), 445 (C++ member), 314 esp_ble_mesh_state_change_time_role_sete_stp_ble_mesh_state_transition_t::trans_time (C++ class), 445 (C++ member), 313 esp_ble_mesh_state_change_time_role_setE_StP:_:BtLiEm_eM_ErSoHl_eSTATIC_OOB (C++ enumerator), (C++ member), 445 331 esp_ble_mesh_state_change_time_set_t ESP_BLE_MESH_SUPPLY_VOLTAGE_TOO_HIGH_ERROR (C++ class), 444 (C macro), 384 esp_ble_mesh_state_change_time_set_t::sEuSbPs_eBcLoEn_dMESH_SUPPLY_VOLTAGE_TOO_HIGH_WARNING (C++ member), 444 (C macro), 384 esp_ble_mesh_state_change_time_set_t::tEaSiP__sBeLcEo_nMdEsSH_SUPPLY_VOLTAGE_TOO_LOW_ERROR (C++ member), 444 (C macro), 384 esp_ble_mesh_state_change_time_set_t::tEaSiP__uBtLcE__dMeElStHa__ScUuPrPrLY_VOLTAGE_TOO_LOW_WARNING (C++ member), 444 (C macro), 384 esp_ble_mesh_state_change_time_set_t::tEiSmPe__BaLuEt_hMoErSiHt_yTAI_OF_DELTA_CHANGE_LEN (C++ member), 444 (C macro), 451 esp_ble_mesh_state_change_time_set_t::tEiSmPe__BzLoEn_eM_EoSfHf_sTeAtI__cOuFr_rZONE_CHANGE_LEN (C (C++ member), 444 macro), 451 esp_ble_mesh_state_change_time_set_t::uEnScPe_rBtLaEi_nMtEySH_TAI_SECONDS_LEN (C macro), (C++ member), 444 451 esp_ble_mesh_state_change_time_status_tESP_BLE_MESH_TAI_UTC_DELTA_MAX_VALUE (C++ class), 444 (C macro), 451 esp_ble_mesh_state_change_time_status_te:s:ps_ubblsee_cmoensdh_tai_utc_delta_set_t (C++ (C++ member), 444 class), 435 esp_ble_mesh_state_change_time_status_te:s:pt_abil_es_emceosnhd_stai_utc_delta_set_t::padding Espressif Systems 2141 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 436 (C++ function), 432 esp_ble_mesh_tai_utc_delta_set_t::tai_dEeSlPt_aB_LcEh_aMnEgSeH_TIME_SCENE_CLIENT_SET_STATE_EVT (C++ member), 436 (C++ enumerator), 453 esp_ble_mesh_tai_utc_delta_set_t::tai_uetscp__dbellet_am_ensehw_time_scene_client_set_state_t (C++ member), 436 (C++ union), 432 esp_ble_mesh_tai_utc_delta_status_cb_t esp_ble_mesh_time_scene_client_set_state_t::scene (C++ class), 438 (C++ member), 433 esp_ble_mesh_tai_utc_delta_status_cb_t:e:sppa_dbdlien_gm_e1sh_time_scene_client_set_state_t::scene (C++ member), 438 (C++ member), 433 esp_ble_mesh_tai_utc_delta_status_cb_t:e:sppa_dbdlien_gm_e2sh_time_scene_client_set_state_t::scene (C++ member), 438 (C++ member), 433 esp_ble_mesh_tai_utc_delta_status_cb_t:e:stpa_ib_ldee_lmteas_hc_htainmgee_scene_client_set_state_t::sched (C++ member), 438 (C++ member), 433 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), 438 (C++ member), 433 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), 438 (C++ member), 433 ESP_BLE_MESH_TAMPER_ERROR (C macro), 385 esp_ble_mesh_time_scene_client_set_state_t::time_ ESP_BLE_MESH_TAMPER_WARNING (C macro), (C++ member), 433 384 esp_ble_mesh_time_scene_client_set_state_t::time_ ESP_BLE_MESH_TIME_AUTHORITY (C macro), (C++ member), 433 452 esp_ble_mesh_time_scene_client_status_cb_t ESP_BLE_MESH_TIME_CLINET (C macro), 452 (C++ union), 433 ESP_BLE_MESH_TIME_NONE (C macro), 452 esp_ble_mesh_time_scene_client_status_cb_t::scene ESP_BLE_MESH_TIME_RELAY (C macro), 452 (C++ member), 433 esp_ble_mesh_time_role_set_t (C++ class), esp_ble_mesh_time_scene_client_status_cb_t::scene 436 (C++ member), 433 esp_ble_mesh_time_role_set_t::time_roleesp_ble_mesh_time_scene_client_status_cb_t::sched (C++ member), 436 (C++ member), 433 esp_ble_mesh_time_role_status_cb_t esp_ble_mesh_time_scene_client_status_cb_t::sched (C++ class), 438 (C++ member), 433 esp_ble_mesh_time_role_status_cb_t::timees_pr_obllee_mesh_time_scene_client_status_cb_t::tai_u (C++ member), 438 (C++ member), 433 esp_ble_mesh_time_scene_client_cb_evente_stp_ble_mesh_time_scene_client_status_cb_t::time_ (C++ enum), 453 (C++ member), 433 esp_ble_mesh_time_scene_client_cb_parame_stp_ble_mesh_time_scene_client_status_cb_t::time_ (C++ class), 439 (C++ member), 433 esp_ble_mesh_time_scene_client_cb_parame_stp:_:belrer_omre_scho_dteime_scene_client_status_cb_t::time_ (C++ member), 440 (C++ member), 433 esp_ble_mesh_time_scene_client_cb_paramE_StP:_:BpLaEr_aMmEsSH_TIME_SCENE_CLIENT_TIMEOUT_EVT (C++ member), 440 (C++ enumerator), 453 esp_ble_mesh_time_scene_client_cb_parame_stp:_:bsltea_tmuess_hc_btime_scene_message_opcode_t (C++ member), 440 (C++ type), 330 esp_ble_mesh_time_scene_client_cb_t esp_ble_mesh_time_scene_server_cb_event_t (C++ type), 452 (C++ enum), 453 ESP_BLE_MESH_TIME_SCENE_CLIENT_EVT_MAX esp_ble_mesh_time_scene_server_cb_param_t (C++ enumerator), 453 (C++ class), 449 esp_ble_mesh_time_scene_client_get_stateesp_ble_mesh_time_scene_server_cb_param_t::ctx (C++ function), 432 (C++ member), 449 ESP_BLE_MESH_TIME_SCENE_CLIENT_GET_STATeEs_pE_VbTle_mesh_time_scene_server_cb_param_t::model (C++ enumerator), 453 (C++ member), 449 esp_ble_mesh_time_scene_client_get_statees_pt_ble_mesh_time_scene_server_cb_param_t::value (C++ union), 432 (C++ member), 449 esp_ble_mesh_time_scene_client_get_statees_pt_:b:lsec_hmeedsuhl_etri_maec_ts_cgeente_server_cb_t (C++ member), 432 (C++ type), 452 ESP_BLE_MESH_TIME_SCENE_CLIENT_PUBLISH_eEsVpT_ble_mesh_time_scene_server_cb_value_t (C++ enumerator), 453 (C++ union), 435 esp_ble_mesh_time_scene_client_set_stateesp_ble_mesh_time_scene_server_cb_value_t::get Espressif Systems 2142 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 435 (C++ member), 433 esp_ble_mesh_time_scene_server_cb_valuee_stp:_:bsleet_mesh_time_scene_server_state_change_t::ti (C++ member), 435 (C++ member), 433 esp_ble_mesh_time_scene_server_cb_valuee_stp:_:bsltea_tmee_schh_atnigmee_scene_server_state_change_t::ti (C++ member), 435 (C++ member), 434 esp_ble_mesh_time_scene_server_cb_valuee_stp:_:bsltea_tmuessh_time_set_t (C++ class), 435 (C++ member), 435 esp_ble_mesh_time_set_t::sub_second ESP_BLE_MESH_TIME_SCENE_SERVER_EVT_MAX (C++ member), 435 (C++ enumerator), 453 esp_ble_mesh_time_set_t::tai_seconds ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_GET_MSG_EV(CT++ member), 435 (C++ enumerator), 453 esp_ble_mesh_time_set_t::tai_utc_delta esp_ble_mesh_time_scene_server_recv_get_msg_t (C++ member), 435 (C++ union), 434 esp_ble_mesh_time_set_t::time_authority esp_ble_mesh_time_scene_server_recv_get_msg_t:(C:+s+chmeedmubleer)r, _43a5ct (C++ member), 434 esp_ble_mesh_time_set_t::time_zone_offset ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_SET_MSG_EV(CT++ member), 435 (C++ enumerator), 453 esp_ble_mesh_time_set_t::uncertainty esp_ble_mesh_time_scene_server_recv_set_msg_t (C++ member), 435 (C++ union), 434 esp_ble_mesh_time_setup_srv_t (C++ esp_ble_mesh_time_scene_server_recv_set_msg_t:cl:asssc),e4n4e1_delete (C++ member), 434 esp_ble_mesh_time_setup_srv_t::model esp_ble_mesh_time_scene_server_recv_set_msg_t:(C:+s+cemneem_breer)c, a44l1l (C++ member), 434 esp_ble_mesh_time_setup_srv_t::rsp_ctrl esp_ble_mesh_time_scene_server_recv_set_msg_t:(C:+s+cemneem_bsetr)o, r44e1 (C++ member), 434 esp_ble_mesh_time_setup_srv_t::state esp_ble_mesh_time_scene_server_recv_set_msg_t:(C:+s+chmeedmubleer)r, _44a1ct (C++ member), 434 esp_ble_mesh_time_srv_t (C++ class), 440 esp_ble_mesh_time_scene_server_recv_sete_smps_gb_lte:_:mteasih__utticm_ed_eslrtva_t::model (C++ (C++ member), 434 member), 440 esp_ble_mesh_time_scene_server_recv_sete_smps_gb_lte:_:mteismhe_time_srv_t::rsp_ctrl (C++ member), 434 (C++ member), 440 esp_ble_mesh_time_scene_server_recv_sete_smps_gb_lte:_:mteismhe__triomlee_srv_t::state (C++ (C++ member), 434 member), 441 esp_ble_mesh_time_scene_server_recv_sete_smps_gb_lte:_:mteismhe__tziomnee_state_t (C++ class), 440 (C++ member), 434 esp_ble_mesh_time_state_t::subsecond ESP_BLE_MESH_TIME_SCENE_SERVER_RECV_STATUS_MSG(C_+E+VTmember), 440 (C++ enumerator), 453 esp_ble_mesh_time_state_t::tai_delta_change esp_ble_mesh_time_scene_server_recv_status_msg(C_+t+ member), 440 (C++ union), 434 esp_ble_mesh_time_state_t::tai_seconds esp_ble_mesh_time_scene_server_recv_status_msg(C_+t+::mteimmbee_r)s, t44a0tus (C++ member), 435 esp_ble_mesh_time_state_t::tai_utc_delta_curr ESP_BLE_MESH_TIME_SCENE_SERVER_STATE_CHANGE_EV(CT++ member), 440 (C++ enumerator), 453 esp_ble_mesh_time_state_t::tai_utc_delta_new esp_ble_mesh_time_scene_server_state_change_t (C++ member), 440 (C++ union), 433 esp_ble_mesh_time_state_t::tai_zone_change esp_ble_mesh_time_scene_server_state_change_t:(C:+s+cemneem_bdeer)l, e44t0e (C++ member), 434 esp_ble_mesh_time_state_t::time (C++ esp_ble_mesh_time_scene_server_state_change_t:m:esmcbeern)e, 4_4r0ecall (C++ member), 434 esp_ble_mesh_time_state_t::time_authority esp_ble_mesh_time_scene_server_state_change_t:(C:+s+cemneem_bsetr)o, r44e0 (C++ member), 434 esp_ble_mesh_time_state_t::time_role esp_ble_mesh_time_scene_server_state_change_t:(C:+s+chmeedmubleer)r, _44a0ct_set (C++ member), 434 esp_ble_mesh_time_state_t::time_zone_offset_curr esp_ble_mesh_time_scene_server_state_change_t:(C:+t+aim_eumtbce_r)d, e44l0ta_set (C++ member), 434 esp_ble_mesh_time_state_t::time_zone_offset_new esp_ble_mesh_time_scene_server_state_change_t:(C:+t+immee_mrboelr)e, _44s0et (C++ member), 434 esp_ble_mesh_time_state_t::uncertainty esp_ble_mesh_time_scene_server_state_change_t:(C:+t+immee_msbeetr), 440 Espressif Systems 2143 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_ble_mesh_time_status_cb_t (C++ esp_ble_mesh_unprov_dev_add_t::addr_type class), 437 (C++ member), 310 esp_ble_mesh_time_status_cb_t::sub_secoensdp_ble_mesh_unprov_dev_add_t::bearer (C++ member), 437 (C++ member), 310 esp_ble_mesh_time_status_cb_t::tai_secoensdps_ble_mesh_unprov_dev_add_t::oob_info (C++ member), 437 (C++ member), 310 esp_ble_mesh_time_status_cb_t::tai_utc_edsepl_tbale_mesh_unprov_dev_add_t::uuid (C++ member), 437 (C++ member), 310 esp_ble_mesh_time_status_cb_t::time_autEhSoPr_iBtLyE_MESH_VENDOR_MODEL (C macro), 317 (C++ member), 437 ESP_BLE_MESH_VIBRATE (C++ enumerator), 331 esp_ble_mesh_time_status_cb_t::time_zonEeS_Po_fBfLsEe_tMESH_VIBRATION_ERROR (C macro), (C++ member), 437 384 esp_ble_mesh_time_status_cb_t::uncertaiEnStPy_BLE_MESH_VIBRATION_WARNING (C (C++ member), 437 macro), 384 esp_ble_mesh_time_zone_set_t (C++ class), ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_DISABLE 435 (C macro), 217 esp_ble_mesh_time_zone_set_t::tai_zone_EcShPa_nBgLeE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE (C++ member), 435 (C macro), 217 esp_ble_mesh_time_zone_set_t::time_zoneE_SoPf_fBsLeEt__OnOeBw_DISABLE (C macro), 217 (C++ member), 435 ESP_BLE_OOB_ENABLE (C macro), 217 esp_ble_mesh_time_zone_status_cb_t esp_ble_oob_req_reply (C++ function), 189 (C++ class), 438 esp_ble_passkey_reply (C++ function), 188 esp_ble_mesh_time_zone_status_cb_t::taie_szpo_nbel_ec_hpacnsgrek_keys_t (C++ class), 210 (C++ member), 438 esp_ble_pcsrk_keys_t::counter (C++ esp_ble_mesh_time_zone_status_cb_t::time_zone_moefmfbsere)t, 2_1c0urr (C++ member), 438 esp_ble_pcsrk_keys_t::csrk (C++ member), esp_ble_mesh_time_zone_status_cb_t::time_zone_2o10ffset_new (C++ member), 438 esp_ble_pcsrk_keys_t::sec_level (C++ ESP_BLE_MESH_TRANSMIT (C macro), 316 member), 210 ESP_BLE_MESH_TTL_DEFAULT (C macro), 315 esp_ble_penc_keys_t (C++ class), 209 ESP_BLE_MESH_TTL_MAX (C macro), 315 esp_ble_penc_keys_t::ediv (C++ member), ESP_BLE_MESH_TWIST (C++ enumerator), 331 209 ESP_BLE_MESH_TYPE_COMPLETE_CB (C++ enu- esp_ble_penc_keys_t::key_size (C++ merator), 331 member), 209 ESP_BLE_MESH_TYPE_INTPUT_CB (C++ enumer- esp_ble_penc_keys_t::ltk (C++ member), ator), 330 209 ESP_BLE_MESH_TYPE_LINK_CLOSE_CB (C++ esp_ble_penc_keys_t::rand (C++ member), enumerator), 330 209 ESP_BLE_MESH_TYPE_LINK_OPEN_CB (C++ esp_ble_penc_keys_t::sec_level (C++ enumerator), 330 member), 209 ESP_BLE_MESH_TYPE_OUTPUT_NUM_CB (C++ esp_ble_pid_keys_t (C++ class), 210 enumerator), 330 esp_ble_pid_keys_t::addr_type (C++ ESP_BLE_MESH_TYPE_OUTPUT_STR_CB (C++ member), 210 enumerator), 330 esp_ble_pid_keys_t::irk (C++ member), 210 ESP_BLE_MESH_TYPE_PROV_CB (C++ enumera- esp_ble_pid_keys_t::static_addr (C++ tor), 330 member), 210 ESP_BLE_MESH_TYPE_RESET_CB (C++ enumera- esp_ble_pkt_data_length_params_t (C++ tor), 331 class), 209 ESP_BLE_MESH_UNKNOWN_TAI_DELTA_CHANGE esp_ble_pkt_data_length_params_t::rx_len (C macro), 451 (C++ member), 209 ESP_BLE_MESH_UNKNOWN_TAI_SECONDS (C esp_ble_pkt_data_length_params_t::tx_len macro), 451 (C++ member), 209 ESP_BLE_MESH_UNKNOWN_TAI_ZONE_CHANGE esp_ble_power_type_t (C++ enum), 281 (C macro), 451 ESP_BLE_PWR_TYPE_ADV (C++ enumerator), 282 esp_ble_mesh_unprov_dev_add_t (C++ ESP_BLE_PWR_TYPE_CONN_HDL0 (C++ enumera- class), 310 tor), 282 esp_ble_mesh_unprov_dev_add_t::addr ESP_BLE_PWR_TYPE_CONN_HDL1 (C++ enumera- (C++ member), 310 tor), 282 Espressif Systems 2144 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLE_PWR_TYPE_CONN_HDL2 (C++ enumera- esp_ble_sec_key_notif_t::bd_addr (C++ tor), 282 member), 211 ESP_BLE_PWR_TYPE_CONN_HDL3 (C++ enumera- esp_ble_sec_key_notif_t::passkey (C++ tor), 282 member), 211 ESP_BLE_PWR_TYPE_CONN_HDL4 (C++ enumera- esp_ble_sec_req_t (C++ class), 211 tor), 282 esp_ble_sec_req_t::bd_addr (C++ member), ESP_BLE_PWR_TYPE_CONN_HDL5 (C++ enumera- 211 tor), 282 esp_ble_sec_t (C++ union), 194 ESP_BLE_PWR_TYPE_CONN_HDL6 (C++ enumera- esp_ble_sec_t::auth_cmpl (C++ member), tor), 282 194 ESP_BLE_PWR_TYPE_CONN_HDL7 (C++ enumera- esp_ble_sec_t::ble_id_keys (C++ member), tor), 282 194 ESP_BLE_PWR_TYPE_CONN_HDL8 (C++ enumera- esp_ble_sec_t::ble_key (C++ member), 194 tor), 282 esp_ble_sec_t::ble_req (C++ member), 194 ESP_BLE_PWR_TYPE_DEFAULT (C++ enumerator), esp_ble_sec_t::key_notif (C++ member), 282 194 ESP_BLE_PWR_TYPE_NUM (C++ enumerator), 282 esp_ble_set_encryption (C++ function), 188 ESP_BLE_PWR_TYPE_SCAN (C++ enumerator), 282 ESP_BLE_SM_AUTHEN_REQ_MODE (C++ enumera- esp_ble_remove_bond_device (C++ function), tor), 224 188 ESP_BLE_SM_CLEAR_STATIC_PASSKEY (C++ esp_ble_resolve_adv_data (C++ function), enumerator), 225 186 ESP_BLE_SM_IOCAP_MODE (C++ enumerator), 224 ESP_BLE_SCA_100PPM (C++ enumerator), 281 ESP_BLE_SM_MAX_KEY_SIZE (C++ enumerator), ESP_BLE_SCA_150PPM (C++ enumerator), 281 225 ESP_BLE_SCA_20PPM (C++ enumerator), 281 ESP_BLE_SM_MAX_PARAM (C++ enumerator), 225 ESP_BLE_SCA_250PPM (C++ enumerator), 281 ESP_BLE_SM_MIN_KEY_SIZE (C++ enumerator), ESP_BLE_SCA_30PPM (C++ enumerator), 281 225 ESP_BLE_SCA_500PPM (C++ enumerator), 281 ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH ESP_BLE_SCA_50PPM (C++ enumerator), 281 (C++ enumerator), 225 ESP_BLE_SCA_75PPM (C++ enumerator), 281 ESP_BLE_SM_OOB_SUPPORT (C++ enumerator), esp_ble_scan_dupilcate_list_flush 225 (C++ function), 279 esp_ble_sm_param_t (C++ enum), 224 esp_ble_scan_duplicate_t (C++ enum), 225 ESP_BLE_SM_PASSKEY (C++ enumerator), 224 esp_ble_scan_filter_t (C++ enum), 225 ESP_BLE_SM_SET_INIT_KEY (C++ enumerator), ESP_BLE_SCAN_PARAM_UNDEF (C macro), 179 224 esp_ble_scan_params_t (C++ class), 208 ESP_BLE_SM_SET_RSP_KEY (C++ enumerator), esp_ble_scan_params_t::own_addr_type 225 (C++ member), 208 ESP_BLE_SM_SET_STATIC_PASSKEY (C++ enu- esp_ble_scan_params_t::scan_duplicate merator), 225 (C++ member), 208 esp_ble_tx_power_get (C++ function), 276 esp_ble_scan_params_t::scan_filter_poliecsyp_ble_tx_power_set (C++ function), 276 (C++ member), 208 ESP_BLE_WHITELIST_ADD (C++ enumerator), 226 esp_ble_scan_params_t::scan_interval ESP_BLE_WHITELIST_REMOVE (C++ enumerator), (C++ member), 208 226 esp_ble_scan_params_t::scan_type (C++ esp_ble_wl_addr_type_t (C++ enum), 181 member), 208 esp_ble_wl_opration_t (C++ enum), 226 esp_ble_scan_params_t::scan_window esp_bluedroid_deinit (C++ function), 182 (C++ member), 208 esp_bluedroid_disable (C++ function), 181 ESP_BLE_SCAN_RSP_DATA_LEN_MAX (C macro), esp_bluedroid_enable (C++ function), 181 219 esp_bluedroid_get_status (C++ function), esp_ble_scan_type_t (C++ enum), 225 181 esp_ble_sec_act_t (C++ enum), 224 esp_bluedroid_init (C++ function), 182 ESP_BLE_SEC_ENCRYPT (C++ enumerator), 224 ESP_BLUEDROID_STATUS_CHECK (C macro), 179 ESP_BLE_SEC_ENCRYPT_MITM (C++ enumerator), ESP_BLUEDROID_STATUS_ENABLED (C++ enu- 224 merator), 182 ESP_BLE_SEC_ENCRYPT_NO_MITM (C++ enumer- ESP_BLUEDROID_STATUS_INITIALIZED (C++ ator), 224 enumerator), 182 esp_ble_sec_key_notif_t (C++ class), 210 esp_bluedroid_status_t (C++ enum), 182 Espressif Systems 2145 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_BLUEDROID_STATUS_UNINITIALIZED esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_ (C++ enumerator), 182 (C++ class), 269 esp_blufi_ap_record_t (C++ class), 272 esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_ esp_blufi_ap_record_t::rssi (C++ mem- (C++ member), 269 ber), 273 esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_ esp_blufi_ap_record_t::ssid (C++ mem- (C++ member), 269 ber), 273 esp_blufi_cb_param_t::blufi_recv_custom_data_evt_ ESP_BLUFI_CALC_MD5_ERROR (C++ enumerator), (C++ class), 269 275 esp_blufi_cb_param_t::blufi_recv_custom_data_evt_ esp_blufi_callbacks_t (C++ class), 273 (C++ member), 270 esp_blufi_callbacks_t::checksum_func esp_blufi_cb_param_t::blufi_recv_custom_data_evt_ (C++ member), 273 (C++ member), 270 esp_blufi_callbacks_t::decrypt_func esp_blufi_cb_param_t::blufi_recv_server_cert_evt_ (C++ member), 273 (C++ class), 270 esp_blufi_callbacks_t::encrypt_func esp_blufi_cb_param_t::blufi_recv_server_cert_evt_ (C++ member), 273 (C++ member), 270 esp_blufi_callbacks_t::event_cb (C++ esp_blufi_cb_param_t::blufi_recv_server_cert_evt_ member), 273 (C++ member), 270 esp_blufi_callbacks_t::negotiate_data_heasnpd_lbelrufi_cb_param_t::blufi_recv_server_pkey_evt_ (C++ member), 273 (C++ class), 270 esp_blufi_cb_event_t (C++ enum), 274 esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_ esp_blufi_cb_param_t (C++ union), 267 (C++ member), 270 esp_blufi_cb_param_t::blufi_connect_evte_sppa_rbalmufi_cb_param_t::blufi_recv_server_pkey_evt_ (C++ class), 268 (C++ member), 270 esp_blufi_cb_param_t::blufi_connect_evte_sppa_rbalmu:f:ic_ocnbn__piadram_t::blufi_recv_softap_auth_mode (C++ member), 268 (C++ class), 270 esp_blufi_cb_param_t::blufi_connect_evte_sppa_rbalmu:f:ir_ecmbo_tpea_rbadma_t::blufi_recv_softap_auth_mode (C++ member), 268 (C++ member), 270 esp_blufi_cb_param_t::blufi_connect_evte_sppa_rbalmu:f:is_ecrbv_epra_riafm_t::blufi_recv_softap_channel_e (C++ member), 268 (C++ class), 270 esp_blufi_cb_param_t::blufi_deinit_finiesshp__ebvltu_fpia_rcabm_param_t::blufi_recv_softap_channel_e (C++ class), 268 (C++ member), 270 esp_blufi_cb_param_t::blufi_deinit_finiesshp__ebvltu_fpia_rcabm_:p:asrtaamt_et::blufi_recv_softap_max_conn_ (C++ member), 268 (C++ class), 270 esp_blufi_cb_param_t::blufi_disconnect_eesvpt__bplaurfaim_cb_param_t::blufi_recv_softap_max_conn_ (C++ class), 268 (C++ member), 270 esp_blufi_cb_param_t::blufi_disconnect_eesvpt__bplaurfaim_:c:br_epmaortaem__btd:a:blufi_recv_softap_passwd_ev (C++ member), 269 (C++ class), 270 esp_blufi_cb_param_t::blufi_get_error_eevstp__pbalruafmi_cb_param_t::blufi_recv_softap_passwd_ev (C++ class), 269 (C++ member), 271 esp_blufi_cb_param_t::blufi_get_error_eevstp__pbalruafmi:_:csbt_aptaeram_t::blufi_recv_softap_passwd_ev (C++ member), 269 (C++ member), 271 esp_blufi_cb_param_t::blufi_init_finishe_sepv_tb_lpuafria_mcb_param_t::blufi_recv_softap_ssid_evt_ (C++ class), 269 (C++ class), 271 esp_blufi_cb_param_t::blufi_init_finishe_sepv_tb_lpuafria_mc:b:_sptaartaem_t::blufi_recv_softap_ssid_evt_ (C++ member), 269 (C++ member), 271 esp_blufi_cb_param_t::blufi_recv_ca_evte_sppa_rbalmufi_cb_param_t::blufi_recv_softap_ssid_evt_ (C++ class), 269 (C++ member), 271 esp_blufi_cb_param_t::blufi_recv_ca_evte_sppa_rbalmu:f:ic_ecrbt_param_t::blufi_recv_sta_bssid_evt_pa (C++ member), 269 (C++ class), 271 esp_blufi_cb_param_t::blufi_recv_ca_evte_sppa_rbalmu:f:ic_ecrbt__plaernam_t::blufi_recv_sta_bssid_evt_pa (C++ member), 269 (C++ member), 271 esp_blufi_cb_param_t::blufi_recv_cliente_scpe_rbtl_uefvit__cpba_rpaamram_t::blufi_recv_sta_passwd_evt_p (C++ class), 269 (C++ class), 271 esp_blufi_cb_param_t::blufi_recv_cliente_scpe_rbtl_uefvit__cpba_rpaamr:a:mc_etr:t:blufi_recv_sta_passwd_evt_p (C++ member), 269 (C++ member), 271 esp_blufi_cb_param_t::blufi_recv_cliente_scpe_rbtl_uefvit__cpba_rpaamr:a:mc_etr:t:_blleunfi_recv_sta_passwd_evt_p (C++ member), 269 (C++ member), 271 Espressif Systems 2146 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_blufi_cb_param_t::blufi_recv_sta_ssEiSdP__eBvLtU_FpIa_rCaHmECKSUM_ERROR (C++ enumerator), (C++ class), 271 275 esp_blufi_cb_param_t::blufi_recv_sta_sseisdp__ebvltu_fpia_rcahme:c:ksssuimd_func_t (C++ type), 274 (C++ member), 271 ESP_BLUFI_DATA_FORMAT_ERROR (C++ enumer- esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_aptoar)r, a2m75::ssid_len (C++ member), 271 ESP_BLUFI_DECRYPT_ERROR (C++ enumerator), esp_blufi_cb_param_t::blufi_recv_username_evt_2p75aram (C++ class), 271 esp_blufi_decrypt_func_t (C++ type), 274 esp_blufi_cb_param_t::blufi_recv_usernaEmSeP__eBvLtU_FpIa_rDaEmI:N:InTa_mFeAILED (C++ enumerator), (C++ member), 271 275 esp_blufi_cb_param_t::blufi_recv_usernaEmSeP__eBvLtU_FpIa_rDaEmI:N:InTa_mOeK_(lCe+n+ enumerator), 275 (C++ member), 271 esp_blufi_deinit_state_t (C++ enum), 275 esp_blufi_cb_param_t::blufi_set_wifi_moEdSeP__eBvLtU_FpIa_rDaHm_MALLOC_ERROR (C++ enumera- (C++ class), 272 tor), 275 esp_blufi_cb_param_t::blufi_set_wifi_moEdSeP__eBvLtU_FpIa_rDaHm_:P:AoRpA_Mm_oEdReROR (C++ enumerator), (C++ member), 272 275 esp_blufi_cb_param_t::ca (C++ member), ESP_BLUFI_ENCRYPT_ERROR (C++ enumerator), 268 275 esp_blufi_cb_param_t::client_cert esp_blufi_encrypt_func_t (C++ type), 273 (C++ member), 268 esp_blufi_error_state_t (C++ enum), 275 esp_blufi_cb_param_t::client_pkey ESP_BLUFI_EVENT_BLE_CONNECT (C++ enumer- (C++ member), 268 ator), 274 esp_blufi_cb_param_t::connect (C++ ESP_BLUFI_EVENT_BLE_DISCONNECT (C++ member), 267 enumerator), 274 esp_blufi_cb_param_t::custom_data esp_blufi_event_cb_t (C++ type), 273 (C++ member), 268 ESP_BLUFI_EVENT_DEAUTHENTICATE_STA esp_blufi_cb_param_t::deinit_finish (C++ enumerator), 274 (C++ member), 267 ESP_BLUFI_EVENT_DEINIT_FINISH (C++ enu- esp_blufi_cb_param_t::disconnect (C++ merator), 274 member), 267 ESP_BLUFI_EVENT_GET_WIFI_LIST (C++ enu- esp_blufi_cb_param_t::init_finish merator), 275 (C++ member), 267 ESP_BLUFI_EVENT_GET_WIFI_STATUS (C++ esp_blufi_cb_param_t::report_error enumerator), 274 (C++ member), 268 ESP_BLUFI_EVENT_INIT_FINISH (C++ enumer- esp_blufi_cb_param_t::server_cert ator), 274 (C++ member), 268 ESP_BLUFI_EVENT_RECV_CA_CERT (C++ enu- esp_blufi_cb_param_t::server_pkey merator), 274 (C++ member), 268 ESP_BLUFI_EVENT_RECV_CLIENT_CERT (C++ esp_blufi_cb_param_t::softap_auth_mode enumerator), 274 (C++ member), 268 ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY esp_blufi_cb_param_t::softap_channel (C++ enumerator), 274 (C++ member), 268 ESP_BLUFI_EVENT_RECV_CUSTOM_DATA (C++ esp_blufi_cb_param_t::softap_max_conn_num enumerator), 275 (C++ member), 268 ESP_BLUFI_EVENT_RECV_SERVER_CERT (C++ esp_blufi_cb_param_t::softap_passwd enumerator), 274 (C++ member), 267 ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY esp_blufi_cb_param_t::softap_ssid (C++ enumerator), 275 (C++ member), 267 ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE esp_blufi_cb_param_t::sta_bssid (C++ (C++ enumerator), 275 member), 267 ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE esp_blufi_cb_param_t::sta_passwd (C++ (C++ enumerator), 274 member), 267 ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL esp_blufi_cb_param_t::sta_ssid (C++ (C++ enumerator), 274 member), 267 ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM esp_blufi_cb_param_t::username (C++ (C++ enumerator), 274 member), 268 ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD esp_blufi_cb_param_t::wifi_mode (C++ (C++ enumerator), 274 member), 267 ESP_BLUFI_EVENT_RECV_SOFTAP_SSID (C++ Espressif Systems 2147 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index enumerator), 274 esp_blufi_negotiate_data_handler_t ESP_BLUFI_EVENT_RECV_STA_BSSID (C++ (C++ type), 273 enumerator), 274 esp_blufi_profile_deinit (C++ function), ESP_BLUFI_EVENT_RECV_STA_PASSWD (C++ 266 enumerator), 274 esp_blufi_profile_init (C++ function), 266 ESP_BLUFI_EVENT_RECV_STA_SSID (C++ enu- ESP_BLUFI_READ_PARAM_ERROR (C++ enumera- merator), 274 tor), 275 ESP_BLUFI_EVENT_RECV_USERNAME (C++ enu- esp_blufi_register_callbacks (C++ func- merator), 274 tion), 266 ESP_BLUFI_EVENT_REPORT_ERROR (C++ enu- esp_blufi_send_custom_data (C++ function), merator), 275 267 ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP esp_blufi_send_error_info (C++ function), (C++ enumerator), 274 267 ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP esp_blufi_send_wifi_conn_report (C++ (C++ enumerator), 274 function), 266 ESP_BLUFI_EVENT_SET_WIFI_OPMODE (C++ esp_blufi_send_wifi_list (C++ function), enumerator), 274 267 esp_blufi_extra_info_t (C++ class), 272 ESP_BLUFI_SEQUENCE_ERROR (C++ enumerator), esp_blufi_extra_info_t::softap_authmode 275 (C++ member), 272 ESP_BLUFI_STA_CONN_FAIL (C++ enumerator), esp_blufi_extra_info_t::softap_authmode_set 275 (C++ member), 272 esp_blufi_sta_conn_state_t (C++ enum), esp_blufi_extra_info_t::softap_channel 275 (C++ member), 272 ESP_BLUFI_STA_CONN_SUCCESS (C++ enumera- esp_blufi_extra_info_t::softap_channel_set tor), 275 (C++ member), 272 esp_bredr_sco_datapath_set (C++ function), esp_blufi_extra_info_t::softap_max_conn_num 276 (C++ member), 272 esp_bredr_tx_power_get (C++ function), 276 esp_blufi_extra_info_t::softap_max_conne_snpu_mb_rseedtr_tx_power_set (C++ function), 276 (C++ member), 272 ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL (C esp_blufi_extra_info_t::softap_passwd macro), 280 (C++ member), 272 esp_bt_controller_config_t (C++ class), esp_blufi_extra_info_t::softap_passwd_len 279 (C++ member), 272 esp_bt_controller_config_t::auto_latency esp_blufi_extra_info_t::softap_ssid (C++ member), 280 (C++ member), 272 esp_bt_controller_config_t::ble_max_conn esp_blufi_extra_info_t::softap_ssid_len (C++ member), 280 (C++ member), 272 esp_bt_controller_config_t::ble_sca esp_blufi_extra_info_t::sta_bssid (C++ member), 280 (C++ member), 272 esp_bt_controller_config_t::bt_legacy_auth_vs_evt esp_blufi_extra_info_t::sta_bssid_set (C++ member), 280 (C++ member), 272 esp_bt_controller_config_t::bt_max_acl_conn esp_blufi_extra_info_t::sta_passwd (C++ member), 280 (C++ member), 272 esp_bt_controller_config_t::bt_max_sync_conn esp_blufi_extra_info_t::sta_passwd_len (C++ member), 280 (C++ member), 272 esp_bt_controller_config_t::bt_sco_datapath esp_blufi_extra_info_t::sta_ssid (C++ (C++ member), 280 member), 272 esp_bt_controller_config_t::controller_debug_flag esp_blufi_extra_info_t::sta_ssid_len (C++ member), 280 (C++ member), 272 esp_bt_controller_config_t::controller_task_prio esp_blufi_get_version (C++ function), 267 (C++ member), 279 ESP_BLUFI_INIT_FAILED (C++ enumerator), 275 esp_bt_controller_config_t::controller_task_stack ESP_BLUFI_INIT_OK (C++ enumerator), 275 (C++ member), 279 ESP_BLUFI_INIT_SECURITY_ERROR (C++ enu- esp_bt_controller_config_t::hci_uart_baudrate merator), 275 (C++ member), 279 esp_blufi_init_state_t (C++ enum), 275 esp_bt_controller_config_t::hci_uart_no ESP_BLUFI_MAKE_PUBLIC_ERROR (C++ enumer- (C++ member), 279 ator), 275 esp_bt_controller_config_t::hli (C++ Espressif Systems 2148 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index member), 280 esp_bt_mode_t (C++ enum), 281 esp_bt_controller_config_t::magic ESP_BT_OCTET16_LEN (C macro), 179 (C++ member), 280 esp_bt_octet16_t (C++ type), 180 esp_bt_controller_config_t::mesh_adv_siEzSeP_BT_OCTET8_LEN (C macro), 179 (C++ member), 280 esp_bt_octet8_t (C++ type), 180 esp_bt_controller_config_t::mode (C++ esp_bt_sleep_disable (C++ function), 279 member), 280 esp_bt_sleep_enable (C++ function), 278 esp_bt_controller_config_t::normal_adv_EsSiPz_eBT_STATUS_AUTH_FAILURE (C++ enumera- (C++ member), 279 tor), 180 esp_bt_controller_config_t::pcm_polar ESP_BT_STATUS_AUTH_REJECTED (C++ enumer- (C++ member), 280 ator), 180 esp_bt_controller_config_t::pcm_role ESP_BT_STATUS_BUSY (C++ enumerator), 180 (C++ member), 280 ESP_BT_STATUS_CONTROL_LE_DATA_LEN_UNSUPPORTED esp_bt_controller_config_t::scan_duplicate_mod(Ce++ enumerator), 180 (C++ member), 279 ESP_BT_STATUS_DONE (C++ enumerator), 180 esp_bt_controller_config_t::scan_duplicEaStPe__BtTy_pSeTATUS_EIR_TOO_LARGE (C++ enumer- (C++ member), 279 ator), 181 esp_bt_controller_config_t::send_adv_reEsSePr_vBeTd__SsTiAzTeUS_ERR_ILLEGAL_PARAMETER_FMT (C++ member), 280 (C++ enumerator), 180 esp_bt_controller_deinit (C++ function), ESP_BT_STATUS_FAIL (C++ enumerator), 180 277 ESP_BT_STATUS_INVALID_STATIC_RAND_ADDR esp_bt_controller_disable (C++ function), (C++ enumerator), 180 277 ESP_BT_STATUS_MEMORY_FULL (C++ enumera- esp_bt_controller_enable (C++ function), tor), 180 277 ESP_BT_STATUS_NOMEM (C++ enumerator), 180 esp_bt_controller_get_status (C++ func- ESP_BT_STATUS_NOT_READY (C++ enumerator), tion), 277 180 esp_bt_controller_init (C++ function), 276 ESP_BT_STATUS_PARAM_OUT_OF_RANGE (C++ esp_bt_controller_mem_release (C++ func- enumerator), 180 tion), 277 ESP_BT_STATUS_PARM_INVALID (C++ enumera- ESP_BT_CONTROLLER_STATUS_ENABLED (C++ tor), 180 enumerator), 281 ESP_BT_STATUS_PEER_LE_DATA_LEN_UNSUPPORTED ESP_BT_CONTROLLER_STATUS_IDLE (C++ enu- (C++ enumerator), 180 merator), 281 ESP_BT_STATUS_PENDING (C++ enumerator), 180 ESP_BT_CONTROLLER_STATUS_INITED (C++ ESP_BT_STATUS_RMT_DEV_DOWN (C++ enumera- enumerator), 281 tor), 180 ESP_BT_CONTROLLER_STATUS_NUM (C++ enu- ESP_BT_STATUS_SUCCESS (C++ enumerator), 180 merator), 281 esp_bt_status_t (C++ enum), 180 esp_bt_controller_status_t (C++ enum), ESP_BT_STATUS_TIMEOUT (C++ enumerator), 180 281 ESP_BT_STATUS_UNACCEPT_CONN_INTERVAL esp_bt_dev_get_address (C++ function), 182 (C++ enumerator), 180 esp_bt_dev_set_device_name (C++ function), ESP_BT_STATUS_UNHANDLED (C++ enumerator), 182 180 esp_bt_dev_type_t (C++ enum), 181 ESP_BT_STATUS_UNSUPPORTED (C++ enumera- ESP_BT_DEVICE_TYPE_BLE (C++ enumerator), tor), 180 181 esp_bt_uuid_t (C++ class), 178 ESP_BT_DEVICE_TYPE_BREDR (C++ enumerator), esp_bt_uuid_t::len (C++ member), 179 181 esp_bt_uuid_t::uuid (C++ member), 179 ESP_BT_DEVICE_TYPE_DUMO (C++ enumerator), esp_bt_uuid_t::uuid128 (C++ member), 179 181 esp_bt_uuid_t::uuid16 (C++ member), 179 esp_bt_duplicate_exceptional_subcode_tyepsep__tbt_uuid_t::uuid32 (C++ member), 179 (C++ enum), 226 ESP_CHIP_ID_ESP32 (C++ enumerator), 1338 esp_bt_mem_release (C++ function), 278 ESP_CHIP_ID_ESP32C2 (C++ enumerator), 1338 ESP_BT_MODE_BLE (C++ enumerator), 281 ESP_CHIP_ID_ESP32C3 (C++ enumerator), 1338 ESP_BT_MODE_BTDM (C++ enumerator), 281 ESP_CHIP_ID_ESP32S2 (C++ enumerator), 1338 ESP_BT_MODE_CLASSIC_BT (C++ enumerator), ESP_CHIP_ID_ESP32S3 (C++ enumerator), 1338 281 ESP_CHIP_ID_INVALID (C++ enumerator), 1338 ESP_BT_MODE_IDLE (C++ enumerator), 281 esp_chip_id_t (C++ enum), 1338 Espressif Systems 2149 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_chip_info (C++ function), 1566 esp_console_register_help_command esp_chip_info_t (C++ class), 1566 (C++ function), 1350 esp_chip_info_t::cores (C++ member), 1566 ESP_CONSOLE_REPL_CONFIG_DEFAULT (C esp_chip_info_t::features (C++ member), macro), 1353 1566 esp_console_repl_config_t (C++ class), esp_chip_info_t::model (C++ member), 1566 1351 esp_chip_info_t::revision (C++ member), esp_console_repl_config_t::history_save_path 1566 (C++ member), 1352 esp_chip_model_t (C++ enum), 1566 esp_console_repl_config_t::max_cmdline_length esp_console_cmd_func_t (C++ type), 1353 (C++ member), 1352 esp_console_cmd_register (C++ function), esp_console_repl_config_t::max_history_len 1349 (C++ member), 1352 esp_console_cmd_t (C++ class), 1352 esp_console_repl_config_t::prompt esp_console_cmd_t::argtable (C++ mem- (C++ member), 1352 ber), 1352 esp_console_repl_config_t::task_priority esp_console_cmd_t::command (C++ member), (C++ member), 1352 1352 esp_console_repl_config_t::task_stack_size esp_console_cmd_t::func (C++ member), (C++ member), 1352 1352 esp_console_repl_s (C++ class), 1353 esp_console_cmd_t::help (C++ member), esp_console_repl_s::del (C++ member), 1352 1353 esp_console_cmd_t::hint (C++ member), esp_console_repl_t (C++ type), 1353 1352 esp_console_run (C++ function), 1349 ESP_CONSOLE_CONFIG_DEFAULT (C macro), 1353 esp_console_split_argv (C++ function), 1349 esp_console_config_t (C++ class), 1351 esp_console_start_repl (C++ function), 1351 esp_console_config_t::hint_bold (C++ esp_cpu_ccount_t (C++ type), 1568 member), 1351 esp_cpu_clear_watchpoint (C++ function), esp_console_config_t::hint_color (C++ 1567 member), 1351 esp_cpu_configure_region_protection esp_console_config_t::max_cmdline_args (C++ function), 1567 (C++ member), 1351 esp_cpu_get_ccount (C++ function), 1567 esp_console_config_t::max_cmdline_lengtehsp_cpu_get_sp (C++ function), 1567 (C++ member), 1351 esp_cpu_in_ocd_debug_mode (C++ function), esp_console_deinit (C++ function), 1349 1567 ESP_CONSOLE_DEV_CDC_CONFIG_DEFAULT (C esp_cpu_reset (C++ function), 1567 macro), 1353 esp_cpu_set_ccount (C++ function), 1567 ESP_CONSOLE_DEV_UART_CONFIG_DEFAULT (C esp_cpu_set_watchpoint (C++ function), 1567 macro), 1353 esp_cpu_stall (C++ function), 1567 esp_console_dev_uart_config_t (C++ esp_cpu_unstall (C++ function), 1567 class), 1352 ESP_CPU_WATCHPOINT_ACCESS (C macro), 1568 esp_console_dev_uart_config_t::baud_ratEeSP_CPU_WATCHPOINT_LOAD (C macro), 1568 (C++ member), 1352 ESP_CPU_WATCHPOINT_STORE (C macro), 1568 esp_console_dev_uart_config_t::channel esp_crt_bundle_attach (C++ function), 132 (C++ member), 1352 esp_crt_bundle_detach (C++ function), 132 esp_console_dev_uart_config_t::rx_gpio_ensupm_crt_bundle_set (C++ function), 132 (C++ member), 1352 esp_deep_sleep (C++ function), 1607 esp_console_dev_uart_config_t::tx_gpio_ensupm_deep_sleep_disable_rom_logging (C++ member), 1352 (C++ function), 1608 esp_console_dev_usb_cdc_config_t (C++ esp_deep_sleep_start (C++ function), 1607 class), 1352 esp_deep_sleep_wake_stub_fn_t (C++ esp_console_get_completion (C++ function), type), 1608 1350 ESP_DEFAULT_GATT_IF (C macro), 179 esp_console_get_hint (C++ function), 1350 esp_default_wake_deep_sleep (C++ func- esp_console_init (C++ function), 1349 tion), 1608 esp_console_new_repl_uart (C++ function), esp_deregister_freertos_idle_hook 1350 (C++ function), 1514 esp_console_new_repl_usb_cdc (C++ func- esp_deregister_freertos_idle_hook_for_cpu tion), 1351 (C++ function), 1514 Espressif Systems 2150 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_deregister_freertos_tick_hook esp_efuse_check_secure_version (C++ (C++ function), 1514 function), 1369 esp_deregister_freertos_tick_hook_for_cepsup_efuse_coding_scheme_t (C++ enum), (C++ function), 1514 1365 esp_derive_local_mac (C++ function), 1565 esp_efuse_count_unused_key_blocks esp_digital_signature_data (C++ class), (C++ function), 1373 696 esp_efuse_desc_t (C++ class), 1374 esp_digital_signature_data::c (C++ esp_efuse_desc_t::bit_count (C++ mem- member), 697 ber), 1374 esp_digital_signature_data::iv (C++ esp_efuse_desc_t::bit_start (C++ mem- member), 697 ber), 1374 esp_digital_signature_data::rsa_length esp_efuse_desc_t::efuse_block (C++ (C++ member), 697 member), 1374 esp_digital_signature_length_t (C++ esp_efuse_disable_rom_download_mode enum), 698 (C++ function), 1369 ESP_DRAM_LOGD (C macro), 1559 esp_efuse_enable_rom_secure_download_mode ESP_DRAM_LOGE (C macro), 1558 (C++ function), 1369 ESP_DRAM_LOGI (C macro), 1558 esp_efuse_find_purpose (C++ function), 1372 ESP_DRAM_LOGV (C macro), 1559 esp_efuse_find_unused_key_block (C++ ESP_DRAM_LOGW (C macro), 1558 function), 1373 ESP_DS_C_LEN (C macro), 697 esp_efuse_get_chip_ver (C++ function), 1368 esp_ds_context_t (C++ type), 698 esp_efuse_get_coding_scheme (C++ func- esp_ds_data_t (C++ type), 698 tion), 1368 esp_ds_encrypt_params (C++ function), 696 esp_efuse_get_digest_revoke (C++ func- esp_ds_finish_sign (C++ function), 696 tion), 1373 esp_ds_is_busy (C++ function), 696 esp_efuse_get_field_size (C++ function), ESP_DS_IV_LEN (C macro), 697 1367 esp_ds_p_data_t (C++ class), 697 esp_efuse_get_key (C++ function), 1372 esp_ds_p_data_t::length (C++ member), 697 esp_efuse_get_key_dis_read (C++ function), esp_ds_p_data_t::M (C++ member), 697 1371 esp_ds_p_data_t::M_prime (C++ member), esp_efuse_get_key_dis_write (C++ func- 697 tion), 1371 esp_ds_p_data_t::Rb (C++ member), 697 esp_efuse_get_key_purpose (C++ function), esp_ds_p_data_t::Y (C++ member), 697 1372 ESP_DS_RSA_1024 (C++ enumerator), 698 esp_efuse_get_keypurpose_dis_write ESP_DS_RSA_2048 (C++ enumerator), 698 (C++ function), 1372 ESP_DS_RSA_3072 (C++ enumerator), 698 esp_efuse_get_pkg_ver (C++ function), 1369 ESP_DS_RSA_4096 (C++ enumerator), 698 esp_efuse_get_purpose_field (C++ func- esp_ds_sign (C++ function), 695 tion), 1372 esp_ds_start_sign (C++ function), 695 esp_efuse_get_write_protect_of_digest_revoke esp_duplicate_info_t (C++ type), 220 (C++ function), 1373 esp_duplicate_scan_exceptional_list_typees_pt_efuse_key_block_unused (C++ function), (C++ enum), 227 1371 ESP_EARLY_LOGD (C macro), 1558 ESP_EFUSE_KEY_PURPOSE_HMAC_DOWN_ALL ESP_EARLY_LOGE (C macro), 1557 (C++ enumerator), 1365 ESP_EARLY_LOGI (C macro), 1558 ESP_EFUSE_KEY_PURPOSE_HMAC_DOWN_DIGITAL_SIGNATURE ESP_EARLY_LOGV (C macro), 1558 (C++ enumerator), 1365 ESP_EARLY_LOGW (C macro), 1557 ESP_EFUSE_KEY_PURPOSE_HMAC_DOWN_JTAG esp_efuse_batch_write_begin (C++ func- (C++ enumerator), 1365 tion), 1370 ESP_EFUSE_KEY_PURPOSE_HMAC_UP (C++ enu- esp_efuse_batch_write_cancel (C++ func- merator), 1365 tion), 1370 ESP_EFUSE_KEY_PURPOSE_MAX (C++ enumera- esp_efuse_batch_write_commit (C++ func- tor), 1365 tion), 1371 ESP_EFUSE_KEY_PURPOSE_RESERVED (C++ esp_efuse_block_is_empty (C++ function), enumerator), 1365 1371 ESP_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST0 esp_efuse_block_t (C++ enum), 1364 (C++ enumerator), 1365 ESP_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST1 Espressif Systems 2151 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ enumerator), 1365 esp_efuse_write_field_bit (C++ function), ESP_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST2 1367 (C++ enumerator), 1365 esp_efuse_write_field_blob (C++ function), ESP_EFUSE_KEY_PURPOSE_USER (C++ enumera- 1366 tor), 1365 esp_efuse_write_field_cnt (C++ function), ESP_EFUSE_KEY_PURPOSE_XTS_AES_128_KEY 1366 (C++ enumerator), 1365 esp_efuse_write_key (C++ function), 1373 ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_1esp_efuse_write_keys (C++ function), 1374 (C++ enumerator), 1365 esp_efuse_write_reg (C++ function), 1368 ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_2ESP_ERR_CODING (C macro), 1375 (C++ enumerator), 1365 ESP_ERR_DAMAGED_READING (C macro), 1375 esp_efuse_mac_get_custom (C++ function), ESP_ERR_DPP_FAILURE (C macro), 585 1564 ESP_ERR_DPP_INVALID_ATTR (C macro), 585 esp_efuse_mac_get_default (C++ function), ESP_ERR_DPP_TX_FAILURE (C macro), 585 1565 ESP_ERR_EFUSE (C macro), 1374 esp_efuse_purpose_t (C++ enum), 1365 ESP_ERR_EFUSE_CNT_IS_FULL (C macro), 1375 esp_efuse_read_block (C++ function), 1368 ESP_ERR_EFUSE_REPEATED_PROG (C macro), esp_efuse_read_field_bit (C++ function), 1375 1366 ESP_ERR_ESP_NETIF_BASE (C macro), 632 esp_efuse_read_field_blob (C++ function), ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED 1365 (C macro), 632 esp_efuse_read_field_cnt (C++ function), ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED 1366 (C macro), 632 esp_efuse_read_reg (C++ function), 1367 ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED (C esp_efuse_read_secure_version (C++ func- macro), 632 tion), 1369 ESP_ERR_ESP_NETIF_DHCPC_START_FAILED esp_efuse_reset (C++ function), 1369 (C macro), 632 ESP_EFUSE_ROM_LOG_ALWAYS_OFF (C++ enu- ESP_ERR_ESP_NETIF_DNS_NOT_CONFIGURED merator), 1375 (C macro), 632 ESP_EFUSE_ROM_LOG_ALWAYS_ON (C++ enumer- ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED ator), 1375 (C macro), 632 ESP_EFUSE_ROM_LOG_ON_GPIO_HIGH (C++ ESP_ERR_ESP_NETIF_IF_NOT_READY (C enumerator), 1375 macro), 632 ESP_EFUSE_ROM_LOG_ON_GPIO_LOW (C++ enu- ESP_ERR_ESP_NETIF_INIT_FAILED (C macro), merator), 1375 632 esp_efuse_rom_log_scheme_t (C++ enum), ESP_ERR_ESP_NETIF_INVALID_PARAMS (C 1375 macro), 632 esp_efuse_set_digest_revoke (C++ func- ESP_ERR_ESP_NETIF_IP6_ADDR_FAILED (C tion), 1373 macro), 632 esp_efuse_set_key_dis_read (C++ function), ESP_ERR_ESP_NETIF_MLD6_FAILED (C macro), 1371 632 esp_efuse_set_key_dis_write (C++ func- ESP_ERR_ESP_NETIF_NO_MEM (C macro), 632 tion), 1371 ESP_ERR_ESP_TLS_BASE (C macro), 94 esp_efuse_set_key_purpose (C++ function), ESP_ERR_ESP_TLS_CANNOT_CREATE_SOCKET 1372 (C macro), 94 esp_efuse_set_keypurpose_dis_write ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAME (C++ function), 1372 (C macro), 94 esp_efuse_set_read_protect (C++ function), ESP_ERR_ESP_TLS_CONNECTION_TIMEOUT (C 1367 macro), 94 esp_efuse_set_rom_log_scheme (C++ func- ESP_ERR_ESP_TLS_FAILED_CONNECT_TO_HOST tion), 1369 (C macro), 94 esp_efuse_set_write_protect (C++ func- ESP_ERR_ESP_TLS_SE_FAILED (C macro), 94 tion), 1367 ESP_ERR_ESP_TLS_SOCKET_SETOPT_FAILED esp_efuse_set_write_protect_of_digest_revoke (C macro), 94 (C++ function), 1373 ESP_ERR_ESP_TLS_TCP_CLOSED_FIN (C esp_efuse_update_secure_version (C++ macro), 94 function), 1369 ESP_ERR_ESP_TLS_UNSUPPORTED_PROTOCOL_FAMILY esp_efuse_write_block (C++ function), 1368 (C macro), 94 Espressif Systems 2152 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_ERR_ESPNOW_ARG (C macro), 509 ESP_ERR_ESPNOW_BASE (C macro), 509 ESP_ERR_ESPNOW_EXIST (C macro), 509 ESP_ERR_ESPNOW_FULL (C macro), 509 ESP_ERR_ESPNOW_IF (C macro), 509 ESP_ERR_ESPNOW_INTERNAL (C macro), 509 ESP_ERR_ESPNOW_NO_MEM (C macro), 509 ESP_ERR_ESPNOW_NOT_FOUND (C macro), 509 ESP_ERR_ESPNOW_NOT_INIT (C macro), 509 ESP_ERR_FLASH_BASE (C macro), 1377 ESP_ERR_FLASH_NO_RESPONSE (C++ enumera- tor), 1306 ESP_ERR_FLASH_NOT_INITIALISED (C macro), 1306 ESP_ERR_FLASH_OP_FAIL (C macro), 1300 ESP_ERR_FLASH_OP_TIMEOUT (C macro), 1300 ESP_ERR_FLASH_PROTECTED (C macro), 1306 ESP_ERR_FLASH_SIZE_NOT_MATCH (C++ enu- merator), 1306 ESP_ERR_FLASH_UNSUPPORTED_CHIP (C macro), 1306 ESP_ERR_FLASH_UNSUPPORTED_HOST (C macro), 1306 ESP_ERR_HTTP_BASE (C macro), 106 ESP_ERR_HTTP_CONNECT (C macro), 106 ESP_ERR_HTTP_CONNECTING (C macro), 106 ESP_ERR_HTTP_CONNECTION_CLOSED (C macro), 106 ESP_ERR_HTTP_EAGAIN (C macro), 106 ESP_ERR_HTTP_FETCH_HEADER (C macro), 106 ESP_ERR_HTTP_INVALID_TRANSPORT (C macro), 106 ESP_ERR_HTTP_MAX_REDIRECT (C macro), 106 ESP_ERR_HTTP_WRITE_DATA (C macro), 106 ESP_ERR_HTTPD_ALLOC_MEM (C macro), 151 ESP_ERR_HTTPD_BASE (C macro), 151 ESP_ERR_HTTPD_HANDLER_EXISTS (C macro), 151 ESP_ERR_HTTPD_HANDLERS_FULL (C macro), 151 ESP_ERR_HTTPD_INVALID_REQ (C macro), 151 ESP_ERR_HTTPD_RESP_HDR (C macro), 151 ESP_ERR_HTTPD_RESP_SEND (C macro), 151 ESP_ERR_HTTPD_RESULT_TRUNC (C macro), 151 ESP_ERR_HTTPD_TASK (C macro), 151 ESP_ERR_HTTPS_OTA_BASE (C macro), 1382 ESP_ERR_HTTPS_OTA_IN_PROGRESS (C macro), 1382 ESP_ERR_HW_CRYPTO_BASE (C macro), 1377 ESP_ERR_INVALID_ARG (C macro), 1377 ESP_ERR_INVALID_CRC (C macro), 1377 ESP_ERR_INVALID_MAC (C macro), 1377 ESP_ERR_INVALID_RESPONSE (C macro), 1377 ESP_ERR_INVALID_SIZE (C macro), 1377 ESP_ERR_INVALID_STATE (C macro), 1377 ESP_ERR_INVALID_VERSION (C macro), 1377 ESP_ERR_MBEDTLS_CERT_PARTLY_OK (C macro), 94 ESP_ERR_MBEDTLS_CTR_DRBG_SEED_FAILED (C macro), 94 ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED (C macro), 95 ESP_ERR_MBEDTLS_SSL_CONF_ALPN_PROTOCOLS_FAILED (C macro), 94 ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILED (C macro), 95 ESP_ERR_MBEDTLS_SSL_CONF_PSK_FAILED (C macro), 95 ESP_ERR_MBEDTLS_SSL_CONFIG_DEFAULTS_FAILED (C macro), 94 ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED (C macro), 95 ESP_ERR_MBEDTLS_SSL_SET_HOSTNAME_FAILED (C macro), 94 ESP_ERR_MBEDTLS_SSL_SETUP_FAILED (C macro), 95 ESP_ERR_MBEDTLS_SSL_TICKET_SETUP_FAILED (C macro), 95 ESP_ERR_MBEDTLS_SSL_WRITE_FAILED (C macro), 95 ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILED (C macro), 95 ESP_ERR_MEMPROT_BASE (C macro), 1377 ESP_ERR_MESH_ARGUMENT (C macro), 537 ESP_ERR_MESH_BASE (C macro), 1377 ESP_ERR_MESH_DISCARD (C macro), 538 ESP_ERR_MESH_DISCARD_DUPLICATE (C macro), 538 ESP_ERR_MESH_DISCONNECTED (C macro), 537 ESP_ERR_MESH_EXCEED_MTU (C macro), 537 ESP_ERR_MESH_INTERFACE (C macro), 537 ESP_ERR_MESH_NO_MEMORY (C macro), 537 ESP_ERR_MESH_NO_PARENT_FOUND (C macro), 537 ESP_ERR_MESH_NO_ROUTE_FOUND (C macro), 537 ESP_ERR_MESH_NOT_ALLOWED (C macro), 537 ESP_ERR_MESH_NOT_CONFIG (C macro), 537 ESP_ERR_MESH_NOT_INIT (C macro), 537 ESP_ERR_MESH_NOT_START (C macro), 537 ESP_ERR_MESH_NOT_SUPPORT (C macro), 537 ESP_ERR_MESH_OPTION_NULL (C macro), 537 ESP_ERR_MESH_OPTION_UNKNOWN (C macro), 537 ESP_ERR_MESH_PS (C macro), 538 ESP_ERR_MESH_QUEUE_FAIL (C macro), 537 ESP_ERR_MESH_QUEUE_FULL (C macro), 537 ESP_ERR_MESH_QUEUE_READ (C macro), 538 ESP_ERR_MESH_RECV_RELEASE (C macro), 538 ESP_ERR_MESH_TIMEOUT (C macro), 537 ESP_ERR_MESH_VOTING (C macro), 538 ESP_ERR_MESH_WIFI_NOT_START (C macro), 537 ESP_ERR_MESH_XMIT (C macro), 538 ESP_ERR_MESH_XON_NO_WINDOW (C macro), 537 ESP_ERR_NO_MEM (C macro), 1376 Espressif Systems 2153 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_ERR_NOT_ENOUGH_UNUSED_KEY_BLOCKS (C macro), 1375 ESP_ERR_NOT_FINISHED (C macro), 1377 ESP_ERR_NOT_FOUND (C macro), 1377 ESP_ERR_NOT_SUPPORTED (C macro), 1377 ESP_ERR_NVS_BASE (C macro), 1261 ESP_ERR_NVS_CONTENT_DIFFERS (C macro), 1262 ESP_ERR_NVS_CORRUPT_KEY_PART (C macro), 1262 ESP_ERR_NVS_ENCR_NOT_SUPPORTED (C macro), 1262 ESP_ERR_NVS_INVALID_HANDLE (C macro), 1261 ESP_ERR_NVS_INVALID_LENGTH (C macro), 1262 ESP_ERR_NVS_INVALID_NAME (C macro), 1261 ESP_ERR_NVS_INVALID_STATE (C macro), 1262 ESP_ERR_NVS_KEY_TOO_LONG (C macro), 1261 ESP_ERR_NVS_KEYS_NOT_INITIALIZED (C macro), 1262 ESP_ERR_NVS_NEW_VERSION_FOUND (C macro), 1262 ESP_ERR_NVS_NO_FREE_PAGES (C macro), 1262 ESP_ERR_NVS_NOT_ENOUGH_SPACE (C macro), 1261 ESP_ERR_NVS_NOT_FOUND (C macro), 1261 ESP_ERR_NVS_NOT_INITIALIZED (C macro), 1261 ESP_ERR_NVS_PAGE_FULL (C macro), 1261 ESP_ERR_NVS_PART_NOT_FOUND (C macro), 1262 ESP_ERR_NVS_READ_ONLY (C macro), 1261 ESP_ERR_NVS_REMOVE_FAILED (C macro), 1261 ESP_ERR_NVS_TYPE_MISMATCH (C macro), 1261 ESP_ERR_NVS_VALUE_TOO_LONG (C macro), 1262 ESP_ERR_NVS_WRONG_ENCRYPTION (C macro), 1262 ESP_ERR_NVS_XTS_CFG_FAILED (C macro), 1262 ESP_ERR_NVS_XTS_CFG_NOT_FOUND (C macro), 1262 ESP_ERR_NVS_XTS_DECR_FAILED (C macro), 1262 ESP_ERR_NVS_XTS_ENCR_FAILED (C macro), 1262 ESP_ERR_OTA_BASE (C macro), 1585 ESP_ERR_OTA_PARTITION_CONFLICT (C macro), 1585 ESP_ERR_OTA_ROLLBACK_FAILED (C macro), 1585 ESP_ERR_OTA_ROLLBACK_INVALID_STATE (C macro), 1585 ESP_ERR_OTA_SELECT_INFO_INVALID (C macro), 1585 ESP_ERR_OTA_SMALL_SEC_VER (C macro), 1585 ESP_ERR_OTA_VALIDATE_FAILED (C macro), 1585 esp_err_t (C++ type), 1377 ESP_ERR_TIMEOUT (C macro), 1377 esp_err_to_name (C++ function), 1376 esp_err_to_name_r (C++ function), 1376 ESP_ERR_ULP_BASE (C macro), 1651 ESP_ERR_ULP_BRANCH_OUT_OF_RANGE (C macro), 1651 ESP_ERR_ULP_DUPLICATE_LABEL (C macro), 1651 ESP_ERR_ULP_INVALID_LOAD_ADDR (C macro), 1651 ESP_ERR_ULP_SIZE_TOO_BIG (C macro), 1651 ESP_ERR_ULP_UNDEFINED_LABEL (C macro), 1651 ESP_ERR_WIFI_BASE (C macro), 1377 ESP_ERR_WIFI_CONN (C macro), 561 ESP_ERR_WIFI_IF (C macro), 560 ESP_ERR_WIFI_INIT_STATE (C macro), 561 ESP_ERR_WIFI_MAC (C macro), 561 ESP_ERR_WIFI_MODE (C macro), 560 ESP_ERR_WIFI_NOT_ASSOC (C macro), 561 ESP_ERR_WIFI_NOT_CONNECT (C macro), 561 ESP_ERR_WIFI_NOT_INIT (C macro), 560 ESP_ERR_WIFI_NOT_STARTED (C macro), 560 ESP_ERR_WIFI_NOT_STOPPED (C macro), 560 ESP_ERR_WIFI_NVS (C macro), 561 ESP_ERR_WIFI_PASSWORD (C macro), 561 ESP_ERR_WIFI_POST (C macro), 561 ESP_ERR_WIFI_SSID (C macro), 561 ESP_ERR_WIFI_STATE (C macro), 560 ESP_ERR_WIFI_STOP_STATE (C macro), 561 ESP_ERR_WIFI_TIMEOUT (C macro), 561 ESP_ERR_WIFI_TX_DISALLOW (C macro), 561 ESP_ERR_WIFI_WAKE_FAIL (C macro), 561 ESP_ERR_WIFI_WOULD_BLOCK (C macro), 561 ESP_ERR_WOLFSSL_CERT_VERIFY_SETUP_FAILED (C macro), 95 ESP_ERR_WOLFSSL_CTX_SETUP_FAILED (C macro), 95 ESP_ERR_WOLFSSL_KEY_VERIFY_SETUP_FAILED (C macro), 95 ESP_ERR_WOLFSSL_SSL_CONF_ALPN_PROTOCOLS_FAILED (C macro), 95 ESP_ERR_WOLFSSL_SSL_HANDSHAKE_FAILED (C macro), 95 ESP_ERR_WOLFSSL_SSL_SET_HOSTNAME_FAILED (C macro), 95 ESP_ERR_WOLFSSL_SSL_SETUP_FAILED (C macro), 95 ESP_ERR_WOLFSSL_SSL_WRITE_FAILED (C macro), 95 ESP_ERROR_CHECK (C macro), 1377 ESP_ERROR_CHECK_WITHOUT_ABORT (C macro), 1377 esp_esptouch_set_timeout (C++ function), 543 esp_eth_config_t (C++ class), 595 esp_eth_config_t::check_link_period_ms (C++ member), 595 esp_eth_config_t::mac (C++ member), 595 esp_eth_config_t::on_lowlevel_deinit_done (C++ member), 596 Espressif Systems 2154 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_eth_config_t::on_lowlevel_init_doneesp_eth_mediator_t (C++ type), 599 (C++ member), 596 esp_eth_netif_glue_handle_t (C++ type), esp_eth_config_t::phy (C++ member), 595 609 esp_eth_config_t::read_phy_reg (C++ esp_eth_new_netif_glue (C++ function), 609 member), 596 ESP_ETH_PHY_ADDR_AUTO (C macro), 608 esp_eth_config_t::stack_input (C++ ESP_ETH_PHY_AUTONEGO_DIS (C++ enumerator), member), 595 608 esp_eth_config_t::write_phy_reg (C++ ESP_ETH_PHY_AUTONEGO_EN (C++ enumerator), member), 596 608 esp_eth_decrease_reference (C++ function), ESP_ETH_PHY_AUTONEGO_G_STAT (C++ enumer- 595 ator), 608 esp_eth_del_netif_glue (C++ function), 609 ESP_ETH_PHY_AUTONEGO_RESTART (C++ enu- esp_eth_detect_phy_addr (C++ function), 598 merator), 608 esp_eth_driver_install (C++ function), 593 esp_eth_phy_new_dp83848 (C++ function), 605 esp_eth_driver_uninstall (C++ function), esp_eth_phy_new_ip101 (C++ function), 604 593 esp_eth_phy_new_ksz80xx (C++ function), 605 esp_eth_handle_t (C++ type), 597 esp_eth_phy_new_lan87xx (C++ function), 605 esp_eth_increase_reference (C++ function), esp_eth_phy_new_rtl8201 (C++ function), 605 595 esp_eth_phy_s (C++ class), 605 esp_eth_io_cmd_t (C++ enum), 597 esp_eth_phy_s::advertise_pause_ability esp_eth_ioctl (C++ function), 594 (C++ member), 607 esp_eth_mac_s (C++ class), 600 esp_eth_phy_s::autonego_ctrl (C++ mem- esp_eth_mac_s::deinit (C++ member), 600 ber), 606 esp_eth_mac_s::del (C++ member), 603 esp_eth_phy_s::deinit (C++ member), 606 esp_eth_mac_s::enable_flow_ctrl (C++ esp_eth_phy_s::del (C++ member), 608 member), 603 esp_eth_phy_s::get_addr (C++ member), 607 esp_eth_mac_s::get_addr (C++ member), 602 esp_eth_phy_s::get_link (C++ member), 606 esp_eth_mac_s::init (C++ member), 600 esp_eth_phy_s::init (C++ member), 606 esp_eth_mac_s::read_phy_reg (C++ mem- esp_eth_phy_s::loopback (C++ member), 607 ber), 601 esp_eth_phy_s::pwrctl (C++ member), 606 esp_eth_mac_s::receive (C++ member), 601 esp_eth_phy_s::reset (C++ member), 605 esp_eth_mac_s::set_addr (C++ member), 602 esp_eth_phy_s::reset_hw (C++ member), 606 esp_eth_mac_s::set_duplex (C++ member), esp_eth_phy_s::set_addr (C++ member), 607 602 esp_eth_phy_s::set_duplex (C++ member), esp_eth_mac_s::set_link (C++ member), 602 607 esp_eth_mac_s::set_mediator (C++ mem- esp_eth_phy_s::set_mediator (C++ mem- ber), 600 ber), 605 esp_eth_mac_s::set_peer_pause_ability esp_eth_phy_s::set_speed (C++ member), (C++ member), 603 607 esp_eth_mac_s::set_promiscuous (C++ esp_eth_phy_t (C++ type), 608 member), 602 esp_eth_receive (C++ function), 594 esp_eth_mac_s::set_speed (C++ member), esp_eth_start (C++ function), 593 602 esp_eth_state_t (C++ enum), 599 esp_eth_mac_s::start (C++ member), 600 esp_eth_stop (C++ function), 593 esp_eth_mac_s::stop (C++ member), 600 esp_eth_transmit (C++ function), 594 esp_eth_mac_s::transmit (C++ member), 601 esp_eth_update_input_path (C++ function), esp_eth_mac_s::write_phy_reg (C++ mem- 593 ber), 601 ESP_EVENT_ANY_BASE (C macro), 1393 esp_eth_mac_t (C++ type), 604 ESP_EVENT_ANY_ID (C macro), 1393 esp_eth_mediator_s (C++ class), 598 ESP_EVENT_DECLARE_BASE (C macro), 1393 esp_eth_mediator_s::on_state_changed ESP_EVENT_DEFINE_BASE (C macro), 1393 (C++ member), 598 esp_event_dump (C++ function), 1391 esp_eth_mediator_s::phy_reg_read (C++ esp_event_handler_instance_register member), 598 (C++ function), 1388 esp_eth_mediator_s::phy_reg_write esp_event_handler_instance_register_with (C++ member), 598 (C++ function), 1387 esp_eth_mediator_s::stack_input (C++ esp_event_handler_instance_t (C++ type), member), 598 1393 Espressif Systems 2155 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_event_handler_instance_unregister ator), 1314 (C++ function), 1390 ESP_FLASH_ENC_MODE_RELEASE (C++ enumera- esp_event_handler_instance_unregister_with tor), 1314 (C++ function), 1389 esp_flash_enc_mode_t (C++ enum), 1314 esp_event_handler_register (C++ function), esp_flash_encrypt_check_and_update 1386 (C++ function), 1313 esp_event_handler_register_with (C++ esp_flash_encrypt_region (C++ function), function), 1387 1313 esp_event_handler_t (C++ type), 1393 esp_flash_encryption_enable_secure_features esp_event_handler_unregister (C++ func- (C++ function), 1314 tion), 1388 esp_flash_encryption_enabled (C++ func- esp_event_handler_unregister_with tion), 1313 (C++ function), 1389 esp_flash_encryption_init_checks (C++ esp_event_isr_post (C++ function), 1391 function), 1314 esp_event_isr_post_to (C++ function), 1391 esp_flash_encryption_set_release_mode esp_event_loop_args_t (C++ class), 1392 (C++ function), 1314 esp_event_loop_args_t::queue_size esp_flash_erase_chip (C++ function), 1292 (C++ member), 1392 esp_flash_erase_region (C++ function), 1292 esp_event_loop_args_t::task_core_id esp_flash_get_chip_write_protect (C++ (C++ member), 1392 function), 1292 esp_event_loop_args_t::task_name (C++ esp_flash_get_protectable_regions member), 1392 (C++ function), 1293 esp_event_loop_args_t::task_priority esp_flash_get_protected_region (C++ (C++ member), 1392 function), 1293 esp_event_loop_args_t::task_stack_size esp_flash_get_size (C++ function), 1291 (C++ member), 1392 esp_flash_init (C++ function), 1291 esp_event_loop_create (C++ function), 1385 esp_flash_io_mode_t (C++ enum), 1305 esp_event_loop_create_default (C++ func- esp_flash_is_quad_mode (C++ function), 1294 tion), 1386 esp_flash_os_functions_t (C++ class), 1295 esp_event_loop_delete (C++ function), 1386 esp_flash_os_functions_t::check_yield esp_event_loop_delete_default (C++ func- (C++ member), 1295 tion), 1386 esp_flash_os_functions_t::delay_us esp_event_loop_handle_t (C++ type), 1393 (C++ member), 1295 esp_event_loop_run (C++ function), 1386 esp_flash_os_functions_t::end (C++ esp_event_post (C++ function), 1390 member), 1295 esp_event_post_to (C++ function), 1390 esp_flash_os_functions_t::get_system_time ESP_EXECUTE_EXPRESSION_WITH_STACK (C (C++ member), 1295 macro), 1345 esp_flash_os_functions_t::get_temp_buffer esp_execute_shared_stack_function (C++ member), 1295 (C++ function), 1345 esp_flash_os_functions_t::region_protected ESP_EXT1_WAKEUP_ALL_LOW (C++ enumerator), (C++ member), 1295 1608 esp_flash_os_functions_t::release_temp_buffer ESP_EXT1_WAKEUP_ANY_HIGH (C++ enumerator), (C++ member), 1295 1608 esp_flash_os_functions_t::start (C++ ESP_FAIL (C macro), 1376 member), 1295 esp_fill_random (C++ function), 1600 esp_flash_os_functions_t::yield (C++ ESP_FLASH_10MHZ (C++ enumerator), 1305 member), 1295 ESP_FLASH_120MHZ (C++ enumerator), 1305 esp_flash_read (C++ function), 1293 ESP_FLASH_20MHZ (C++ enumerator), 1305 esp_flash_read_encrypted (C++ function), ESP_FLASH_26MHZ (C++ enumerator), 1305 1294 ESP_FLASH_40MHZ (C++ enumerator), 1305 esp_flash_read_id (C++ function), 1291 ESP_FLASH_5MHZ (C++ enumerator), 1305 esp_flash_read_unique_chip_id (C++ func- ESP_FLASH_80MHZ (C++ enumerator), 1305 tion), 1292 esp_flash_chip_driver_initialized esp_flash_region_t (C++ class), 1295 (C++ function), 1291 esp_flash_region_t::offset (C++ member), ESP_FLASH_ENC_MODE_DEVELOPMENT (C++ 1295 enumerator), 1314 esp_flash_region_t::size (C++ member), ESP_FLASH_ENC_MODE_DISABLED (C++ enumer- 1295 Espressif Systems 2156 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_flash_set_chip_write_protect (C++ (C++ enumerator), 223 function), 1292 esp_gap_ble_channels (C++ type), 220 esp_flash_set_protected_region (C++ ESP_GAP_BLE_CHANNELS_LEN (C macro), 219 function), 1293 ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT ESP_FLASH_SPEED_MAX (C++ enumerator), 1305 (C++ enumerator), 222 ESP_FLASH_SPEED_MIN (C macro), 1305 ESP_GAP_BLE_EVT_MAX (C++ enumerator), 223 esp_flash_speed_t (C++ enum), 1305 ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT esp_flash_spi_device_config_t (C++ (C++ enumerator), 222 class), 1290 ESP_GAP_BLE_EXT_ADV_REPORT_EVT (C++ esp_flash_spi_device_config_t::cs_id enumerator), 222 (C++ member), 1291 ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT esp_flash_spi_device_config_t::cs_io_num (C++ enumerator), 222 (C++ member), 1291 ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT esp_flash_spi_device_config_t::host_id (C++ enumerator), 222 (C++ member), 1291 ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT esp_flash_spi_device_config_t::input_delay_ns (C++ enumerator), 222 (C++ member), 1291 ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT esp_flash_spi_device_config_t::io_mode (C++ enumerator), 222 (C++ member), 1291 ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT esp_flash_spi_device_config_t::speed (C++ enumerator), 222 (C++ member), 1291 ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT esp_flash_t (C++ class), 1295 (C++ enumerator), 222 esp_flash_t (C++ type), 1296 ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT esp_flash_t::busy (C++ member), 1296 (C++ enumerator), 222 esp_flash_t::chip_drv (C++ member), 1296 ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT esp_flash_t::chip_id (C++ member), 1296 (C++ enumerator), 222 esp_flash_t::host (C++ member), 1296 ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT esp_flash_t::os_func (C++ member), 1296 (C++ enumerator), 222 esp_flash_t::os_func_data (C++ member), ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT 1296 (C++ enumerator), 222 esp_flash_t::read_mode (C++ member), 1296 ESP_GAP_BLE_KEY_EVT (C++ enumerator), 221 esp_flash_t::reserved_flags (C++ mem- ESP_GAP_BLE_LOCAL_ER_EVT (C++ enumerator), ber), 1296 221 esp_flash_t::size (C++ member), 1296 ESP_GAP_BLE_LOCAL_IR_EVT (C++ enumerator), esp_flash_write (C++ function), 1294 221 esp_flash_write_encrypted (C++ function), ESP_GAP_BLE_NC_REQ_EVT (C++ enumerator), 1294 221 esp_flash_write_protect_crypt_cnt ESP_GAP_BLE_OOB_REQ_EVT (C++ enumerator), (C++ function), 1313 221 esp_freertos_idle_cb_t (C++ type), 1514 ESP_GAP_BLE_PASSKEY_NOTIF_EVT (C++ enu- esp_freertos_tick_cb_t (C++ type), 1514 merator), 221 ESP_GAP_BLE_ADD_WHITELIST_COMPLETE_EVT ESP_GAP_BLE_PASSKEY_REQ_EVT (C++ enumer- (C macro), 219 ator), 221 ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EEVSTP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT (C++ enumerator), 221 (C++ enumerator), 222 ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT (C++ enumerator), 221 (C++ enumerator), 222 ESP_GAP_BLE_ADV_START_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT (C++ enumerator), 221 (C++ enumerator), 222 ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT (C++ enumerator), 221 (C++ enumerator), 222 ESP_GAP_BLE_ADV_TERMINATED_EVT (C++ ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT enumerator), 223 (C++ enumerator), 222 ESP_GAP_BLE_AUTH_CMPL_EVT (C++ enumera- ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT tor), 221 (C++ enumerator), 223 esp_gap_ble_cb_event_t (C++ enum), 221 ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT esp_gap_ble_cb_t (C++ type), 220 (C++ enumerator), 222 ESP_GAP_BLE_CHANNEL_SELETE_ALGORITHM_EVETSP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT Espressif Systems 2157 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ enumerator), 222 (C++ enumerator), 221 ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EESVPT_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COM (C++ enumerator), 222 (C++ enumerator), 222 ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COEMSPPL_EGTAEP__EBVLTE_UPDATE_WHITELIST_COMPLETE_EVT (C++ enumerator), 222 (C++ enumerator), 222 ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVTesp_gap_conn_params_t (C++ class), 208 (C++ enumerator), 223 esp_gap_conn_params_t::interval (C++ ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT member), 209 (C++ enumerator), 223 esp_gap_conn_params_t::latency (C++ ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLEmTeEm_bEerV)T, 209 (C++ enumerator), 222 esp_gap_conn_params_t::timeout (C++ ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT member), 209 (C++ enumerator), 222 ESP_GAP_SEARCH_DI_DISC_CMPL_EVT (C++ ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETenEu_mEeVrTator), 226 (C++ enumerator), 222 ESP_GAP_SEARCH_DISC_BLE_RES_EVT (C++ ESP_GAP_BLE_READ_PHY_COMPLETE_EVT enumerator), 226 (C++ enumerator), 222 ESP_GAP_SEARCH_DISC_CMPL_EVT (C++ enu- ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT merator), 226 (C++ enumerator), 222 ESP_GAP_SEARCH_DISC_RES_EVT (C++ enumer- ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT ator), 226 (C++ enumerator), 221 esp_gap_search_evt_t (C++ enum), 226 ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVTESP_GAP_SEARCH_INQ_CMPL_EVT (C++ enumer- (C++ enumerator), 221 ator), 226 ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT ESP_GAP_SEARCH_INQ_DISCARD_NUM_EVT (C++ enumerator), 223 (C++ enumerator), 226 ESP_GAP_BLE_SCAN_RESULT_EVT (C++ enumer- ESP_GAP_SEARCH_INQ_RES_EVT (C++ enumera- ator), 221 tor), 226 ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLEESTPE__GEAVPT_SEARCH_SEARCH_CANCEL_CMPL_EVT (C++ enumerator), 221 (C++ enumerator), 226 ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EESVPT_GATT_ALREADY_OPEN (C++ enumerator), 236 (C++ enumerator), 221 ESP_GATT_APP_RSP (C++ enumerator), 236 ESP_GAP_BLE_SCAN_START_COMPLETE_EVT ESP_GATT_ATTR_HANDLE_MAX (C macro), 234 (C++ enumerator), 221 ESP_GATT_AUTH_FAIL (C++ enumerator), 236 ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT ESP_GATT_AUTH_REQ_MITM (C++ enumerator), (C++ enumerator), 221 237 ESP_GAP_BLE_SCAN_TIMEOUT_EVT (C++ enu- ESP_GATT_AUTH_REQ_NO_MITM (C++ enumera- merator), 222 tor), 237 ESP_GAP_BLE_SEC_REQ_EVT (C++ enumerator), ESP_GATT_AUTH_REQ_NONE (C++ enumerator), 221 237 esp_gap_ble_set_authorization (C++ func- ESP_GATT_AUTH_REQ_SIGNED_MITM (C++ enu- tion), 189 merator), 237 esp_gap_ble_set_channels (C++ function), ESP_GATT_AUTH_REQ_SIGNED_NO_MITM (C++ 189 enumerator), 237 ESP_GAP_BLE_SET_CHANNELS_EVT (C++ enu- esp_gatt_auth_req_t (C++ enum), 237 merator), 222 ESP_GATT_AUTO_RSP (C macro), 235 ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETEES_PE_VGTATT_BODY_SENSOR_LOCATION (C macro), (C++ enumerator), 222 234 ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EESVPT_GATT_BUSY (C++ enumerator), 236 (C++ enumerator), 221 ESP_GATT_CANCEL (C++ enumerator), 236 ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVTESP_GATT_CCC_CFG_ERR (C++ enumerator), 236 (C++ enumerator), 221 ESP_GATT_CHAR_PROP_BIT_AUTH (C macro), ESP_GAP_BLE_SET_PREFERED_DEFAULT_PHY_COMPLETE_2E35VT (C++ enumerator), 222 ESP_GATT_CHAR_PROP_BIT_BROADCAST (C ESP_GAP_BLE_SET_PREFERED_PHY_COMPLETE_EVT macro), 234 (C++ enumerator), 222 ESP_GATT_CHAR_PROP_BIT_EXT_PROP (C ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT macro), 235 (C++ enumerator), 221 ESP_GATT_CHAR_PROP_BIT_INDICATE (C ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT macro), 235 Espressif Systems 2158 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_GATT_CHAR_PROP_BIT_NOTIFY (C macro), 235 ESP_GATT_CHAR_PROP_BIT_READ (C macro), 235 ESP_GATT_CHAR_PROP_BIT_WRITE (C macro), 235 ESP_GATT_CHAR_PROP_BIT_WRITE_NR (C macro), 235 esp_gatt_char_prop_t (C++ type), 235 ESP_GATT_CMD_STARTED (C++ enumerator), 236 ESP_GATT_CONGESTED (C++ enumerator), 236 ESP_GATT_CONN_CONN_CANCEL (C++ enumera- tor), 237 ESP_GATT_CONN_FAIL_ESTABLISH (C++ enu- merator), 237 ESP_GATT_CONN_L2C_FAILURE (C++ enumera- tor), 236 ESP_GATT_CONN_LMP_TIMEOUT (C++ enumera- tor), 237 ESP_GATT_CONN_NONE (C++ enumerator), 237 esp_gatt_conn_params_t (C++ class), 230 esp_gatt_conn_params_t::interval (C++ member), 230 esp_gatt_conn_params_t::latency (C++ member), 230 esp_gatt_conn_params_t::timeout (C++ member), 230 esp_gatt_conn_reason_t (C++ enum), 236 ESP_GATT_CONN_TERMINATE_LOCAL_HOST (C++ enumerator), 237 ESP_GATT_CONN_TERMINATE_PEER_USER (C++ enumerator), 237 ESP_GATT_CONN_TIMEOUT (C++ enumerator), 236 ESP_GATT_CONN_UNKNOWN (C++ enumerator), 236 ESP_GATT_DB_ALL (C++ enumerator), 238 esp_gatt_db_attr_type_t (C++ enum), 237 ESP_GATT_DB_CHARACTERISTIC (C++ enumera- tor), 237 ESP_GATT_DB_DESCRIPTOR (C++ enumerator), 237 ESP_GATT_DB_FULL (C++ enumerator), 236 ESP_GATT_DB_INCLUDED_SERVICE (C++ enu- merator), 238 ESP_GATT_DB_PRIMARY_SERVICE (C++ enumer- ator), 237 ESP_GATT_DB_SECONDARY_SERVICE (C++ enu- merator), 237 ESP_GATT_DUP_REG (C++ enumerator), 236 ESP_GATT_ENCRYPED_MITM (C++ enumerator), 236 ESP_GATT_ENCRYPED_NO_MITM (C++ enumera- tor), 236 ESP_GATT_ERR_UNLIKELY (C++ enumerator), 236 ESP_GATT_ERROR (C++ enumerator), 236 ESP_GATT_HEART_RATE_CNTL_POINT (C macro), 234 ESP_GATT_HEART_RATE_MEAS (C macro), 234 esp_gatt_id_t (C++ class), 228 esp_gatt_id_t::inst_id (C++ member), 228 esp_gatt_id_t::uuid (C++ member), 228 ESP_GATT_IF_NONE (C macro), 235 esp_gatt_if_t (C++ type), 235 ESP_GATT_ILLEGAL_HANDLE (C macro), 234 ESP_GATT_ILLEGAL_PARAMETER (C++ enumera- tor), 236 ESP_GATT_ILLEGAL_UUID (C macro), 234 ESP_GATT_INSUF_AUTHENTICATION (C++ enu- merator), 235 ESP_GATT_INSUF_AUTHORIZATION (C++ enu- merator), 235 ESP_GATT_INSUF_ENCRYPTION (C++ enumera- tor), 236 ESP_GATT_INSUF_KEY_SIZE (C++ enumerator), 236 ESP_GATT_INSUF_RESOURCE (C++ enumerator), 236 ESP_GATT_INTERNAL_ERROR (C++ enumerator), 236 ESP_GATT_INVALID_ATTR_LEN (C++ enumera- tor), 236 ESP_GATT_INVALID_CFG (C++ enumerator), 236 ESP_GATT_INVALID_HANDLE (C++ enumerator), 235 ESP_GATT_INVALID_OFFSET (C++ enumerator), 235 ESP_GATT_INVALID_PDU (C++ enumerator), 235 ESP_GATT_MAX_ATTR_LEN (C macro), 235 ESP_GATT_MAX_READ_MULTI_HANDLES (C macro), 234 ESP_GATT_MORE (C++ enumerator), 236 ESP_GATT_NO_RESOURCES (C++ enumerator), 236 ESP_GATT_NOT_ENCRYPTED (C++ enumerator), 236 ESP_GATT_NOT_FOUND (C++ enumerator), 235 ESP_GATT_NOT_LONG (C++ enumerator), 235 ESP_GATT_OK (C++ enumerator), 235 ESP_GATT_OUT_OF_RANGE (C++ enumerator), 236 ESP_GATT_PENDING (C++ enumerator), 236 ESP_GATT_PERM_READ (C macro), 234 ESP_GATT_PERM_READ_AUTHORIZATION (C macro), 234 ESP_GATT_PERM_READ_ENC_MITM (C macro), 234 ESP_GATT_PERM_READ_ENCRYPTED (C macro), 234 esp_gatt_perm_t (C++ type), 235 ESP_GATT_PERM_WRITE (C macro), 234 ESP_GATT_PERM_WRITE_AUTHORIZATION (C macro), 234 ESP_GATT_PERM_WRITE_ENC_MITM (C macro), 234 ESP_GATT_PERM_WRITE_ENCRYPTED (C macro), 234 ESP_GATT_PERM_WRITE_SIGNED (C macro), 234 ESP_GATT_PERM_WRITE_SIGNED_MITM (C macro), 234 Espressif Systems 2159 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_GATT_PRC_IN_PROGRESS (C++ enumerator), 236 ESP_GATT_PREP_WRITE_CANCEL (C macro), 248 ESP_GATT_PREP_WRITE_CANCEL (C++ enumera- tor), 235 ESP_GATT_PREP_WRITE_EXEC (C macro), 248 ESP_GATT_PREP_WRITE_EXEC (C++ enumerator), 235 esp_gatt_prep_write_type (C++ enum), 235 ESP_GATT_PREPARE_Q_FULL (C++ enumerator), 235 ESP_GATT_READ_NOT_PERMIT (C++ enumerator), 235 ESP_GATT_REQ_NOT_SUPPORTED (C++ enumera- tor), 235 ESP_GATT_RSP_BY_APP (C macro), 235 esp_gatt_rsp_t (C++ union), 227 esp_gatt_rsp_t::attr_value (C++ member), 228 esp_gatt_rsp_t::handle (C++ member), 228 ESP_GATT_SERVICE_FROM_NVS_FLASH (C++ enumerator), 237 ESP_GATT_SERVICE_FROM_REMOTE_DEVICE (C++ enumerator), 237 ESP_GATT_SERVICE_FROM_UNKNOWN (C++ enu- merator), 237 ESP_GATT_SERVICE_STARTED (C++ enumerator), 236 esp_gatt_srvc_id_t (C++ class), 228 esp_gatt_srvc_id_t::id (C++ member), 228 esp_gatt_srvc_id_t::is_primary (C++ member), 228 ESP_GATT_STACK_RSP (C++ enumerator), 236 esp_gatt_status_t (C++ enum), 235 ESP_GATT_UNKNOWN_ERROR (C++ enumerator), 236 ESP_GATT_UNSUPPORT_GRP_TYPE (C++ enumer- ator), 236 ESP_GATT_UUID_ALERT_LEVEL (C macro), 233 ESP_GATT_UUID_ALERT_NTF_SVC (C macro), 232 ESP_GATT_UUID_ALERT_STATUS (C macro), 233 ESP_GATT_UUID_Automation_IO_SVC (C macro), 232 ESP_GATT_UUID_BATTERY_LEVEL (C macro), 234 ESP_GATT_UUID_BATTERY_SERVICE_SVC (C macro), 232 ESP_GATT_UUID_BLOOD_PRESSURE_SVC (C macro), 232 ESP_GATT_UUID_BODY_COMPOSITION (C macro), 232 ESP_GATT_UUID_BOND_MANAGEMENT_SVC (C macro), 232 ESP_GATT_UUID_CHAR_AGG_FORMAT (C macro), 233 ESP_GATT_UUID_CHAR_CLIENT_CONFIG (C macro), 232 ESP_GATT_UUID_CHAR_DECLARE (C macro), 232 ESP_GATT_UUID_CHAR_DESCRIPTION (C macro), 232 ESP_GATT_UUID_CHAR_EXT_PROP (C macro), 232 ESP_GATT_UUID_CHAR_PRESENT_FORMAT (C macro), 232 ESP_GATT_UUID_CHAR_SRVR_CONFIG (C macro), 232 ESP_GATT_UUID_CHAR_VALID_RANGE (C macro), 233 ESP_GATT_UUID_CONT_GLUCOSE_MONITOR_SVC (C macro), 232 ESP_GATT_UUID_CSC_FEATURE (C macro), 234 ESP_GATT_UUID_CSC_MEASUREMENT (C macro), 234 ESP_GATT_UUID_CURRENT_TIME (C macro), 233 ESP_GATT_UUID_CURRENT_TIME_SVC (C macro), 232 ESP_GATT_UUID_CYCLING_POWER_SVC (C macro), 232 ESP_GATT_UUID_CYCLING_SPEED_CADENCE_SVC (C macro), 232 ESP_GATT_UUID_DEVICE_INFO_SVC (C macro), 232 ESP_GATT_UUID_ENV_SENSING_CONFIG_DESCR (C macro), 233 ESP_GATT_UUID_ENV_SENSING_MEASUREMENT_DESCR (C macro), 233 ESP_GATT_UUID_ENV_SENSING_TRIGGER_DESCR (C macro), 233 ESP_GATT_UUID_ENVIRONMENTAL_SENSING_SVC (C macro), 232 ESP_GATT_UUID_EXT_RPT_REF_DESCR (C macro), 233 ESP_GATT_UUID_FW_VERSION_STR (C macro), 233 ESP_GATT_UUID_GAP_CENTRAL_ADDR_RESOL (C macro), 233 ESP_GATT_UUID_GAP_DEVICE_NAME (C macro), 233 ESP_GATT_UUID_GAP_ICON (C macro), 233 ESP_GATT_UUID_GAP_PREF_CONN_PARAM (C macro), 233 ESP_GATT_UUID_GATT_SRV_CHGD (C macro), 233 ESP_GATT_UUID_GLUCOSE_SVC (C macro), 232 ESP_GATT_UUID_GM_CONTEXT (C macro), 233 ESP_GATT_UUID_GM_CONTROL_POINT (C macro), 233 ESP_GATT_UUID_GM_FEATURE (C macro), 233 ESP_GATT_UUID_GM_MEASUREMENT (C macro), 233 ESP_GATT_UUID_HEALTH_THERMOM_SVC (C macro), 232 ESP_GATT_UUID_HEART_RATE_SVC (C macro), 232 ESP_GATT_UUID_HID_BT_KB_INPUT (C macro), Espressif Systems 2160 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index 234 234 ESP_GATT_UUID_HID_BT_KB_OUTPUT (C ESP_GATT_UUID_SCAN_PARAMETERS_SVC (C macro), 234 macro), 232 ESP_GATT_UUID_HID_BT_MOUSE_INPUT (C ESP_GATT_UUID_SCAN_REFRESH (C macro), 234 macro), 234 ESP_GATT_UUID_SEC_SERVICE (C macro), 232 ESP_GATT_UUID_HID_CONTROL_POINT (C ESP_GATT_UUID_SENSOR_LOCATION (C macro), macro), 234 234 ESP_GATT_UUID_HID_INFORMATION (C macro), ESP_GATT_UUID_SERIAL_NUMBER_STR (C 233 macro), 233 ESP_GATT_UUID_HID_PROTO_MODE (C macro), ESP_GATT_UUID_SW_VERSION_STR (C macro), 234 233 ESP_GATT_UUID_HID_REPORT (C macro), 234 ESP_GATT_UUID_SYSTEM_ID (C macro), 233 ESP_GATT_UUID_HID_REPORT_MAP (C macro), ESP_GATT_UUID_TIME_TRIGGER_DESCR (C 234 macro), 233 ESP_GATT_UUID_HID_SVC (C macro), 232 ESP_GATT_UUID_TX_POWER_LEVEL (C macro), ESP_GATT_UUID_HW_VERSION_STR (C macro), 233 233 ESP_GATT_UUID_TX_POWER_SVC (C macro), 232 ESP_GATT_UUID_IEEE_DATA (C macro), 233 ESP_GATT_UUID_USER_DATA_SVC (C macro), ESP_GATT_UUID_IMMEDIATE_ALERT_SVC (C 232 macro), 232 ESP_GATT_UUID_VALUE_TRIGGER_DESCR (C ESP_GATT_UUID_INCLUDE_SERVICE (C macro), macro), 233 232 ESP_GATT_UUID_WEIGHT_SCALE_SVC (C ESP_GATT_UUID_LINK_LOSS_SVC (C macro), macro), 232 232 esp_gatt_value_t (C++ class), 229 ESP_GATT_UUID_LOCAL_TIME_INFO (C macro), esp_gatt_value_t::auth_req (C++ member), 233 230 ESP_GATT_UUID_LOCATION_AND_NAVIGATION_SeVsCp_gatt_value_t::handle (C++ member), (C macro), 232 230 ESP_GATT_UUID_MANU_NAME (C macro), 233 esp_gatt_value_t::len (C++ member), 230 ESP_GATT_UUID_MODEL_NUMBER_STR (C esp_gatt_value_t::offset (C++ member), macro), 233 230 ESP_GATT_UUID_NEXT_DST_CHANGE_SVC (C esp_gatt_value_t::value (C++ member), 230 macro), 232 ESP_GATT_WRITE_NOT_PERMIT (C++ enumera- ESP_GATT_UUID_NUM_DIGITALS_DESCR (C tor), 235 macro), 233 ESP_GATT_WRITE_TYPE_NO_RSP (C++ enumera- ESP_GATT_UUID_NW_STATUS (C macro), 233 tor), 237 ESP_GATT_UUID_NW_TRIGGER (C macro), 233 ESP_GATT_WRITE_TYPE_RSP (C++ enumerator), ESP_GATT_UUID_PHONE_ALERT_STATUS_SVC 237 (C macro), 232 esp_gatt_write_type_t (C++ enum), 237 ESP_GATT_UUID_PNP_ID (C macro), 233 ESP_GATT_WRONG_STATE (C++ enumerator), 236 ESP_GATT_UUID_PRI_SERVICE (C macro), 232 ESP_GATTC_ACL_EVT (C++ enumerator), 264 ESP_GATT_UUID_REF_TIME_INFO (C macro), ESP_GATTC_ADV_DATA_EVT (C++ enumerator), 233 265 ESP_GATT_UUID_REF_TIME_UPDATE_SVC (C ESP_GATTC_ADV_VSC_EVT (C++ enumerator), 265 macro), 232 ESP_GATTC_BTH_SCAN_CFG_EVT (C++ enumera- ESP_GATT_UUID_RINGER_CP (C macro), 233 tor), 265 ESP_GATT_UUID_RINGER_SETTING (C macro), ESP_GATTC_BTH_SCAN_DIS_EVT (C++ enumera- 233 tor), 265 ESP_GATT_UUID_RPT_REF_DESCR (C macro), ESP_GATTC_BTH_SCAN_ENB_EVT (C++ enumera- 233 tor), 265 ESP_GATT_UUID_RSC_FEATURE (C macro), 234 ESP_GATTC_BTH_SCAN_PARAM_EVT (C++ enu- ESP_GATT_UUID_RSC_MEASUREMENT (C macro), merator), 265 234 ESP_GATTC_BTH_SCAN_RD_EVT (C++ enumera- ESP_GATT_UUID_RUNNING_SPEED_CADENCE_SVC tor), 265 (C macro), 232 ESP_GATTC_BTH_SCAN_THR_EVT (C++ enumera- ESP_GATT_UUID_SC_CONTROL_POINT (C tor), 265 macro), 234 ESP_GATTC_CANCEL_OPEN_EVT (C++ enumera- ESP_GATT_UUID_SCAN_INT_WINDOW (C macro), tor), 264 Espressif Systems 2161 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_gattc_cb_event_t (C++ enum), 264 esp_gattc_multi_t::handles (C++ member), esp_gattc_cb_t (C++ type), 264 230 ESP_GATTC_CFG_MTU_EVT (C++ enumerator), 265 esp_gattc_multi_t::num_attr (C++ mem- esp_gattc_char_elem_t (C++ class), 231 ber), 230 esp_gattc_char_elem_t::char_handle ESP_GATTC_NOTIFY_EVT (C++ enumerator), 264 (C++ member), 231 ESP_GATTC_OPEN_EVT (C++ enumerator), 264 esp_gattc_char_elem_t::properties ESP_GATTC_PREP_WRITE_EVT (C++ enumerator), (C++ member), 231 264 esp_gattc_char_elem_t::uuid (C++ mem- ESP_GATTC_QUEUE_FULL_EVT (C++ enumerator), ber), 231 266 ESP_GATTC_CLOSE_EVT (C++ enumerator), 264 ESP_GATTC_READ_CHAR_EVT (C++ enumerator), ESP_GATTC_CONGEST_EVT (C++ enumerator), 265 264 ESP_GATTC_CONNECT_EVT (C++ enumerator), 265 ESP_GATTC_READ_DESCR_EVT (C++ enumerator), esp_gattc_db_elem_t (C++ class), 230 264 esp_gattc_db_elem_t::attribute_handle ESP_GATTC_READ_MULTIPLE_EVT (C++ enumer- (C++ member), 230 ator), 265 esp_gattc_db_elem_t::end_handle (C++ ESP_GATTC_REG_EVT (C++ enumerator), 264 member), 230 ESP_GATTC_REG_FOR_NOTIFY_EVT (C++ enu- esp_gattc_db_elem_t::properties (C++ merator), 265 member), 230 ESP_GATTC_SCAN_FLT_CFG_EVT (C++ enumera- esp_gattc_db_elem_t::start_handle tor), 265 (C++ member), 230 ESP_GATTC_SCAN_FLT_PARAM_EVT (C++ enu- esp_gattc_db_elem_t::type (C++ member), merator), 265 230 ESP_GATTC_SCAN_FLT_STATUS_EVT (C++ enu- esp_gattc_db_elem_t::uuid (C++ member), merator), 265 231 ESP_GATTC_SEARCH_CMPL_EVT (C++ enumera- esp_gattc_descr_elem_t (C++ class), 231 tor), 264 esp_gattc_descr_elem_t::handle (C++ ESP_GATTC_SEARCH_RES_EVT (C++ enumerator), member), 231 264 esp_gattc_descr_elem_t::uuid (C++ mem- esp_gattc_service_elem_t (C++ class), 231 ber), 231 esp_gattc_service_elem_t::end_handle ESP_GATTC_DIS_SRVC_CMPL_EVT (C++ enumer- (C++ member), 231 ator), 266 esp_gattc_service_elem_t::is_primary ESP_GATTC_DISCONNECT_EVT (C++ enumerator), (C++ member), 231 265 esp_gattc_service_elem_t::start_handle ESP_GATTC_ENC_CMPL_CB_EVT (C++ enumera- (C++ member), 231 tor), 265 esp_gattc_service_elem_t::uuid (C++ ESP_GATTC_EXEC_EVT (C++ enumerator), 264 member), 231 ESP_GATTC_GET_ADDR_LIST_EVT (C++ enumer- ESP_GATTC_SET_ASSOC_EVT (C++ enumerator), ator), 266 266 esp_gattc_incl_svc_elem_t (C++ class), 231 ESP_GATTC_SRVC_CHG_EVT (C++ enumerator), esp_gattc_incl_svc_elem_t::handle 264 (C++ member), 231 ESP_GATTC_UNREG_EVT (C++ enumerator), 264 esp_gattc_incl_svc_elem_t::incl_srvc_e_EhSaPn_dGlAeTTC_UNREG_FOR_NOTIFY_EVT (C++ (C++ member), 231 enumerator), 265 esp_gattc_incl_svc_elem_t::incl_srvc_s_EhSaPn_dGlAeTTC_WRITE_CHAR_EVT (C++ enumerator), (C++ member), 231 264 esp_gattc_incl_svc_elem_t::uuid (C++ ESP_GATTC_WRITE_DESCR_EVT (C++ enumera- member), 231 tor), 264 ESP_GATTC_MULT_ADV_DATA_EVT (C++ enumer- ESP_GATTS_ADD_CHAR_DESCR_EVT (C++ enu- ator), 265 merator), 249 ESP_GATTC_MULT_ADV_DIS_EVT (C++ enumera- ESP_GATTS_ADD_CHAR_EVT (C++ enumerator), tor), 265 249 ESP_GATTC_MULT_ADV_ENB_EVT (C++ enumera- ESP_GATTS_ADD_INCL_SRVC_EVT (C++ enumer- tor), 265 ator), 249 ESP_GATTC_MULT_ADV_UPD_EVT (C++ enumera- esp_gatts_attr_db_t (C++ class), 229 tor), 265 esp_gatts_attr_db_t::att_desc (C++ esp_gattc_multi_t (C++ class), 230 member), 229 Espressif Systems 2162 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_gatts_attr_db_t::attr_control ESP_GOTO_ON_ERROR_ISR (C macro), 1376 (C++ member), 229 ESP_GOTO_ON_FALSE (C macro), 1376 ESP_GATTS_CANCEL_OPEN_EVT (C++ enumera- ESP_GOTO_ON_FALSE_ISR (C macro), 1376 tor), 249 esp_hmac_calculate (C++ function), 692 esp_gatts_cb_event_t (C++ enum), 248 esp_hmac_jtag_disable (C++ function), 693 esp_gatts_cb_t (C++ type), 248 esp_hmac_jtag_enable (C++ function), 692 ESP_GATTS_CLOSE_EVT (C++ enumerator), 249 esp_http_client_add_auth (C++ function), ESP_GATTS_CONF_EVT (C++ enumerator), 249 103 ESP_GATTS_CONGEST_EVT (C++ enumerator), 249 esp_http_client_auth_type_t (C++ enum), ESP_GATTS_CONNECT_EVT (C++ enumerator), 249 108 ESP_GATTS_CREAT_ATTR_TAB_EVT (C++ enu- esp_http_client_cleanup (C++ function), 102 merator), 250 esp_http_client_close (C++ function), 102 ESP_GATTS_CREATE_EVT (C++ enumerator), 249 esp_http_client_config_t (C++ class), 104 ESP_GATTS_DELETE_EVT (C++ enumerator), 249 esp_http_client_config_t::auth_type ESP_GATTS_DISCONNECT_EVT (C++ enumerator), (C++ member), 105 249 esp_http_client_config_t::buffer_size ESP_GATTS_EXEC_WRITE_EVT (C++ enumerator), (C++ member), 105 249 esp_http_client_config_t::buffer_size_tx esp_gatts_incl128_svc_desc_t (C++ class), (C++ member), 105 229 esp_http_client_config_t::cert_len esp_gatts_incl128_svc_desc_t::end_hdl (C++ member), 105 (C++ member), 229 esp_http_client_config_t::cert_pem esp_gatts_incl128_svc_desc_t::start_hdl (C++ member), 105 (C++ member), 229 esp_http_client_config_t::client_cert_len esp_gatts_incl_svc_desc_t (C++ class), 229 (C++ member), 105 esp_gatts_incl_svc_desc_t::end_hdl esp_http_client_config_t::client_cert_pem (C++ member), 229 (C++ member), 105 esp_gatts_incl_svc_desc_t::start_hdl esp_http_client_config_t::client_key_len (C++ member), 229 (C++ member), 105 esp_gatts_incl_svc_desc_t::uuid (C++ esp_http_client_config_t::client_key_password member), 229 (C++ member), 105 ESP_GATTS_LISTEN_EVT (C++ enumerator), 249 esp_http_client_config_t::client_key_password_len ESP_GATTS_MTU_EVT (C++ enumerator), 249 (C++ member), 105 ESP_GATTS_OPEN_EVT (C++ enumerator), 249 esp_http_client_config_t::client_key_pem ESP_GATTS_READ_EVT (C++ enumerator), 249 (C++ member), 105 ESP_GATTS_REG_EVT (C++ enumerator), 249 esp_http_client_config_t::crt_bundle_attach ESP_GATTS_RESPONSE_EVT (C++ enumerator), (C++ member), 106 249 esp_http_client_config_t::disable_auto_redirect ESP_GATTS_SEND_SERVICE_CHANGE_EVT (C++ member), 105 (C++ enumerator), 250 esp_http_client_config_t::event_handler ESP_GATTS_SET_ATTR_VAL_EVT (C++ enumera- (C++ member), 105 tor), 250 esp_http_client_config_t::host (C++ ESP_GATTS_START_EVT (C++ enumerator), 249 member), 104 ESP_GATTS_STOP_EVT (C++ enumerator), 249 esp_http_client_config_t::if_name ESP_GATTS_UNREG_EVT (C++ enumerator), 249 (C++ member), 106 ESP_GATTS_WRITE_EVT (C++ enumerator), 249 esp_http_client_config_t::is_async esp_gcov_dump (C++ function), 1343 (C++ member), 105 esp_get_deep_sleep_wake_stub (C++ func- esp_http_client_config_t::keep_alive_count tion), 1608 (C++ member), 106 esp_get_flash_encryption_mode (C++ func- esp_http_client_config_t::keep_alive_enable tion), 1313 (C++ member), 106 esp_get_free_heap_size (C++ function), 1562 esp_http_client_config_t::keep_alive_idle esp_get_free_internal_heap_size (C++ (C++ member), 106 function), 1562 esp_http_client_config_t::keep_alive_interval esp_get_idf_version (C++ function), 1564 (C++ member), 106 esp_get_minimum_free_heap_size (C++ esp_http_client_config_t::max_authorization_retri function), 1563 (C++ member), 105 ESP_GOTO_ON_ERROR (C macro), 1376 esp_http_client_config_t::max_redirection_count Espressif Systems 2163 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 105 100 esp_http_client_config_t::method (C++ esp_http_client_get_header (C++ function), member), 105 99 esp_http_client_config_t::password esp_http_client_get_password (C++ func- (C++ member), 104 tion), 100 esp_http_client_config_t::path (C++ esp_http_client_get_post_field (C++ member), 105 function), 99 esp_http_client_config_t::port (C++ esp_http_client_get_status_code (C++ member), 104 function), 102 esp_http_client_config_t::query (C++ esp_http_client_get_transport_type member), 105 (C++ function), 102 esp_http_client_config_t::skip_cert_comemsopn__hntatmpe__cclhieecnkt_get_url (C++ function), 103 (C++ member), 106 esp_http_client_get_username (C++ func- esp_http_client_config_t::timeout_ms tion), 100 (C++ member), 105 esp_http_client_handle_t (C++ type), 106 esp_http_client_config_t::transport_typeesp_http_client_init (C++ function), 98 (C++ member), 105 esp_http_client_is_chunked_response esp_http_client_config_t::url (C++ (C++ function), 102 member), 104 esp_http_client_is_complete_data_received esp_http_client_config_t::use_global_ca_store (C++ function), 103 (C++ member), 106 esp_http_client_method_t (C++ enum), 107 esp_http_client_config_t::user_agent esp_http_client_open (C++ function), 101 (C++ member), 105 esp_http_client_perform (C++ function), 98 esp_http_client_config_t::user_data esp_http_client_read (C++ function), 102 (C++ member), 105 esp_http_client_read_response (C++ func- esp_http_client_config_t::username tion), 103 (C++ member), 104 esp_http_client_set_authtype (C++ func- esp_http_client_delete_header (C++ func- tion), 100 tion), 101 esp_http_client_set_header (C++ function), esp_http_client_event (C++ class), 104 99 esp_http_client_event::client (C++ esp_http_client_set_method (C++ function), member), 104 101 esp_http_client_event::data (C++ mem- esp_http_client_set_password (C++ func- ber), 104 tion), 100 esp_http_client_event::data_len (C++ esp_http_client_set_post_field (C++ member), 104 function), 99 esp_http_client_event::event_id (C++ esp_http_client_set_redirection (C++ member), 104 function), 103 esp_http_client_event::header_key esp_http_client_set_timeout_ms (C++ (C++ member), 104 function), 101 esp_http_client_event::header_value esp_http_client_set_url (C++ function), 99 (C++ member), 104 esp_http_client_set_username (C++ func- esp_http_client_event::user_data (C++ tion), 100 member), 104 esp_http_client_transport_t (C++ enum), esp_http_client_event_handle_t (C++ 107 type), 106 esp_http_client_write (C++ function), 101 esp_http_client_event_id_t (C++ enum), esp_https_ota (C++ function), 1379 107 esp_https_ota_abort (C++ function), 1380 esp_http_client_event_t (C++ type), 106 esp_https_ota_begin (C++ function), 1379 esp_http_client_fetch_headers (C++ func- esp_https_ota_config_t (C++ class), 1381 tion), 101 esp_https_ota_config_t::bulk_flash_erase esp_http_client_flush_response (C++ (C++ member), 1381 function), 103 esp_https_ota_config_t::http_client_init_cb esp_http_client_get_chunk_length (C++ (C++ member), 1381 function), 104 esp_https_ota_config_t::http_config esp_http_client_get_content_length (C++ member), 1381 (C++ function), 102 esp_https_ota_config_t::max_http_request_size esp_http_client_get_errno (C++ function), (C++ member), 1381 Espressif Systems 2164 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_https_ota_config_t::partial_http_doewsnpl_oiamdage_header_t::spi_mode (C++ mem- (C++ member), 1381 ber), 1337 esp_https_ota_finish (C++ function), 1380 esp_image_header_t::spi_pin_drv (C++ esp_https_ota_get_image_len_read (C++ member), 1337 function), 1381 esp_image_header_t::spi_size (C++ mem- esp_https_ota_get_image_size (C++ func- ber), 1337 tion), 1381 esp_image_header_t::spi_speed (C++ esp_https_ota_get_img_desc (C++ function), member), 1337 1380 esp_image_header_t::wp_pin (C++ member), esp_https_ota_handle_t (C++ type), 1382 1337 esp_https_ota_is_complete_data_receivedESP_IMAGE_MAX_SEGMENTS (C macro), 1338 (C++ function), 1380 esp_image_segment_header_t (C++ class), esp_https_ota_perform (C++ function), 1379 1337 esp_https_server_user_cb (C++ type), 156 esp_image_segment_header_t::data_len esp_https_server_user_cb_arg (C++ class), (C++ member), 1337 155 esp_image_segment_header_t::load_addr esp_https_server_user_cb_arg_t (C++ (C++ member), 1337 type), 156 esp_image_spi_freq_t (C++ enum), 1339 ESP_IDF_VERSION (C macro), 1564 ESP_IMAGE_SPI_MODE_DIO (C++ enumerator), ESP_IDF_VERSION_MAJOR (C macro), 1564 1338 ESP_IDF_VERSION_MINOR (C macro), 1564 ESP_IMAGE_SPI_MODE_DOUT (C++ enumerator), ESP_IDF_VERSION_PATCH (C macro), 1564 1339 ESP_IDF_VERSION_VAL (C macro), 1564 ESP_IMAGE_SPI_MODE_FAST_READ (C++ enu- ESP_IMAGE_FLASH_SIZE_128MB (C++ enumera- merator), 1339 tor), 1339 ESP_IMAGE_SPI_MODE_QIO (C++ enumerator), ESP_IMAGE_FLASH_SIZE_16MB (C++ enumera- 1338 tor), 1339 ESP_IMAGE_SPI_MODE_QOUT (C++ enumerator), ESP_IMAGE_FLASH_SIZE_1MB (C++ enumerator), 1338 1339 ESP_IMAGE_SPI_MODE_SLOW_READ (C++ enu- ESP_IMAGE_FLASH_SIZE_2MB (C++ enumerator), merator), 1339 1339 esp_image_spi_mode_t (C++ enum), 1338 ESP_IMAGE_FLASH_SIZE_32MB (C++ enumera- ESP_IMAGE_SPI_SPEED_20M (C++ enumerator), tor), 1339 1339 ESP_IMAGE_FLASH_SIZE_4MB (C++ enumerator), ESP_IMAGE_SPI_SPEED_26M (C++ enumerator), 1339 1339 ESP_IMAGE_FLASH_SIZE_64MB (C++ enumera- ESP_IMAGE_SPI_SPEED_40M (C++ enumerator), tor), 1339 1339 ESP_IMAGE_FLASH_SIZE_8MB (C++ enumerator), ESP_IMAGE_SPI_SPEED_80M (C++ enumerator), 1339 1339 ESP_IMAGE_FLASH_SIZE_MAX (C++ enumerator), esp_int_wdt_init (C++ function), 1658 1339 esp_intr_alloc (C++ function), 1550 esp_image_flash_size_t (C++ enum), 1339 esp_intr_alloc_intrstatus (C++ function), ESP_IMAGE_HEADER_MAGIC (C macro), 1338 1550 esp_image_header_t (C++ class), 1336 ESP_INTR_DISABLE (C macro), 1553 esp_image_header_t::chip_id (C++ mem- esp_intr_disable (C++ function), 1551 ber), 1337 esp_intr_disable_source (C++ function), esp_image_header_t::entry_addr (C++ 1552 member), 1337 ESP_INTR_ENABLE (C macro), 1553 esp_image_header_t::hash_appended esp_intr_enable (C++ function), 1552 (C++ member), 1337 esp_intr_enable_source (C++ function), 1552 esp_image_header_t::magic (C++ member), ESP_INTR_FLAG_EDGE (C macro), 1553 1337 ESP_INTR_FLAG_HIGH (C macro), 1553 esp_image_header_t::min_chip_rev (C++ ESP_INTR_FLAG_INTRDISABLED (C macro), 1553 member), 1337 ESP_INTR_FLAG_IRAM (C macro), 1553 esp_image_header_t::reserved (C++ mem- ESP_INTR_FLAG_LEVEL1 (C macro), 1552 ber), 1337 ESP_INTR_FLAG_LEVEL2 (C macro), 1552 esp_image_header_t::segment_count ESP_INTR_FLAG_LEVEL3 (C macro), 1552 (C++ member), 1337 ESP_INTR_FLAG_LEVEL4 (C macro), 1552 Espressif Systems 2165 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_INTR_FLAG_LEVEL5 (C macro), 1552 ESP_INTR_FLAG_LEVEL6 (C macro), 1552 ESP_INTR_FLAG_LEVELMASK (C macro), 1553 ESP_INTR_FLAG_LOWMED (C macro), 1553 ESP_INTR_FLAG_NMI (C macro), 1553 ESP_INTR_FLAG_SHARED (C macro), 1553 esp_intr_flags_to_level (C++ function), 1552 esp_intr_free (C++ function), 1551 esp_intr_get_cpu (C++ function), 1551 esp_intr_get_intno (C++ function), 1551 esp_intr_mark_shared (C++ function), 1550 esp_intr_noniram_disable (C++ function), 1552 esp_intr_noniram_enable (C++ function), 1552 esp_intr_reserve (C++ function), 1550 esp_intr_set_in_iram (C++ function), 1552 ESP_IO_CAP_IN (C macro), 217 ESP_IO_CAP_IO (C macro), 217 ESP_IO_CAP_KBDISP (C macro), 217 ESP_IO_CAP_NONE (C macro), 217 ESP_IO_CAP_OUT (C macro), 217 esp_ip4_addr (C++ class), 635 esp_ip4_addr1 (C macro), 635 esp_ip4_addr1_16 (C macro), 635 esp_ip4_addr2 (C macro), 635 esp_ip4_addr2_16 (C macro), 635 esp_ip4_addr3 (C macro), 635 esp_ip4_addr3_16 (C macro), 635 esp_ip4_addr4 (C macro), 635 esp_ip4_addr4_16 (C macro), 635 esp_ip4_addr_get_byte (C macro), 635 esp_ip4_addr_t (C++ type), 636 esp_ip4addr_aton (C++ function), 628 ESP_IP4ADDR_INIT (C macro), 635 esp_ip4addr_ntoa (C++ function), 628 ESP_IP4TOADDR (C macro), 635 ESP_IP4TOUINT32 (C macro), 635 esp_ip6_addr (C++ class), 635 ESP_IP6_ADDR_BLOCK1 (C macro), 635 ESP_IP6_ADDR_BLOCK2 (C macro), 635 ESP_IP6_ADDR_BLOCK3 (C macro), 635 ESP_IP6_ADDR_BLOCK4 (C macro), 635 ESP_IP6_ADDR_BLOCK5 (C macro), 635 ESP_IP6_ADDR_BLOCK6 (C macro), 635 ESP_IP6_ADDR_BLOCK7 (C macro), 635 ESP_IP6_ADDR_BLOCK8 (C macro), 635 ESP_IP6_ADDR_IS_GLOBAL (C++ enumerator), 636 ESP_IP6_ADDR_IS_IPV4_MAPPED_IPV6 (C++ enumerator), 636 ESP_IP6_ADDR_IS_LINK_LOCAL (C++ enumera- tor), 636 ESP_IP6_ADDR_IS_SITE_LOCAL (C++ enumera- tor), 636 ESP_IP6_ADDR_IS_UNIQUE_LOCAL (C++ enu- merator), 636 ESP_IP6_ADDR_IS_UNKNOWN (C++ enumerator), 636 esp_ip6_addr_t (C++ type), 636 esp_ip6_addr_type_t (C++ enum), 636 ESP_IP6ADDR_INIT (C macro), 635 esp_ip_addr_t (C++ type), 636 ESP_IPADDR_TYPE_ANY (C macro), 635 ESP_IPADDR_TYPE_V4 (C macro), 635 ESP_IPADDR_TYPE_V6 (C macro), 635 esp_ipc_call (C++ function), 1546 esp_ipc_call_blocking (C++ function), 1546 esp_ipc_func_t (C++ type), 1546 esp_ipc_isr_asm_call (C++ function), 1547 esp_ipc_isr_asm_call_blocking (C++ func- tion), 1547 esp_ipc_isr_func_t (C++ type), 1548 esp_ipc_isr_release_other_cpu (C++ func- tion), 1547 esp_ipc_isr_stall_abort (C++ function), 1547 esp_ipc_isr_stall_other_cpu (C++ func- tion), 1547 esp_ipc_isr_stall_pause (C++ function), 1547 esp_ipc_isr_stall_resume (C++ function), 1547 ESP_LCD_COLOR_SPACE_BGR (C++ enumerator), 729 ESP_LCD_COLOR_SPACE_MONOCHROME (C++ enumerator), 729 ESP_LCD_COLOR_SPACE_RGB (C++ enumerator), 729 esp_lcd_color_space_t (C++ enum), 729 esp_lcd_del_i80_bus (C++ function), 731 esp_lcd_i2c_bus_handle_t (C++ type), 734 esp_lcd_i80_bus_config_t (C++ class), 732 esp_lcd_i80_bus_config_t::bus_width (C++ member), 733 esp_lcd_i80_bus_config_t::clk_src (C++ member), 733 esp_lcd_i80_bus_config_t::data_gpio_nums (C++ member), 733 esp_lcd_i80_bus_config_t::dc_gpio_num (C++ member), 733 esp_lcd_i80_bus_config_t::max_transfer_bytes (C++ member), 733 esp_lcd_i80_bus_config_t::psram_trans_align (C++ member), 733 esp_lcd_i80_bus_config_t::sram_trans_align (C++ member), 733 esp_lcd_i80_bus_config_t::wr_gpio_num (C++ member), 733 esp_lcd_i80_bus_handle_t (C++ type), 734 esp_lcd_new_i80_bus (C++ function), 731 esp_lcd_new_panel_io_i2c (C++ function), 730 esp_lcd_new_panel_io_i80 (C++ function), 731 Espressif Systems 2166 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_lcd_new_panel_io_spi (C++ function), (C++ member), 733 730 esp_lcd_panel_io_i80_config_t::dc_data_level esp_lcd_new_panel_nt35510 (C++ function), (C++ member), 733 739 esp_lcd_panel_io_i80_config_t::dc_dummy_level esp_lcd_new_panel_ssd1306 (C++ function), (C++ member), 733 739 esp_lcd_panel_io_i80_config_t::dc_idle_level esp_lcd_new_panel_st7789 (C++ function), (C++ member), 733 739 esp_lcd_panel_io_i80_config_t::dc_levels esp_lcd_new_rgb_panel (C++ function), 736 (C++ member), 733 esp_lcd_panel_del (C++ function), 734 esp_lcd_panel_io_i80_config_t::lcd_cmd_bits esp_lcd_panel_dev_config_t (C++ class), (C++ member), 733 740 esp_lcd_panel_io_i80_config_t::lcd_param_bits esp_lcd_panel_dev_config_t::bits_per_pixel (C++ member), 733 (C++ member), 740 esp_lcd_panel_io_i80_config_t::on_color_trans_don esp_lcd_panel_dev_config_t::color_space (C++ member), 733 (C++ member), 740 esp_lcd_panel_io_i80_config_t::pclk_active_neg esp_lcd_panel_dev_config_t::reset_active_high (C++ member), 734 (C++ member), 740 esp_lcd_panel_io_i80_config_t::pclk_hz esp_lcd_panel_dev_config_t::reset_gpio_num (C++ member), 733 (C++ member), 740 esp_lcd_panel_io_i80_config_t::pclk_idle_low esp_lcd_panel_disp_off (C++ function), 736 (C++ member), 734 esp_lcd_panel_draw_bitmap (C++ function), esp_lcd_panel_io_i80_config_t::reverse_color_bits 735 (C++ member), 734 esp_lcd_panel_handle_t (C++ type), 729 esp_lcd_panel_io_i80_config_t::swap_color_bytes esp_lcd_panel_init (C++ function), 734 (C++ member), 734 esp_lcd_panel_invert_color (C++ function), esp_lcd_panel_io_i80_config_t::trans_queue_depth 735 (C++ member), 733 esp_lcd_panel_io_color_trans_done_cb_t esp_lcd_panel_io_i80_config_t::user_ctx (C++ type), 734 (C++ member), 733 esp_lcd_panel_io_del (C++ function), 730 esp_lcd_panel_io_spi_config_t (C++ esp_lcd_panel_io_event_data_t (C++ class), 731 class), 731 esp_lcd_panel_io_spi_config_t::cs_gpio_num esp_lcd_panel_io_handle_t (C++ type), 729 (C++ member), 731 esp_lcd_panel_io_i2c_config_t (C++ esp_lcd_panel_io_spi_config_t::dc_as_cmd_phase class), 732 (C++ member), 732 esp_lcd_panel_io_i2c_config_t::control_epshpa_slec_db_yptaensel_io_spi_config_t::dc_gpio_num (C++ member), 732 (C++ member), 731 esp_lcd_panel_io_i2c_config_t::dc_bit_oefsfps_eltcd_panel_io_spi_config_t::dc_low_on_data (C++ member), 732 (C++ member), 732 esp_lcd_panel_io_i2c_config_t::dc_low_oens_pd_altcad_panel_io_spi_config_t::lcd_cmd_bits (C++ member), 732 (C++ member), 732 esp_lcd_panel_io_i2c_config_t::dev_addresp_lcd_panel_io_spi_config_t::lcd_param_bits (C++ member), 732 (C++ member), 732 esp_lcd_panel_io_i2c_config_t::lcd_cmd_ebsipt_slcd_panel_io_spi_config_t::octal_mode (C++ member), 732 (C++ member), 732 esp_lcd_panel_io_i2c_config_t::lcd_paraems_pb_iltcsd_panel_io_spi_config_t::on_color_trans_don (C++ member), 732 (C++ member), 732 esp_lcd_panel_io_i2c_config_t::on_colore_stpr_alncsd__dpoanneel_io_spi_config_t::pclk_hz (C++ member), 732 (C++ member), 732 esp_lcd_panel_io_i2c_config_t::user_ctxesp_lcd_panel_io_spi_config_t::spi_mode (C++ member), 732 (C++ member), 732 esp_lcd_panel_io_i80_config_t (C++ esp_lcd_panel_io_spi_config_t::trans_queue_depth class), 733 (C++ member), 732 esp_lcd_panel_io_i80_config_t::cs_activees_ph_ilgchd_panel_io_spi_config_t::user_ctx (C++ member), 733 (C++ member), 732 esp_lcd_panel_io_i80_config_t::cs_gpio_ensupm_lcd_panel_io_tx_color (C++ function), (C++ member), 733 730 esp_lcd_panel_io_i80_config_t::dc_cmd_leesvpe_llcd_panel_io_tx_param (C++ function), Espressif Systems 2167 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index 729 esp_lcd_rgb_timing_t::pclk_hz (C++ esp_lcd_panel_mirror (C++ function), 735 member), 737 esp_lcd_panel_reset (C++ function), 734 esp_lcd_rgb_timing_t::pclk_idle_high esp_lcd_panel_set_gap (C++ function), 735 (C++ member), 738 esp_lcd_panel_swap_xy (C++ function), 735 esp_lcd_rgb_timing_t::v_res (C++ mem- esp_lcd_rgb_panel_config_t (C++ class), ber), 737 738 esp_lcd_rgb_timing_t::vsync_back_porch esp_lcd_rgb_panel_config_t::clk_src (C++ member), 738 (C++ member), 738 esp_lcd_rgb_timing_t::vsync_front_porch esp_lcd_rgb_panel_config_t::data_gpio_nums (C++ member), 738 (C++ member), 738 esp_lcd_rgb_timing_t::vsync_idle_low esp_lcd_rgb_panel_config_t::data_width (C++ member), 738 (C++ member), 738 esp_lcd_rgb_timing_t::vsync_pulse_width esp_lcd_rgb_panel_config_t::de_gpio_num (C++ member), 737 (C++ member), 738 esp_lcd_spi_bus_handle_t (C++ type), 734 esp_lcd_rgb_panel_config_t::disp_activeE_SlPo_wLE_AUTH_BOND (C macro), 217 (C++ member), 739 ESP_LE_AUTH_NO_BOND (C macro), 217 esp_lcd_rgb_panel_config_t::disp_gpio_nEuSmP_LE_AUTH_REQ_BOND_MITM (C macro), 217 (C++ member), 738 ESP_LE_AUTH_REQ_MITM (C macro), 217 esp_lcd_rgb_panel_config_t::fb_in_psramESP_LE_AUTH_REQ_SC_BOND (C macro), 217 (C++ member), 739 ESP_LE_AUTH_REQ_SC_MITM (C macro), 217 esp_lcd_rgb_panel_config_t::hsync_gpio_EnSuPm_LE_AUTH_REQ_SC_MITM_BOND (C macro), (C++ member), 738 217 esp_lcd_rgb_panel_config_t::on_frame_trEaSnPs__LdEo_nAeUTH_REQ_SC_ONLY (C macro), 217 (C++ member), 738 ESP_LE_KEY_LCSRK (C macro), 217 esp_lcd_rgb_panel_config_t::pclk_gpio_nEuSmP_LE_KEY_LENC (C macro), 217 (C++ member), 738 ESP_LE_KEY_LID (C macro), 217 esp_lcd_rgb_panel_config_t::psram_transE_SaPl_iLgEn_KEY_LLK (C macro), 217 (C++ member), 738 ESP_LE_KEY_NONE (C macro), 216 esp_lcd_rgb_panel_config_t::relax_on_idElSeP_LE_KEY_PCSRK (C macro), 217 (C++ member), 739 ESP_LE_KEY_PENC (C macro), 217 esp_lcd_rgb_panel_config_t::sram_trans_EaSlPi_gLnE_KEY_PID (C macro), 217 (C++ member), 738 ESP_LE_KEY_PLK (C macro), 217 esp_lcd_rgb_panel_config_t::timings esp_light_sleep_start (C++ function), 1607 (C++ member), 738 esp_link_key (C++ type), 180 esp_lcd_rgb_panel_config_t::user_ctx esp_local_ctrl_add_property (C++ func- (C++ member), 738 tion), 112 esp_lcd_rgb_panel_config_t::vsync_gpio_ensupm_local_ctrl_config (C++ class), 116 (C++ member), 738 esp_local_ctrl_config::handlers (C++ esp_lcd_rgb_panel_event_data_t (C++ member), 116 class), 738 esp_local_ctrl_config::max_properties esp_lcd_rgb_panel_frame_trans_done_cb_t (C++ member), 116 (C++ type), 739 esp_local_ctrl_config::proto_sec (C++ esp_lcd_rgb_timing_t (C++ class), 736 member), 116 esp_lcd_rgb_timing_t::de_idle_high esp_local_ctrl_config::transport (C++ (C++ member), 738 member), 116 esp_lcd_rgb_timing_t::h_res (C++ mem- esp_local_ctrl_config::transport_config ber), 737 (C++ member), 116 esp_lcd_rgb_timing_t::hsync_back_porch esp_local_ctrl_config_t (C++ type), 117 (C++ member), 737 esp_local_ctrl_get_property (C++ func- esp_lcd_rgb_timing_t::hsync_front_porch tion), 113 (C++ member), 737 esp_local_ctrl_get_transport_ble (C++ esp_lcd_rgb_timing_t::hsync_idle_low function), 112 (C++ member), 738 esp_local_ctrl_get_transport_httpd esp_lcd_rgb_timing_t::hsync_pulse_width (C++ function), 112 (C++ member), 737 esp_local_ctrl_handlers (C++ class), 114 esp_lcd_rgb_timing_t::pclk_active_neg esp_local_ctrl_handlers::get_prop_values (C++ member), 738 (C++ member), 115 Espressif Systems 2168 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_local_ctrl_handlers::set_prop_values (C++ member), 113 (C++ member), 115 ESP_LOCAL_CTRL_TRANSPORT_HTTPD (C esp_local_ctrl_handlers::usr_ctx (C++ macro), 116 member), 115 esp_local_ctrl_transport_t (C++ type), 116 esp_local_ctrl_handlers::usr_ctx_free_fEnSP_LOG_BUFFER_CHAR (C macro), 1557 (C++ member), 115 ESP_LOG_BUFFER_CHAR_LEVEL (C macro), 1557 esp_local_ctrl_handlers_t (C++ type), 116 ESP_LOG_BUFFER_HEX (C macro), 1557 esp_local_ctrl_prop (C++ class), 114 ESP_LOG_BUFFER_HEX_LEVEL (C macro), 1556 esp_local_ctrl_prop::ctx (C++ member), ESP_LOG_BUFFER_HEXDUMP (C macro), 1557 114 ESP_LOG_DEBUG (C++ enumerator), 1559 esp_local_ctrl_prop::ctx_free_fn (C++ ESP_LOG_EARLY_IMPL (C macro), 1558 member), 114 esp_log_early_timestamp (C++ function), esp_local_ctrl_prop::flags (C++ member), 1556 114 ESP_LOG_ERROR (C++ enumerator), 1559 esp_local_ctrl_prop::name (C++ member), ESP_LOG_INFO (C++ enumerator), 1559 114 ESP_LOG_LEVEL (C macro), 1558 esp_local_ctrl_prop::size (C++ member), esp_log_level_get (C++ function), 1555 114 ESP_LOG_LEVEL_LOCAL (C macro), 1558 esp_local_ctrl_prop::type (C++ member), esp_log_level_set (C++ function), 1555 114 esp_log_level_t (C++ enum), 1559 esp_local_ctrl_prop_t (C++ type), 116 ESP_LOG_NONE (C++ enumerator), 1559 esp_local_ctrl_prop_val (C++ class), 114 esp_log_set_vprintf (C++ function), 1556 esp_local_ctrl_prop_val::data (C++ esp_log_system_timestamp (C++ function), member), 114 1556 esp_local_ctrl_prop_val::free_fn (C++ esp_log_timestamp (C++ function), 1556 member), 114 ESP_LOG_VERBOSE (C++ enumerator), 1559 esp_local_ctrl_prop_val::size (C++ ESP_LOG_WARN (C++ enumerator), 1559 member), 114 esp_log_write (C++ function), 1556 esp_local_ctrl_prop_val_t (C++ type), 116 esp_log_writev (C++ function), 1556 esp_local_ctrl_proto_sec (C++ enum), 117 ESP_LOGD (C macro), 1558 esp_local_ctrl_proto_sec_cfg (C++ class), ESP_LOGE (C macro), 1558 115 ESP_LOGI (C macro), 1558 esp_local_ctrl_proto_sec_cfg::custom_haEnSdPl_eLOGV (C macro), 1558 (C++ member), 115 ESP_LOGW (C macro), 1558 esp_local_ctrl_proto_sec_cfg::pop ESP_MAC_BT (C++ enumerator), 1565 (C++ member), 116 ESP_MAC_ETH (C++ enumerator), 1565 esp_local_ctrl_proto_sec_cfg::version ESP_MAC_IEEE802154 (C++ enumerator), 1566 (C++ member), 115 esp_mac_type_t (C++ enum), 1565 esp_local_ctrl_proto_sec_cfg_t (C++ ESP_MAC_WIFI_SOFTAP (C++ enumerator), 1565 type), 117 ESP_MAC_WIFI_STA (C++ enumerator), 1565 esp_local_ctrl_proto_sec_t (C++ type), 116 esp_mesh_allow_root_conflicts (C++ func- esp_local_ctrl_remove_property (C++ tion), 524 function), 113 esp_mesh_available_txupQ_num (C++ func- esp_local_ctrl_set_handler (C++ function), tion), 523 113 esp_mesh_connect (C++ function), 527 esp_local_ctrl_start (C++ function), 112 esp_mesh_deinit (C++ function), 516 esp_local_ctrl_stop (C++ function), 112 esp_mesh_delete_group_id (C++ function), ESP_LOCAL_CTRL_TRANSPORT_BLE (C macro), 524 116 esp_mesh_disable_ps (C++ function), 528 esp_local_ctrl_transport_config_ble_t esp_mesh_disconnect (C++ function), 527 (C++ type), 116 esp_mesh_enable_ps (C++ function), 528 esp_local_ctrl_transport_config_httpd_tesp_mesh_fix_root (C++ function), 526 (C++ type), 116 esp_mesh_flush_scan_result (C++ function), esp_local_ctrl_transport_config_t 527 (C++ union), 113 esp_mesh_flush_upstream_packets (C++ esp_local_ctrl_transport_config_t::ble function), 527 (C++ member), 113 esp_mesh_get_active_duty_cycle (C++ esp_local_ctrl_transport_config_t::httpd function), 529 Espressif Systems 2169 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_mesh_get_ap_assoc_expire (C++ func- esp_mesh_post_toDS_state (C++ function), tion), 523 523 esp_mesh_get_ap_authmode (C++ function), esp_mesh_ps_duty_signaling (C++ function), 521 530 esp_mesh_get_ap_connections (C++ func- esp_mesh_recv (C++ function), 517 tion), 521 esp_mesh_recv_toDS (C++ function), 518 esp_mesh_get_capacity_num (C++ function), esp_mesh_scan_get_ap_ie_len (C++ func- 525 tion), 526 esp_mesh_get_config (C++ function), 519 esp_mesh_scan_get_ap_record (C++ func- esp_mesh_get_group_list (C++ function), 524 tion), 526 esp_mesh_get_group_num (C++ function), 524 esp_mesh_send (C++ function), 516 esp_mesh_get_id (C++ function), 520 esp_mesh_send_block_time (C++ function), esp_mesh_get_ie_crypto_key (C++ function), 517 525 esp_mesh_set_active_duty_cycle (C++ esp_mesh_get_layer (C++ function), 521 function), 529 esp_mesh_get_max_layer (C++ function), 520 esp_mesh_set_ap_assoc_expire (C++ func- esp_mesh_get_network_duty_cycle (C++ tion), 522 function), 530 esp_mesh_set_ap_authmode (C++ function), esp_mesh_get_non_mesh_connections 520 (C++ function), 521 esp_mesh_set_ap_connections (C++ func- esp_mesh_get_parent_bssid (C++ function), tion), 521 521 esp_mesh_set_ap_password (C++ function), esp_mesh_get_root_healing_delay (C++ 520 function), 525 esp_mesh_set_capacity_num (C++ function), esp_mesh_get_router (C++ function), 519 525 esp_mesh_get_router_bssid (C++ function), esp_mesh_set_config (C++ function), 518 528 esp_mesh_set_group_id (C++ function), 524 esp_mesh_get_routing_table (C++ function), esp_mesh_set_id (C++ function), 519 523 esp_mesh_set_ie_crypto_funcs (C++ func- esp_mesh_get_routing_table_size (C++ tion), 525 function), 523 esp_mesh_set_ie_crypto_key (C++ function), esp_mesh_get_running_active_duty_cycle 525 (C++ function), 530 esp_mesh_set_max_layer (C++ function), 520 esp_mesh_get_rx_pending (C++ function), 523 esp_mesh_set_network_duty_cycle (C++ esp_mesh_get_self_organized (C++ func- function), 529 tion), 522 esp_mesh_set_parent (C++ function), 526 esp_mesh_get_subnet_nodes_list (C++ esp_mesh_set_root_healing_delay (C++ function), 527 function), 525 esp_mesh_get_subnet_nodes_num (C++ func- esp_mesh_set_router (C++ function), 519 tion), 527 esp_mesh_set_self_organized (C++ func- esp_mesh_get_topology (C++ function), 528 tion), 521 esp_mesh_get_total_node_num (C++ func- esp_mesh_set_topology (C++ function), 528 tion), 523 esp_mesh_set_type (C++ function), 520 esp_mesh_get_tsf_time (C++ function), 528 esp_mesh_set_vote_percentage (C++ func- esp_mesh_get_tx_pending (C++ function), 523 tion), 522 esp_mesh_get_type (C++ function), 520 esp_mesh_set_xon_qsize (C++ function), 524 esp_mesh_get_vote_percentage (C++ func- esp_mesh_start (C++ function), 516 tion), 522 esp_mesh_stop (C++ function), 516 esp_mesh_get_xon_qsize (C++ function), 524 esp_mesh_switch_channel (C++ function), 527 esp_mesh_init (C++ function), 515 esp_mesh_topology_t (C++ enum), 542 esp_mesh_is_device_active (C++ function), esp_mesh_waive_root (C++ function), 522 528 esp_mqtt_client_config_t (C++ class), 78 esp_mesh_is_my_group (C++ function), 525 esp_mqtt_client_config_t::alpn_protos esp_mesh_is_ps_enabled (C++ function), 528 (C++ member), 80 esp_mesh_is_root (C++ function), 521 esp_mqtt_client_config_t::buffer_size esp_mesh_is_root_conflicts_allowed (C++ member), 79 (C++ function), 524 esp_mqtt_client_config_t::cert_len esp_mesh_is_root_fixed (C++ function), 526 (C++ member), 80 Espressif Systems 2170 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_mqtt_client_config_t::cert_pem esp_mqtt_client_config_t::psk_hint_key (C++ member), 79 (C++ member), 80 esp_mqtt_client_config_t::client_cert_leesnp_mqtt_client_config_t::reconnect_timeout_ms (C++ member), 80 (C++ member), 80 esp_mqtt_client_config_t::client_cert_peesmp_mqtt_client_config_t::refresh_connection_afte (C++ member), 80 (C++ member), 80 esp_mqtt_client_config_t::client_id esp_mqtt_client_config_t::set_null_client_id (C++ member), 79 (C++ member), 79 esp_mqtt_client_config_t::client_key_leensp_mqtt_client_config_t::skip_cert_common_name_c (C++ member), 80 (C++ member), 80 esp_mqtt_client_config_t::client_key_peemsp_mqtt_client_config_t::task_prio (C++ member), 80 (C++ member), 79 esp_mqtt_client_config_t::clientkey_pasesswpo_rmdqtt_client_config_t::task_stack (C++ member), 80 (C++ member), 79 esp_mqtt_client_config_t::clientkey_pasesswpo_rmdq_tlte_nclient_config_t::transport (C++ member), 80 (C++ member), 80 esp_mqtt_client_config_t::crt_bundle_atetsapc_hmqtt_client_config_t::uri (C++ (C++ member), 80 member), 79 esp_mqtt_client_config_t::disable_auto_ersepc_omnqntetc_tclient_config_t::use_global_ca_store (C++ member), 79 (C++ member), 80 esp_mqtt_client_config_t::disable_cleane_sspe_smsqitotn_client_config_t::use_secure_element (C++ member), 79 (C++ member), 80 esp_mqtt_client_config_t::disable_keepaelsipv_emqtt_client_config_t::user_context (C++ member), 81 (C++ member), 79 esp_mqtt_client_config_t::ds_data esp_mqtt_client_config_t::username (C++ member), 80 (C++ member), 79 esp_mqtt_client_config_t::event_handle esp_mqtt_client_destroy (C++ function), 76 (C++ member), 79 esp_mqtt_client_disconnect (C++ function), esp_mqtt_client_config_t::event_loop_handle 75 (C++ member), 79 esp_mqtt_client_enqueue (C++ function), 76 esp_mqtt_client_config_t::host (C++ esp_mqtt_client_get_outbox_size (C++ member), 79 function), 77 esp_mqtt_client_config_t::keepalive esp_mqtt_client_handle_t (C++ type), 81 (C++ member), 79 esp_mqtt_client_init (C++ function), 75 esp_mqtt_client_config_t::lwt_msg esp_mqtt_client_publish (C++ function), 76 (C++ member), 79 esp_mqtt_client_reconnect (C++ function), esp_mqtt_client_config_t::lwt_msg_len 75 (C++ member), 79 esp_mqtt_client_register_event (C++ esp_mqtt_client_config_t::lwt_qos function), 77 (C++ member), 79 esp_mqtt_client_set_uri (C++ function), 75 esp_mqtt_client_config_t::lwt_retain esp_mqtt_client_start (C++ function), 75 (C++ member), 79 esp_mqtt_client_stop (C++ function), 75 esp_mqtt_client_config_t::lwt_topic esp_mqtt_client_subscribe (C++ function), (C++ member), 79 75 esp_mqtt_client_config_t::message_retraensspm_imtq_ttti_mceloiuetnt_unsubscribe (C++ func- (C++ member), 81 tion), 76 esp_mqtt_client_config_t::network_timeoeustp__mmsqtt_connect_return_code_t (C++ (C++ member), 81 enum), 82 esp_mqtt_client_config_t::out_buffer_siezsep_mqtt_error_codes (C++ class), 77 (C++ member), 80 esp_mqtt_error_codes::connect_return_code esp_mqtt_client_config_t::password (C++ member), 78 (C++ member), 79 esp_mqtt_error_codes::error_type (C++ esp_mqtt_client_config_t::path (C++ member), 78 member), 81 esp_mqtt_error_codes::esp_tls_cert_verify_flags esp_mqtt_client_config_t::port (C++ (C++ member), 78 member), 79 esp_mqtt_error_codes::esp_tls_last_esp_err esp_mqtt_client_config_t::protocol_ver (C++ member), 77 (C++ member), 80 esp_mqtt_error_codes::esp_tls_stack_err Espressif Systems 2171 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 77 esp_netif_create_default_wifi_mesh_netifs esp_mqtt_error_codes::esp_transport_sock_errno(C++ function), 638 (C++ member), 78 esp_netif_create_default_wifi_sta esp_mqtt_error_codes_t (C++ type), 81 (C++ function), 637 esp_mqtt_error_type_t (C++ enum), 82 esp_netif_create_ip6_linklocal (C++ esp_mqtt_event_handle_t (C++ type), 81 function), 627 esp_mqtt_event_id_t (C++ enum), 81 esp_netif_create_wifi (C++ function), 638 esp_mqtt_event_t (C++ class), 78 esp_netif_deinit (C++ function), 619 esp_mqtt_event_t::client (C++ member), 78 esp_netif_destroy (C++ function), 619 esp_mqtt_event_t::current_data_offset esp_netif_destroy_default_wifi (C++ (C++ member), 78 function), 638 esp_mqtt_event_t::data (C++ member), 78 ESP_NETIF_DHCP_CLIENT (C++ enumerator), 634 esp_mqtt_event_t::data_len (C++ member), ESP_NETIF_DHCP_INIT (C++ enumerator), 633 78 esp_netif_dhcp_option_id_t (C++ enum), esp_mqtt_event_t::dup (C++ member), 78 633 esp_mqtt_event_t::error_handle (C++ esp_netif_dhcp_option_mode_t (C++ enum), member), 78 633 esp_mqtt_event_t::event_id (C++ member), ESP_NETIF_DHCP_SERVER (C++ enumerator), 634 78 ESP_NETIF_DHCP_STARTED (C++ enumerator), esp_mqtt_event_t::msg_id (C++ member), 78 633 esp_mqtt_event_t::qos (C++ member), 78 ESP_NETIF_DHCP_STATUS_MAX (C++ enumera- esp_mqtt_event_t::retain (C++ member), 78 tor), 633 esp_mqtt_event_t::session_present esp_netif_dhcp_status_t (C++ enum), 633 (C++ member), 78 ESP_NETIF_DHCP_STOPPED (C++ enumerator), esp_mqtt_event_t::topic (C++ member), 78 633 esp_mqtt_event_t::topic_len (C++ mem- esp_netif_dhcpc_get_status (C++ function), ber), 78 626 esp_mqtt_event_t::total_data_len (C++ esp_netif_dhcpc_option (C++ function), 625 member), 78 esp_netif_dhcpc_start (C++ function), 625 esp_mqtt_event_t::user_context (C++ esp_netif_dhcpc_stop (C++ function), 625 member), 78 esp_netif_dhcps_get_status (C++ function), esp_mqtt_protocol_ver_t (C++ enum), 83 626 esp_mqtt_set_config (C++ function), 77 esp_netif_dhcps_option (C++ function), 625 esp_mqtt_transport_t (C++ enum), 83 esp_netif_dhcps_start (C++ function), 626 esp_netif_action_add_ip6_address (C++ esp_netif_dhcps_stop (C++ function), 626 function), 622 ESP_NETIF_DNS_BACKUP (C++ enumerator), 633 esp_netif_action_connected (C++ function), ESP_NETIF_DNS_FALLBACK (C++ enumerator), 621 633 esp_netif_action_disconnected (C++ func- esp_netif_dns_info_t (C++ class), 630 tion), 621 esp_netif_dns_info_t::ip (C++ member), esp_netif_action_got_ip (C++ function), 621 630 esp_netif_action_join_ip6_multicast_groEuSpP_NETIF_DNS_MAIN (C++ enumerator), 633 (C++ function), 622 ESP_NETIF_DNS_MAX (C++ enumerator), 633 esp_netif_action_leave_ip6_multicast_greosupp_netif_dns_type_t (C++ enum), 633 (C++ function), 622 ESP_NETIF_DOMAIN_NAME_SERVER (C++ enu- esp_netif_action_remove_ip6_address merator), 633 (C++ function), 622 esp_netif_driver_base_s (C++ class), 632 esp_netif_action_start (C++ function), 621 esp_netif_driver_base_t (C++ type), 632 esp_netif_action_stop (C++ function), 621 esp_netif_driver_ifconfig (C++ class), 632 esp_netif_attach (C++ function), 619 esp_netif_driver_ifconfig_t (C++ type), esp_netif_attach_wifi_ap (C++ function), 632 637 ESP_NETIF_FLAG_AUTOUP (C++ enumerator), 634 esp_netif_attach_wifi_station (C++ func- ESP_NETIF_FLAG_EVENT_IP_MODIFIED (C++ tion), 637 enumerator), 634 esp_netif_config (C++ class), 632 ESP_NETIF_FLAG_GARP (C++ enumerator), 634 esp_netif_config_t (C++ type), 632 ESP_NETIF_FLAG_IS_PPP (C++ enumerator), 634 esp_netif_create_default_wifi_ap (C++ ESP_NETIF_FLAG_IS_SLIP (C++ enumerator), function), 637 634 Espressif Systems 2172 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_netif_flags (C++ enum), 634 esp_netif_ip6_info_t (C++ class), 630 esp_netif_flags_t (C++ type), 632 esp_netif_ip6_info_t::ip (C++ member), esp_netif_free_rx_buffer (C++ function), 630 640 esp_netif_ip_addr_copy (C++ function), 635 esp_netif_get_all_ip6 (C++ function), 628 ESP_NETIF_IP_ADDRESS_LEASE_TIME (C++ esp_netif_get_desc (C++ function), 629 enumerator), 633 esp_netif_get_dns_info (C++ function), 627 ESP_NETIF_IP_EVENT_GOT_IP (C++ enumera- esp_netif_get_event_id (C++ function), 629 tor), 634 esp_netif_get_flags (C++ function), 629 ESP_NETIF_IP_EVENT_LOST_IP (C++ enumera- esp_netif_get_handle_from_ifkey (C++ tor), 634 function), 629 esp_netif_ip_event_type (C++ enum), 634 esp_netif_get_handle_from_netif_impl esp_netif_ip_event_type_t (C++ type), 632 (C++ function), 640 esp_netif_ip_info_t (C++ class), 630 esp_netif_get_hostname (C++ function), 623 esp_netif_ip_info_t::gw (C++ member), 630 esp_netif_get_ifkey (C++ function), 629 esp_netif_ip_info_t::ip (C++ member), 630 esp_netif_get_io_driver (C++ function), 628 esp_netif_ip_info_t::netmask (C++ mem- esp_netif_get_ip6_global (C++ function), ber), 630 627 ESP_NETIF_IP_REQUEST_RETRY_TIME (C++ esp_netif_get_ip6_linklocal (C++ func- enumerator), 633 tion), 627 esp_netif_is_netif_up (C++ function), 623 esp_netif_get_ip_info (C++ function), 623 esp_netif_netstack_buf_free (C++ func- esp_netif_get_mac (C++ function), 623 tion), 629 esp_netif_get_netif_impl (C++ function), esp_netif_netstack_buf_ref (C++ function), 640 629 esp_netif_get_netif_impl_index (C++ esp_netif_netstack_config_t (C++ type), function), 624 632 esp_netif_get_netif_impl_name (C++ func- esp_netif_new (C++ function), 619 tion), 624 esp_netif_next (C++ function), 629 esp_netif_get_nr_of_ifs (C++ function), 629 ESP_NETIF_OP_GET (C++ enumerator), 633 esp_netif_get_old_ip_info (C++ function), ESP_NETIF_OP_MAX (C++ enumerator), 633 623 ESP_NETIF_OP_SET (C++ enumerator), 633 esp_netif_get_route_prio (C++ function), ESP_NETIF_OP_START (C++ enumerator), 633 629 esp_netif_post_transmit_hook_attach esp_netif_htonl (C macro), 635 (C++ function), 620 esp_netif_inherent_config (C++ class), 631 esp_netif_post_transmit_hook_detach esp_netif_inherent_config::flags (C++ (C++ function), 620 member), 631 esp_netif_receive (C++ function), 620 esp_netif_inherent_config::get_ip_eventesp_netif_receive_t (C++ type), 632 (C++ member), 631 esp_netif_recv_hook_attach (C++ function), esp_netif_inherent_config::if_desc 620 (C++ member), 631 esp_netif_recv_hook_detach (C++ function), esp_netif_inherent_config::if_key 621 (C++ member), 631 ESP_NETIF_REQUESTED_IP_ADDRESS (C++ esp_netif_inherent_config::ip_info enumerator), 633 (C++ member), 631 ESP_NETIF_ROUTER_SOLICITATION_ADDRESS esp_netif_inherent_config::lost_ip_event (C++ enumerator), 633 (C++ member), 631 esp_netif_set_default_netif (C++ func- esp_netif_inherent_config::mac (C++ tion), 622 member), 631 esp_netif_set_dns_info (C++ function), 626 esp_netif_inherent_config::route_prio esp_netif_set_driver_config (C++ func- (C++ member), 631 tion), 619 esp_netif_inherent_config_t (C++ type), esp_netif_set_hostname (C++ function), 623 632 esp_netif_set_ip4_addr (C++ function), 628 esp_netif_init (C++ function), 619 esp_netif_set_ip_info (C++ function), 624 esp_netif_iodriver_handle (C++ type), 632 esp_netif_set_mac (C++ function), 622 esp_netif_ip4_makeu32 (C macro), 635 esp_netif_set_old_ip_info (C++ function), esp_netif_ip6_get_addr_type (C++ func- 624 tion), 634 esp_netif_str_to_ip4 (C++ function), 628 Espressif Systems 2173 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_netif_str_to_ip6 (C++ function), 628 ESP_NETIF_SUBNET_MASK (C++ enumerator), 633 esp_netif_t (C++ type), 632 esp_netif_transmit (C++ function), 640 esp_netif_transmit_hook_attach (C++ function), 620 esp_netif_transmit_hook_detach (C++ function), 620 esp_netif_transmit_wrap (C++ function), 640 ESP_NETIF_VENDOR_CLASS_IDENTIFIER (C++ enumerator), 633 ESP_NETIF_VENDOR_SPECIFIC_INFO (C++ enumerator), 634 esp_nimble_hci_and_controller_deinit (C++ function), 497 esp_nimble_hci_and_controller_init (C++ function), 496 esp_nimble_hci_deinit (C++ function), 497 esp_nimble_hci_init (C++ function), 496 esp_now_add_peer (C++ function), 507 esp_now_deinit (C++ function), 506 esp_now_del_peer (C++ function), 507 ESP_NOW_ETH_ALEN (C macro), 509 esp_now_fetch_peer (C++ function), 507 esp_now_get_peer (C++ function), 507 esp_now_get_peer_num (C++ function), 508 esp_now_get_version (C++ function), 506 esp_now_init (C++ function), 506 esp_now_is_peer_exist (C++ function), 508 ESP_NOW_KEY_LEN (C macro), 509 ESP_NOW_MAX_DATA_LEN (C macro), 510 ESP_NOW_MAX_ENCRYPT_PEER_NUM (C macro), 510 ESP_NOW_MAX_TOTAL_PEER_NUM (C macro), 510 esp_now_mod_peer (C++ function), 507 esp_now_peer_info (C++ class), 508 esp_now_peer_info::channel (C++ member), 509 esp_now_peer_info::encrypt (C++ member), 509 esp_now_peer_info::ifidx (C++ member), 509 esp_now_peer_info::lmk (C++ member), 509 esp_now_peer_info::peer_addr (C++ mem- ber), 509 esp_now_peer_info::priv (C++ member), 509 esp_now_peer_info_t (C++ type), 510 esp_now_peer_num (C++ class), 509 esp_now_peer_num::encrypt_num (C++ member), 509 esp_now_peer_num::total_num (C++ mem- ber), 509 esp_now_peer_num_t (C++ type), 510 esp_now_recv_cb_t (C++ type), 510 esp_now_register_recv_cb (C++ function), 506 esp_now_register_send_cb (C++ function), 506 esp_now_send (C++ function), 506 esp_now_send_cb_t (C++ type), 510 ESP_NOW_SEND_FAIL (C++ enumerator), 510 esp_now_send_status_t (C++ enum), 510 ESP_NOW_SEND_SUCCESS (C++ enumerator), 510 esp_now_set_pmk (C++ function), 508 esp_now_set_wake_window (C++ function), 508 esp_now_unregister_recv_cb (C++ function), 506 esp_now_unregister_send_cb (C++ function), 506 ESP_OK (C macro), 1376 ESP_OK_EFUSE_CNT (C macro), 1374 esp_openthread_border_router_deinit (C++ function), 613 esp_openthread_border_router_init (C++ function), 613 esp_openthread_deinit (C++ function), 610 esp_openthread_event_t (C++ enum), 611 esp_openthread_get_backbone_netif (C++ function), 614 esp_openthread_get_instance (C++ func- tion), 610 esp_openthread_get_netif (C++ function), 613 esp_openthread_host_connection_config_t (C++ class), 611 esp_openthread_host_connection_config_t::host_con (C++ member), 611 esp_openthread_host_connection_config_t::host_uar (C++ member), 611 esp_openthread_host_connection_mode_t (C++ enum), 612 esp_openthread_init (C++ function), 609 esp_openthread_launch_mainloop (C++ function), 609 esp_openthread_lock_acquire (C++ func- tion), 612 esp_openthread_lock_deinit (C++ function), 612 esp_openthread_lock_init (C++ function), 612 esp_openthread_lock_release (C++ func- tion), 613 esp_openthread_mainloop_context_t (C++ class), 610 esp_openthread_mainloop_context_t::error_fds (C++ member), 610 esp_openthread_mainloop_context_t::max_fd (C++ member), 610 esp_openthread_mainloop_context_t::read_fds (C++ member), 610 esp_openthread_mainloop_context_t::timeout (C++ member), 610 esp_openthread_mainloop_context_t::write_fds (C++ member), 610 esp_openthread_netif_glue_deinit (C++ function), 613 Espressif Systems 2174 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_openthread_netif_glue_init (C++ (C++ function), 1583 function), 613 esp_ota_get_running_partition (C++ func- esp_openthread_platform_config_t (C++ tion), 1583 class), 611 esp_ota_get_state_partition (C++ func- esp_openthread_platform_config_t::host_config tion), 1584 (C++ member), 611 esp_ota_handle_t (C++ type), 1585 esp_openthread_platform_config_t::port_ecsopn_foitga_mark_app_invalid_rollback_and_reboot (C++ member), 611 (C++ function), 1583 esp_openthread_platform_config_t::radioe_scpo_noftiag_mark_app_valid_cancel_rollback (C++ member), 611 (C++ function), 1583 esp_openthread_port_config_t (C++ class), esp_ota_revoke_secure_boot_public_key 611 (C++ function), 1584 esp_openthread_port_config_t::netif_queeusep__soitzae_secure_boot_public_key_index_t (C++ member), 611 (C++ enum), 1585 esp_openthread_port_config_t::storage_peasrpt_iottiao_ns_enta_mbeoot_partition (C++ function), (C++ member), 611 1582 esp_openthread_port_config_t::task_queuees_ps_ioztea_write (C++ function), 1581 (C++ member), 611 esp_ota_write_with_offset (C++ function), esp_openthread_radio_config_t (C++ 1581 class), 610 esp_partition_check_identity (C++ func- esp_openthread_radio_config_t::radio_mode tion), 1310 (C++ member), 611 esp_partition_deregister_external esp_openthread_radio_config_t::radio_uart_conf(Ci+g+ function), 1310 (C++ member), 611 esp_partition_erase_range (C++ function), esp_openthread_radio_mode_t (C++ enum), 1309 612 esp_partition_find (C++ function), 1306 esp_openthread_set_backbone_netif esp_partition_find_first (C++ function), (C++ function), 613 1307 esp_openthread_uart_config_t (C++ class), esp_partition_get (C++ function), 1307 610 esp_partition_get_sha256 (C++ function), esp_openthread_uart_config_t::port 1309 (C++ member), 610 esp_partition_iterator_release (C++ esp_openthread_uart_config_t::rx_pin function), 1307 (C++ member), 610 esp_partition_iterator_t (C++ type), 1311 esp_openthread_uart_config_t::tx_pin esp_partition_mmap (C++ function), 1309 (C++ member), 610 esp_partition_next (C++ function), 1307 esp_openthread_uart_config_t::uart_confeisgp_partition_read (C++ function), 1307 (C++ member), 610 esp_partition_read_raw (C++ function), 1308 esp_ota_abort (C++ function), 1582 esp_partition_register_external (C++ esp_ota_begin (C++ function), 1581 function), 1310 esp_ota_check_rollback_is_possible ESP_PARTITION_SUBTYPE_ANY (C++ enumera- (C++ function), 1584 tor), 1313 esp_ota_end (C++ function), 1582 ESP_PARTITION_SUBTYPE_APP_FACTORY esp_ota_erase_last_boot_app_partition (C++ enumerator), 1312 (C++ function), 1584 ESP_PARTITION_SUBTYPE_APP_OTA_0 (C++ esp_ota_get_app_description (C++ func- enumerator), 1312 tion), 1580 ESP_PARTITION_SUBTYPE_APP_OTA_1 (C++ esp_ota_get_app_elf_sha256 (C++ function), enumerator), 1312 1580 ESP_PARTITION_SUBTYPE_APP_OTA_10 (C++ esp_ota_get_app_partition_count (C++ enumerator), 1312 function), 1583 ESP_PARTITION_SUBTYPE_APP_OTA_11 (C++ esp_ota_get_boot_partition (C++ function), enumerator), 1312 1582 ESP_PARTITION_SUBTYPE_APP_OTA_12 (C++ esp_ota_get_last_invalid_partition enumerator), 1312 (C++ function), 1584 ESP_PARTITION_SUBTYPE_APP_OTA_13 (C++ esp_ota_get_next_update_partition enumerator), 1312 (C++ function), 1583 ESP_PARTITION_SUBTYPE_APP_OTA_14 (C++ esp_ota_get_partition_description enumerator), 1312 Espressif Systems 2175 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_PARTITION_SUBTYPE_APP_OTA_15 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_2 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_3 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_4 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_5 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_6 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_7 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_8 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_9 (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_MAX (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_OTA_MIN (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_APP_TEST (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_DATA_COREDUMP (C++ enumerator), 1313 ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM (C++ enumerator), 1313 ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD (C++ enumerator), 1313 ESP_PARTITION_SUBTYPE_DATA_FAT (C++ enumerator), 1313 ESP_PARTITION_SUBTYPE_DATA_NVS (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS (C++ enumerator), 1313 ESP_PARTITION_SUBTYPE_DATA_OTA (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_DATA_PHY (C++ enumerator), 1312 ESP_PARTITION_SUBTYPE_DATA_SPIFFS (C++ enumerator), 1313 ESP_PARTITION_SUBTYPE_DATA_UNDEFINED (C++ enumerator), 1313 ESP_PARTITION_SUBTYPE_OTA (C macro), 1311 esp_partition_subtype_t (C++ enum), 1311 esp_partition_t (C++ class), 1310 esp_partition_t::address (C++ member), 1311 esp_partition_t::encrypted (C++ member), 1311 esp_partition_t::flash_chip (C++ mem- ber), 1311 esp_partition_t::label (C++ member), 1311 esp_partition_t::size (C++ member), 1311 esp_partition_t::subtype (C++ member), 1311 esp_partition_t::type (C++ member), 1311 ESP_PARTITION_TYPE_ANY (C++ enumerator), 1311 ESP_PARTITION_TYPE_APP (C++ enumerator), 1311 ESP_PARTITION_TYPE_DATA (C++ enumerator), 1311 esp_partition_type_t (C++ enum), 1311 esp_partition_verify (C++ function), 1307 esp_partition_write (C++ function), 1308 esp_partition_write_raw (C++ function), 1308 ESP_PD_DOMAIN_CPU (C++ enumerator), 1609 ESP_PD_DOMAIN_MAX (C++ enumerator), 1609 ESP_PD_DOMAIN_RTC8M (C++ enumerator), 1609 ESP_PD_DOMAIN_RTC_FAST_MEM (C++ enumera- tor), 1609 ESP_PD_DOMAIN_RTC_PERIPH (C++ enumerator), 1609 ESP_PD_DOMAIN_RTC_SLOW_MEM (C++ enumera- tor), 1609 ESP_PD_DOMAIN_VDDSDIO (C++ enumerator), 1609 ESP_PD_DOMAIN_XTAL (C++ enumerator), 1609 ESP_PD_OPTION_AUTO (C++ enumerator), 1609 ESP_PD_OPTION_OFF (C++ enumerator), 1609 ESP_PD_OPTION_ON (C++ enumerator), 1609 esp_phy_calibration_data_t (C++ class), 1915 esp_phy_calibration_data_t::mac (C++ member), 1915 esp_phy_calibration_data_t::opaque (C++ member), 1915 esp_phy_calibration_data_t::version (C++ member), 1915 esp_phy_calibration_mode_t (C++ enum), 1915 esp_phy_common_clock_disable (C++ func- tion), 1914 esp_phy_common_clock_enable (C++ func- tion), 1914 esp_phy_disable (C++ function), 1914 esp_phy_enable (C++ function), 1914 esp_phy_erase_cal_data_in_nvs (C++ func- tion), 1914 esp_phy_get_init_data (C++ function), 1913 esp_phy_init_data_t (C++ class), 1915 esp_phy_init_data_t::params (C++ mem- ber), 1915 esp_phy_load_cal_and_init (C++ function), 1914 esp_phy_load_cal_data_from_nvs (C++ function), 1914 esp_phy_release_init_data (C++ function), 1913 esp_phy_rf_get_on_ts (C++ function), 1914 esp_phy_store_cal_data_to_nvs (C++ func- tion), 1914 esp_phy_update_country_info (C++ func- Espressif Systems 2176 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index tion), 1915 1592 esp_ping_callbacks_t (C++ class), 160 esp_pm_lock_acquire (C++ function), 1593 esp_ping_callbacks_t::cb_args (C++ esp_pm_lock_create (C++ function), 1592 member), 160 esp_pm_lock_delete (C++ function), 1593 esp_ping_callbacks_t::on_ping_end esp_pm_lock_handle_t (C++ type), 1594 (C++ member), 160 esp_pm_lock_release (C++ function), 1593 esp_ping_callbacks_t::on_ping_success esp_pm_lock_type_t (C++ enum), 1594 (C++ member), 160 ESP_PM_NO_LIGHT_SLEEP (C++ enumerator), esp_ping_callbacks_t::on_ping_timeout 1594 (C++ member), 160 esp_power_level_t (C++ enum), 282 esp_ping_config_t (C++ class), 160 esp_pthread_cfg_t (C++ class), 1598 esp_ping_config_t::count (C++ member), esp_pthread_cfg_t::inherit_cfg (C++ 160 member), 1598 esp_ping_config_t::data_size (C++ mem- esp_pthread_cfg_t::pin_to_core (C++ ber), 160 member), 1598 esp_ping_config_t::interface (C++ mem- esp_pthread_cfg_t::prio (C++ member), ber), 160 1598 esp_ping_config_t::interval_ms (C++ esp_pthread_cfg_t::stack_size (C++ member), 160 member), 1598 esp_ping_config_t::target_addr (C++ esp_pthread_cfg_t::thread_name (C++ member), 160 member), 1598 esp_ping_config_t::task_prio (C++ mem- esp_pthread_get_cfg (C++ function), 1598 ber), 160 esp_pthread_get_default_config (C++ esp_ping_config_t::task_stack_size function), 1598 (C++ member), 160 esp_pthread_init (C++ function), 1598 esp_ping_config_t::timeout_ms (C++ esp_pthread_set_cfg (C++ function), 1598 member), 160 ESP_PWR_LVL_N0 (C++ enumerator), 282 esp_ping_config_t::tos (C++ member), 160 ESP_PWR_LVL_N11 (C++ enumerator), 283 ESP_PING_COUNT_INFINITE (C macro), 161 ESP_PWR_LVL_N12 (C++ enumerator), 282 ESP_PING_DEFAULT_CONFIG (C macro), 161 ESP_PWR_LVL_N14 (C++ enumerator), 283 esp_ping_delete_session (C++ function), 159 ESP_PWR_LVL_N2 (C++ enumerator), 283 esp_ping_get_profile (C++ function), 159 ESP_PWR_LVL_N3 (C++ enumerator), 282 esp_ping_handle_t (C++ type), 161 ESP_PWR_LVL_N5 (C++ enumerator), 283 esp_ping_new_session (C++ function), 159 ESP_PWR_LVL_N6 (C++ enumerator), 282 ESP_PING_PROF_DURATION (C++ enumerator), ESP_PWR_LVL_N8 (C++ enumerator), 283 161 ESP_PWR_LVL_N9 (C++ enumerator), 282 ESP_PING_PROF_IPADDR (C++ enumerator), 161 ESP_PWR_LVL_P1 (C++ enumerator), 283 ESP_PING_PROF_REPLY (C++ enumerator), 161 ESP_PWR_LVL_P3 (C++ enumerator), 282 ESP_PING_PROF_REQUEST (C++ enumerator), 161 ESP_PWR_LVL_P4 (C++ enumerator), 283 ESP_PING_PROF_SEQNO (C++ enumerator), 161 ESP_PWR_LVL_P6 (C++ enumerator), 282 ESP_PING_PROF_SIZE (C++ enumerator), 161 ESP_PWR_LVL_P7 (C++ enumerator), 283 ESP_PING_PROF_TIMEGAP (C++ enumerator), 161 ESP_PWR_LVL_P9 (C++ enumerator), 283 ESP_PING_PROF_TTL (C++ enumerator), 161 esp_random (C++ function), 1600 esp_ping_profile_t (C++ enum), 161 esp_read_mac (C++ function), 1565 esp_ping_start (C++ function), 159 esp_register_freertos_idle_hook (C++ esp_ping_stop (C++ function), 159 function), 1513 ESP_PM_APB_FREQ_MAX (C++ enumerator), 1594 esp_register_freertos_idle_hook_for_cpu esp_pm_config_esp32s3_t (C++ class), 1594 (C++ function), 1513 esp_pm_config_esp32s3_t::light_sleep_eneasbpl_eregister_freertos_tick_hook (C++ (C++ member), 1594 function), 1514 esp_pm_config_esp32s3_t::max_freq_mhz esp_register_freertos_tick_hook_for_cpu (C++ member), 1594 (C++ function), 1514 esp_pm_config_esp32s3_t::min_freq_mhz esp_register_shutdown_handler (C++ func- (C++ member), 1594 tion), 1562 esp_pm_configure (C++ function), 1592 esp_reset_reason (C++ function), 1562 ESP_PM_CPU_FREQ_MAX (C++ enumerator), 1594 esp_reset_reason_t (C++ enum), 1563 esp_pm_dump_locks (C++ function), 1594 esp_restart (C++ function), 1562 esp_pm_get_configuration (C++ function), ESP_RETURN_ON_ERROR (C macro), 1375 Espressif Systems 2177 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ESP_RETURN_ON_ERROR_ISR (C macro), 1376 ESP_RETURN_ON_FALSE (C macro), 1376 ESP_RETURN_ON_FALSE_ISR (C macro), 1376 esp_rom_delay_us (C++ function), 1542 esp_rom_get_cpu_ticks_per_us (C++ func- tion), 1543 esp_rom_get_reset_reason (C++ function), 1543 esp_rom_install_channel_putc (C++ func- tion), 1543 esp_rom_install_uart_printf (C++ func- tion), 1543 esp_rom_printf (C++ function), 1542 esp_rom_route_intr_matrix (C++ function), 1543 ESP_RST_BROWNOUT (C++ enumerator), 1563 ESP_RST_DEEPSLEEP (C++ enumerator), 1563 ESP_RST_EXT (C++ enumerator), 1563 ESP_RST_INT_WDT (C++ enumerator), 1563 ESP_RST_PANIC (C++ enumerator), 1563 ESP_RST_POWERON (C++ enumerator), 1563 ESP_RST_SDIO (C++ enumerator), 1563 ESP_RST_SW (C++ enumerator), 1563 ESP_RST_TASK_WDT (C++ enumerator), 1563 ESP_RST_UNKNOWN (C++ enumerator), 1563 ESP_RST_WDT (C++ enumerator), 1563 ESP_SCO_DATA_PATH_HCI (C++ enumerator), 283 ESP_SCO_DATA_PATH_PCM (C++ enumerator), 283 esp_sco_data_path_t (C++ enum), 283 esp_secure_boot_read_key_digests (C++ function), 1374 esp_service_source_t (C++ enum), 237 esp_set_deep_sleep_wake_stub (C++ func- tion), 1608 esp_sleep_config_gpio_isolate (C++ func- tion), 1608 esp_sleep_cpu_pd_low_init (C++ function), 1608 esp_sleep_disable_wakeup_source (C++ function), 1604 esp_sleep_disable_wifi_wakeup (C++ func- tion), 1607 esp_sleep_enable_ext0_wakeup (C++ func- tion), 1605 esp_sleep_enable_ext1_wakeup (C++ func- tion), 1606 esp_sleep_enable_gpio_switch (C++ func- tion), 1608 esp_sleep_enable_gpio_wakeup (C++ func- tion), 1606 esp_sleep_enable_timer_wakeup (C++ func- tion), 1605 esp_sleep_enable_touchpad_wakeup (C++ function), 1605 esp_sleep_enable_uart_wakeup (C++ func- tion), 1606 esp_sleep_enable_ulp_wakeup (C++ func- tion), 1605 esp_sleep_enable_wifi_wakeup (C++ function), 1606 esp_sleep_ext1_wakeup_mode_t (C++ enum), 1608 esp_sleep_get_ext1_wakeup_status (C++ function), 1607 esp_sleep_get_touchpad_wakeup_status (C++ function), 1605 esp_sleep_get_wakeup_cause (C++ function), 1607 esp_sleep_is_valid_wakeup_gpio (C++ function), 1605 esp_sleep_pd_config (C++ function), 1607 esp_sleep_pd_domain_t (C++ enum), 1609 esp_sleep_pd_option_t (C++ enum), 1609 esp_sleep_source_t (C++ enum), 1609 ESP_SLEEP_WAKEUP_ALL (C++ enumerator), 1609 ESP_SLEEP_WAKEUP_BT (C++ enumerator), 1610 esp_sleep_wakeup_cause_t (C++ type), 1608 ESP_SLEEP_WAKEUP_COCPU (C++ enumerator), 1610 ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG (C++ enumerator), 1610 ESP_SLEEP_WAKEUP_EXT0 (C++ enumerator), 1609 ESP_SLEEP_WAKEUP_EXT1 (C++ enumerator), 1609 ESP_SLEEP_WAKEUP_GPIO (C++ enumerator), 1610 ESP_SLEEP_WAKEUP_TIMER (C++ enumerator), 1609 ESP_SLEEP_WAKEUP_TOUCHPAD (C++ enumera- tor), 1609 ESP_SLEEP_WAKEUP_UART (C++ enumerator), 1610 ESP_SLEEP_WAKEUP_ULP (C++ enumerator), 1609 ESP_SLEEP_WAKEUP_UNDEFINED (C++ enumera- tor), 1609 ESP_SLEEP_WAKEUP_WIFI (C++ enumerator), 1610 esp_smartconfig_fast_mode (C++ function), 543 esp_smartconfig_get_rvd_data (C++ func- tion), 544 esp_smartconfig_get_version (C++ func- tion), 543 esp_smartconfig_set_type (C++ function), 543 esp_smartconfig_start (C++ function), 543 esp_smartconfig_stop (C++ function), 543 esp_spiffs_format (C++ function), 1317 esp_spiffs_info (C++ function), 1317 esp_spiffs_mounted (C++ function), 1317 esp_supp_dpp_bootstrap_gen (C++ function), 585 esp_supp_dpp_bootstrap_t (C++ type), 585 ESP_SUPP_DPP_CFG_RECVD (C++ enumerator), 586 Espressif Systems 2178 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_supp_dpp_deinit (C++ function), 585 (C++ function), 1541 esp_supp_dpp_event_cb_t (C++ type), 585 ESP_TIMER_MAX (C++ enumerator), 1542 esp_supp_dpp_event_t (C++ enum), 586 esp_timer_start_once (C++ function), 1539 ESP_SUPP_DPP_FAIL (C++ enumerator), 586 esp_timer_start_periodic (C++ function), esp_supp_dpp_init (C++ function), 584 1539 esp_supp_dpp_start_listen (C++ function), esp_timer_stop (C++ function), 1540 585 ESP_TIMER_TASK (C++ enumerator), 1542 esp_supp_dpp_stop_listen (C++ function), esp_tls (C++ class), 92 585 esp_tls::cacert (C++ member), 92 ESP_SUPP_DPP_URI_READY (C++ enumerator), esp_tls::cacert_ptr (C++ member), 92 586 esp_tls::clientcert (C++ member), 92 esp_system_abort (C++ function), 1563 esp_tls::clientkey (C++ member), 92 esp_sysview_flush (C++ function), 1343 esp_tls::conf (C++ member), 92 esp_sysview_heap_trace_alloc (C++ func- esp_tls::conn_state (C++ member), 92 tion), 1344 esp_tls::ctr_drbg (C++ member), 92 esp_sysview_heap_trace_free (C++ func- esp_tls::entropy (C++ member), 92 tion), 1344 esp_tls::error_handle (C++ member), 93 esp_sysview_heap_trace_start (C++ func- esp_tls::is_tls (C++ member), 93 tion), 1343 esp_tls::read (C++ member), 92 esp_sysview_heap_trace_stop (C++ func- esp_tls::role (C++ member), 93 tion), 1344 esp_tls::rset (C++ member), 93 esp_sysview_vprintf (C++ function), 1343 esp_tls::server_fd (C++ member), 92 esp_task_wdt_add (C++ function), 1658 esp_tls::sockfd (C++ member), 92 esp_task_wdt_deinit (C++ function), 1658 esp_tls::ssl (C++ member), 92 esp_task_wdt_delete (C++ function), 1659 esp_tls::write (C++ member), 92 esp_task_wdt_init (C++ function), 1658 esp_tls::wset (C++ member), 93 esp_task_wdt_reset (C++ function), 1659 esp_tls_cfg (C++ class), 90 esp_task_wdt_status (C++ function), 1659 esp_tls_cfg::alpn_protos (C++ member), 90 esp_timer_cb_t (C++ type), 1542 esp_tls_cfg::cacert_buf (C++ member), 91 esp_timer_create (C++ function), 1539 esp_tls_cfg::cacert_bytes (C++ member), esp_timer_create_args_t (C++ class), 1541 91 esp_timer_create_args_t::arg (C++ mem- esp_tls_cfg::cacert_pem_buf (C++ mem- ber), 1542 ber), 91 esp_timer_create_args_t::callback esp_tls_cfg::cacert_pem_bytes (C++ (C++ member), 1542 member), 91 esp_timer_create_args_t::dispatch_methoedsp_tls_cfg::clientcert_buf (C++ mem- (C++ member), 1542 ber), 91 esp_timer_create_args_t::name (C++ esp_tls_cfg::clientcert_bytes (C++ member), 1542 member), 91 esp_timer_create_args_t::skip_unhandlede_sepv_etnltss_cfg::clientcert_pem_buf (C++ (C++ member), 1542 member), 91 esp_timer_deinit (C++ function), 1539 esp_tls_cfg::clientcert_pem_bytes esp_timer_delete (C++ function), 1540 (C++ member), 91 esp_timer_dispatch_t (C++ enum), 1542 esp_tls_cfg::clientkey_buf (C++ member), esp_timer_dump (C++ function), 1541 91 esp_timer_early_init (C++ function), 1539 esp_tls_cfg::clientkey_bytes (C++ mem- esp_timer_get_expiry_time (C++ function), ber), 91 1541 esp_tls_cfg::clientkey_password (C++ esp_timer_get_next_alarm (C++ function), member), 91 1540 esp_tls_cfg::clientkey_password_len esp_timer_get_next_alarm_for_wake_up (C++ member), 91 (C++ function), 1540 esp_tls_cfg::clientkey_pem_buf (C++ esp_timer_get_period (C++ function), 1540 member), 91 esp_timer_get_time (C++ function), 1540 esp_tls_cfg::clientkey_pem_bytes (C++ esp_timer_handle_t (C++ type), 1542 member), 91 esp_timer_init (C++ function), 1539 esp_tls_cfg::common_name (C++ member), 91 esp_timer_is_active (C++ function), 1541 esp_tls_cfg::crt_bundle_attach (C++ esp_timer_isr_dispatch_need_yield member), 92 Espressif Systems 2179 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_tls_cfg::ds_data (C++ member), 92 esp_tls_cfg::if_name (C++ member), 92 esp_tls_cfg::is_plain_tcp (C++ member), 92 esp_tls_cfg::keep_alive_cfg (C++ mem- ber), 92 esp_tls_cfg::non_block (C++ member), 91 esp_tls_cfg::psk_hint_key (C++ member), 92 esp_tls_cfg::skip_common_name (C++ member), 91 esp_tls_cfg::timeout_ms (C++ member), 91 esp_tls_cfg::use_global_ca_store (C++ member), 91 esp_tls_cfg::use_secure_element (C++ member), 91 esp_tls_cfg_t (C++ type), 93 ESP_TLS_CLIENT (C++ enumerator), 94 esp_tls_conn_delete (C++ function), 88 esp_tls_conn_destroy (C++ function), 88 esp_tls_conn_http_new (C++ function), 86 esp_tls_conn_http_new_async (C++ func- tion), 87 esp_tls_conn_new (C++ function), 86 esp_tls_conn_new_async (C++ function), 87 esp_tls_conn_new_sync (C++ function), 86 esp_tls_conn_read (C++ function), 87 esp_tls_conn_state (C++ enum), 93 esp_tls_conn_state_t (C++ type), 93 esp_tls_conn_write (C++ function), 87 ESP_TLS_CONNECTING (C++ enumerator), 93 ESP_TLS_DONE (C++ enumerator), 93 ESP_TLS_ERR_SSL_TIMEOUT (C macro), 95 ESP_TLS_ERR_SSL_WANT_READ (C macro), 95 ESP_TLS_ERR_SSL_WANT_WRITE (C macro), 95 ESP_TLS_ERR_TYPE_ESP (C++ enumerator), 96 ESP_TLS_ERR_TYPE_MAX (C++ enumerator), 96 ESP_TLS_ERR_TYPE_MBEDTLS (C++ enumerator), 96 ESP_TLS_ERR_TYPE_MBEDTLS_CERT_FLAGS (C++ enumerator), 96 ESP_TLS_ERR_TYPE_SYSTEM (C++ enumerator), 96 ESP_TLS_ERR_TYPE_UNKNOWN (C++ enumerator), 96 ESP_TLS_ERR_TYPE_WOLFSSL (C++ enumerator), 96 ESP_TLS_ERR_TYPE_WOLFSSL_CERT_FLAGS (C++ enumerator), 96 esp_tls_error_handle_t (C++ type), 95 esp_tls_error_type_t (C++ enum), 96 ESP_TLS_FAIL (C++ enumerator), 93 esp_tls_free_global_ca_store (C++ func- tion), 89 esp_tls_get_and_clear_error_type (C++ function), 89 esp_tls_get_and_clear_last_error (C++ function), 89 esp_tls_get_bytes_avail (C++ function), 88 esp_tls_get_conn_sockfd (C++ function), 88 esp_tls_get_global_ca_store (C++ func- tion), 89 ESP_TLS_HANDSHAKE (C++ enumerator), 93 ESP_TLS_INIT (C++ enumerator), 93 esp_tls_init (C++ function), 86 esp_tls_init_global_ca_store (C++ func- tion), 88 esp_tls_last_error (C++ class), 94 esp_tls_last_error::esp_tls_error_code (C++ member), 94 esp_tls_last_error::esp_tls_flags (C++ member), 94 esp_tls_last_error::last_error (C++ member), 94 esp_tls_last_error_t (C++ type), 95 esp_tls_plain_tcp_connect (C++ function), 89 esp_tls_role (C++ enum), 94 esp_tls_role_t (C++ type), 93 ESP_TLS_SERVER (C++ enumerator), 94 esp_tls_set_global_ca_store (C++ func- tion), 88 esp_tls_t (C++ type), 93 esp_tusb_deinit_console (C++ function), 916 esp_tusb_init_console (C++ function), 916 esp_unregister_shutdown_handler (C++ function), 1562 ESP_UUID_LEN_128 (C macro), 179 ESP_UUID_LEN_16 (C macro), 179 ESP_UUID_LEN_32 (C macro), 179 esp_vendor_ie_cb_t (C++ type), 562 esp_vfs_close (C++ function), 1322 esp_vfs_dev_uart_port_set_rx_line_endings (C++ function), 1329 esp_vfs_dev_uart_port_set_tx_line_endings (C++ function), 1329 esp_vfs_dev_uart_register (C++ function), 1329 esp_vfs_dev_uart_set_rx_line_endings (C++ function), 1329 esp_vfs_dev_uart_set_tx_line_endings (C++ function), 1329 esp_vfs_dev_uart_use_driver (C++ func- tion), 1330 esp_vfs_dev_uart_use_nonblocking (C++ function), 1330 ESP_VFS_EVENTD_CONFIG_DEFAULT (C macro), 1330 esp_vfs_eventfd_config_t (C++ class), 1330 esp_vfs_eventfd_config_t::max_fds (C++ member), 1330 esp_vfs_eventfd_register (C++ function), 1330 esp_vfs_eventfd_unregister (C++ function), 1330 esp_vfs_fat_mount_config_t (C++ class), Espressif Systems 2180 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index 1237, 1332 esp_vfs_select_triggered_isr (C++ func- esp_vfs_fat_mount_config_t::allocation_unit_sitizone), 1324 (C++ member), 1237, 1332 esp_vfs_spiffs_conf_t (C++ class), 1317 esp_vfs_fat_mount_config_t::format_if_meosupn_tv_ffsa_islpeidffs_conf_t::base_path (C++ (C++ member), 1237, 1332 member), 1317 esp_vfs_fat_mount_config_t::max_files esp_vfs_spiffs_conf_t::format_if_mount_failed (C++ member), 1237, 1332 (C++ member), 1317 esp_vfs_fat_rawflash_mount (C++ function), esp_vfs_spiffs_conf_t::max_files (C++ 1237 member), 1317 esp_vfs_fat_rawflash_unmount (C++ func- esp_vfs_spiffs_conf_t::partition_label tion), 1238 (C++ member), 1317 esp_vfs_fat_register (C++ function), 1235 esp_vfs_spiffs_register (C++ function), esp_vfs_fat_sdcard_unmount (C++ function), 1316 1237 esp_vfs_spiffs_unregister (C++ function), esp_vfs_fat_sdmmc_mount (C++ function), 1317 1235 esp_vfs_stat (C++ function), 1322 esp_vfs_fat_sdmmc_unmount (C++ function), esp_vfs_t (C++ class), 1325 1236 esp_vfs_t::access (C++ member), 1327 esp_vfs_fat_sdspi_mount (C++ function), esp_vfs_t::access_p (C++ member), 1327 1236 esp_vfs_t::close (C++ member), 1325 esp_vfs_fat_spiflash_mount (C++ function), esp_vfs_t::close_p (C++ member), 1325 1332 esp_vfs_t::closedir (C++ member), 1326 esp_vfs_fat_spiflash_unmount (C++ func- esp_vfs_t::closedir_p (C++ member), 1326 tion), 1332 esp_vfs_t::end_select (C++ member), 1328 esp_vfs_fat_unregister_path (C++ func- esp_vfs_t::fcntl (C++ member), 1327 tion), 1235 esp_vfs_t::fcntl_p (C++ member), 1327 ESP_VFS_FLAG_CONTEXT_PTR (C macro), 1328 esp_vfs_t::flags (C++ member), 1325 ESP_VFS_FLAG_DEFAULT (C macro), 1328 esp_vfs_t::fstat (C++ member), 1326 esp_vfs_fstat (C++ function), 1322 esp_vfs_t::fstat_p (C++ member), 1326 esp_vfs_id_t (C++ type), 1329 esp_vfs_t::fsync (C++ member), 1327 esp_vfs_l2tap_intf_register (C++ func- esp_vfs_t::fsync_p (C++ member), 1327 tion), 636 esp_vfs_t::ftruncate (C++ member), 1327 esp_vfs_l2tap_intf_unregister (C++ func- esp_vfs_t::ftruncate_p (C++ member), 1327 tion), 636 esp_vfs_t::get_socket_select_semaphore esp_vfs_link (C++ function), 1322 (C++ member), 1328 esp_vfs_lseek (C++ function), 1322 esp_vfs_t::ioctl (C++ member), 1327 esp_vfs_open (C++ function), 1322 esp_vfs_t::ioctl_p (C++ member), 1327 ESP_VFS_PATH_MAX (C macro), 1328 esp_vfs_t::link (C++ member), 1326 esp_vfs_pread (C++ function), 1324 esp_vfs_t::link_p (C++ member), 1326 esp_vfs_pwrite (C++ function), 1324 esp_vfs_t::lseek (C++ member), 1325 esp_vfs_read (C++ function), 1322 esp_vfs_t::lseek_p (C++ member), 1325 esp_vfs_register (C++ function), 1322 esp_vfs_t::mkdir (C++ member), 1327 esp_vfs_register_fd (C++ function), 1323 esp_vfs_t::mkdir_p (C++ member), 1326 esp_vfs_register_fd_range (C++ function), esp_vfs_t::open (C++ member), 1325 1322 esp_vfs_t::open_p (C++ member), 1325 esp_vfs_register_fd_with_local_fd esp_vfs_t::opendir (C++ member), 1326 (C++ function), 1323 esp_vfs_t::opendir_p (C++ member), 1326 esp_vfs_register_with_id (C++ function), esp_vfs_t::pread (C++ member), 1325 1323 esp_vfs_t::pread_p (C++ member), 1325 esp_vfs_rename (C++ function), 1322 esp_vfs_t::pwrite (C++ member), 1325 esp_vfs_select (C++ function), 1323 esp_vfs_t::pwrite_p (C++ member), 1325 esp_vfs_select_sem_t (C++ class), 1324 esp_vfs_t::read (C++ member), 1325 esp_vfs_select_sem_t::is_sem_local esp_vfs_t::read_p (C++ member), 1325 (C++ member), 1325 esp_vfs_t::readdir (C++ member), 1326 esp_vfs_select_sem_t::sem (C++ member), esp_vfs_t::readdir_p (C++ member), 1326 1325 esp_vfs_t::readdir_r (C++ member), 1326 esp_vfs_select_triggered (C++ function), esp_vfs_t::readdir_r_p (C++ member), 1326 1324 esp_vfs_t::rename (C++ member), 1326 Espressif Systems 2181 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index esp_vfs_t::rename_p (C++ member), 1326 esp_vhci_host_callback::notify_host_send_availabl esp_vfs_t::rmdir (C++ member), 1327 (C++ member), 280 esp_vfs_t::rmdir_p (C++ member), 1327 esp_vhci_host_callback_t (C++ type), 281 esp_vfs_t::seekdir (C++ member), 1326 esp_vhci_host_check_send_available esp_vfs_t::seekdir_p (C++ member), 1326 (C++ function), 277 esp_vfs_t::socket_select (C++ member), esp_vhci_host_register_callback (C++ 1328 function), 277 esp_vfs_t::start_select (C++ member), esp_vhci_host_send_packet (C++ function), 1328 277 esp_vfs_t::stat (C++ member), 1326 esp_wake_deep_sleep (C++ function), 1607 esp_vfs_t::stat_p (C++ member), 1326 esp_wifi_80211_tx (C++ function), 555 esp_vfs_t::stop_socket_select (C++ esp_wifi_ap_get_sta_aid (C++ function), 553 member), 1328 esp_wifi_ap_get_sta_list (C++ function), esp_vfs_t::stop_socket_select_isr 553 (C++ member), 1328 esp_wifi_bt_power_domain_off (C++ func- esp_vfs_t::tcdrain (C++ member), 1327 tion), 279 esp_vfs_t::tcdrain_p (C++ member), 1327 esp_wifi_bt_power_domain_on (C++ func- esp_vfs_t::tcflow (C++ member), 1328 tion), 279 esp_vfs_t::tcflow_p (C++ member), 1328 esp_wifi_clear_default_wifi_driver_and_handlers esp_vfs_t::tcflush (C++ member), 1328 (C++ function), 637 esp_vfs_t::tcflush_p (C++ member), 1328 esp_wifi_clear_fast_connect (C++ func- esp_vfs_t::tcgetattr (C++ member), 1327 tion), 547 esp_vfs_t::tcgetattr_p (C++ member), 1327 esp_wifi_config_11b_rate (C++ function), esp_vfs_t::tcgetsid (C++ member), 1328 558 esp_vfs_t::tcgetsid_p (C++ member), 1328 esp_wifi_config_80211_tx_rate (C++ func- esp_vfs_t::tcsendbreak (C++ member), 1328 tion), 559 esp_vfs_t::tcsendbreak_p (C++ member), esp_wifi_config_espnow_rate (C++ func- 1328 tion), 558 esp_vfs_t::tcsetattr (C++ member), 1327 esp_wifi_connect (C++ function), 547 esp_vfs_t::tcsetattr_p (C++ member), 1327 esp_wifi_deauth_sta (C++ function), 547 esp_vfs_t::telldir (C++ member), 1326 esp_wifi_deinit (C++ function), 546 esp_vfs_t::telldir_p (C++ member), 1326 esp_wifi_disconnect (C++ function), 547 esp_vfs_t::truncate (C++ member), 1327 esp_wifi_ftm_end_session (C++ function), esp_vfs_t::truncate_p (C++ member), 1327 558 esp_vfs_t::unlink (C++ member), 1326 esp_wifi_ftm_initiate_session (C++ func- esp_vfs_t::unlink_p (C++ member), 1326 tion), 557 esp_vfs_t::utime (C++ member), 1327 esp_wifi_ftm_resp_set_offset (C++ func- esp_vfs_t::utime_p (C++ member), 1327 tion), 558 esp_vfs_t::write (C++ member), 1325 esp_wifi_get_ant (C++ function), 556 esp_vfs_t::write_p (C++ member), 1325 esp_wifi_get_ant_gpio (C++ function), 556 esp_vfs_tusb_cdc_register (C++ function), esp_wifi_get_bandwidth (C++ function), 549 917 esp_wifi_get_channel (C++ function), 550 esp_vfs_tusb_cdc_unregister (C++ func- esp_wifi_get_config (C++ function), 553 tion), 917 esp_wifi_get_country (C++ function), 551 esp_vfs_unlink (C++ function), 1322 esp_wifi_get_country_code (C++ function), esp_vfs_unregister (C++ function), 1323 559 esp_vfs_unregister_fd (C++ function), 1323 esp_wifi_get_event_mask (C++ function), 555 esp_vfs_unregister_with_id (C++ function), esp_wifi_get_inactive_time (C++ function), 1323 557 esp_vfs_usb_serial_jtag_use_driver esp_wifi_get_mac (C++ function), 551 (C++ function), 1330 esp_wifi_get_max_tx_power (C++ function), esp_vfs_usb_serial_jtag_use_nonblocking 554 (C++ function), 1330 esp_wifi_get_mode (C++ function), 546 esp_vfs_utime (C++ function), 1322 esp_wifi_get_promiscuous (C++ function), esp_vfs_write (C++ function), 1322 552 esp_vhci_host_callback (C++ class), 280 esp_wifi_get_promiscuous_ctrl_filter esp_vhci_host_callback::notify_host_recv (C++ function), 552 (C++ member), 280 esp_wifi_get_promiscuous_filter (C++ Espressif Systems 2182 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index function), 552 essl_clear_intr (C++ function), 124 esp_wifi_get_protocol (C++ function), 549 essl_get_intr (C++ function), 124 esp_wifi_get_ps (C++ function), 549 essl_get_intr_ena (C++ function), 124 esp_wifi_get_tsf_time (C++ function), 556 essl_get_packet (C++ function), 123 esp_wifi_init (C++ function), 545 essl_get_rx_data_size (C++ function), 122 ESP_WIFI_MAX_CONN_NUM (C macro), 575 essl_get_tx_buffer_num (C++ function), 122 esp_wifi_restore (C++ function), 547 essl_handle_t (C++ type), 125 esp_wifi_scan_get_ap_num (C++ function), essl_init (C++ function), 122 548 essl_read_reg (C++ function), 123 esp_wifi_scan_get_ap_records (C++ func- essl_reset_cnt (C++ function), 122 tion), 548 essl_sdio_config_t (C++ class), 125 esp_wifi_scan_start (C++ function), 547 essl_sdio_config_t::card (C++ member), esp_wifi_scan_stop (C++ function), 548 125 esp_wifi_set_ant (C++ function), 556 essl_sdio_config_t::recv_buffer_size esp_wifi_set_ant_gpio (C++ function), 556 (C++ member), 125 esp_wifi_set_bandwidth (C++ function), 549 essl_sdio_deinit_dev (C++ function), 125 esp_wifi_set_channel (C++ function), 550 essl_sdio_init_dev (C++ function), 125 esp_wifi_set_config (C++ function), 552 essl_send_packet (C++ function), 122 esp_wifi_set_connectionless_wake_interveaslsl_send_slave_intr (C++ function), 125 (C++ function), 558 essl_set_intr_ena (C++ function), 124 esp_wifi_set_country (C++ function), 550 essl_spi_config_t (C++ class), 130 esp_wifi_set_country_code (C++ function), essl_spi_config_t::rx_sync_reg (C++ 558 member), 130 esp_wifi_set_csi (C++ function), 556 essl_spi_config_t::spi (C++ member), 130 esp_wifi_set_csi_config (C++ function), 555 essl_spi_config_t::tx_buf_size (C++ esp_wifi_set_csi_rx_cb (C++ function), 555 member), 130 esp_wifi_set_default_wifi_ap_handlers essl_spi_config_t::tx_sync_reg (C++ (C++ function), 637 member), 130 esp_wifi_set_default_wifi_sta_handlers essl_spi_deinit_dev (C++ function), 126 (C++ function), 637 essl_spi_get_packet (C++ function), 126 esp_wifi_set_event_mask (C++ function), 554 essl_spi_init_dev (C++ function), 126 esp_wifi_set_inactive_time (C++ function), essl_spi_rdbuf (C++ function), 127 557 essl_spi_rdbuf_polling (C++ function), 127 esp_wifi_set_mac (C++ function), 551 essl_spi_rddma (C++ function), 128 esp_wifi_set_max_tx_power (C++ function), essl_spi_rddma_done (C++ function), 129 554 essl_spi_rddma_seg (C++ function), 129 esp_wifi_set_mode (C++ function), 546 essl_spi_read_reg (C++ function), 126 esp_wifi_set_promiscuous (C++ function), essl_spi_reset_cnt (C++ function), 127 551 essl_spi_send_packet (C++ function), 127 esp_wifi_set_promiscuous_ctrl_filter essl_spi_wrbuf (C++ function), 128 (C++ function), 552 essl_spi_wrbuf_polling (C++ function), 128 esp_wifi_set_promiscuous_filter (C++ essl_spi_wrdma (C++ function), 129 function), 552 essl_spi_wrdma_done (C++ function), 130 esp_wifi_set_promiscuous_rx_cb (C++ essl_spi_wrdma_seg (C++ function), 129 function), 551 essl_spi_write_reg (C++ function), 126 esp_wifi_set_protocol (C++ function), 549 essl_wait_for_ready (C++ function), 122 esp_wifi_set_ps (C++ function), 549 essl_wait_int (C++ function), 124 esp_wifi_set_rssi_threshold (C++ func- essl_write_reg (C++ function), 123 tion), 557 eStandardSleep (C++ enumerator), 1425 esp_wifi_set_storage (C++ function), 553 eSuspended (C++ enumerator), 1425 esp_wifi_set_vendor_ie (C++ function), 554 eTaskGetState (C++ function), 1403 esp_wifi_set_vendor_ie_cb (C++ function), eTaskState (C++ enum), 1425 554 ETH_CMD_G_AUTONEGO (C++ enumerator), 597 esp_wifi_sta_get_ap_info (C++ function), ETH_CMD_G_DUPLEX_MODE (C++ enumerator), 597 548 ETH_CMD_G_MAC_ADDR (C++ enumerator), 597 esp_wifi_start (C++ function), 546 ETH_CMD_G_PHY_ADDR (C++ enumerator), 597 esp_wifi_statis_dump (C++ function), 557 ETH_CMD_G_SPEED (C++ enumerator), 597 esp_wifi_stop (C++ function), 546 ETH_CMD_S_AUTONEGO (C++ enumerator), 597 Espressif Systems 2183 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ETH_CMD_S_DUPLEX_MODE (C++ enumerator), 597 ETH_CMD_S_FLOW_CTRL (C++ enumerator), 597 ETH_CMD_S_MAC_ADDR (C++ enumerator), 597 ETH_CMD_S_PHY_ADDR (C++ enumerator), 597 ETH_CMD_S_PHY_LOOPBACK (C++ enumerator), 597 ETH_CMD_S_PROMISCUOUS (C++ enumerator), 597 ETH_CMD_S_SPEED (C++ enumerator), 597 ETH_DEFAULT_CONFIG (C macro), 597 eth_event_t (C++ enum), 599 eth_mac_clock_config_t (C++ union), 599 eth_mac_clock_config_t::clock_gpio (C++ member), 600 eth_mac_clock_config_t::clock_mode (C++ member), 600 eth_mac_clock_config_t::mii (C++ mem- ber), 600 eth_mac_clock_config_t::rmii (C++ mem- ber), 600 eth_mac_config_t (C++ class), 603 eth_mac_config_t::flags (C++ member), 603 eth_mac_config_t::rx_task_prio (C++ member), 603 eth_mac_config_t::rx_task_stack_size (C++ member), 603 eth_mac_config_t::sw_reset_timeout_ms (C++ member), 603 ETH_MAC_DEFAULT_CONFIG (C macro), 603 ETH_MAC_FLAG_PIN_TO_CORE (C macro), 603 ETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE (C macro), 603 eth_phy_autoneg_cmd_t (C++ enum), 608 eth_phy_config_t (C++ class), 608 eth_phy_config_t::autonego_timeout_ms (C++ member), 608 eth_phy_config_t::phy_addr (C++ member), 608 eth_phy_config_t::reset_gpio_num (C++ member), 608 eth_phy_config_t::reset_timeout_ms (C++ member), 608 ETH_PHY_DEFAULT_CONFIG (C macro), 608 ETH_STATE_DEINIT (C++ enumerator), 599 ETH_STATE_DUPLEX (C++ enumerator), 599 ETH_STATE_LINK (C++ enumerator), 599 ETH_STATE_LLINIT (C++ enumerator), 599 ETH_STATE_PAUSE (C++ enumerator), 599 ETH_STATE_SPEED (C++ enumerator), 599 ETHERNET_EVENT_CONNECTED (C++ enumerator), 599 ETHERNET_EVENT_DISCONNECTED (C++ enumer- ator), 599 ETHERNET_EVENT_START (C++ enumerator), 599 ETHERNET_EVENT_STOP (C++ enumerator), 599 ETS_INTERNAL_INTR_SOURCE_OFF (C macro), 1553 ETS_INTERNAL_PROFILING_INTR_SOURCE (C macro), 1553 ETS_INTERNAL_SW0_INTR_SOURCE (C macro), 1553 ETS_INTERNAL_SW1_INTR_SOURCE (C macro), 1553 ETS_INTERNAL_TIMER0_INTR_SOURCE (C macro), 1553 ETS_INTERNAL_TIMER1_INTR_SOURCE (C macro), 1553 ETS_INTERNAL_TIMER2_INTR_SOURCE (C macro), 1553 EventBits_t (C++ type), 1481 eventfd (C++ function), 1330 EventGroupHandle_t (C++ type), 1481 F FAST_PROV_ACT_ENTER (C++ enumerator), 332 FAST_PROV_ACT_EXIT (C++ enumerator), 332 FAST_PROV_ACT_MAX (C++ enumerator), 332 FAST_PROV_ACT_NONE (C++ enumerator), 332 FAST_PROV_ACT_SUSPEND (C++ enumerator), 332 ff_diskio_impl_t (C++ class), 1238 ff_diskio_impl_t::init (C++ member), 1238 ff_diskio_impl_t::ioctl (C++ member), 1238 ff_diskio_impl_t::read (C++ member), 1238 ff_diskio_impl_t::status (C++ member), 1238 ff_diskio_impl_t::write (C++ member), 1238 ff_diskio_register (C++ function), 1238 ff_diskio_register_raw_partition (C++ function), 1239 ff_diskio_register_sdmmc (C++ function), 1239 ff_diskio_register_wl_partition (C++ function), 1239 FLASH_WRAP_MODE_16B (C++ enumerator), 1301 FLASH_WRAP_MODE_32B (C++ enumerator), 1301 FLASH_WRAP_MODE_64B (C++ enumerator), 1301 FLASH_WRAP_MODE_8B (C++ enumerator), 1301 FLASH_WRAP_MODE_DISABLE (C++ enumerator), 1301 FTM_STATUS_CONF_REJECTED (C++ enumerator), 584 FTM_STATUS_FAIL (C++ enumerator), 584 FTM_STATUS_NO_RESPONSE (C++ enumerator), 584 FTM_STATUS_SUCCESS (C++ enumerator), 584 FTM_STATUS_UNSUPPORTED (C++ enumerator), 584 G get_phy_version_str (C++ function), 1915 gpio_config (C++ function), 662 gpio_config_t (C++ class), 668 gpio_config_t::intr_type (C++ member), 668 gpio_config_t::mode (C++ member), 668 Espressif Systems 2184 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index gpio_config_t::pin_bit_mask (C++ member), 668 gpio_config_t::pull_down_en (C++ member), 668 gpio_config_t::pull_up_en (C++ member), 668 gpio_deep_sleep_hold_dis (C++ function), 666 gpio_deep_sleep_hold_en (C++ function), 666 GPIO_DRIVE_CAP_0 (C++ enumerator), 673 GPIO_DRIVE_CAP_1 (C++ enumerator), 673 GPIO_DRIVE_CAP_2 (C++ enumerator), 673 GPIO_DRIVE_CAP_3 (C++ enumerator), 673 GPIO_DRIVE_CAP_DEFAULT (C++ enumerator), 673 GPIO_DRIVE_CAP_MAX (C++ enumerator), 673 gpio_drive_cap_t (C++ enum), 673 GPIO_FLOATING (C++ enumerator), 673 gpio_force_hold_all (C++ function), 667 gpio_force_unhold_all (C++ function), 667 gpio_get_drive_capability (C++ function), 666 gpio_get_level (C++ function), 663 gpio_hold_dis (C++ function), 666 gpio_hold_en (C++ function), 666 gpio_install_isr_service (C++ function), 665 gpio_int_type_t (C++ enum), 672 GPIO_INTR_ANYEDGE (C++ enumerator), 672 GPIO_INTR_DISABLE (C++ enumerator), 672 gpio_intr_disable (C++ function), 662 gpio_intr_enable (C++ function), 662 GPIO_INTR_HIGH_LEVEL (C++ enumerator), 672 GPIO_INTR_LOW_LEVEL (C++ enumerator), 672 GPIO_INTR_MAX (C++ enumerator), 672 GPIO_INTR_NEGEDGE (C++ enumerator), 672 GPIO_INTR_POSEDGE (C++ enumerator), 672 gpio_iomux_in (C++ function), 666 gpio_iomux_out (C++ function), 667 GPIO_IS_VALID_GPIO (C macro), 668 GPIO_IS_VALID_OUTPUT_GPIO (C macro), 668 gpio_isr_handle_t (C++ type), 668 gpio_isr_handler_add (C++ function), 665 gpio_isr_handler_remove (C++ function), 665 gpio_isr_register (C++ function), 664 gpio_isr_t (C++ type), 670 GPIO_MODE_DISABLE (C++ enumerator), 672 GPIO_MODE_INPUT (C++ enumerator), 672 GPIO_MODE_INPUT_OUTPUT (C++ enumerator), 672 GPIO_MODE_INPUT_OUTPUT_OD (C++ enumera- tor), 672 GPIO_MODE_OUTPUT (C++ enumerator), 672 GPIO_MODE_OUTPUT_OD (C++ enumerator), 672 gpio_mode_t (C++ enum), 672 GPIO_NUM_0 (C++ enumerator), 670 GPIO_NUM_1 (C++ enumerator), 670 GPIO_NUM_10 (C++ enumerator), 670 GPIO_NUM_11 (C++ enumerator), 670 GPIO_NUM_12 (C++ enumerator), 670 GPIO_NUM_13 (C++ enumerator), 670 GPIO_NUM_14 (C++ enumerator), 670 GPIO_NUM_15 (C++ enumerator), 670 GPIO_NUM_16 (C++ enumerator), 670 GPIO_NUM_17 (C++ enumerator), 670 GPIO_NUM_18 (C++ enumerator), 671 GPIO_NUM_19 (C++ enumerator), 671 GPIO_NUM_2 (C++ enumerator), 670 GPIO_NUM_20 (C++ enumerator), 671 GPIO_NUM_21 (C++ enumerator), 671 GPIO_NUM_26 (C++ enumerator), 671 GPIO_NUM_27 (C++ enumerator), 671 GPIO_NUM_28 (C++ enumerator), 671 GPIO_NUM_29 (C++ enumerator), 671 GPIO_NUM_3 (C++ enumerator), 670 GPIO_NUM_30 (C++ enumerator), 671 GPIO_NUM_31 (C++ enumerator), 671 GPIO_NUM_32 (C++ enumerator), 671 GPIO_NUM_33 (C++ enumerator), 671 GPIO_NUM_34 (C++ enumerator), 671 GPIO_NUM_35 (C++ enumerator), 671 GPIO_NUM_36 (C++ enumerator), 671 GPIO_NUM_37 (C++ enumerator), 671 GPIO_NUM_38 (C++ enumerator), 671 GPIO_NUM_39 (C++ enumerator), 671 GPIO_NUM_4 (C++ enumerator), 670 GPIO_NUM_40 (C++ enumerator), 671 GPIO_NUM_41 (C++ enumerator), 671 GPIO_NUM_42 (C++ enumerator), 671 GPIO_NUM_43 (C++ enumerator), 671 GPIO_NUM_44 (C++ enumerator), 671 GPIO_NUM_45 (C++ enumerator), 672 GPIO_NUM_46 (C++ enumerator), 672 GPIO_NUM_47 (C++ enumerator), 672 GPIO_NUM_48 (C++ enumerator), 672 GPIO_NUM_5 (C++ enumerator), 670 GPIO_NUM_6 (C++ enumerator), 670 GPIO_NUM_7 (C++ enumerator), 670 GPIO_NUM_8 (C++ enumerator), 670 GPIO_NUM_9 (C++ enumerator), 670 GPIO_NUM_MAX (C++ enumerator), 672 GPIO_NUM_NC (C++ enumerator), 670 gpio_num_t (C++ enum), 670 GPIO_PIN_COUNT (C macro), 668 GPIO_PIN_REG_0 (C macro), 668 GPIO_PIN_REG_1 (C macro), 668 GPIO_PIN_REG_10 (C macro), 668 GPIO_PIN_REG_11 (C macro), 668 GPIO_PIN_REG_12 (C macro), 669 GPIO_PIN_REG_13 (C macro), 669 GPIO_PIN_REG_14 (C macro), 669 GPIO_PIN_REG_15 (C macro), 669 GPIO_PIN_REG_16 (C macro), 669 GPIO_PIN_REG_17 (C macro), 669 GPIO_PIN_REG_18 (C macro), 669 GPIO_PIN_REG_19 (C macro), 669 Espressif Systems 2185 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index GPIO_PIN_REG_2 (C macro), 668 GPIO_PIN_REG_20 (C macro), 669 GPIO_PIN_REG_21 (C macro), 669 GPIO_PIN_REG_22 (C macro), 669 GPIO_PIN_REG_23 (C macro), 669 GPIO_PIN_REG_24 (C macro), 669 GPIO_PIN_REG_25 (C macro), 669 GPIO_PIN_REG_26 (C macro), 669 GPIO_PIN_REG_27 (C macro), 669 GPIO_PIN_REG_28 (C macro), 669 GPIO_PIN_REG_29 (C macro), 669 GPIO_PIN_REG_3 (C macro), 668 GPIO_PIN_REG_30 (C macro), 669 GPIO_PIN_REG_31 (C macro), 669 GPIO_PIN_REG_32 (C macro), 669 GPIO_PIN_REG_33 (C macro), 669 GPIO_PIN_REG_34 (C macro), 669 GPIO_PIN_REG_35 (C macro), 669 GPIO_PIN_REG_36 (C macro), 669 GPIO_PIN_REG_37 (C macro), 669 GPIO_PIN_REG_38 (C macro), 669 GPIO_PIN_REG_39 (C macro), 669 GPIO_PIN_REG_4 (C macro), 668 GPIO_PIN_REG_40 (C macro), 669 GPIO_PIN_REG_41 (C macro), 669 GPIO_PIN_REG_42 (C macro), 669 GPIO_PIN_REG_43 (C macro), 669 GPIO_PIN_REG_44 (C macro), 669 GPIO_PIN_REG_45 (C macro), 669 GPIO_PIN_REG_46 (C macro), 669 GPIO_PIN_REG_47 (C macro), 669 GPIO_PIN_REG_48 (C macro), 669 GPIO_PIN_REG_5 (C macro), 668 GPIO_PIN_REG_6 (C macro), 668 GPIO_PIN_REG_7 (C macro), 668 GPIO_PIN_REG_8 (C macro), 668 GPIO_PIN_REG_9 (C macro), 668 GPIO_PORT_0 (C++ enumerator), 670 GPIO_PORT_MAX (C++ enumerator), 670 gpio_port_t (C++ enum), 670 gpio_pull_mode_t (C++ enum), 673 gpio_pulldown_dis (C++ function), 665 GPIO_PULLDOWN_DISABLE (C++ enumerator), 673 gpio_pulldown_en (C++ function), 664 GPIO_PULLDOWN_ENABLE (C++ enumerator), 673 GPIO_PULLDOWN_ONLY (C++ enumerator), 673 gpio_pulldown_t (C++ enum), 672 gpio_pullup_dis (C++ function), 664 GPIO_PULLUP_DISABLE (C++ enumerator), 672 gpio_pullup_en (C++ function), 664 GPIO_PULLUP_ENABLE (C++ enumerator), 672 GPIO_PULLUP_ONLY (C++ enumerator), 673 GPIO_PULLUP_PULLDOWN (C++ enumerator), 673 gpio_pullup_t (C++ enum), 672 gpio_reset_pin (C++ function), 662 gpio_set_direction (C++ function), 663 gpio_set_drive_capability (C++ function), 665 gpio_set_intr_type (C++ function), 662 gpio_set_level (C++ function), 663 gpio_set_pull_mode (C++ function), 663 gpio_sleep_sel_dis (C++ function), 667 gpio_sleep_sel_en (C++ function), 667 gpio_sleep_set_direction (C++ function), 667 gpio_sleep_set_pull_mode (C++ function), 667 gpio_uninstall_isr_service (C++ function), 665 gpio_wakeup_disable (C++ function), 664 gpio_wakeup_enable (C++ function), 663 gptimer_alarm_cb_t (C++ type), 685 gptimer_alarm_config_t (C++ class), 685 gptimer_alarm_config_t::alarm_count (C++ member), 685 gptimer_alarm_config_t::auto_reload_on_alarm (C++ member), 685 gptimer_alarm_config_t::reload_count (C++ member), 685 gptimer_alarm_event_data_t (C++ class), 684 gptimer_alarm_event_data_t::alarm_value (C++ member), 684 gptimer_alarm_event_data_t::count_value (C++ member), 684 GPTIMER_CLK_SRC_APB (C++ enumerator), 686 GPTIMER_CLK_SRC_XTAL (C++ enumerator), 686 gptimer_clock_source_t (C++ enum), 685 gptimer_config_t (C++ class), 685 gptimer_config_t::clk_src (C++ member), 685 gptimer_config_t::direction (C++ mem- ber), 685 gptimer_config_t::intr_shared (C++ member), 685 gptimer_config_t::resolution_hz (C++ member), 685 gptimer_count_direction_t (C++ enum), 686 GPTIMER_COUNT_DOWN (C++ enumerator), 686 GPTIMER_COUNT_UP (C++ enumerator), 686 gptimer_del_timer (C++ function), 683 gptimer_event_callbacks_t (C++ class), 684 gptimer_event_callbacks_t::on_alarm (C++ member), 685 gptimer_get_raw_count (C++ function), 683 gptimer_handle_t (C++ type), 685 gptimer_new_timer (C++ function), 682 gptimer_register_event_callbacks (C++ function), 683 gptimer_set_alarm_action (C++ function), 684 gptimer_set_raw_count (C++ function), 683 gptimer_start (C++ function), 684 gptimer_stop (C++ function), 684 Espressif Systems 2186 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index H heap_trace_record_t::address (C++ mem- heap_caps_add_region (C++ function), 1522 ber), 1536 heap_caps_add_region_with_caps (C++ heap_trace_record_t::alloced_by (C++ function), 1522 member), 1536 heap_caps_aligned_alloc (C++ function), heap_trace_record_t::ccount (C++ mem- 1517 ber), 1536 heap_caps_aligned_calloc (C++ function), heap_trace_record_t::freed_by (C++ 1517 member), 1536 heap_caps_aligned_free (C++ function), 1517 heap_trace_record_t::size (C++ member), heap_caps_calloc (C++ function), 1517 1536 heap_caps_calloc_prefer (C++ function), heap_trace_resume (C++ function), 1535 1520 heap_trace_start (C++ function), 1535 heap_caps_check_integrity (C++ function), heap_trace_stop (C++ function), 1535 1519 HMAC_KEY0 (C++ enumerator), 693 heap_caps_check_integrity_addr (C++ HMAC_KEY1 (C++ enumerator), 693 function), 1519 HMAC_KEY2 (C++ enumerator), 693 heap_caps_check_integrity_all (C++ func- HMAC_KEY3 (C++ enumerator), 693 tion), 1518 HMAC_KEY4 (C++ enumerator), 693 heap_caps_dump (C++ function), 1520 HMAC_KEY5 (C++ enumerator), 693 heap_caps_dump_all (C++ function), 1520 hmac_key_id_t (C++ enum), 693 heap_caps_enable_nonos_stack_heaps HMAC_KEY_MAX (C++ enumerator), 693 (C++ function), 1522 HOST_CONNECTION_MODE_CLI_UART (C++ enu- heap_caps_free (C++ function), 1516 merator), 612 heap_caps_get_allocated_size (C++ func- HOST_CONNECTION_MODE_NONE (C++ enumera- tion), 1520 tor), 612 heap_caps_get_free_size (C++ function), HOST_CONNECTION_MODE_RCP_UART (C++ enu- 1518 merator), 612 heap_caps_get_info (C++ function), 1518 HTTP_AUTH_TYPE_BASIC (C++ enumerator), 108 heap_caps_get_largest_free_block (C++ HTTP_AUTH_TYPE_DIGEST (C++ enumerator), 108 function), 1518 HTTP_AUTH_TYPE_NONE (C++ enumerator), 108 heap_caps_get_minimum_free_size (C++ http_client_init_cb_t (C++ type), 1382 function), 1518 HTTP_EVENT_DISCONNECTED (C++ enumerator), heap_caps_get_total_size (C++ function), 107 1518 HTTP_EVENT_ERROR (C++ enumerator), 107 heap_caps_init (C++ function), 1522 http_event_handle_cb (C++ type), 106 heap_caps_malloc (C++ function), 1516 HTTP_EVENT_HEADER_SENT (C++ enumerator), heap_caps_malloc_extmem_enable (C++ 107 function), 1519 HTTP_EVENT_HEADERS_SENT (C++ enumerator), heap_caps_malloc_prefer (C++ function), 107 1519 HTTP_EVENT_ON_CONNECTED (C++ enumerator), heap_caps_print_heap_info (C++ function), 107 1518 HTTP_EVENT_ON_DATA (C++ enumerator), 107 heap_caps_realloc (C++ function), 1517 HTTP_EVENT_ON_FINISH (C++ enumerator), 107 heap_caps_realloc_prefer (C++ function), HTTP_EVENT_ON_HEADER (C++ enumerator), 107 1519 HTTP_EVENT_REDIRECT (C++ enumerator), 107 heap_caps_register_failed_alloc_callbacHkTTP_METHOD_COPY (C++ enumerator), 108 (C++ function), 1516 HTTP_METHOD_DELETE (C++ enumerator), 107 HEAP_TRACE_ALL (C++ enumerator), 1536 HTTP_METHOD_GET (C++ enumerator), 107 heap_trace_dump (C++ function), 1536 HTTP_METHOD_HEAD (C++ enumerator), 107 heap_trace_get (C++ function), 1536 HTTP_METHOD_LOCK (C++ enumerator), 108 heap_trace_get_count (C++ function), 1535 HTTP_METHOD_MAX (C++ enumerator), 108 heap_trace_init_standalone (C++ function), HTTP_METHOD_MKCOL (C++ enumerator), 108 1535 HTTP_METHOD_MOVE (C++ enumerator), 108 heap_trace_init_tohost (C++ function), 1535 HTTP_METHOD_NOTIFY (C++ enumerator), 107 HEAP_TRACE_LEAKS (C++ enumerator), 1536 HTTP_METHOD_OPTIONS (C++ enumerator), 108 heap_trace_mode_t (C++ enum), 1536 HTTP_METHOD_PATCH (C++ enumerator), 107 heap_trace_record_t (C++ class), 1536 HTTP_METHOD_POST (C++ enumerator), 107 HTTP_METHOD_PROPFIND (C++ enumerator), 108 Espressif Systems 2187 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index HTTP_METHOD_PROPPATCH (C++ enumerator), 108 httpd_config::max_resp_headers (C++ HTTP_METHOD_PUT (C++ enumerator), 107 member), 148 HTTP_METHOD_SUBSCRIBE (C++ enumerator), 108 httpd_config::max_uri_handlers (C++ HTTP_METHOD_UNLOCK (C++ enumerator), 108 member), 148 HTTP_METHOD_UNSUBSCRIBE (C++ enumerator), httpd_config::open_fn (C++ member), 149 108 httpd_config::recv_wait_timeout (C++ HTTP_TRANSPORT_OVER_SSL (C++ enumerator), member), 148 107 httpd_config::send_wait_timeout (C++ HTTP_TRANSPORT_OVER_TCP (C++ enumerator), member), 148 107 httpd_config::server_port (C++ member), HTTP_TRANSPORT_UNKNOWN (C++ enumerator), 148 107 httpd_config::stack_size (C++ member), HTTPD_200 (C macro), 151 148 HTTPD_204 (C macro), 151 httpd_config::task_priority (C++ mem- HTTPD_207 (C macro), 151 ber), 148 HTTPD_400 (C macro), 151 httpd_config::uri_match_fn (C++ member), HTTPD_400_BAD_REQUEST (C++ enumerator), 154 149 HTTPD_401_UNAUTHORIZED (C++ enumerator), httpd_config_t (C++ type), 153 154 HTTPD_DEFAULT_CONFIG (C macro), 151 HTTPD_403_FORBIDDEN (C++ enumerator), 154 HTTPD_ERR_CODE_MAX (C++ enumerator), 154 HTTPD_404 (C macro), 151 httpd_err_code_t (C++ enum), 154 HTTPD_404_NOT_FOUND (C++ enumerator), 154 httpd_err_handler_func_t (C++ type), 152 HTTPD_405_METHOD_NOT_ALLOWED (C++ enu- httpd_free_ctx_fn_t (C++ type), 153 merator), 154 httpd_get_client_list (C++ function), 148 HTTPD_408 (C macro), 151 httpd_get_global_transport_ctx (C++ HTTPD_408_REQ_TIMEOUT (C++ enumerator), 154 function), 147 HTTPD_411_LENGTH_REQUIRED (C++ enumera- httpd_get_global_user_ctx (C++ function), tor), 154 147 HTTPD_414_URI_TOO_LONG (C++ enumerator), httpd_handle_t (C++ type), 153 154 HTTPD_MAX_REQ_HDR_LEN (C macro), 150 HTTPD_431_REQ_HDR_FIELDS_TOO_LARGE HTTPD_MAX_URI_LEN (C macro), 150 (C++ enumerator), 154 httpd_method_t (C++ type), 153 HTTPD_500 (C macro), 151 httpd_open_func_t (C++ type), 153 HTTPD_500_INTERNAL_SERVER_ERROR (C++ httpd_pending_func_t (C++ type), 152 enumerator), 154 httpd_query_key_value (C++ function), 139 HTTPD_501_METHOD_NOT_IMPLEMENTED (C++ httpd_queue_work (C++ function), 146 enumerator), 154 httpd_recv_func_t (C++ type), 152 HTTPD_505_VERSION_NOT_SUPPORTED (C++ httpd_register_err_handler (C++ function), enumerator), 154 145 httpd_close_func_t (C++ type), 153 httpd_register_uri_handler (C++ function), httpd_config (C++ class), 148 135 httpd_config::backlog_conn (C++ member), httpd_req (C++ class), 149 148 httpd_req::aux (C++ member), 150 httpd_config::close_fn (C++ member), 149 httpd_req::content_len (C++ member), 150 httpd_config::core_id (C++ member), 148 httpd_req::free_ctx (C++ member), 150 httpd_config::ctrl_port (C++ member), 148 httpd_req::handle (C++ member), 149 httpd_config::global_transport_ctx httpd_req::ignore_sess_ctx_changes (C++ member), 149 (C++ member), 150 httpd_config::global_transport_ctx_freeh_tftnpd_req::method (C++ member), 149 (C++ member), 149 httpd_req::sess_ctx (C++ member), 150 httpd_config::global_user_ctx (C++ httpd_req::uri (C++ member), 149 member), 148 httpd_req::user_ctx (C++ member), 150 httpd_config::global_user_ctx_free_fn httpd_req_get_cookie_val (C++ function), (C++ member), 149 139 httpd_config::lru_purge_enable (C++ httpd_req_get_hdr_value_len (C++ func- member), 148 tion), 138 httpd_config::max_open_sockets (C++ httpd_req_get_hdr_value_str (C++ func- member), 148 tion), 138 Espressif Systems 2188 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index httpd_req_get_url_query_len (C++ function), 138 httpd_req_get_url_query_str (C++ function), 138 httpd_req_recv (C++ function), 137 httpd_req_t (C++ type), 151 httpd_req_to_sockfd (C++ function), 137 httpd_resp_send (C++ function), 140 httpd_resp_send_404 (C++ function), 143 httpd_resp_send_408 (C++ function), 143 httpd_resp_send_500 (C++ function), 143 httpd_resp_send_chunk (C++ function), 140 httpd_resp_send_err (C++ function), 142 httpd_resp_sendstr (C++ function), 141 httpd_resp_sendstr_chunk (C++ function), 141 httpd_resp_set_hdr (C++ function), 142 httpd_resp_set_status (C++ function), 141 httpd_resp_set_type (C++ function), 142 HTTPD_RESP_USE_STRLEN (C macro), 151 httpd_send (C++ function), 144 httpd_send_func_t (C++ type), 151 httpd_sess_get_ctx (C++ function), 146 httpd_sess_get_transport_ctx (C++ func- tion), 146 httpd_sess_set_ctx (C++ function), 146 httpd_sess_set_pending_override (C++ function), 137 httpd_sess_set_recv_override (C++ func- tion), 136 httpd_sess_set_send_override (C++ func- tion), 136 httpd_sess_set_transport_ctx (C++ func- tion), 147 httpd_sess_trigger_close (C++ function), 147 httpd_sess_update_lru_counter (C++ func- tion), 147 HTTPD_SOCK_ERR_FAIL (C macro), 150 HTTPD_SOCK_ERR_INVALID (C macro), 150 HTTPD_SOCK_ERR_TIMEOUT (C macro), 151 httpd_socket_recv (C++ function), 144 httpd_socket_send (C++ function), 144 httpd_ssl_config (C++ class), 155 httpd_ssl_config::cacert_len (C++ mem- ber), 156 httpd_ssl_config::cacert_pem (C++ mem- ber), 156 httpd_ssl_config::httpd (C++ member), 155 httpd_ssl_config::port_insecure (C++ member), 156 httpd_ssl_config::port_secure (C++ member), 156 httpd_ssl_config::prvtkey_len (C++ member), 156 httpd_ssl_config::prvtkey_pem (C++ member), 156 httpd_ssl_config::servercert (C++ member), 155 httpd_ssl_config::servercert_len (C++ member), 156 httpd_ssl_config::session_tickets (C++ member), 156 httpd_ssl_config::transport_mode (C++ member), 156 httpd_ssl_config::use_secure_element (C++ member), 156 httpd_ssl_config::user_cb (C++ member), 156 HTTPD_SSL_CONFIG_DEFAULT (C macro), 156 httpd_ssl_config_t (C++ type), 156 httpd_ssl_start (C++ function), 155 httpd_ssl_stop (C++ function), 155 HTTPD_SSL_TRANSPORT_INSECURE (C++ enu- merator), 157 httpd_ssl_transport_mode_t (C++ enum), 157 HTTPD_SSL_TRANSPORT_SECURE (C++ enumera- tor), 157 HTTPD_SSL_USER_CB_SESS_CLOSE (C++ enu- merator), 157 HTTPD_SSL_USER_CB_SESS_CREATE (C++ enu- merator), 157 httpd_ssl_user_cb_state_t (C++ enum), 157 httpd_start (C++ function), 145 httpd_stop (C++ function), 145 HTTPD_TYPE_JSON (C macro), 151 HTTPD_TYPE_OCTET (C macro), 151 HTTPD_TYPE_TEXT (C macro), 151 httpd_unregister_uri (C++ function), 136 httpd_unregister_uri_handler (C++ func- tion), 136 httpd_uri (C++ class), 150 httpd_uri::handler (C++ member), 150 httpd_uri::method (C++ member), 150 httpd_uri::uri (C++ member), 150 httpd_uri::user_ctx (C++ member), 150 httpd_uri_match_func_t (C++ type), 153 httpd_uri_match_wildcard (C++ function), 140 httpd_uri_t (C++ type), 151 httpd_work_fn_t (C++ type), 154 HttpStatus_BadRequest (C++ enumerator), 108 HttpStatus_Code (C++ enum), 108 HttpStatus_Forbidden (C++ enumerator), 108 HttpStatus_Found (C++ enumerator), 108 HttpStatus_InternalError (C++ enumerator), 109 HttpStatus_MovedPermanently (C++ enumer- ator), 108 HttpStatus_MultipleChoices (C++ enumera- tor), 108 HttpStatus_NotFound (C++ enumerator), 109 HttpStatus_Ok (C++ enumerator), 108 Espressif Systems 2189 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index HttpStatus_PermanentRedirect (C++ enumerator), 108 HttpStatus_SeeOther (C++ enumerator), 108 HttpStatus_TemporaryRedirect (C++ enu- merator), 108 HttpStatus_Unauthorized (C++ enumerator), 108 I i2c_ack_type_t (C++ enum), 713 I2C_ADDR_BIT_10 (C++ enumerator), 713 I2C_ADDR_BIT_7 (C++ enumerator), 713 I2C_ADDR_BIT_MAX (C++ enumerator), 713 i2c_addr_mode_t (C++ enum), 713 I2C_APB_CLK_FREQ (C macro), 711 I2C_CLK_FREQ_MAX (C macro), 712 i2c_cmd_handle_t (C++ type), 712 i2c_cmd_link_create (C++ function), 706 i2c_cmd_link_create_static (C++ function), 705 i2c_cmd_link_delete (C++ function), 706 i2c_cmd_link_delete_static (C++ function), 706 i2c_config_t (C++ class), 711 i2c_config_t::addr_10bit_en (C++ mem- ber), 711 i2c_config_t::clk_flags (C++ member), 711 i2c_config_t::clk_speed (C++ member), 711 i2c_config_t::master (C++ member), 711 i2c_config_t::maximum_speed (C++ mem- ber), 711 i2c_config_t::mode (C++ member), 711 i2c_config_t::scl_io_num (C++ member), 711 i2c_config_t::scl_pullup_en (C++ mem- ber), 711 i2c_config_t::sda_io_num (C++ member), 711 i2c_config_t::sda_pullup_en (C++ mem- ber), 711 i2c_config_t::slave (C++ member), 711 i2c_config_t::slave_addr (C++ member), 711 I2C_DATA_MODE_LSB_FIRST (C++ enumerator), 713 I2C_DATA_MODE_MAX (C++ enumerator), 713 I2C_DATA_MODE_MSB_FIRST (C++ enumerator), 713 i2c_driver_delete (C++ function), 704 i2c_driver_install (C++ function), 703 i2c_filter_disable (C++ function), 709 i2c_filter_enable (C++ function), 708 i2c_get_data_mode (C++ function), 710 i2c_get_data_timing (C++ function), 710 i2c_get_period (C++ function), 708 i2c_get_start_timing (C++ function), 709 i2c_get_stop_timing (C++ function), 709 i2c_get_timeout (C++ function), 710 I2C_INTERNAL_STRUCT_SIZE (C macro), 712 I2C_LINK_RECOMMENDED_SIZE (C macro), 712 I2C_MASTER_ACK (C++ enumerator), 713 I2C_MASTER_ACK_MAX (C++ enumerator), 713 i2c_master_cmd_begin (C++ function), 707 I2C_MASTER_LAST_NACK (C++ enumerator), 713 I2C_MASTER_NACK (C++ enumerator), 713 I2C_MASTER_READ (C++ enumerator), 712 i2c_master_read (C++ function), 707 i2c_master_read_byte (C++ function), 707 i2c_master_read_from_device (C++ func- tion), 705 i2c_master_start (C++ function), 706 i2c_master_stop (C++ function), 707 I2C_MASTER_WRITE (C++ enumerator), 712 i2c_master_write (C++ function), 706 i2c_master_write_byte (C++ function), 706 i2c_master_write_read_device (C++ func- tion), 705 i2c_master_write_to_device (C++ function), 704 I2C_MODE_MASTER (C++ enumerator), 712 I2C_MODE_MAX (C++ enumerator), 712 I2C_MODE_SLAVE (C++ enumerator), 712 i2c_mode_t (C++ enum), 712 I2C_NUM_0 (C macro), 711 I2C_NUM_1 (C macro), 711 I2C_NUM_MAX (C macro), 711 i2c_param_config (C++ function), 704 i2c_port_t (C++ type), 712 i2c_reset_rx_fifo (C++ function), 704 i2c_reset_tx_fifo (C++ function), 704 i2c_rw_t (C++ enum), 712 I2C_SCLK_DEFAULT (C++ enumerator), 713 I2C_SCLK_MAX (C++ enumerator), 713 I2C_SCLK_RTC (C++ enumerator), 713 I2C_SCLK_SRC_FLAG_AWARE_DFS (C macro), 712 I2C_SCLK_SRC_FLAG_FOR_NOMAL (C macro), 711 I2C_SCLK_SRC_FLAG_LIGHT_SLEEP (C macro), 712 i2c_sclk_t (C++ enum), 713 I2C_SCLK_XTAL (C++ enumerator), 713 i2c_set_data_mode (C++ function), 710 i2c_set_data_timing (C++ function), 710 i2c_set_period (C++ function), 708 i2c_set_pin (C++ function), 704 i2c_set_start_timing (C++ function), 709 i2c_set_stop_timing (C++ function), 709 i2c_set_timeout (C++ function), 710 i2c_slave_read_buffer (C++ function), 708 i2c_slave_write_buffer (C++ function), 708 i2c_trans_mode_t (C++ enum), 712 I2S_BITS_PER_CHAN_16BIT (C++ enumerator), 724 I2S_BITS_PER_CHAN_24BIT (C++ enumerator), 725 Espressif Systems 2190 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index I2S_BITS_PER_CHAN_32BIT (C++ enumerator), 725 I2S_BITS_PER_CHAN_8BIT (C++ enumerator), 724 I2S_BITS_PER_CHAN_DEFAULT (C++ enumerator), 724 i2s_bits_per_chan_t (C++ enum), 724 I2S_BITS_PER_SAMPLE_16BIT (C++ enumera- tor), 724 I2S_BITS_PER_SAMPLE_24BIT (C++ enumera- tor), 724 I2S_BITS_PER_SAMPLE_32BIT (C++ enumera- tor), 724 I2S_BITS_PER_SAMPLE_8BIT (C++ enumerator), 724 i2s_bits_per_sample_t (C++ enum), 724 I2S_CHANNEL_FMT_ALL_LEFT (C++ enumerator), 726 I2S_CHANNEL_FMT_ALL_RIGHT (C++ enumera- tor), 726 I2S_CHANNEL_FMT_MULTIPLE (C++ enumerator), 726 I2S_CHANNEL_FMT_ONLY_LEFT (C++ enumera- tor), 726 I2S_CHANNEL_FMT_ONLY_RIGHT (C++ enumera- tor), 726 I2S_CHANNEL_FMT_RIGHT_LEFT (C++ enumera- tor), 726 i2s_channel_fmt_t (C++ enum), 726 I2S_CHANNEL_MONO (C++ enumerator), 725 I2S_CHANNEL_STEREO (C++ enumerator), 725 i2s_channel_t (C++ enum), 725 I2S_CLK_D2CLK (C++ enumerator), 727 i2s_clock_src_t (C++ enum), 727 I2S_COMM_FORMAT_I2S (C++ enumerator), 726 I2S_COMM_FORMAT_I2S_LSB (C++ enumerator), 726 I2S_COMM_FORMAT_I2S_MSB (C++ enumerator), 726 I2S_COMM_FORMAT_PCM (C++ enumerator), 726 I2S_COMM_FORMAT_PCM_LONG (C++ enumerator), 726 I2S_COMM_FORMAT_PCM_SHORT (C++ enumera- tor), 726 I2S_COMM_FORMAT_STAND_I2S (C++ enumera- tor), 726 I2S_COMM_FORMAT_STAND_MAX (C++ enumera- tor), 726 I2S_COMM_FORMAT_STAND_MSB (C++ enumera- tor), 726 I2S_COMM_FORMAT_STAND_PCM_LONG (C++ enumerator), 726 I2S_COMM_FORMAT_STAND_PCM_SHORT (C++ enumerator), 726 i2s_comm_format_t (C++ enum), 726 i2s_config_t (C++ type), 723 i2s_driver_config_t (C++ class), 722 i2s_driver_config_t::big_edin (C++ member), 723 i2s_driver_config_t::bit_order_msb (C++ member), 723 i2s_driver_config_t::bits_per_chan (C++ member), 723 i2s_driver_config_t::bits_per_sample (C++ member), 722 i2s_driver_config_t::chan_mask (C++ member), 723 i2s_driver_config_t::channel_format (C++ member), 722 i2s_driver_config_t::communication_format (C++ member), 722 i2s_driver_config_t::dma_buf_count (C++ member), 722 i2s_driver_config_t::dma_buf_len (C++ member), 723 i2s_driver_config_t::dma_desc_num (C++ member), 722 i2s_driver_config_t::dma_frame_num (C++ member), 722 i2s_driver_config_t::fixed_mclk (C++ member), 723 i2s_driver_config_t::intr_alloc_flags (C++ member), 722 i2s_driver_config_t::left_align (C++ member), 723 i2s_driver_config_t::mclk_multiple (C++ member), 723 i2s_driver_config_t::mode (C++ member), 722 i2s_driver_config_t::sample_rate (C++ member), 722 i2s_driver_config_t::skip_msk (C++ member), 723 i2s_driver_config_t::total_chan (C++ member), 723 i2s_driver_config_t::tx_desc_auto_clear (C++ member), 723 i2s_driver_config_t::use_apll (C++ member), 723 i2s_driver_install (C++ function), 718 i2s_driver_uninstall (C++ function), 719 I2S_EVENT_DMA_ERROR (C++ enumerator), 724 I2S_EVENT_MAX (C++ enumerator), 724 I2S_EVENT_RX_DONE (C++ enumerator), 724 I2S_EVENT_RX_Q_OVF (C++ enumerator), 724 i2s_event_t (C++ class), 723 i2s_event_t::size (C++ member), 723 i2s_event_t::type (C++ member), 723 I2S_EVENT_TX_DONE (C++ enumerator), 724 I2S_EVENT_TX_Q_OVF (C++ enumerator), 724 i2s_event_type_t (C++ enum), 724 i2s_get_clk (C++ function), 721 i2s_isr_handle_t (C++ type), 723 I2S_MCLK_MULTIPLE_128 (C++ enumerator), 727 I2S_MCLK_MULTIPLE_256 (C++ enumerator), 727 I2S_MCLK_MULTIPLE_384 (C++ enumerator), 727 Espressif Systems 2191 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index I2S_MCLK_MULTIPLE_DEFAULT (C++ enumera- i2s_set_pdm_rx_down_sample (C++ function), tor), 727 718 i2s_mclk_multiple_t (C++ enum), 727 i2s_set_pdm_tx_up_sample (C++ function), I2S_MODE_MASTER (C++ enumerator), 727 718 I2S_MODE_PDM (C++ enumerator), 727 i2s_set_pin (C++ function), 717 I2S_MODE_RX (C++ enumerator), 727 i2s_set_sample_rates (C++ function), 720 I2S_MODE_SLAVE (C++ enumerator), 727 i2s_start (C++ function), 720 i2s_mode_t (C++ enum), 726 i2s_stop (C++ function), 720 I2S_MODE_TX (C++ enumerator), 727 I2S_TDM_ACTIVE_CH0 (C++ enumerator), 725 I2S_NUM_0 (C++ enumerator), 724 I2S_TDM_ACTIVE_CH1 (C++ enumerator), 725 I2S_NUM_1 (C++ enumerator), 724 I2S_TDM_ACTIVE_CH10 (C++ enumerator), 725 I2S_NUM_MAX (C++ enumerator), 724 I2S_TDM_ACTIVE_CH11 (C++ enumerator), 725 I2S_PCM_A_COMPRESS (C++ enumerator), 727 I2S_TDM_ACTIVE_CH12 (C++ enumerator), 725 I2S_PCM_A_DECOMPRESS (C++ enumerator), 727 I2S_TDM_ACTIVE_CH13 (C++ enumerator), 725 i2s_pcm_cfg_t (C++ class), 721 I2S_TDM_ACTIVE_CH14 (C++ enumerator), 725 i2s_pcm_cfg_t::pcm_type (C++ member), 721 I2S_TDM_ACTIVE_CH15 (C++ enumerator), 725 i2s_pcm_compress_t (C++ enum), 727 I2S_TDM_ACTIVE_CH2 (C++ enumerator), 725 i2s_pcm_config (C++ function), 720 I2S_TDM_ACTIVE_CH3 (C++ enumerator), 725 I2S_PCM_DISABLE (C++ enumerator), 727 I2S_TDM_ACTIVE_CH4 (C++ enumerator), 725 I2S_PCM_U_COMPRESS (C++ enumerator), 727 I2S_TDM_ACTIVE_CH5 (C++ enumerator), 725 I2S_PCM_U_DECOMPRESS (C++ enumerator), 727 I2S_TDM_ACTIVE_CH6 (C++ enumerator), 725 I2S_PDM_DEFAULT_UPSAMPLE_CONFIG (C I2S_TDM_ACTIVE_CH7 (C++ enumerator), 725 macro), 723 I2S_TDM_ACTIVE_CH8 (C++ enumerator), 725 I2S_PDM_DSR_16S (C++ enumerator), 728 I2S_TDM_ACTIVE_CH9 (C++ enumerator), 725 I2S_PDM_DSR_8S (C++ enumerator), 727 i2s_write (C++ function), 719 I2S_PDM_DSR_MAX (C++ enumerator), 728 i2s_write_expand (C++ function), 719 i2s_pdm_dsr_t (C++ enum), 727 i2s_zero_dma_buffer (C++ function), 720 i2s_pdm_sig_scale_t (C++ enum), 728 I_ADC (C macro), 1641 I2S_PDM_SIG_SCALING_DIV_2 (C++ enumera- I_ADDI (C macro), 1646 tor), 728 I_ADDR (C macro), 1646 I2S_PDM_SIG_SCALING_MUL_1 (C++ enumera- I_ANDI (C macro), 1646 tor), 728 I_ANDR (C macro), 1646 I2S_PDM_SIG_SCALING_MUL_2 (C++ enumera- I_BE (C macro), 1645 tor), 728 I_BG (C macro), 1645 I2S_PDM_SIG_SCALING_MUL_4 (C++ enumera- I_BL (C macro), 1645 tor), 728 I_BSGE (C macro), 1645 i2s_pdm_tx_upsample_cfg_t (C++ class), 721 I_BSL (C macro), 1646 i2s_pdm_tx_upsample_cfg_t::fp (C++ I_BSLE (C macro), 1645 member), 722 I_BXFI (C macro), 1645 i2s_pdm_tx_upsample_cfg_t::fs (C++ I_BXFR (C macro), 1645 member), 722 I_BXI (C macro), 1645 i2s_pdm_tx_upsample_cfg_t::sample_rate I_BXR (C macro), 1645 (C++ member), 722 I_BXZI (C macro), 1645 i2s_pin_config_t (C++ class), 722 I_BXZR (C macro), 1645 i2s_pin_config_t::bck_io_num (C++ mem- I_DELAY (C macro), 1641 ber), 722 I_END (C macro), 1641 i2s_pin_config_t::data_in_num (C++ I_HALT (C macro), 1641 member), 722 I_LD (C macro), 1644 i2s_pin_config_t::data_out_num (C++ I_LD_MANUAL (C macro), 1644 member), 722 I_LDH (C macro), 1645 i2s_pin_config_t::mck_io_num (C++ mem- I_LDL (C macro), 1645 ber), 722 I_LSHI (C macro), 1646 i2s_pin_config_t::ws_io_num (C++ mem- I_LSHR (C macro), 1646 ber), 722 I_MOVI (C macro), 1646 I2S_PIN_NO_CHANGE (C macro), 723 I_MOVR (C macro), 1646 i2s_port_t (C++ enum), 724 I_ORI (C macro), 1646 i2s_read (C++ function), 719 I_ORR (C macro), 1646 i2s_set_clk (C++ function), 721 I_RD_REG (C macro), 1641 Espressif Systems 2192 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index I_RSHI (C macro), 1646 ip_event_got_ip_t (C++ class), 630 I_RSHR (C macro), 1646 ip_event_got_ip_t::esp_netif (C++ mem- I_ST (C macro), 1642 ber), 630 I_ST32 (C macro), 1642 ip_event_got_ip_t::if_index (C++ mem- I_ST_AUTO (C macro), 1643 ber), 630 I_ST_MANUAL (C macro), 1641 ip_event_got_ip_t::ip_changed (C++ I_STAGE_DEC (C macro), 1646 member), 630 I_STAGE_INC (C macro), 1646 ip_event_got_ip_t::ip_info (C++ member), I_STAGE_RST (C macro), 1646 630 I_STH (C macro), 1642 IP_EVENT_PPP_GOT_IP (C++ enumerator), 634 I_STH_LABEL (C macro), 1643 IP_EVENT_PPP_LOST_IP (C++ enumerator), 634 I_STI (C macro), 1644 IP_EVENT_STA_GOT_IP (C++ enumerator), 634 I_STI32 (C macro), 1644 IP_EVENT_STA_LOST_IP (C++ enumerator), 634 I_STI_LABEL (C macro), 1644 ip_event_t (C++ enum), 634 I_STL (C macro), 1642 IPSTR (C macro), 635 I_STL_LABEL (C macro), 1642 IPV62STR (C macro), 635 I_STO (C macro), 1644 IPV6STR (C macro), 635 I_SUBI (C macro), 1646 I_SUBR (C macro), 1646 L I_TSENS (C macro), 1641 L2TAP_G_INTF_DEVICE (C++ enumerator), 637 I_WAKE (C macro), 1641 L2TAP_G_RCV_FILTER (C++ enumerator), 637 I_WR_REG (C macro), 1641 l2tap_ioctl_opt_t (C++ enum), 637 I_WR_REG_BIT (C macro), 1641 L2TAP_S_INTF_DEVICE (C++ enumerator), 637 iface_destroy (C++ type), 64 L2TAP_S_RCV_FILTER (C++ enumerator), 637 iface_init (C++ type), 64 L2TAP_VFS_CONFIG_DEFAULT (C macro), 636 iface_setup (C++ type), 64 l2tap_vfs_config_t (C++ class), 636 iface_start (C++ type), 64 L2TAP_VFS_DEFAULT_PATH (C macro), 636 intr_handle_data_t (C++ type), 1553 LCD_CLK_SRC_APLL (C++ enumerator), 729 intr_handle_t (C++ type), 1553 LCD_CLK_SRC_PLL160M (C++ enumerator), 729 intr_handler_t (C++ type), 1553 LCD_CLK_SRC_PLL240M (C++ enumerator), 729 IP2STR (C macro), 635 LCD_CLK_SRC_XTAL (C++ enumerator), 729 ip_event_add_ip6_t (C++ class), 631 lcd_clock_source_t (C++ enum), 729 ip_event_add_ip6_t::addr (C++ member), LEDC_APB_CLK (C++ enumerator), 753 631 LEDC_APB_CLK_HZ (C macro), 752 ip_event_add_ip6_t::preferred (C++ LEDC_AUTO_CLK (C++ enumerator), 753 member), 631 ledc_bind_channel_timer (C++ function), 747 IP_EVENT_AP_STAIPASSIGNED (C++ enumera- ledc_cb_event_t (C++ enum), 752 tor), 634 ledc_cb_param_t (C++ class), 751 ip_event_ap_staipassigned_t (C++ class), ledc_cb_param_t::channel (C++ member), 631 751 ip_event_ap_staipassigned_t::esp_netif ledc_cb_param_t::duty (C++ member), 751 (C++ member), 631 ledc_cb_param_t::event (C++ member), 751 ip_event_ap_staipassigned_t::ip (C++ ledc_cb_param_t::speed_mode (C++ mem- member), 631 ber), 751 ip_event_ap_staipassigned_t::mac (C++ ledc_cb_register (C++ function), 750 member), 631 ledc_cb_t (C++ type), 752 IP_EVENT_ETH_GOT_IP (C++ enumerator), 634 ledc_cbs_t (C++ class), 751 IP_EVENT_ETH_LOST_IP (C++ enumerator), 634 ledc_cbs_t::fade_cb (C++ member), 752 IP_EVENT_GOT_IP6 (C++ enumerator), 634 LEDC_CHANNEL_0 (C++ enumerator), 753 ip_event_got_ip6_t (C++ class), 630 LEDC_CHANNEL_1 (C++ enumerator), 754 ip_event_got_ip6_t::esp_netif (C++ LEDC_CHANNEL_2 (C++ enumerator), 754 member), 631 LEDC_CHANNEL_3 (C++ enumerator), 754 ip_event_got_ip6_t::if_index (C++ mem- LEDC_CHANNEL_4 (C++ enumerator), 754 ber), 631 LEDC_CHANNEL_5 (C++ enumerator), 754 ip_event_got_ip6_t::ip6_info (C++ mem- LEDC_CHANNEL_6 (C++ enumerator), 754 ber), 631 LEDC_CHANNEL_7 (C++ enumerator), 754 ip_event_got_ip6_t::ip_index (C++ mem- ledc_channel_config (C++ function), 743 ber), 631 ledc_channel_config_t (C++ class), 750 Espressif Systems 2193 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ledc_channel_config_t::channel (C++ member), 750 ledc_channel_config_t::duty (C++ member), 751 ledc_channel_config_t::flags (C++ member), 751 ledc_channel_config_t::gpio_num (C++ member), 750 ledc_channel_config_t::hpoint (C++ member), 751 ledc_channel_config_t::intr_type (C++ member), 750 ledc_channel_config_t::output_invert (C++ member), 751 ledc_channel_config_t::speed_mode (C++ member), 750 ledc_channel_config_t::timer_sel (C++ member), 750 LEDC_CHANNEL_MAX (C++ enumerator), 754 ledc_channel_t (C++ enum), 753 ledc_clk_cfg_t (C++ enum), 753 ledc_clk_src_t (C++ enum), 753 LEDC_DUTY_DIR_DECREASE (C++ enumerator), 752 LEDC_DUTY_DIR_INCREASE (C++ enumerator), 752 LEDC_DUTY_DIR_MAX (C++ enumerator), 753 ledc_duty_direction_t (C++ enum), 752 LEDC_ERR_DUTY (C macro), 752 LEDC_ERR_VAL (C macro), 752 LEDC_FADE_END_EVT (C++ enumerator), 752 ledc_fade_func_install (C++ function), 748 ledc_fade_func_uninstall (C++ function), 748 LEDC_FADE_MAX (C++ enumerator), 755 ledc_fade_mode_t (C++ enum), 755 LEDC_FADE_NO_WAIT (C++ enumerator), 755 ledc_fade_start (C++ function), 748 ledc_fade_stop (C++ function), 749 LEDC_FADE_WAIT_DONE (C++ enumerator), 755 ledc_get_duty (C++ function), 746 ledc_get_freq (C++ function), 745 ledc_get_hpoint (C++ function), 745 LEDC_INTR_DISABLE (C++ enumerator), 752 LEDC_INTR_FADE_END (C++ enumerator), 752 LEDC_INTR_MAX (C++ enumerator), 752 ledc_intr_type_t (C++ enum), 752 ledc_isr_handle_t (C++ type), 752 ledc_isr_register (C++ function), 746 LEDC_LOW_SPEED_MODE (C++ enumerator), 752 ledc_mode_t (C++ enum), 752 LEDC_REF_CLK_HZ (C macro), 752 LEDC_SCLK (C++ enumerator), 753 ledc_set_duty (C++ function), 745 ledc_set_duty_and_update (C++ function), 749 ledc_set_duty_with_hpoint (C++ function), 745 ledc_set_fade (C++ function), 746 ledc_set_fade_step_and_start (C++ func- tion), 750 ledc_set_fade_time_and_start (C++ func- tion), 749 ledc_set_fade_with_step (C++ function), 747 ledc_set_fade_with_time (C++ function), 748 ledc_set_freq (C++ function), 744 ledc_set_pin (C++ function), 744 LEDC_SLOW_CLK_APB (C++ enumerator), 753 LEDC_SLOW_CLK_RTC8M (C++ enumerator), 753 ledc_slow_clk_sel_t (C++ enum), 753 LEDC_SLOW_CLK_XTAL (C++ enumerator), 753 LEDC_SPEED_MODE_MAX (C++ enumerator), 752 ledc_stop (C++ function), 744 LEDC_TIMER_0 (C++ enumerator), 753 LEDC_TIMER_1 (C++ enumerator), 753 LEDC_TIMER_10_BIT (C++ enumerator), 754 LEDC_TIMER_11_BIT (C++ enumerator), 754 LEDC_TIMER_12_BIT (C++ enumerator), 754 LEDC_TIMER_13_BIT (C++ enumerator), 754 LEDC_TIMER_14_BIT (C++ enumerator), 754 LEDC_TIMER_1_BIT (C++ enumerator), 754 LEDC_TIMER_2 (C++ enumerator), 753 LEDC_TIMER_2_BIT (C++ enumerator), 754 LEDC_TIMER_3 (C++ enumerator), 753 LEDC_TIMER_3_BIT (C++ enumerator), 754 LEDC_TIMER_4_BIT (C++ enumerator), 754 LEDC_TIMER_5_BIT (C++ enumerator), 754 LEDC_TIMER_6_BIT (C++ enumerator), 754 LEDC_TIMER_7_BIT (C++ enumerator), 754 LEDC_TIMER_8_BIT (C++ enumerator), 754 LEDC_TIMER_9_BIT (C++ enumerator), 754 LEDC_TIMER_BIT_MAX (C++ enumerator), 755 ledc_timer_bit_t (C++ enum), 754 ledc_timer_config (C++ function), 744 ledc_timer_config_t (C++ class), 751 ledc_timer_config_t::bit_num (C++ mem- ber), 751 ledc_timer_config_t::clk_cfg (C++ mem- ber), 751 ledc_timer_config_t::duty_resolution (C++ member), 751 ledc_timer_config_t::freq_hz (C++ mem- ber), 751 ledc_timer_config_t::speed_mode (C++ member), 751 ledc_timer_config_t::timer_num (C++ member), 751 LEDC_TIMER_MAX (C++ enumerator), 753 ledc_timer_pause (C++ function), 747 ledc_timer_resume (C++ function), 747 ledc_timer_rst (C++ function), 747 ledc_timer_set (C++ function), 746 ledc_timer_t (C++ enum), 753 ledc_update_duty (C++ function), 744 LEDC_USE_APB_CLK (C++ enumerator), 753 LEDC_USE_RTC8M_CLK (C++ enumerator), 753 Espressif Systems 2194 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index LEDC_USE_XTAL_CLK (C++ enumerator), 753 linenoiseCompletions (C++ type), 1353 M M_BE (C macro), 1647 M_BG (C macro), 1647 M_BL (C macro), 1647 M_BRANCH (C macro), 1646 M_BX (C macro), 1647 M_BXF (C macro), 1647 M_BXZ (C macro), 1647 M_LABEL (C macro), 1646 MAC2STR (C macro), 1565 MACSTR (C macro), 1565 MALLOC_CAP_32BIT (C macro), 1520 MALLOC_CAP_8BIT (C macro), 1520 MALLOC_CAP_DEFAULT (C macro), 1521 MALLOC_CAP_DMA (C macro), 1520 MALLOC_CAP_EXEC (C macro), 1520 MALLOC_CAP_INTERNAL (C macro), 1521 MALLOC_CAP_INVALID (C macro), 1521 MALLOC_CAP_IRAM_8BIT (C macro), 1521 MALLOC_CAP_PID2 (C macro), 1520 MALLOC_CAP_PID3 (C macro), 1521 MALLOC_CAP_PID4 (C macro), 1521 MALLOC_CAP_PID5 (C macro), 1521 MALLOC_CAP_PID6 (C macro), 1521 MALLOC_CAP_PID7 (C macro), 1521 MALLOC_CAP_RETENTION (C macro), 1521 MALLOC_CAP_RTCRAM (C macro), 1521 MALLOC_CAP_SPIRAM (C macro), 1521 MAX_BLE_DEVNAME_LEN (C macro), 1213 MAX_BLE_MANUFACTURER_DATA_LEN (C macro), 1213 MAX_FDS (C macro), 1328 MAX_PASSPHRASE_LEN (C macro), 576 MAX_SSID_LEN (C macro), 576 MAX_WPS_AP_CRED (C macro), 576 mb_communication_info_t (C++ union), 62 mb_communication_info_t::baudrate (C++ member), 63 mb_communication_info_t::dummy_port (C++ member), 63 mb_communication_info_t::ip_addr (C++ member), 63 mb_communication_info_t::ip_addr_type (C++ member), 63 mb_communication_info_t::ip_mode (C++ member), 63 mb_communication_info_t::ip_netif_ptr (C++ member), 63 mb_communication_info_t::ip_port (C++ member), 63 mb_communication_info_t::mode (C++ member), 63 mb_communication_info_t::parity (C++ member), 63 mb_communication_info_t::port (C++ member), 63 mb_communication_info_t::slave_addr (C++ member), 63 mb_communication_info_t::[anonymous] (C++ member), 63 MB_CONTROLLER_PRIORITY (C macro), 63 MB_CONTROLLER_STACK_SIZE (C macro), 63 mb_descr_size_t (C++ enum), 69 mb_descr_type_t (C++ enum), 69 MB_DEVICE_ADDRESS (C macro), 63 MB_DEVICE_SPEED (C macro), 63 MB_EVENT_COILS_RD (C++ enumerator), 64 MB_EVENT_COILS_WR (C++ enumerator), 64 MB_EVENT_DISCRETE_RD (C++ enumerator), 64 mb_event_group_t (C++ enum), 64 MB_EVENT_HOLDING_REG_RD (C++ enumerator), 64 MB_EVENT_HOLDING_REG_WR (C++ enumerator), 64 MB_EVENT_INPUT_REG_RD (C++ enumerator), 64 MB_EVENT_NO_EVENTS (C++ enumerator), 64 MB_EVENT_STACK_STARTED (C++ enumerator), 64 MB_IPV4 (C++ enumerator), 65 MB_IPV6 (C++ enumerator), 65 MB_MASTER_ASSERT (C macro), 69 MB_MASTER_CHECK (C macro), 69 MB_MODE_ASCII (C++ enumerator), 65 MB_MODE_RTU (C++ enumerator), 65 MB_MODE_TCP (C++ enumerator), 65 mb_mode_type_t (C++ enum), 65 MB_MODE_UDP (C++ enumerator), 65 MB_PAR_INFO_TOUT (C macro), 63 MB_PARAM_COIL (C++ enumerator), 65 MB_PARAM_COUNT (C++ enumerator), 65 MB_PARAM_DISCRETE (C++ enumerator), 65 MB_PARAM_HOLDING (C++ enumerator), 64 mb_param_info_t (C++ class), 71 mb_param_info_t::address (C++ member), 71 mb_param_info_t::mb_offset (C++ member), 71 mb_param_info_t::size (C++ member), 71 mb_param_info_t::time_stamp (C++ mem- ber), 71 mb_param_info_t::type (C++ member), 71 MB_PARAM_INPUT (C++ enumerator), 65 mb_param_perms_t (C++ enum), 70 mb_param_request_t (C++ class), 69 mb_param_request_t::command (C++ mem- ber), 69 mb_param_request_t::reg_size (C++ mem- ber), 69 mb_param_request_t::reg_start (C++ member), 69 mb_param_request_t::slave_addr (C++ member), 69 mb_param_type_t (C++ enum), 64 MB_PARAM_UNKNOWN (C++ enumerator), 65 Espressif Systems 2195 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index mb_parameter_descriptor_t (C++ class), 68 mbc_master_get_cid_info (C++ function), 66 mb_parameter_descriptor_t::access mbc_master_get_parameter (C++ function), 67 (C++ member), 68 mbc_master_init (C++ function), 65 mb_parameter_descriptor_t::cid (C++ mbc_master_init_iface (C++ function), 66 member), 68 mbc_master_init_tcp (C++ function), 65 mb_parameter_descriptor_t::mb_param_typmebc_master_send_request (C++ function), 66 (C++ member), 68 mbc_master_set_descriptor (C++ function), mb_parameter_descriptor_t::mb_reg_start 66 (C++ member), 68 mbc_master_set_parameter (C++ function), 67 mb_parameter_descriptor_t::mb_size mbc_master_setup (C++ function), 66 (C++ member), 68 mbc_master_start (C++ function), 66 mb_parameter_descriptor_t::mb_slave_addmrbc_slave_check_event (C++ function), 71 (C++ member), 68 mbc_slave_destroy (C++ function), 70 mb_parameter_descriptor_t::param_key mbc_slave_get_param_info (C++ function), 71 (C++ member), 68 mbc_slave_init (C++ function), 70 mb_parameter_descriptor_t::param_offsetmbc_slave_init_iface (C++ function), 70 (C++ member), 68 mbc_slave_init_tcp (C++ function), 70 mb_parameter_descriptor_t::param_opts mbc_slave_set_descriptor (C++ function), 71 (C++ member), 68 mbc_slave_setup (C++ function), 71 mb_parameter_descriptor_t::param_size mbc_slave_start (C++ function), 71 (C++ member), 68 MCPWM0A (C++ enumerator), 774 mb_parameter_descriptor_t::param_type MCPWM0B (C++ enumerator), 774 (C++ member), 68 MCPWM1A (C++ enumerator), 774 mb_parameter_descriptor_t::param_units MCPWM1B (C++ enumerator), 774 (C++ member), 68 MCPWM2A (C++ enumerator), 774 mb_parameter_opt_t (C++ union), 67 MCPWM2B (C++ enumerator), 774 mb_parameter_opt_t::max (C++ member), 68 MCPWM_ACTION_FORCE_HIGH (C++ enumerator), mb_parameter_opt_t::min (C++ member), 68 778 mb_parameter_opt_t::opt1 (C++ member), 68 MCPWM_ACTION_FORCE_LOW (C++ enumerator), mb_parameter_opt_t::opt2 (C++ member), 68 778 mb_parameter_opt_t::opt3 (C++ member), 68 MCPWM_ACTION_NO_CHANGE (C++ enumerator), mb_parameter_opt_t::step (C++ member), 68 778 mb_parameter_opt_t::[anonymous] (C++ mcpwm_action_on_pwmxa_t (C++ type), 773 member), 68 mcpwm_action_on_pwmxb_t (C++ type), 773 MB_PARITY_NONE (C macro), 63 MCPWM_ACTION_TOGGLE (C++ enumerator), 778 MB_PORT_COUNT (C++ enumerator), 64 MCPWM_ACTIVE_HIGH_COMPLIMENT_MODE MB_PORT_INACTIVE (C++ enumerator), 64 (C++ enumerator), 778 MB_PORT_SERIAL_MASTER (C++ enumerator), 64 MCPWM_ACTIVE_HIGH_MODE (C++ enumerator), MB_PORT_SERIAL_SLAVE (C++ enumerator), 64 778 MB_PORT_TCP_MASTER (C++ enumerator), 64 MCPWM_ACTIVE_LOW_COMPLIMENT_MODE (C++ MB_PORT_TCP_SLAVE (C++ enumerator), 64 enumerator), 778 mb_port_type_t (C++ enum), 64 MCPWM_ACTIVE_LOW_MODE (C++ enumerator), 778 mb_register_area_descriptor_t (C++ MCPWM_ACTIVE_RED_FED_FROM_PWMXA (C++ class), 72 enumerator), 778 mb_register_area_descriptor_t::address MCPWM_ACTIVE_RED_FED_FROM_PWMXB (C++ (C++ member), 72 enumerator), 778 mb_register_area_descriptor_t::size MCPWM_BOTH_EDGE (C++ enumerator), 777 (C++ member), 72 MCPWM_BYPASS_FED (C++ enumerator), 778 mb_register_area_descriptor_t::start_ofMfCsPeWtM_BYPASS_RED (C++ enumerator), 777 (C++ member), 72 MCPWM_CAP_0 (C++ enumerator), 774 mb_register_area_descriptor_t::type MCPWM_CAP_1 (C++ enumerator), 774 (C++ member), 72 MCPWM_CAP_2 (C++ enumerator), 774 MB_RETURN_ON_FALSE (C macro), 63 mcpwm_capture_channel_id_t (C++ type), 773 MB_SLAVE_ASSERT (C macro), 72 mcpwm_capture_config_t (C++ class), 772 MB_SLAVE_CHECK (C macro), 72 mcpwm_capture_config_t::cap_edge (C++ mb_tcp_addr_type_t (C++ enum), 65 member), 772 MB_UART_PORT (C macro), 63 mcpwm_capture_config_t::cap_prescale mbc_master_destroy (C++ function), 66 (C++ member), 772 Espressif Systems 2196 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index mcpwm_capture_config_t::capture_cb mcpwm_deadtime_disable (C++ function), 767 (C++ member), 773 mcpwm_deadtime_enable (C++ function), 767 mcpwm_capture_config_t::user_data MCPWM_DEADTIME_TYPE_MAX (C++ enumerator), (C++ member), 773 778 mcpwm_capture_disable (C++ function), 768 mcpwm_deadtime_type_t (C++ enum), 777 mcpwm_capture_disable_channel (C++ func- MCPWM_DOWN_COUNTER (C++ enumerator), 777 tion), 769 MCPWM_DUTY_MODE_0 (C++ enumerator), 777 mcpwm_capture_enable (C++ function), 768 MCPWM_DUTY_MODE_1 (C++ enumerator), 777 mcpwm_capture_enable_channel (C++ func- MCPWM_DUTY_MODE_MAX (C++ enumerator), 777 tion), 769 mcpwm_duty_type_t (C++ enum), 777 mcpwm_capture_on_edge_t (C++ enum), 776 MCPWM_FAULT_0 (C++ enumerator), 774 mcpwm_capture_signal_get_edge (C++ func- MCPWM_FAULT_1 (C++ enumerator), 774 tion), 769 MCPWM_FAULT_2 (C++ enumerator), 774 mcpwm_capture_signal_get_value (C++ mcpwm_fault_deinit (C++ function), 768 function), 769 mcpwm_fault_init (C++ function), 767 mcpwm_capture_signal_t (C++ enum), 778 mcpwm_fault_input_level_t (C++ enum), 776 mcpwm_carrier_config_t (C++ class), 772 mcpwm_fault_set_cyc_mode (C++ function), mcpwm_carrier_config_t::carrier_duty 768 (C++ member), 772 mcpwm_fault_set_oneshot_mode (C++ func- mcpwm_carrier_config_t::carrier_ivt_mode tion), 767 (C++ member), 772 mcpwm_fault_signal_t (C++ enum), 775 mcpwm_carrier_config_t::carrier_os_modeMCPWM_FORCE_MCPWMXA_HIGH (C macro), 773 (C++ member), 772 MCPWM_FORCE_MCPWMXA_LOW (C macro), 773 mcpwm_carrier_config_t::carrier_period MCPWM_FORCE_MCPWMXB_HIGH (C macro), 773 (C++ member), 772 MCPWM_FORCE_MCPWMXB_LOW (C macro), 773 mcpwm_carrier_config_t::pulse_width_in_MoCsPWM_FREEZE_COUNTER (C++ enumerator), 777 (C++ member), 772 MCPWM_GEN_A (C++ enumerator), 775 mcpwm_carrier_disable (C++ function), 766 MCPWM_GEN_ACTION_HIGH (C++ enumerator), 762 mcpwm_carrier_enable (C++ function), 766 MCPWM_GEN_ACTION_KEEP (C++ enumerator), 762 mcpwm_carrier_init (C++ function), 765 MCPWM_GEN_ACTION_LOW (C++ enumerator), 762 mcpwm_carrier_oneshot_mode_disable MCPWM_GEN_ACTION_TOGGLE (C++ enumerator), (C++ function), 767 762 mcpwm_carrier_oneshot_mode_enable MCPWM_GEN_B (C++ enumerator), 775 (C++ function), 766 MCPWM_GEN_MAX (C++ enumerator), 775 mcpwm_carrier_os_t (C++ enum), 775 mcpwm_generator_action_t (C++ enum), 762 MCPWM_CARRIER_OUT_IVT_DIS (C++ enumera- mcpwm_generator_t (C++ enum), 775 tor), 775 mcpwm_get_duty (C++ function), 764 MCPWM_CARRIER_OUT_IVT_EN (C++ enumerator), mcpwm_get_duty_in_us (C++ function), 765 775 mcpwm_get_frequency (C++ function), 764 mcpwm_carrier_out_ivt_t (C++ enum), 775 mcpwm_gpio_init (C++ function), 762 mcpwm_carrier_output_invert (C++ func- mcpwm_group_set_resolution (C++ function), tion), 767 763 mcpwm_carrier_set_duty_cycle (C++ func- MCPWM_HAL_GENERATOR_MODE_FORCE_HIGH tion), 766 (C++ enumerator), 777 mcpwm_carrier_set_period (C++ function), MCPWM_HAL_GENERATOR_MODE_FORCE_LOW 766 (C++ enumerator), 777 mcpwm_config_t (C++ class), 772 MCPWM_HIGH_LEVEL_TGR (C++ enumerator), 776 mcpwm_config_t::cmpr_a (C++ member), 772 mcpwm_init (C++ function), 763 mcpwm_config_t::cmpr_b (C++ member), 772 mcpwm_intr_t (C++ enum), 777 mcpwm_config_t::counter_mode (C++ mem- mcpwm_io_signals_t (C++ enum), 774 ber), 772 mcpwm_isr_register (C++ function), 771 mcpwm_config_t::duty_mode (C++ member), MCPWM_LL_INTR_CAP0 (C++ enumerator), 777 772 MCPWM_LL_INTR_CAP1 (C++ enumerator), 777 mcpwm_config_t::frequency (C++ member), MCPWM_LL_INTR_CAP2 (C++ enumerator), 777 772 MCPWM_LOW_LEVEL_TGR (C++ enumerator), 776 MCPWM_COUNTER_MAX (C++ enumerator), 777 MCPWM_NEG_EDGE (C++ enumerator), 776 mcpwm_counter_type_t (C++ enum), 777 MCPWM_NO_CHANGE_IN_MCPWMXA (C macro), 773 MCPWM_DEADTIME_BYPASS (C++ enumerator), 777 MCPWM_NO_CHANGE_IN_MCPWMXB (C macro), 773 Espressif Systems 2197 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index MCPWM_ONESHOT_MODE_DIS (C++ enumerator), MCPWM_SELECT_TIMER1_SYNC (C++ enumerator), 775 776 MCPWM_ONESHOT_MODE_EN (C++ enumerator), 775 MCPWM_SELECT_TIMER2_SYNC (C++ enumerator), mcpwm_operator_t (C++ type), 773 776 MCPWM_OPR_A (C macro), 773 mcpwm_set_duty (C++ function), 764 MCPWM_OPR_B (C macro), 773 mcpwm_set_duty_in_us (C++ function), 764 MCPWM_OPR_MAX (C macro), 773 mcpwm_set_duty_type (C++ function), 764 mcpwm_output_action_t (C++ enum), 778 mcpwm_set_frequency (C++ function), 763 mcpwm_pin_config_t (C++ class), 771 mcpwm_set_pin (C++ function), 763 mcpwm_pin_config_t::mcpwm0a_out_num mcpwm_set_signal_high (C++ function), 765 (C++ member), 771 mcpwm_set_signal_low (C++ function), 765 mcpwm_pin_config_t::mcpwm0b_out_num mcpwm_set_timer_sync_output (C++ func- (C++ member), 771 tion), 770 mcpwm_pin_config_t::mcpwm1a_out_num mcpwm_start (C++ function), 765 (C++ member), 771 mcpwm_stop (C++ function), 765 mcpwm_pin_config_t::mcpwm1b_out_num MCPWM_SWSYNC_SOURCE_DISABLED (C++ enu- (C++ member), 771 merator), 776 mcpwm_pin_config_t::mcpwm2a_out_num MCPWM_SWSYNC_SOURCE_SYNCIN (C++ enumera- (C++ member), 771 tor), 776 mcpwm_pin_config_t::mcpwm2b_out_num MCPWM_SWSYNC_SOURCE_TEP (C++ enumerator), (C++ member), 771 776 mcpwm_pin_config_t::mcpwm_cap0_in_num MCPWM_SWSYNC_SOURCE_TEZ (C++ enumerator), (C++ member), 771 776 mcpwm_pin_config_t::mcpwm_cap1_in_num MCPWM_SYNC_0 (C++ enumerator), 774 (C++ member), 771 MCPWM_SYNC_1 (C++ enumerator), 774 mcpwm_pin_config_t::mcpwm_cap2_in_num MCPWM_SYNC_2 (C++ enumerator), 774 (C++ member), 771 mcpwm_sync_config_t (C++ class), 773 mcpwm_pin_config_t::mcpwm_fault0_in_nummcpwm_sync_config_t::count_direction (C++ member), 771 (C++ member), 773 mcpwm_pin_config_t::mcpwm_fault1_in_nummcpwm_sync_config_t::sync_sig (C++ (C++ member), 771 member), 773 mcpwm_pin_config_t::mcpwm_fault2_in_nummcpwm_sync_config_t::timer_val (C++ (C++ member), 771 member), 773 mcpwm_pin_config_t::mcpwm_sync0_in_num mcpwm_sync_configure (C++ function), 770 (C++ member), 771 mcpwm_sync_disable (C++ function), 770 mcpwm_pin_config_t::mcpwm_sync1_in_num mcpwm_sync_enable (C++ function), 769 (C++ member), 771 mcpwm_sync_invert_gpio_synchro (C++ mcpwm_pin_config_t::mcpwm_sync2_in_num function), 770 (C++ member), 771 mcpwm_sync_signal_t (C++ enum), 776 MCPWM_POS_EDGE (C++ enumerator), 776 MCPWM_TIMER_0 (C++ enumerator), 775 MCPWM_SELCT_SYNC0 (C macro), 773 MCPWM_TIMER_1 (C++ enumerator), 775 MCPWM_SELCT_SYNC1 (C macro), 773 MCPWM_TIMER_2 (C++ enumerator), 775 MCPWM_SELCT_SYNC2 (C macro), 773 MCPWM_TIMER_COUNT_MODE_DOWN (C++ enumer- MCPWM_SELECT_CAP0 (C++ enumerator), 778 ator), 762 MCPWM_SELECT_CAP1 (C++ enumerator), 778 MCPWM_TIMER_COUNT_MODE_PAUSE (C++ enu- MCPWM_SELECT_CAP2 (C++ enumerator), 778 merator), 761 MCPWM_SELECT_F0 (C++ enumerator), 775 mcpwm_timer_count_mode_t (C++ enum), 761 MCPWM_SELECT_F1 (C++ enumerator), 776 MCPWM_TIMER_COUNT_MODE_UP (C++ enumera- MCPWM_SELECT_F2 (C++ enumerator), 776 tor), 762 MCPWM_SELECT_GPIO_SYNC0 (C++ enumerator), MCPWM_TIMER_COUNT_MODE_UP_DOWN (C++ 776 enumerator), 762 MCPWM_SELECT_GPIO_SYNC1 (C++ enumerator), MCPWM_TIMER_DIRECTION_DOWN (C++ enumera- 776 tor), 761 MCPWM_SELECT_GPIO_SYNC2 (C++ enumerator), mcpwm_timer_direction_t (C++ enum), 761 776 MCPWM_TIMER_DIRECTION_UP (C++ enumerator), MCPWM_SELECT_NO_INPUT (C++ enumerator), 776 761 MCPWM_SELECT_TIMER0_SYNC (C++ enumerator), MCPWM_TIMER_EVENT_PEAK (C++ enumerator), 776 761 Espressif Systems 2198 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index mcpwm_timer_event_t (C++ enum), 761 MCPWM_TIMER_EVENT_ZERO (C++ enumerator), 761 mcpwm_timer_execute_cmd_t (C++ enum), 762 MCPWM_TIMER_MAX (C++ enumerator), 775 mcpwm_timer_set_resolution (C++ function), 763 MCPWM_TIMER_START_NO_STOP (C++ enumera- tor), 762 MCPWM_TIMER_START_STOP_AT_PEAK (C++ enumerator), 762 MCPWM_TIMER_START_STOP_AT_ZERO (C++ enumerator), 762 MCPWM_TIMER_STOP_AT_PEAK (C++ enumerator), 762 MCPWM_TIMER_STOP_AT_ZERO (C++ enumerator), 762 mcpwm_timer_sync_trigger_t (C++ enum), 776 mcpwm_timer_t (C++ enum), 775 mcpwm_timer_trigger_soft_sync (C++ func- tion), 770 MCPWM_TOG_MCPWMXA (C macro), 773 MCPWM_TOG_MCPWMXB (C macro), 773 MCPWM_TRIP_TYPE_CBC (C++ enumerator), 762 MCPWM_TRIP_TYPE_OST (C++ enumerator), 762 mcpwm_trip_type_t (C++ enum), 762 MCPWM_UNIT_0 (C++ enumerator), 775 MCPWM_UNIT_1 (C++ enumerator), 775 MCPWM_UNIT_MAX (C++ enumerator), 775 mcpwm_unit_t (C++ enum), 775 MCPWM_UP_COUNTER (C++ enumerator), 777 MCPWM_UP_DOWN_COUNTER (C++ enumerator), 777 mdns_delegate_hostname_add (C++ function), 165 mdns_delegate_hostname_remove (C++ func- tion), 165 mdns_event_actions_t (C++ enum), 176 MDNS_EVENT_ANNOUNCE_IP4 (C++ enumerator), 176 MDNS_EVENT_ANNOUNCE_IP6 (C++ enumerator), 176 MDNS_EVENT_DISABLE_IP4 (C++ enumerator), 176 MDNS_EVENT_DISABLE_IP6 (C++ enumerator), 176 MDNS_EVENT_ENABLE_IP4 (C++ enumerator), 176 MDNS_EVENT_ENABLE_IP6 (C++ enumerator), 176 mdns_free (C++ function), 164 mdns_hostname_exists (C++ function), 165 mdns_hostname_set (C++ function), 164 mdns_init (C++ function), 164 mdns_instance_name_set (C++ function), 165 mdns_ip_addr_s (C++ class), 174 mdns_ip_addr_s::addr (C++ member), 175 mdns_ip_addr_s::next (C++ member), 175 mdns_ip_addr_t (C++ type), 176 MDNS_IP_PROTOCOL_MAX (C++ enumerator), 176 mdns_ip_protocol_t (C++ enum), 176 MDNS_IP_PROTOCOL_V4 (C++ enumerator), 176 MDNS_IP_PROTOCOL_V6 (C++ enumerator), 176 mdns_netif_action (C++ function), 174 mdns_query (C++ function), 172 mdns_query_a (C++ function), 173 mdns_query_aaaa (C++ function), 173 mdns_query_async_delete (C++ function), 171 mdns_query_async_get_results (C++ func- tion), 171 mdns_query_async_new (C++ function), 171 mdns_query_generic (C++ function), 172 MDNS_QUERY_MULTICAST (C++ enumerator), 176 mdns_query_notify_t (C++ type), 176 mdns_query_ptr (C++ function), 172 mdns_query_results_free (C++ function), 172 mdns_query_srv (C++ function), 173 mdns_query_transmission_type_t (C++ enum), 176 mdns_query_txt (C++ function), 173 MDNS_QUERY_UNICAST (C++ enumerator), 176 mdns_register_netif (C++ function), 174 mdns_result_s (C++ class), 175 mdns_result_s::addr (C++ member), 175 mdns_result_s::esp_netif (C++ member), 175 mdns_result_s::hostname (C++ member), 175 mdns_result_s::instance_name (C++ mem- ber), 175 mdns_result_s::ip_protocol (C++ member), 175 mdns_result_s::next (C++ member), 175 mdns_result_s::port (C++ member), 175 mdns_result_s::proto (C++ member), 175 mdns_result_s::service_type (C++ mem- ber), 175 mdns_result_s::ttl (C++ member), 175 mdns_result_s::txt (C++ member), 175 mdns_result_s::txt_count (C++ member), 175 mdns_result_s::txt_value_len (C++ mem- ber), 175 mdns_result_t (C++ type), 176 mdns_search_once_t (C++ type), 176 mdns_service_add (C++ function), 165 mdns_service_add_for_host (C++ function), 166 mdns_service_exists (C++ function), 166 mdns_service_exists_with_instance (C++ function), 166 mdns_service_instance_name_set (C++ function), 167 mdns_service_instance_name_set_for_host (C++ function), 167 mdns_service_port_set (C++ function), 167 mdns_service_port_set_for_host (C++ function), 167 mdns_service_remove (C++ function), 166 Espressif Systems 2199 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index mdns_service_remove_all (C++ function), 171 MESH_DATA_ENC (C macro), 538 mdns_service_remove_for_host (C++ func- MESH_DATA_FROMDS (C macro), 538 tion), 167 MESH_DATA_GROUP (C macro), 538 mdns_service_subtype_add_for_host MESH_DATA_NONBLOCK (C macro), 538 (C++ function), 171 MESH_DATA_P2P (C macro), 538 mdns_service_txt_item_remove (C++ func- mesh_data_t (C++ class), 534 tion), 170 mesh_data_t::data (C++ member), 535 mdns_service_txt_item_remove_for_host mesh_data_t::proto (C++ member), 535 (C++ function), 170 mesh_data_t::size (C++ member), 535 mdns_service_txt_item_set (C++ function), mesh_data_t::tos (C++ member), 535 168 MESH_DATA_TODS (C macro), 538 mdns_service_txt_item_set_for_host mesh_disconnect_reason_t (C++ enum), 541 (C++ function), 169 MESH_EVENT_CHANNEL_SWITCH (C++ enumera- mdns_service_txt_item_set_for_host_with_explictoirt),_5v3a9lue_len (C++ function), 169 mesh_event_channel_switch_t (C++ class), mdns_service_txt_item_set_with_explicit_value_5l32en (C++ function), 169 mesh_event_channel_switch_t::channel mdns_service_txt_set (C++ function), 168 (C++ member), 532 mdns_service_txt_set_for_host (C++ func- MESH_EVENT_CHILD_CONNECTED (C++ enumera- tion), 168 tor), 539 mdns_txt_item_t (C++ class), 174 mesh_event_child_connected_t (C++ type), mdns_txt_item_t::key (C++ member), 174 539 mdns_txt_item_t::value (C++ member), 174 MESH_EVENT_CHILD_DISCONNECTED (C++ enu- MDNS_TYPE_A (C macro), 175 merator), 539 MDNS_TYPE_AAAA (C macro), 175 mesh_event_child_disconnected_t (C++ MDNS_TYPE_ANY (C macro), 175 type), 539 MDNS_TYPE_NSEC (C macro), 175 mesh_event_connected_t (C++ class), 532 MDNS_TYPE_OPT (C macro), 175 mesh_event_connected_t::connected MDNS_TYPE_PTR (C macro), 175 (C++ member), 532 MDNS_TYPE_SRV (C macro), 175 mesh_event_connected_t::duty (C++ mem- MDNS_TYPE_TXT (C macro), 175 ber), 532 mdns_unregister_netif (C++ function), 174 mesh_event_connected_t::self_layer mesh_addr_t (C++ union), 530 (C++ member), 532 mesh_addr_t::addr (C++ member), 530 mesh_event_disconnected_t (C++ type), 539 mesh_addr_t::mip (C++ member), 530 MESH_EVENT_FIND_NETWORK (C++ enumerator), mesh_ap_cfg_t (C++ class), 535 540 mesh_ap_cfg_t::max_connection (C++ mesh_event_find_network_t (C++ class), 533 member), 535 mesh_event_find_network_t::channel mesh_ap_cfg_t::nonmesh_max_connection (C++ member), 533 (C++ member), 535 mesh_event_find_network_t::router_bssid mesh_ap_cfg_t::password (C++ member), 535 (C++ member), 533 MESH_ASSOC_FLAG_NETWORK_FREE (C macro), mesh_event_id_t (C++ enum), 539 538 mesh_event_info_t (C++ union), 531 MESH_ASSOC_FLAG_ROOT_FIXED (C macro), 538 mesh_event_info_t::channel_switch MESH_ASSOC_FLAG_ROOTS_FOUND (C macro), (C++ member), 531 538 mesh_event_info_t::child_connected MESH_ASSOC_FLAG_VOTE_IN_PROGRESS (C (C++ member), 531 macro), 538 mesh_event_info_t::child_disconnected mesh_cfg_t (C++ class), 535 (C++ member), 531 mesh_cfg_t::allow_channel_switch (C++ mesh_event_info_t::connected (C++ mem- member), 535 ber), 531 mesh_cfg_t::channel (C++ member), 535 mesh_event_info_t::disconnected (C++ mesh_cfg_t::crypto_funcs (C++ member), member), 531 536 mesh_event_info_t::find_network (C++ mesh_cfg_t::mesh_ap (C++ member), 536 member), 531 mesh_cfg_t::mesh_id (C++ member), 536 mesh_event_info_t::layer_change (C++ mesh_cfg_t::router (C++ member), 536 member), 531 MESH_DATA_DROP (C macro), 538 mesh_event_info_t::network_state (C++ Espressif Systems 2200 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index member), 531 mesh_event_root_address_t (C++ type), 539 mesh_event_info_t::no_parent (C++ mem- MESH_EVENT_ROOT_ASKED_YIELD (C++ enumer- ber), 531 ator), 540 mesh_event_info_t::ps_duty (C++ member), mesh_event_root_conflict_t (C++ class), 531 533 mesh_event_info_t::root_addr (C++ mem- mesh_event_root_conflict_t::addr (C++ ber), 531 member), 533 mesh_event_info_t::root_conflict (C++ mesh_event_root_conflict_t::capacity member), 531 (C++ member), 533 mesh_event_info_t::root_fixed (C++ mesh_event_root_conflict_t::rssi (C++ member), 531 member), 533 mesh_event_info_t::router_switch (C++ MESH_EVENT_ROOT_FIXED (C++ enumerator), 540 member), 531 mesh_event_root_fixed_t (C++ class), 534 mesh_event_info_t::routing_table (C++ mesh_event_root_fixed_t::is_fixed member), 531 (C++ member), 534 mesh_event_info_t::scan_done (C++ mem- MESH_EVENT_ROOT_SWITCH_ACK (C++ enumera- ber), 531 tor), 540 mesh_event_info_t::switch_req (C++ MESH_EVENT_ROOT_SWITCH_REQ (C++ enumera- member), 531 tor), 540 mesh_event_info_t::toDS_state (C++ mesh_event_root_switch_req_t (C++ class), member), 531 533 mesh_event_info_t::vote_started (C++ mesh_event_root_switch_req_t::rc_addr member), 531 (C++ member), 533 MESH_EVENT_LAYER_CHANGE (C++ enumerator), mesh_event_root_switch_req_t::reason 540 (C++ member), 533 mesh_event_layer_change_t (C++ class), 532 MESH_EVENT_ROUTER_SWITCH (C++ enumerator), mesh_event_layer_change_t::new_layer 540 (C++ member), 533 mesh_event_router_switch_t (C++ type), 539 MESH_EVENT_MAX (C++ enumerator), 540 MESH_EVENT_ROUTING_TABLE_ADD (C++ enu- MESH_EVENT_NETWORK_STATE (C++ enumerator), merator), 539 540 mesh_event_routing_table_change_t mesh_event_network_state_t (C++ class), (C++ class), 533 534 mesh_event_routing_table_change_t::rt_size_change mesh_event_network_state_t::is_rootless (C++ member), 534 (C++ member), 534 mesh_event_routing_table_change_t::rt_size_new MESH_EVENT_NO_PARENT_FOUND (C++ enumera- (C++ member), 534 tor), 539 MESH_EVENT_ROUTING_TABLE_REMOVE (C++ mesh_event_no_parent_found_t (C++ class), enumerator), 539 532 MESH_EVENT_SCAN_DONE (C++ enumerator), 540 mesh_event_no_parent_found_t::scan_timemsesh_event_scan_done_t (C++ class), 534 (C++ member), 532 mesh_event_scan_done_t::number (C++ MESH_EVENT_PARENT_CONNECTED (C++ enumer- member), 534 ator), 539 MESH_EVENT_STARTED (C++ enumerator), 539 MESH_EVENT_PARENT_DISCONNECTED (C++ MESH_EVENT_STOP_RECONNECTION (C++ enu- enumerator), 539 merator), 540 MESH_EVENT_PS_CHILD_DUTY (C++ enumerator), MESH_EVENT_STOPPED (C++ enumerator), 539 540 MESH_EVENT_TODS_STATE (C++ enumerator), 540 MESH_EVENT_PS_DEVICE_DUTY (C++ enumera- mesh_event_toDS_state_t (C++ enum), 542 tor), 540 MESH_EVENT_VOTE_STARTED (C++ enumerator), mesh_event_ps_duty_t (C++ class), 534 540 mesh_event_ps_duty_t::child_connected mesh_event_vote_started_t (C++ class), 533 (C++ member), 534 mesh_event_vote_started_t::attempts mesh_event_ps_duty_t::duty (C++ member), (C++ member), 533 534 mesh_event_vote_started_t::rc_addr MESH_EVENT_PS_PARENT_DUTY (C++ enumera- (C++ member), 533 tor), 540 mesh_event_vote_started_t::reason MESH_EVENT_ROOT_ADDRESS (C++ enumerator), (C++ member), 533 540 MESH_EVENT_VOTE_STOPPED (C++ enumerator), Espressif Systems 2201 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index 540 MESH_IDLE (C++ enumerator), 540 MESH_INIT_CONFIG_DEFAULT (C macro), 539 MESH_LEAF (C++ enumerator), 541 MESH_MPS (C macro), 537 MESH_MTU (C macro), 537 MESH_NODE (C++ enumerator), 541 MESH_OPT_RECV_DS_ADDR (C macro), 538 MESH_OPT_SEND_GROUP (C macro), 538 mesh_opt_t (C++ class), 534 mesh_opt_t::len (C++ member), 534 mesh_opt_t::type (C++ member), 534 mesh_opt_t::val (C++ member), 534 MESH_PROTO_AP (C++ enumerator), 541 MESH_PROTO_BIN (C++ enumerator), 541 MESH_PROTO_HTTP (C++ enumerator), 541 MESH_PROTO_JSON (C++ enumerator), 541 MESH_PROTO_MQTT (C++ enumerator), 541 MESH_PROTO_STA (C++ enumerator), 541 mesh_proto_t (C++ enum), 541 MESH_PS_DEVICE_DUTY_DEMAND (C macro), 539 MESH_PS_DEVICE_DUTY_REQUEST (C macro), 538 MESH_PS_NETWORK_DUTY_APPLIED_ENTIRE (C macro), 539 MESH_PS_NETWORK_DUTY_APPLIED_UPLINK (C macro), 539 MESH_PS_NETWORK_DUTY_MASTER (C macro), 539 mesh_rc_config_t (C++ union), 531 mesh_rc_config_t::attempts (C++ member), 532 mesh_rc_config_t::rc_addr (C++ member), 532 MESH_REASON_CYCLIC (C++ enumerator), 541 MESH_REASON_DIFF_ID (C++ enumerator), 542 MESH_REASON_EMPTY_PASSWORD (C++ enumera- tor), 542 MESH_REASON_IE_UNKNOWN (C++ enumerator), 542 MESH_REASON_LEAF (C++ enumerator), 542 MESH_REASON_PARENT_IDLE (C++ enumerator), 541 MESH_REASON_PARENT_STOPPED (C++ enumera- tor), 542 MESH_REASON_PARENT_UNENCRYPTED (C++ enumerator), 542 MESH_REASON_PARENT_WORSE (C++ enumerator), 542 MESH_REASON_ROOTS (C++ enumerator), 542 MESH_REASON_SCAN_FAIL (C++ enumerator), 542 MESH_REASON_WAIVE_ROOT (C++ enumerator), 542 MESH_ROOT (C++ enumerator), 541 MESH_ROOT_LAYER (C macro), 537 mesh_router_t (C++ class), 535 mesh_router_t::allow_router_switch (C++ member), 535 mesh_router_t::bssid (C++ member), 535 mesh_router_t::password (C++ member), 535 mesh_router_t::ssid (C++ member), 535 mesh_router_t::ssid_len (C++ member), 535 mesh_rx_pending_t (C++ class), 536 mesh_rx_pending_t::toDS (C++ member), 536 mesh_rx_pending_t::toSelf (C++ member), 536 MESH_STA (C++ enumerator), 541 MESH_TODS_REACHABLE (C++ enumerator), 542 MESH_TODS_UNREACHABLE (C++ enumerator), 542 MESH_TOPO_CHAIN (C++ enumerator), 542 MESH_TOPO_TREE (C++ enumerator), 542 MESH_TOS_DEF (C++ enumerator), 541 MESH_TOS_E2E (C++ enumerator), 541 MESH_TOS_P2P (C++ enumerator), 541 mesh_tos_t (C++ enum), 541 mesh_tx_pending_t (C++ class), 536 mesh_tx_pending_t::broadcast (C++ mem- ber), 536 mesh_tx_pending_t::mgmt (C++ member), 536 mesh_tx_pending_t::to_child (C++ mem- ber), 536 mesh_tx_pending_t::to_child_p2p (C++ member), 536 mesh_tx_pending_t::to_parent (C++ mem- ber), 536 mesh_tx_pending_t::to_parent_p2p (C++ member), 536 mesh_type_t (C++ enum), 540 MESH_VOTE_REASON_CHILD_INITIATED (C++ enumerator), 541 MESH_VOTE_REASON_ROOT_INITIATED (C++ enumerator), 541 mesh_vote_reason_t (C++ enum), 541 mesh_vote_t (C++ class), 536 mesh_vote_t::config (C++ member), 536 mesh_vote_t::is_rc_specified (C++ mem- ber), 536 mesh_vote_t::percentage (C++ member), 536 MessageBufferHandle_t (C++ type), 1497 mip_t (C++ class), 532 mip_t::ip4 (C++ member), 532 mip_t::port (C++ member), 532 MQTT_CONNECTION_ACCEPTED (C++ enumerator), 82 MQTT_CONNECTION_REFUSE_BAD_USERNAME (C++ enumerator), 82 MQTT_CONNECTION_REFUSE_ID_REJECTED (C++ enumerator), 82 MQTT_CONNECTION_REFUSE_NOT_AUTHORIZED (C++ enumerator), 82 MQTT_CONNECTION_REFUSE_PROTOCOL (C++ enumerator), 82 MQTT_CONNECTION_REFUSE_SERVER_UNAVAILABLE (C++ enumerator), 82 MQTT_ERROR_TYPE_CONNECTION_REFUSED (C++ enumerator), 83 Espressif Systems 2202 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index MQTT_ERROR_TYPE_ESP_TLS (C macro), 81 multi_heap_minimum_free_size (C++ func- MQTT_ERROR_TYPE_NONE (C++ enumerator), 83 tion), 1525 MQTT_ERROR_TYPE_TCP_TRANSPORT (C++ enu- multi_heap_realloc (C++ function), 1524 merator), 83 multi_heap_register (C++ function), 1524 MQTT_EVENT_ANY (C++ enumerator), 81 multi_heap_set_lock (C++ function), 1524 MQTT_EVENT_BEFORE_CONNECT (C++ enumera- tor), 82 N mqtt_event_callback_t (C++ type), 81 name_uuid (C++ class), 1213 MQTT_EVENT_CONNECTED (C++ enumerator), 81 name_uuid::name (C++ member), 1213 MQTT_EVENT_DATA (C++ enumerator), 82 name_uuid::uuid (C++ member), 1213 MQTT_EVENT_DELETED (C++ enumerator), 82 nvs_close (C++ function), 1259 MQTT_EVENT_DISCONNECTED (C++ enumerator), nvs_commit (C++ function), 1258 81 NVS_DEFAULT_PART_NAME (C macro), 1262 MQTT_EVENT_ERROR (C++ enumerator), 81 nvs_entry_find (C++ function), 1260 MQTT_EVENT_PUBLISHED (C++ enumerator), 82 nvs_entry_info (C++ function), 1260 MQTT_EVENT_SUBSCRIBED (C++ enumerator), 82 nvs_entry_info_t (C++ class), 1261 MQTT_EVENT_UNSUBSCRIBED (C++ enumerator), nvs_entry_info_t::key (C++ member), 1261 82 nvs_entry_info_t::namespace_name (C++ MQTT_PROTOCOL_UNDEFINED (C++ enumerator), member), 1261 83 nvs_entry_info_t::type (C++ member), 1261 MQTT_PROTOCOL_V_3_1 (C++ enumerator), 83 nvs_entry_next (C++ function), 1260 MQTT_PROTOCOL_V_3_1_1 (C++ enumerator), 83 nvs_erase_all (C++ function), 1258 MQTT_TRANSPORT_OVER_SSL (C++ enumerator), nvs_erase_key (C++ function), 1258 83 nvs_flash_deinit (C++ function), 1251 MQTT_TRANSPORT_OVER_TCP (C++ enumerator), nvs_flash_deinit_partition (C++ function), 83 1252 MQTT_TRANSPORT_OVER_WS (C++ enumerator), 83 nvs_flash_erase (C++ function), 1252 MQTT_TRANSPORT_OVER_WSS (C++ enumerator), nvs_flash_erase_partition (C++ function), 83 1252 MQTT_TRANSPORT_UNKNOWN (C++ enumerator), 83 nvs_flash_erase_partition_ptr (C++ func- multi_heap_aligned_alloc (C++ function), tion), 1252 1523 nvs_flash_generate_keys (C++ function), multi_heap_aligned_free (C++ function), 1253 1524 nvs_flash_init (C++ function), 1251 multi_heap_check (C++ function), 1525 nvs_flash_init_partition (C++ function), multi_heap_dump (C++ function), 1525 1251 multi_heap_free (C++ function), 1524 nvs_flash_init_partition_ptr (C++ func- multi_heap_free_size (C++ function), 1525 tion), 1251 multi_heap_get_allocated_size (C++ func- nvs_flash_read_security_cfg (C++ func- tion), 1524 tion), 1253 multi_heap_get_info (C++ function), 1525 nvs_flash_secure_init (C++ function), 1252 multi_heap_handle_t (C++ type), 1526 nvs_flash_secure_init_partition (C++ multi_heap_info_t (C++ class), 1526 function), 1253 multi_heap_info_t::allocated_blocks nvs_get_blob (C++ function), 1257 (C++ member), 1526 nvs_get_i16 (C++ function), 1256 multi_heap_info_t::free_blocks (C++ nvs_get_i32 (C++ function), 1256 member), 1526 nvs_get_i64 (C++ function), 1256 multi_heap_info_t::largest_free_block nvs_get_i8 (C++ function), 1255 (C++ member), 1526 nvs_get_stats (C++ function), 1259 multi_heap_info_t::minimum_free_bytes nvs_get_str (C++ function), 1256 (C++ member), 1526 nvs_get_u16 (C++ function), 1256 multi_heap_info_t::total_allocated_bytensvs_get_u32 (C++ function), 1256 (C++ member), 1526 nvs_get_u64 (C++ function), 1256 multi_heap_info_t::total_blocks (C++ nvs_get_u8 (C++ function), 1255 member), 1526 nvs_get_used_entry_count (C++ function), multi_heap_info_t::total_free_bytes 1259 (C++ member), 1526 nvs_handle (C++ type), 1262 multi_heap_malloc (C++ function), 1524 nvs_handle_t (C++ type), 1262 Espressif Systems 2203 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index nvs_iterator_t (C++ type), 1262 NVS_KEY_NAME_MAX_SIZE (C macro), 1262 NVS_KEY_SIZE (C macro), 1254 nvs_open (C++ function), 1257 nvs_open_from_partition (C++ function), 1257 nvs_open_mode (C++ type), 1262 nvs_open_mode_t (C++ enum), 1263 NVS_PART_NAME_MAX_SIZE (C macro), 1262 NVS_READONLY (C++ enumerator), 1263 NVS_READWRITE (C++ enumerator), 1263 nvs_release_iterator (C++ function), 1260 nvs_sec_cfg_t (C++ class), 1253 nvs_sec_cfg_t::eky (C++ member), 1253 nvs_sec_cfg_t::tky (C++ member), 1253 nvs_set_blob (C++ function), 1257 nvs_set_i16 (C++ function), 1254 nvs_set_i32 (C++ function), 1254 nvs_set_i64 (C++ function), 1254 nvs_set_i8 (C++ function), 1254 nvs_set_str (C++ function), 1255 nvs_set_u16 (C++ function), 1254 nvs_set_u32 (C++ function), 1254 nvs_set_u64 (C++ function), 1254 nvs_set_u8 (C++ function), 1254 nvs_stats_t (C++ class), 1261 nvs_stats_t::free_entries (C++ member), 1261 nvs_stats_t::namespace_count (C++ mem- ber), 1261 nvs_stats_t::total_entries (C++ member), 1261 nvs_stats_t::used_entries (C++ member), 1261 NVS_TYPE_ANY (C++ enumerator), 1263 NVS_TYPE_BLOB (C++ enumerator), 1263 NVS_TYPE_I16 (C++ enumerator), 1263 NVS_TYPE_I32 (C++ enumerator), 1263 NVS_TYPE_I64 (C++ enumerator), 1263 NVS_TYPE_I8 (C++ enumerator), 1263 NVS_TYPE_STR (C++ enumerator), 1263 nvs_type_t (C++ enum), 1263 NVS_TYPE_U16 (C++ enumerator), 1263 NVS_TYPE_U32 (C++ enumerator), 1263 NVS_TYPE_U64 (C++ enumerator), 1263 NVS_TYPE_U8 (C++ enumerator), 1263 O OPCODE_ADC (C macro), 1639 OPCODE_ALU (C macro), 1639 OPCODE_BRANCH (C macro), 1640 OPCODE_DELAY (C macro), 1639 OPCODE_END (C macro), 1640 OPCODE_HALT (C macro), 1640 OPCODE_I2C (C macro), 1639 OPCODE_LD (C macro), 1640 OPCODE_MACRO (C macro), 1640 OPCODE_RD_REG (C macro), 1638 OPCODE_ST (C macro), 1639 OPCODE_TSENS (C macro), 1640 OPCODE_WR_REG (C macro), 1638 OPENTHREAD_EVENT_GOT_IP6 (C++ enumerator), 612 OPENTHREAD_EVENT_IF_DOWN (C++ enumerator), 611 OPENTHREAD_EVENT_IF_UP (C++ enumerator), 611 OPENTHREAD_EVENT_LOST_IP6 (C++ enumera- tor), 612 OPENTHREAD_EVENT_MULTICAST_GROUP_JOIN (C++ enumerator), 612 OPENTHREAD_EVENT_MULTICAST_GROUP_LEAVE (C++ enumerator), 612 OPENTHREAD_EVENT_START (C++ enumerator), 611 OPENTHREAD_EVENT_STOP (C++ enumerator), 611 OPENTHREAD_EVENT_TREL_ADD_IP6 (C++ enu- merator), 612 OPENTHREAD_EVENT_TREL_MULTICAST_GROUP_JOIN (C++ enumerator), 612 OPENTHREAD_EVENT_TREL_REMOVE_IP6 (C++ enumerator), 612 OTA_SIZE_UNKNOWN (C macro), 1585 OTA_WITH_SEQUENTIAL_WRITES (C macro), 1585 P PAR_PERMS_READ (C++ enumerator), 70 PAR_PERMS_READ_TRIGGER (C++ enumerator), 70 PAR_PERMS_READ_WRITE (C++ enumerator), 70 PAR_PERMS_READ_WRITE_TRIGGER (C++ enu- merator), 70 PAR_PERMS_TRIGGER (C++ enumerator), 70 PAR_PERMS_WRITE (C++ enumerator), 70 PAR_PERMS_WRITE_TRIGGER (C++ enumerator), 70 PARAM_MAX_SIZE (C++ enumerator), 69 PARAM_SIZE_ASCII (C++ enumerator), 69 PARAM_SIZE_ASCII24 (C++ enumerator), 69 PARAM_SIZE_FLOAT (C++ enumerator), 69 PARAM_SIZE_U16 (C++ enumerator), 69 PARAM_SIZE_U32 (C++ enumerator), 69 PARAM_SIZE_U8 (C++ enumerator), 69 PARAM_TYPE_ASCII (C++ enumerator), 69 PARAM_TYPE_FLOAT (C++ enumerator), 69 PARAM_TYPE_U16 (C++ enumerator), 69 PARAM_TYPE_U32 (C++ enumerator), 69 PARAM_TYPE_U8 (C++ enumerator), 69 pcnt_chan_config_t (C++ class), 788 pcnt_chan_config_t::edge_gpio_num (C++ member), 788 pcnt_chan_config_t::invert_edge_input (C++ member), 788 pcnt_chan_config_t::invert_level_input (C++ member), 788 pcnt_chan_config_t::io_loop_back (C++ member), 788 Espressif Systems 2204 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index pcnt_chan_config_t::level_gpio_num PCNT_UNIT_ZERO_CROSS_POS_NEG (C++ enu- (C++ member), 788 merator), 789 PCNT_CHANNEL_EDGE_ACTION_DECREASE PCNT_UNIT_ZERO_CROSS_POS_ZERO (C++ enu- (C++ enumerator), 789 merator), 789 PCNT_CHANNEL_EDGE_ACTION_HOLD (C++ enu- pcnt_watch_cb_t (C++ type), 788 merator), 789 pcnt_watch_event_data_t (C++ class), 787 PCNT_CHANNEL_EDGE_ACTION_INCREASE pcnt_watch_event_data_t::watch_point_value (C++ enumerator), 789 (C++ member), 787 pcnt_channel_edge_action_t (C++ enum), pcnt_watch_event_data_t::zero_cross_mode 789 (C++ member), 787 pcnt_channel_handle_t (C++ type), 788 pcQueueGetName (C++ function), 1432 PCNT_CHANNEL_LEVEL_ACTION_HOLD (C++ pcTaskGetName (C++ function), 1409 enumerator), 789 pcTimerGetName (C++ function), 1463 PCNT_CHANNEL_LEVEL_ACTION_INVERSE PendedFunction_t (C++ type), 1473 (C++ enumerator), 789 PHY_RF_CAL_FULL (C++ enumerator), 1915 PCNT_CHANNEL_LEVEL_ACTION_KEEP (C++ PHY_RF_CAL_NONE (C++ enumerator), 1915 enumerator), 789 PHY_RF_CAL_PARTIAL (C++ enumerator), 1915 pcnt_channel_level_action_t (C++ enum), print_class_descriptor_cb (C++ type), 934 789 PROTOCOM_SEC0 (C++ enumerator), 117 pcnt_channel_set_edge_action (C++ func- PROTOCOM_SEC1 (C++ enumerator), 117 tion), 787 PROTOCOM_SEC_CUSTOM (C++ enumerator), 117 pcnt_channel_set_level_action (C++ func- protocomm_add_endpoint (C++ function), 1207 tion), 787 protocomm_ble_config (C++ class), 1213 pcnt_del_channel (C++ function), 786 protocomm_ble_config::device_name pcnt_del_unit (C++ function), 784 (C++ member), 1213 pcnt_event_callbacks_t (C++ class), 787 protocomm_ble_config::manufacturer_data pcnt_event_callbacks_t::on_reach (C++ (C++ member), 1213 member), 787 protocomm_ble_config::manufacturer_data_len pcnt_glitch_filter_config_t (C++ class), (C++ member), 1213 788 protocomm_ble_config::nu_lookup (C++ pcnt_glitch_filter_config_t::max_glitch_ns member), 1213 (C++ member), 788 protocomm_ble_config::nu_lookup_count pcnt_new_channel (C++ function), 786 (C++ member), 1213 pcnt_new_unit (C++ function), 784 protocomm_ble_config::service_uuid pcnt_unit_add_watch_point (C++ function), (C++ member), 1213 786 protocomm_ble_config_t (C++ type), 1214 pcnt_unit_clear_count (C++ function), 785 protocomm_ble_name_uuid_t (C++ type), 1214 pcnt_unit_config_t (C++ class), 787 protocomm_ble_start (C++ function), 1212 pcnt_unit_config_t::high_limit (C++ protocomm_ble_stop (C++ function), 1212 member), 788 protocomm_close_session (C++ function), pcnt_unit_config_t::low_limit (C++ 1208 member), 788 protocomm_delete (C++ function), 1207 pcnt_unit_get_count (C++ function), 785 protocomm_http_server_config_t (C++ pcnt_unit_handle_t (C++ type), 788 class), 1212 pcnt_unit_register_event_callbacks protocomm_http_server_config_t::port (C++ function), 785 (C++ member), 1212 pcnt_unit_remove_watch_point (C++ func- protocomm_http_server_config_t::stack_size tion), 786 (C++ member), 1212 pcnt_unit_set_glitch_filter (C++ func- protocomm_http_server_config_t::task_priority tion), 784 (C++ member), 1212 pcnt_unit_start (C++ function), 784 protocomm_httpd_config_data_t (C++ pcnt_unit_stop (C++ function), 785 union), 1211 pcnt_unit_zero_cross_mode_t (C++ enum), protocomm_httpd_config_data_t::config 789 (C++ member), 1211 PCNT_UNIT_ZERO_CROSS_NEG_POS (C++ enu- protocomm_httpd_config_data_t::handle merator), 789 (C++ member), 1211 PCNT_UNIT_ZERO_CROSS_NEG_ZERO (C++ enu- protocomm_httpd_config_t (C++ class), 1212 merator), 789 protocomm_httpd_config_t::data (C++ Espressif Systems 2205 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index member), 1212 PTHREAD_STACK_MIN (C macro), 1599 protocomm_httpd_config_t::ext_handle_prpovvTiadsekdGetThreadLocalStoragePointer (C++ member), 1212 (C++ function), 1410 PROTOCOMM_HTTPD_DEFAULT_CONFIG (C pvTimerGetTimerID (C++ function), 1460 macro), 1212 pxTaskGetStackStart (C++ function), 1410 protocomm_httpd_start (C++ function), 1211 protocomm_httpd_stop (C++ function), 1211 Q protocomm_new (C++ function), 1207 protocomm_open_session (C++ function), 1207 protocomm_remove_endpoint (C++ function), 1207 QueueHandle_t (C++ type), 1443 QueueSetHandle_t (C++ type), 1443 QueueSetMemberHandle_t (C++ type), 1443 protocomm_req_handle (C++ function), 1208 R pppppppppppppppppppppPPPPPppppprrrrrrrrrrrrrrrrrrrrrRRRRRsssssoooooooooooooooooooooOOOOOkkkkktttttttttttttttttttttVVVXX_____ooooooooooooooooooooo___YYhkkkkcccccccccccccccccccccDDD__ieeeeoooooooooooooooooooooAAAFFnyyyyb(bb1((11bb1133mmmmmmmmmmmmmmmmmmmmmTTTIIt____CCCeeeee2222233mmmmmmmmmmmmmmmmmmmmmAAALL_hhhhrrrrr+++1110022)))))________________________TTkiiii00099,,,,,+++rssssssssssssssssstuuFINEEennnn11111mmmeeeeeeeeeeeeeeeeeennLVERRytttt22222(11111CqcccccccccccccccttssA_T___:::eee(00000mmmC+_uuuuuuuuuuuuuuu__eeGI_BWt:::+hrrrrrrrrrrrrrrrsvttSNILHhkkbbb+(eeeCaiiiiiiiiiiiiiiiee___DDAIiee+rrrt+ntttttttttttttttcrsvFEXCTnyyy)))c,,,pdyyyyyyyyyyyyyyyuseeLX_KEt_+l(111eaCl::::::::______ricrA_FLLs)222((st,CC+e::::::::hpppptiousGFLIIiys1111)p++rccdeinsvaooootnriLASSz000+,((2eCC_llenneeenppppyioAGTTe++9)0(m,0C+teocciwcrd::_tnG9m((((cm9eCCCC+asrrt_ul::ty+l((((3maaeCCCC+++neyytredl+m(cmstb(++(C+u_ppri_aey+++rs(mC(Ceafo)bpC+ptttatttnC+++ru,c+)+eeacfm)+rnya+,n+r1r)ul,c++toa,)e3c2as_y+nr+(((((9,)eemstt1o1(CCCC1Cpcinpr,y0snn9Co)28te0)b+++++p3isoeuu,0n),+1oeffe1mmmm,3+++++)prq10nruu)+8,11,)ee2)ot_eenn1,28,mm1rr1ccr_h29mmmmmaat012tt0ybbiitsa00tt92oo1eeeeepooee9_en0nnmmmmm0errrr8)))))))ssd-----,,,,,,,eslsieRRRRRRRRRRRRRRRRRrRRRRRRrRRRRRRRRRRRRRrsor0123AAADDDDIIIIiimMMMMMMmMMMMMMMMMMMMMminDDD____NNNNnntTTTTTTtTTTTTTTTTTTTTt((((oCCCCIIIRRRRGGGGgg______________________nOOOEEEEBBBBbbaBBBCCCcCCCCCCCCCCCCCcmmmm___GGGGUUUUuudAAAAAAaHHHHHHHHHHHHHhaaaaMMM____FFFFffdSSSRRRrAAAAAAAAAAAAAacccc188888OOOPPPP____fH_EEERRRrNNNNNNNNNNNNNnrrrr500000ooooDDDEEEETTTTeacCCCIIIiNNNNNNNNNNNNNn138664))))EEERRRRYYYYrnhLLLEEEeEEEEEEEEEEEEEe,,,,31111___IIIIPPPPTdaKKKRRRrLLLLLLLLLLLLLl6666NSUPPPPEEEEyln_____________________3333APAHHHH____penAMXLLLl01234567BFFIMs8888TIR____ABMNe_ePATEEEeULLDAt((((((((CCCCCCCCI_TRRRSLYAO_tlBXAVVVvSAALXa++++++++VR_TTTELTXSt_LEEEeYGGEt((((CCCCECRCCCNOEPtLLLlSSu++++++++(((((CCCCC++++PC___SWBLo______s(eeeeeeeeC+++++PCIISUI_HLMtAI_++++nnnnnnnn((CC+N2OPFTgIOAWNr+++++uuuuuuuu((teeemmmmmmmmCC+TCLrGWXAVey+nnnm(((eeeeepCCC++LIoHREs+uuueeeeeeeennnnn(((eaerrrrrrrrCCmmmC++TuERu++uuuuu)nm(aaaaaaaace,mmmmm++Cp_Tl++rueeettttttttn(maooooooooee1orrr(CmD_t++ueeee)nnCmaaarrrrrrrrc)5aee,rrrr+mFS_,))))))))ruuetttnn1(+aaaac1aee,,,,,,,,oooor1CmmSIt+ruue3ttttnn5arrrc88888888)+ooooo6rmm+G,)))uure)1t00000000arrrr)3,,,oo,r1mm(,3))))+77777777eet9ar888)ee8C,,,,(o6rr1,)ee(nnCt0000aar18883+,oC6rr1uu)7778tt50008aar63f,oo6+mm)1788ttu19rr63oo,mm3een))218rr6,,rrcc))aa2aa111tl,,cciatt255o88oorrsn11oo00rrs))))))3388,,,,,, Espressif Systems 2206 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index rmt_channel_status_result_t::status (C++ member), 804 rmt_channel_status_t (C++ enum), 808 rmt_channel_t (C++ enum), 807 RMT_CHANNEL_UNINIT (C++ enumerator), 808 RMT_CLK_SRC_APB (C++ enumerator), 809 RMT_CLK_SRC_FAST_RC (C++ enumerator), 809 RMT_CLK_SRC_NONE (C++ enumerator), 809 RMT_CLK_SRC_REFTICK (C++ enumerator), 809 RMT_CLK_SRC_XTAL (C++ enumerator), 809 rmt_clock_source_t (C++ enum), 809 rmt_config (C++ function), 800 rmt_config_t (C++ class), 805 rmt_config_t::channel (C++ member), 805 rmt_config_t::clk_div (C++ member), 806 rmt_config_t::flags (C++ member), 806 rmt_config_t::gpio_num (C++ member), 806 rmt_config_t::mem_block_num (C++ mem- ber), 806 rmt_config_t::rmt_mode (C++ member), 805 rmt_config_t::rx_config (C++ member), 806 rmt_config_t::tx_config (C++ member), 806 RMT_DATA_MODE_FIFO (C++ enumerator), 808 RMT_DATA_MODE_MAX (C++ enumerator), 808 RMT_DATA_MODE_MEM (C++ enumerator), 808 rmt_data_mode_t (C++ enum), 808 RMT_DEFAULT_CONFIG_RX (C macro), 806 RMT_DEFAULT_CONFIG_TX (C macro), 806 rmt_driver_install (C++ function), 801 rmt_driver_uninstall (C++ function), 801 rmt_enable_tx_loop_autostop (C++ func- tion), 804 rmt_fill_tx_items (C++ function), 800 rmt_get_channel_status (C++ function), 801 rmt_get_clk_div (C++ function), 794 rmt_get_counter_clock (C++ function), 801 rmt_get_idle_level (C++ function), 799 rmt_get_mem_block_num (C++ function), 795 rmt_get_mem_pd (C++ function), 796 rmt_get_memory_owner (C++ function), 797 rmt_get_ringbuf_handle (C++ function), 802 rmt_get_rx_idle_thresh (C++ function), 795 rmt_get_source_clk (C++ function), 798 rmt_get_status (C++ function), 799 rmt_get_tx_loop_mode (C++ function), 798 RMT_IDLE_LEVEL_HIGH (C++ enumerator), 808 RMT_IDLE_LEVEL_LOW (C++ enumerator), 808 RMT_IDLE_LEVEL_MAX (C++ enumerator), 808 rmt_idle_level_t (C++ enum), 808 rmt_isr_deregister (C++ function), 800 rmt_isr_handle_t (C++ type), 806 rmt_isr_register (C++ function), 800 rmt_item32_t (C++ class), 804 rmt_item32_t::duration0 (C++ member), 804 rmt_item32_t::duration1 (C++ member), 804 rmt_item32_t::level0 (C++ member), 804 rmt_item32_t::level1 (C++ member), 804 rmt_item32_t::val (C++ member), 804 RMT_MEM_ITEM_NUM (C macro), 806 RMT_MEM_OWNER_MAX (C++ enumerator), 807 RMT_MEM_OWNER_RX (C++ enumerator), 807 rmt_mem_owner_t (C++ enum), 807 RMT_MEM_OWNER_TX (C++ enumerator), 807 rmt_mem_t (C++ class), 804 RMT_MODE_MAX (C++ enumerator), 808 RMT_MODE_RX (C++ enumerator), 808 rmt_mode_t (C++ enum), 808 RMT_MODE_TX (C++ enumerator), 808 rmt_register_tx_end_callback (C++ func- tion), 803 rmt_remove_channel_from_group (C++ func- tion), 803 rmt_rx_config_t (C++ class), 805 rmt_rx_config_t::carrier_duty_percent (C++ member), 805 rmt_rx_config_t::carrier_freq_hz (C++ member), 805 rmt_rx_config_t::carrier_level (C++ member), 805 rmt_rx_config_t::filter_en (C++ member), 805 rmt_rx_config_t::filter_ticks_thresh (C++ member), 805 rmt_rx_config_t::idle_threshold (C++ member), 805 rmt_rx_config_t::rm_carrier (C++ mem- ber), 805 rmt_rx_memory_reset (C++ function), 797 rmt_rx_start (C++ function), 797 rmt_rx_stop (C++ function), 797 rmt_set_clk_div (C++ function), 794 rmt_set_err_intr_en (C++ function), 799 rmt_set_gpio (C++ function), 800 rmt_set_idle_level (C++ function), 798 rmt_set_mem_block_num (C++ function), 795 rmt_set_mem_pd (C++ function), 796 rmt_set_memory_owner (C++ function), 797 rmt_set_rx_filter (C++ function), 798 rmt_set_rx_idle_thresh (C++ function), 794 rmt_set_rx_intr_en (C++ function), 799 rmt_set_rx_thr_intr_en (C++ function), 803 rmt_set_source_clk (C++ function), 798 rmt_set_tx_carrier (C++ function), 796 rmt_set_tx_intr_en (C++ function), 799 rmt_set_tx_loop_count (C++ function), 804 rmt_set_tx_loop_mode (C++ function), 797 rmt_set_tx_thr_intr_en (C++ function), 799 rmt_source_clk_t (C++ enum), 807 rmt_symbol_word_t (C++ union), 809 rmt_symbol_word_t::duration0 (C++ mem- ber), 809 rmt_symbol_word_t::duration1 (C++ mem- ber), 809 rmt_symbol_word_t::level0 (C++ member), 809 Espressif Systems 2207 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index rmt_symbol_word_t::level1 (C++ member), 809 rmt_symbol_word_t::val (C++ member), 809 rmt_symbol_word_t::[anonymous] (C++ member), 809 rmt_translator_get_context (C++ function), 802 rmt_translator_init (C++ function), 802 rmt_translator_set_context (C++ function), 802 rmt_tx_config_t (C++ class), 804 rmt_tx_config_t::carrier_duty_percent (C++ member), 805 rmt_tx_config_t::carrier_en (C++ mem- ber), 805 rmt_tx_config_t::carrier_freq_hz (C++ member), 805 rmt_tx_config_t::carrier_level (C++ member), 805 rmt_tx_config_t::idle_level (C++ mem- ber), 805 rmt_tx_config_t::idle_output_en (C++ member), 805 rmt_tx_config_t::loop_count (C++ mem- ber), 805 rmt_tx_config_t::loop_en (C++ member), 805 rmt_tx_end_callback_t (C++ class), 806 rmt_tx_end_callback_t::arg (C++ member), 806 rmt_tx_end_callback_t::function (C++ member), 806 rmt_tx_end_fn_t (C++ type), 806 rmt_tx_memory_reset (C++ function), 797 rmt_tx_start (C++ function), 796 rmt_tx_stop (C++ function), 796 rmt_wait_tx_done (C++ function), 802 rmt_write_items (C++ function), 801 rmt_write_sample (C++ function), 803 ROLE_FAST_PROV (C++ enumerator), 332 ROLE_NODE (C++ enumerator), 332 ROLE_PROVISIONER (C++ enumerator), 332 rtc_gpio_deinit (C++ function), 674 rtc_gpio_force_hold_all (C++ function), 676 rtc_gpio_force_hold_dis_all (C++ func- tion), 676 rtc_gpio_get_drive_capability (C++ func- tion), 675 rtc_gpio_get_level (C++ function), 674 rtc_gpio_hold_dis (C++ function), 676 rtc_gpio_hold_en (C++ function), 676 rtc_gpio_init (C++ function), 673 RTC_GPIO_IS_VALID_GPIO (C macro), 677 rtc_gpio_is_valid_gpio (C++ function), 673 rtc_gpio_isolate (C++ function), 676 RTC_GPIO_MODE_DISABLED (C++ enumerator), 677 RTC_GPIO_MODE_INPUT_ONLY (C++ enumerator), 677 RTC_GPIO_MODE_INPUT_OUTPUT (C++ enumera- tor), 677 RTC_GPIO_MODE_INPUT_OUTPUT_OD (C++ enu- merator), 677 RTC_GPIO_MODE_OUTPUT_OD (C++ enumerator), 677 RTC_GPIO_MODE_OUTPUT_ONLY (C++ enumera- tor), 677 rtc_gpio_mode_t (C++ enum), 677 rtc_gpio_pulldown_dis (C++ function), 675 rtc_gpio_pulldown_en (C++ function), 675 rtc_gpio_pullup_dis (C++ function), 675 rtc_gpio_pullup_en (C++ function), 674 rtc_gpio_set_direction (C++ function), 674 rtc_gpio_set_direction_in_sleep (C++ function), 674 rtc_gpio_set_drive_capability (C++ func- tion), 675 rtc_gpio_set_level (C++ function), 674 rtc_gpio_wakeup_disable (C++ function), 676 rtc_gpio_wakeup_enable (C++ function), 676 rtc_io_number_get (C++ function), 673 RTC_SLOW_MEM (C macro), 1652 S sample_to_rmt_t (C++ type), 806 SC_EVENT_FOUND_CHANNEL (C++ enumerator), 545 SC_EVENT_GOT_SSID_PSWD (C++ enumerator), 545 SC_EVENT_SCAN_DONE (C++ enumerator), 545 SC_EVENT_SEND_ACK_DONE (C++ enumerator), 545 SC_TYPE_AIRKISS (C++ enumerator), 545 SC_TYPE_ESPTOUCH (C++ enumerator), 545 SC_TYPE_ESPTOUCH_AIRKISS (C++ enumerator), 545 SC_TYPE_ESPTOUCH_V2 (C++ enumerator), 545 sdmmc_can_discard (C++ function), 1273 sdmmc_can_trim (C++ function), 1273 sdmmc_card_init (C++ function), 1272 sdmmc_card_print_info (C++ function), 1272 sdmmc_card_t (C++ class), 1279 sdmmc_card_t::cid (C++ member), 1280 sdmmc_card_t::csd (C++ member), 1280 sdmmc_card_t::ext_csd (C++ member), 1280 sdmmc_card_t::host (C++ member), 1280 sdmmc_card_t::is_ddr (C++ member), 1280 sdmmc_card_t::is_mem (C++ member), 1280 sdmmc_card_t::is_mmc (C++ member), 1280 sdmmc_card_t::is_sdio (C++ member), 1280 sdmmc_card_t::log_bus_width (C++ mem- ber), 1280 sdmmc_card_t::max_freq_khz (C++ member), 1280 sdmmc_card_t::num_io_functions (C++ member), 1280 Espressif Systems 2208 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index sdmmc_card_t::ocr (C++ member), 1280 sdmmc_card_t::raw_cid (C++ member), 1280 sdmmc_card_t::rca (C++ member), 1280 sdmmc_card_t::reserved (C++ member), 1280 sdmmc_card_t::scr (C++ member), 1280 sdmmc_card_t::ssr (C++ member), 1280 sdmmc_cid_t (C++ class), 1277 sdmmc_cid_t::date (C++ member), 1277 sdmmc_cid_t::mfg_id (C++ member), 1277 sdmmc_cid_t::name (C++ member), 1277 sdmmc_cid_t::oem_id (C++ member), 1277 sdmmc_cid_t::revision (C++ member), 1277 sdmmc_cid_t::serial (C++ member), 1277 sdmmc_command_t (C++ class), 1278 sdmmc_command_t::arg (C++ member), 1278 sdmmc_command_t::blklen (C++ member), 1278 sdmmc_command_t::data (C++ member), 1278 sdmmc_command_t::datalen (C++ member), 1278 sdmmc_command_t::error (C++ member), 1279 sdmmc_command_t::flags (C++ member), 1279 sdmmc_command_t::opcode (C++ member), 1278 sdmmc_command_t::response (C++ member), 1278 sdmmc_command_t::timeout_ms (C++ mem- ber), 1279 sdmmc_csd_t (C++ class), 1276 sdmmc_csd_t::capacity (C++ member), 1277 sdmmc_csd_t::card_command_class (C++ member), 1277 sdmmc_csd_t::csd_ver (C++ member), 1277 sdmmc_csd_t::mmc_ver (C++ member), 1277 sdmmc_csd_t::read_block_len (C++ mem- ber), 1277 sdmmc_csd_t::sector_size (C++ member), 1277 sdmmc_csd_t::tr_speed (C++ member), 1277 SDMMC_DISCARD_ARG (C++ enumerator), 1281 SDMMC_ERASE_ARG (C++ enumerator), 1281 sdmmc_erase_arg_t (C++ enum), 1281 sdmmc_erase_sectors (C++ function), 1273 sdmmc_ext_csd_t (C++ class), 1278 sdmmc_ext_csd_t::erase_mem_state (C++ member), 1278 sdmmc_ext_csd_t::power_class (C++ mem- ber), 1278 sdmmc_ext_csd_t::rev (C++ member), 1278 sdmmc_ext_csd_t::sec_feature (C++ mem- ber), 1278 SDMMC_FREQ_26M (C macro), 1281 SDMMC_FREQ_52M (C macro), 1281 SDMMC_FREQ_DEFAULT (C macro), 1281 SDMMC_FREQ_HIGHSPEED (C macro), 1281 SDMMC_FREQ_PROBING (C macro), 1281 sdmmc_full_erase (C++ function), 1274 sdmmc_get_status (C++ function), 1272 SDMMC_HOST_DEFAULT (C macro), 815 sdmmc_host_deinit (C++ function), 814 sdmmc_host_do_transaction (C++ function), 813 SDMMC_HOST_FLAG_1BIT (C macro), 1280 SDMMC_HOST_FLAG_4BIT (C macro), 1280 SDMMC_HOST_FLAG_8BIT (C macro), 1280 SDMMC_HOST_FLAG_DDR (C macro), 1280 SDMMC_HOST_FLAG_DEINIT_ARG (C macro), 1280 SDMMC_HOST_FLAG_SPI (C macro), 1280 sdmmc_host_get_slot_width (C++ function), 813 sdmmc_host_init (C++ function), 812 sdmmc_host_init_slot (C++ function), 812 sdmmc_host_io_int_enable (C++ function), 814 sdmmc_host_io_int_wait (C++ function), 814 sdmmc_host_pullup_en (C++ function), 814 sdmmc_host_set_bus_ddr_mode (C++ func- tion), 813 sdmmc_host_set_bus_width (C++ function), 813 sdmmc_host_set_card_clk (C++ function), 813 SDMMC_HOST_SLOT_0 (C macro), 815 SDMMC_HOST_SLOT_1 (C macro), 815 sdmmc_host_t (C++ class), 1279 sdmmc_host_t::command_timeout_ms (C++ member), 1279 sdmmc_host_t::deinit (C++ member), 1279 sdmmc_host_t::deinit_p (C++ member), 1279 sdmmc_host_t::do_transaction (C++ mem- ber), 1279 sdmmc_host_t::flags (C++ member), 1279 sdmmc_host_t::get_bus_width (C++ mem- ber), 1279 sdmmc_host_t::init (C++ member), 1279 sdmmc_host_t::io_int_enable (C++ mem- ber), 1279 sdmmc_host_t::io_int_wait (C++ member), 1279 sdmmc_host_t::io_voltage (C++ member), 1279 sdmmc_host_t::max_freq_khz (C++ member), 1279 sdmmc_host_t::set_bus_ddr_mode (C++ member), 1279 sdmmc_host_t::set_bus_width (C++ mem- ber), 1279 sdmmc_host_t::set_card_clk (C++ member), 1279 sdmmc_host_t::slot (C++ member), 1279 sdmmc_io_enable_int (C++ function), 1275 sdmmc_io_get_cis_data (C++ function), 1276 sdmmc_io_print_cis_info (C++ function), 1276 sdmmc_io_read_blocks (C++ function), 1275 sdmmc_io_read_byte (C++ function), 1274 sdmmc_io_read_bytes (C++ function), 1274 Espressif Systems 2209 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index sdmmc_io_wait_int (C++ function), 1275 sdmmc_io_write_blocks (C++ function), 1275 sdmmc_io_write_byte (C++ function), 1274 sdmmc_io_write_bytes (C++ function), 1274 sdmmc_mmc_can_sanitize (C++ function), 1273 sdmmc_mmc_sanitize (C++ function), 1273 sdmmc_read_sectors (C++ function), 1273 sdmmc_response_t (C++ type), 1281 sdmmc_scr_t (C++ class), 1277 sdmmc_scr_t::bus_width (C++ member), 1277 sdmmc_scr_t::erase_mem_state (C++ mem- ber), 1277 sdmmc_scr_t::reserved (C++ member), 1277 sdmmc_scr_t::rsvd_mnf (C++ member), 1277 sdmmc_scr_t::sd_spec (C++ member), 1277 SDMMC_SLOT_CONFIG_DEFAULT (C macro), 816 sdmmc_slot_config_t (C++ class), 814 sdmmc_slot_config_t::cd (C++ member), 815 sdmmc_slot_config_t::clk (C++ member), 814 sdmmc_slot_config_t::cmd (C++ member), 814 sdmmc_slot_config_t::d0 (C++ member), 815 sdmmc_slot_config_t::d1 (C++ member), 815 sdmmc_slot_config_t::d2 (C++ member), 815 sdmmc_slot_config_t::d3 (C++ member), 815 sdmmc_slot_config_t::d4 (C++ member), 815 sdmmc_slot_config_t::d5 (C++ member), 815 sdmmc_slot_config_t::d6 (C++ member), 815 sdmmc_slot_config_t::d7 (C++ member), 815 sdmmc_slot_config_t::flags (C++ member), 815 sdmmc_slot_config_t::gpio_cd (C++ mem- ber), 815 sdmmc_slot_config_t::gpio_wp (C++ mem- ber), 815 sdmmc_slot_config_t::width (C++ member), 815 sdmmc_slot_config_t::wp (C++ member), 815 SDMMC_SLOT_FLAG_INTERNAL_PULLUP (C macro), 815 SDMMC_SLOT_NO_CD (C macro), 815 SDMMC_SLOT_NO_WP (C macro), 815 SDMMC_SLOT_WIDTH_DEFAULT (C macro), 815 sdmmc_ssr_t (C++ class), 1278 sdmmc_ssr_t::cur_bus_width (C++ member), 1278 sdmmc_ssr_t::discard_support (C++ mem- ber), 1278 sdmmc_ssr_t::fule_support (C++ member), 1278 sdmmc_ssr_t::reserved (C++ member), 1278 sdmmc_switch_func_rsp_t (C++ class), 1278 sdmmc_switch_func_rsp_t::data (C++ member), 1278 sdmmc_write_sectors (C++ function), 1272 SDSPI_DEFAULT_DMA (C macro), 820 SDSPI_DEFAULT_HOST (C macro), 820 sdspi_dev_handle_t (C++ type), 821 SDSPI_DEVICE_CONFIG_DEFAULT (C macro), 820 sdspi_device_config_t (C++ class), 819 sdspi_device_config_t::gpio_cd (C++ member), 820 sdspi_device_config_t::gpio_cs (C++ member), 819 sdspi_device_config_t::gpio_int (C++ member), 820 sdspi_device_config_t::gpio_wp (C++ member), 820 sdspi_device_config_t::host_id (C++ member), 819 SDSPI_HOST_DEFAULT (C macro), 820 sdspi_host_deinit (C++ function), 819 sdspi_host_do_transaction (C++ function), 818 sdspi_host_init (C++ function), 818 sdspi_host_init_device (C++ function), 818 sdspi_host_init_slot (C++ function), 819 sdspi_host_io_int_enable (C++ function), 819 sdspi_host_io_int_wait (C++ function), 819 sdspi_host_remove_device (C++ function), 818 sdspi_host_set_card_clk (C++ function), 818 SDSPI_SLOT_CONFIG_DEFAULT (C macro), 820 sdspi_slot_config_t (C++ class), 820 sdspi_slot_config_t::dma_channel (C++ member), 820 sdspi_slot_config_t::gpio_cd (C++ mem- ber), 820 sdspi_slot_config_t::gpio_cs (C++ mem- ber), 820 sdspi_slot_config_t::gpio_int (C++ member), 820 sdspi_slot_config_t::gpio_miso (C++ member), 820 sdspi_slot_config_t::gpio_mosi (C++ member), 820 sdspi_slot_config_t::gpio_sck (C++ member), 820 sdspi_slot_config_t::gpio_wp (C++ mem- ber), 820 SDSPI_SLOT_NO_CD (C macro), 820 SDSPI_SLOT_NO_INT (C macro), 820 SDSPI_SLOT_NO_WP (C macro), 820 SECURE_BOOT_PUBLIC_KEY_INDEX_0 (C++ enumerator), 1585 SECURE_BOOT_PUBLIC_KEY_INDEX_1 (C++ enumerator), 1585 SECURE_BOOT_PUBLIC_KEY_INDEX_2 (C++ enumerator), 1585 SemaphoreHandle_t (C++ type), 1456 semBINARY_SEMAPHORE_QUEUE_LENGTH (C macro), 1444 semGIVE_BLOCK_TIME (C macro), 1444 Espressif Systems 2210 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index semSEMAPHORE_QUEUE_ITEM_LENGTH (C (C++ member), 544 macro), 1444 smartconfig_type_t (C++ enum), 545 shared_stack_function (C++ type), 1345 sntp_get_sync_interval (C++ function), 1613 shutdown_handler_t (C++ type), 1563 sntp_get_sync_mode (C++ function), 1613 SIGMADELTA_CHANNEL_0 (C++ enumerator), 823 sntp_get_sync_status (C++ function), 1613 SIGMADELTA_CHANNEL_1 (C++ enumerator), 823 sntp_restart (C++ function), 1614 SIGMADELTA_CHANNEL_2 (C++ enumerator), 823 sntp_set_sync_interval (C++ function), 1613 SIGMADELTA_CHANNEL_3 (C++ enumerator), 823 sntp_set_sync_mode (C++ function), 1613 SIGMADELTA_CHANNEL_4 (C++ enumerator), 823 sntp_set_sync_status (C++ function), 1613 SIGMADELTA_CHANNEL_5 (C++ enumerator), 823 sntp_set_time_sync_notification_cb SIGMADELTA_CHANNEL_6 (C++ enumerator), 823 (C++ function), 1613 SIGMADELTA_CHANNEL_7 (C++ enumerator), 824 SNTP_SYNC_MODE_IMMED (C++ enumerator), 1614 SIGMADELTA_CHANNEL_MAX (C++ enumerator), SNTP_SYNC_MODE_SMOOTH (C++ enumerator), 824 1614 sigmadelta_channel_t (C++ enum), 823 sntp_sync_mode_t (C++ enum), 1614 sigmadelta_config (C++ function), 821 SNTP_SYNC_STATUS_COMPLETED (C++ enumera- sigmadelta_config_t (C++ class), 823 tor), 1614 sigmadelta_config_t::channel (C++ mem- SNTP_SYNC_STATUS_IN_PROGRESS (C++ enu- ber), 823 merator), 1614 sigmadelta_config_t::sigmadelta_duty SNTP_SYNC_STATUS_RESET (C++ enumerator), (C++ member), 823 1614 sigmadelta_config_t::sigmadelta_gpio sntp_sync_status_t (C++ enum), 1614 (C++ member), 823 sntp_sync_time (C++ function), 1613 sigmadelta_config_t::sigmadelta_prescalsentp_sync_time_cb_t (C++ type), 1614 (C++ member), 823 SOC_ADC_ARBITER_SUPPORTED (C macro), 1569 SIGMADELTA_PORT_0 (C++ enumerator), 823 SOC_ADC_CALIBRATION_V1_SUPPORTED (C SIGMADELTA_PORT_MAX (C++ enumerator), 823 macro), 1569 sigmadelta_port_t (C++ enum), 823 SOC_ADC_CHANNEL_NUM (C macro), 1569 sigmadelta_set_duty (C++ function), 822 SOC_ADC_DIG_CTRL_SUPPORTED (C macro), 1569 sigmadelta_set_pin (C++ function), 822 SOC_ADC_DIGI_CONTROLLER_NUM (C macro), sigmadelta_set_prescale (C++ function), 822 1569 slave_transaction_cb_t (C++ type), 848 SOC_ADC_DIGI_MAX_BITWIDTH (C macro), 1569 smartconfig_event_got_ssid_pswd_t SOC_ADC_FILTER_SUPPORTED (C macro), 1569 (C++ class), 544 SOC_ADC_MAX_BITWIDTH (C macro), 1569 smartconfig_event_got_ssid_pswd_t::bssiSdOC_ADC_MAX_CHANNEL_NUM (C macro), 1569 (C++ member), 544 SOC_ADC_MONITOR_SUPPORTED (C macro), 1569 smartconfig_event_got_ssid_pswd_t::bssiSdO_Cs_eAtDC_PATT_LEN_MAX (C macro), 1569 (C++ member), 544 SOC_ADC_PERIPH_NUM (C macro), 1569 smartconfig_event_got_ssid_pswd_t::cellSpOhCo_nAeD_Ci_pRTC_CTRL_SUPPORTED (C macro), 1569 (C++ member), 544 SOC_ADC_SAMPLE_FREQ_THRES_HIGH (C smartconfig_event_got_ssid_pswd_t::password macro), 1569 (C++ member), 544 SOC_ADC_SAMPLE_FREQ_THRES_LOW (C macro), smartconfig_event_got_ssid_pswd_t::ssid 1569 (C++ member), 544 SOC_ADC_SUPPORTED (C macro), 1568 smartconfig_event_got_ssid_pswd_t::tokeSnOC_AES_GDMA (C macro), 1574 (C++ member), 544 SOC_AES_SUPPORT_AES_128 (C macro), 1574 smartconfig_event_got_ssid_pswd_t::typeSOC_AES_SUPPORT_AES_256 (C macro), 1574 (C++ member), 544 SOC_AES_SUPPORT_DMA (C macro), 1574 smartconfig_event_t (C++ enum), 545 SOC_AES_SUPPORTED (C macro), 1569 SMARTCONFIG_START_CONFIG_DEFAULT (C SOC_APB_BACKUP_DMA (C macro), 1570 macro), 544 SOC_APPCPU_HAS_CLOCK_GATING_BUG (C smartconfig_start_config_t (C++ class), macro), 1569 544 SOC_ASYNC_MEMCPY_SUPPORTED (C macro), 1568 smartconfig_start_config_t::enable_log SOC_BLUEDROID_SUPPORTED (C macro), 1568 (C++ member), 544 SOC_BT_SUPPORTED (C macro), 1568 smartconfig_start_config_t::esp_touch_vS2O_Ce_nCaAbClHeE__cSrUyPpPtORT_WRAP (C macro), 1568 (C++ member), 544 SOC_CCOMP_TIMER_SUPPORTED (C macro), 1568 smartconfig_start_config_t::esp_touch_vS2O_Ck_eCyOEX_HW_PTI (C macro), 1575 Espressif Systems 2211 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index SOC_CPU_CORES_NUM (C macro), 1568 SOC_DEDIC_GPIO_IN_CHANNELS_NUM (C macro), 1570 SOC_DEDIC_GPIO_OUT_AUTO_ENABLE (C macro), 1570 SOC_DEDIC_GPIO_OUT_CHANNELS_NUM (C macro), 1570 SOC_DEDICATED_GPIO_SUPPORTED (C macro), 1568 SOC_DIG_SIGN_SUPPORTED (C macro), 1569 SOC_DS_KEY_CHECK_MAX_WAIT_US (C macro), 1570 SOC_DS_KEY_PARAM_MD_IV_LENGTH (C macro), 1570 SOC_DS_SIGNATURE_MAX_BIT_LEN (C macro), 1570 SOC_EFUSE_KEY_PURPOSE_FIELD (C macro), 1569 SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS (C macro), 1574 SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS (C macro), 1574 SOC_FLASH_ENC_SUPPORTED (C macro), 1569 SOC_FLASH_ENCRYPTED_XTS_AES_BLOCK_MAX (C macro), 1574 SOC_FLASH_ENCRYPTION_XTS_AES (C macro), 1574 SOC_FLASH_ENCRYPTION_XTS_AES_128 (C macro), 1574 SOC_FLASH_ENCRYPTION_XTS_AES_256 (C macro), 1574 SOC_GDMA_GROUPS (C macro), 1570 SOC_GDMA_PAIRS_PER_GROUP (C macro), 1570 SOC_GDMA_PSRAM_MIN_ALIGN (C macro), 1570 SOC_GDMA_SUPPORT_PSRAM (C macro), 1570 SOC_GDMA_SUPPORTED (C macro), 1568 SOC_GPIO_PIN_COUNT (C macro), 1570 SOC_GPIO_PORT (C macro), 1570 SOC_GPIO_SUPPORT_FORCE_HOLD (C macro), 1570 SOC_GPIO_SUPPORT_RTC_INDEPENDENT (C macro), 1570 SOC_GPIO_SUPPORT_SLP_SWITCH (C macro), 1570 SOC_GPIO_VALID_GPIO_MASK (C macro), 1570 SOC_GPIO_VALID_OUTPUT_GPIO_MASK (C macro), 1570 SOC_HMAC_SUPPORTED (C macro), 1569 SOC_I2C_FIFO_LEN (C macro), 1570 SOC_I2C_NUM (C macro), 1570 SOC_I2C_SUPPORT_HW_CLR_BUS (C macro), 1570 SOC_I2C_SUPPORT_HW_FSM_RST (C macro), 1570 SOC_I2C_SUPPORT_RTC (C macro), 1570 SOC_I2C_SUPPORT_SLAVE (C macro), 1570 SOC_I2C_SUPPORT_XTAL (C macro), 1570 SOC_I2S_HW_VERSION_2 (C macro), 1570 SOC_I2S_NUM (C macro), 1570 SOC_I2S_SUPPORTED (C macro), 1569 SOC_I2S_SUPPORTS_PCM (C macro), 1570 SOC_I2S_SUPPORTS_PDM (C macro), 1570 SOC_I2S_SUPPORTS_PDM_CODEC (C macro), 1570 SOC_I2S_SUPPORTS_PDM_RX (C macro), 1570 SOC_I2S_SUPPORTS_PDM_TX (C macro), 1570 SOC_I2S_SUPPORTS_TDM (C macro), 1570 SOC_LCD_I80_BUS_WIDTH (C macro), 1572 SOC_LCD_I80_BUSES (C macro), 1572 SOC_LCD_I80_SUPPORTED (C macro), 1572 SOC_LCD_RGB_DATA_WIDTH (C macro), 1572 SOC_LCD_RGB_PANELS (C macro), 1572 SOC_LCD_RGB_SUPPORTED (C macro), 1572 SOC_LCDCAM_SUPPORTED (C macro), 1568 SOC_MAC_BB_PD_MEM_SIZE (C macro), 1574 SOC_MCPWM_BASE_CLK_HZ (C macro), 1571 SOC_MCPWM_CAPTURE_CHANNELS_PER_TIMER (C macro), 1571 SOC_MCPWM_CAPTURE_TIMERS_PER_GROUP (C macro), 1571 SOC_MCPWM_COMPARATORS_PER_OPERATOR (C macro), 1571 SOC_MCPWM_GENERATORS_PER_OPERATOR (C macro), 1571 SOC_MCPWM_GPIO_FAULTS_PER_GROUP (C macro), 1571 SOC_MCPWM_GPIO_SYNCHROS_PER_GROUP (C macro), 1571 SOC_MCPWM_GROUPS (C macro), 1571 SOC_MCPWM_OPERATORS_PER_GROUP (C macro), 1571 SOC_MCPWM_SUPPORTED (C macro), 1568 SOC_MCPWM_SWSYNC_CAN_PROPAGATE (C macro), 1571 SOC_MCPWM_TIMERS_PER_GROUP (C macro), 1571 SOC_MCPWM_TRIGGERS_PER_OPERATOR (C macro), 1571 SOC_MEMSPI_IS_INDEPENDENT (C macro), 1573 SOC_MPI_SUPPORTED (C macro), 1569 SOC_PCNT_CHANNELS_PER_UNIT (C macro), 1571 SOC_PCNT_GROUPS (C macro), 1571 SOC_PCNT_SUPPORTED (C macro), 1568 SOC_PCNT_THRES_POINT_PER_UNIT (C macro), 1571 SOC_PCNT_UNITS_PER_GROUP (C macro), 1571 SOC_PHY_DIG_REGS_MEM_SIZE (C macro), 1574 SOC_PM_SUPPORT_BT_WAKEUP (C macro), 1574 SOC_PM_SUPPORT_CPU_PD (C macro), 1574 SOC_PM_SUPPORT_DEEPSLEEP_CHECK_STUB_ONLY (C macro), 1574 SOC_PM_SUPPORT_EXT_WAKEUP (C macro), 1574 SOC_PM_SUPPORT_TAGMEM_PD (C macro), 1574 SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP (C macro), 1574 SOC_PM_SUPPORT_WIFI_WAKEUP (C macro), 1574 SOC_PSRAM_DMA_CAPABLE (C macro), 1569 SOC_REG_TO_ULP_PERIPH_SEL (C++ function), 1635 SOC_RISCV_COPROC_SUPPORTED (C macro), 1568 Espressif Systems 2212 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index SOC_RMT_CHANNELS_PER_GROUP (C macro), 1571 SOC_SHA_SUPPORT_SHA1 (C macro), 1574 SOC_RMT_GROUPS (C macro), 1571 SOC_SHA_SUPPORT_SHA224 (C macro), 1574 SOC_RMT_MEM_WORDS_PER_CHANNEL (C macro), SOC_SHA_SUPPORT_SHA256 (C macro), 1574 1571 SOC_SHA_SUPPORT_SHA384 (C macro), 1574 SOC_RMT_RX_CANDIDATES_PER_GROUP (C SOC_SHA_SUPPORT_SHA512 (C macro), 1574 macro), 1571 SOC_SHA_SUPPORT_SHA512_224 (C macro), 1574 SOC_RMT_SUPPORT_DMA (C macro), 1572 SOC_SHA_SUPPORT_SHA512_256 (C macro), 1574 SOC_RMT_SUPPORT_RX_DEMODULATION (C SOC_SHA_SUPPORT_SHA512_T (C macro), 1574 macro), 1571 SOC_SHA_SUPPORTED (C macro), 1569 SOC_RMT_SUPPORT_RX_PINGPONG (C macro), SOC_SIGMADELTA_CHANNEL_NUM (C macro), 1572 1571 SOC_SIGMADELTA_NUM (C macro), 1572 SOC_RMT_SUPPORT_TX_ASYNC_STOP (C macro), SOC_SIGMADELTA_SUPPORTED (C macro), 1569 1571 SOC_SPI_MAX_PRE_DIVIDER (C macro), 1573 SOC_RMT_SUPPORT_TX_CARRIER_ALWAYS_ON SOC_SPI_MAXIMUM_BUFFER_SIZE (C macro), (C macro), 1572 1572 SOC_RMT_SUPPORT_TX_LOOP_AUTO_STOP (C SOC_SPI_MEM_SUPPORT_AUTO_RESUME (C macro), 1572 macro), 1575 SOC_RMT_SUPPORT_TX_LOOP_COUNT (C macro), SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND (C 1571 macro), 1574 SOC_RMT_SUPPORT_TX_SYNCHRO (C macro), 1572 SOC_SPI_MEM_SUPPORT_AUTO_WAIT_IDLE (C SOC_RMT_SUPPORT_XTAL (C macro), 1572 macro), 1574 SOC_RMT_SUPPORTED (C macro), 1569 SOC_SPI_MEM_SUPPORT_OPI_MODE (C macro), SOC_RMT_TX_CANDIDATES_PER_GROUP (C 1575 macro), 1571 SOC_SPI_MEM_SUPPORT_SW_SUSPEND (C SOC_RSA_MAX_BIT_LEN (C macro), 1574 macro), 1575 SOC_RTC_CNTL_CPU_PD_DMA_ADDR_ALIGN (C SOC_SPI_MEM_SUPPORT_TIME_TUNING (C macro), 1572 macro), 1575 SOC_RTC_CNTL_CPU_PD_DMA_BLOCK_SIZE (C SOC_SPI_PERIPH_CS_NUM (C macro), 1572 macro), 1572 SOC_SPI_PERIPH_NUM (C macro), 1572 SOC_RTC_CNTL_CPU_PD_DMA_BUS_WIDTH (C SOC_SPI_PERIPH_SUPPORT_CONTROL_DUMMY_OUT macro), 1572 (C macro), 1573 SOC_RTC_CNTL_CPU_PD_REG_FILE_NUM (C SOC_SPI_PERIPH_SUPPORT_MULTILINE_MODE macro), 1572 (C macro), 1573 SOC_RTC_CNTL_CPU_PD_RETENTION_MEM_SIZE SOC_SPI_SLAVE_SUPPORT_SEG_TRANS (C (C macro), 1572 macro), 1572 SOC_RTC_CNTL_TAGMEM_PD_DMA_ADDR_ALIGN SOC_SPI_SUPPORT_CD_SIG (C macro), 1572 (C macro), 1572 SOC_SPI_SUPPORT_CONTINUOUS_TRANS (C SOC_RTC_CNTL_TAGMEM_PD_DMA_BUS_WIDTH macro), 1572 (C macro), 1572 SOC_SPI_SUPPORT_DDRCLK (C macro), 1572 SOC_RTC_FAST_MEM_SUPPORTED (C macro), 1569 SOC_SPI_SUPPORT_OCT (C macro), 1573 SOC_RTC_SLOW_MEM_SUPPORTED (C macro), 1569 SOC_SPI_SUPPORT_SLAVE_HD_VER2 (C macro), SOC_RTCIO_HOLD_SUPPORTED (C macro), 1572 1573 SOC_RTCIO_INPUT_OUTPUT_SUPPORTED (C SOC_SPIRAM_SUPPORTED (C macro), 1573 macro), 1572 SOC_SUPPORT_COEXISTENCE (C macro), 1569 SOC_RTCIO_PIN_COUNT (C macro), 1572 SOC_SUPPORT_SECURE_BOOT_REVOKE_KEY (C SOC_RTCIO_WAKE_SUPPORTED (C macro), 1572 macro), 1574 SOC_SDMMC_HOST_SUPPORTED (C macro), 1569 SOC_SUPPORTS_SECURE_DL_MODE (C macro), SOC_SDMMC_NUM_SLOTS (C macro), 1575 1569 SOC_SDMMC_SUPPORT_XTAL_CLOCK (C macro), SOC_SYSTIMER_ALARM_MISS_COMPENSATE (C 1575 macro), 1573 SOC_SDMMC_USE_GPIO_MATRIX (C macro), 1575 SOC_SYSTIMER_ALARM_NUM (C macro), 1573 SOC_SECURE_BOOT_SUPPORTED (C macro), 1569 SOC_SYSTIMER_BIT_WIDTH_HI (C macro), 1573 SOC_SECURE_BOOT_V2_RSA (C macro), 1574 SOC_SYSTIMER_BIT_WIDTH_LO (C macro), 1573 SOC_SHA_DMA_MAX_BUFFER_SIZE (C macro), SOC_SYSTIMER_COUNTER_NUM (C macro), 1573 1574 SOC_SYSTIMER_FIXED_TICKS_US (C macro), SOC_SHA_GDMA (C macro), 1574 1573 SOC_SHA_SUPPORT_DMA (C macro), 1574 SOC_SYSTIMER_INT_LEVEL (C macro), 1573 SOC_SHA_SUPPORT_RESUME (C macro), 1574 SOC_TEMP_SENSOR_SUPPORTED (C macro), 1569 Espressif Systems 2213 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index SOC_TEMPERATURE_SENSOR_SUPPORT_FAST_RC spi_bus_config_t::data4_io_num (C++ (C macro), 1575 member), 833 SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (C spi_bus_config_t::data5_io_num (C++ macro), 1573 member), 833 SOC_TIMER_GROUP_SUPPORT_XTAL (C macro), spi_bus_config_t::data6_io_num (C++ 1573 member), 833 SOC_TIMER_GROUP_TIMERS_PER_GROUP (C spi_bus_config_t::data7_io_num (C++ macro), 1573 member), 833 SOC_TIMER_GROUP_TOTAL_TIMERS (C macro), spi_bus_config_t::flags (C++ member), 833 1573 spi_bus_config_t::intr_flags (C++ mem- SOC_TIMER_GROUPS (C macro), 1573 ber), 833 SOC_TOUCH_PAD_MEASURE_WAIT_MAX (C spi_bus_config_t::max_transfer_sz macro), 1573 (C++ member), 833 SOC_TOUCH_PAD_THRESHOLD_MAX (C macro), spi_bus_config_t::miso_io_num (C++ 1573 member), 833 SOC_TOUCH_PROXIMITY_CHANNEL_NUM (C spi_bus_config_t::mosi_io_num (C++ macro), 1573 member), 833 SOC_TOUCH_PROXIMITY_MEAS_DONE_SUPPORTEDspi_bus_config_t::quadhd_io_num (C++ (C macro), 1573 member), 833 SOC_TOUCH_SENSOR_NUM (C macro), 1573 spi_bus_config_t::quadwp_io_num (C++ SOC_TOUCH_VERSION_2 (C macro), 1573 member), 833 SOC_TWAI_SUPPORTED (C macro), 1568 spi_bus_config_t::sclk_io_num (C++ SOC_UART_BITRATE_MAX (C macro), 1573 member), 833 SOC_UART_FIFO_LEN (C macro), 1573 spi_bus_free (C++ function), 832 SOC_UART_NUM (C macro), 1573 spi_bus_initialize (C++ function), 832 SOC_UART_REQUIRE_CORE_RESET (C macro), spi_bus_remove_device (C++ function), 835 1573 spi_bus_remove_flash_device (C++ func- SOC_UART_SUPPORT_FSM_TX_WAIT_SEND (C tion), 1290 macro), 1573 spi_cal_clock (C++ function), 837 SOC_UART_SUPPORT_RTC_CLK (C macro), 1573 SPI_CLK_APB (C++ enumerator), 831 SOC_UART_SUPPORT_WAKEUP_INT (C macro), SPI_CLK_XTAL (C++ enumerator), 831 1573 spi_clock_source_t (C++ enum), 831 SOC_UART_SUPPORT_XTAL_CLK (C macro), 1573 spi_common_dma_t (C++ enum), 834 SOC_ULP_SUPPORTED (C macro), 1568 SPI_DEVICE_3WIRE (C macro), 841 SOC_USB_OTG_SUPPORTED (C macro), 1568 spi_device_acquire_bus (C++ function), 837 SOC_USB_PERIPH_NUM (C macro), 1573 SPI_DEVICE_BIT_LSBFIRST (C macro), 841 SOC_USB_SERIAL_JTAG_SUPPORTED (C macro), SPI_DEVICE_CLK_AS_CS (C macro), 841 1568 SPI_DEVICE_DDRCLK (C macro), 841 SOC_WIFI_HW_TSF (C macro), 1574 spi_device_get_trans_result (C++ func- SOC_WIFI_LIGHT_SLEEP_CLK_WIDTH (C tion), 836 macro), 1574 SPI_DEVICE_HALFDUPLEX (C macro), 841 SOC_WIFI_SUPPORTED (C macro), 1568 spi_device_handle_t (C++ type), 842 SOC_XT_WDT_SUPPORTED (C macro), 1569 spi_device_interface_config_t (C++ SPI1_HOST (C++ enumerator), 831 class), 838 SPI2_HOST (C++ enumerator), 831 spi_device_interface_config_t::address_bits SPI3_HOST (C++ enumerator), 831 (C++ member), 838 spi_bus_add_device (C++ function), 835 spi_device_interface_config_t::clock_speed_hz spi_bus_add_flash_device (C++ function), (C++ member), 838 1290 spi_device_interface_config_t::command_bits spi_bus_config_t (C++ class), 832 (C++ member), 838 spi_bus_config_t::data0_io_num (C++ spi_device_interface_config_t::cs_ena_posttrans member), 833 (C++ member), 838 spi_bus_config_t::data1_io_num (C++ spi_device_interface_config_t::cs_ena_pretrans member), 833 (C++ member), 838 spi_bus_config_t::data2_io_num (C++ spi_device_interface_config_t::dummy_bits member), 833 (C++ member), 838 spi_bus_config_t::data3_io_num (C++ spi_device_interface_config_t::duty_cycle_pos member), 833 (C++ member), 838 Espressif Systems 2214 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index spi_device_interface_config_t::flags (C++ member), 1303 (C++ member), 839 spi_flash_encryption_t::flash_encryption_enable spi_device_interface_config_t::input_delay_ns (C++ member), 1302 (C++ member), 839 spi_flash_erase_range (C++ function), 1297 spi_device_interface_config_t::mode spi_flash_erase_sector (C++ function), 1297 (C++ member), 838 SPI_FLASH_FASTRD (C++ enumerator), 1305 spi_device_interface_config_t::post_cb spi_flash_get_chip_size (C++ function), (C++ member), 839 1296 spi_device_interface_config_t::pre_cb spi_flash_guard_end_func_t (C++ type), (C++ member), 839 1301 spi_device_interface_config_t::queue_siszpei_flash_guard_funcs_t (C++ class), 1300 (C++ member), 839 spi_flash_guard_funcs_t::end (C++ mem- spi_device_interface_config_t::spics_io_num ber), 1300 (C++ member), 839 spi_flash_guard_funcs_t::is_safe_write_address SPI_DEVICE_NO_DUMMY (C macro), 841 (C++ member), 1300 spi_device_polling_end (C++ function), 836 spi_flash_guard_funcs_t::op_lock (C++ spi_device_polling_start (C++ function), member), 1300 836 spi_flash_guard_funcs_t::op_unlock spi_device_polling_transmit (C++ func- (C++ member), 1300 tion), 837 spi_flash_guard_funcs_t::start (C++ SPI_DEVICE_POSITIVE_CS (C macro), 841 member), 1300 spi_device_queue_trans (C++ function), 835 spi_flash_guard_funcs_t::yield (C++ spi_device_release_bus (C++ function), 837 member), 1300 SPI_DEVICE_RXBIT_LSBFIRST (C macro), 841 spi_flash_guard_get (C++ function), 1299 spi_device_transmit (C++ function), 836 spi_flash_guard_set (C++ function), 1299 SPI_DEVICE_TXBIT_LSBFIRST (C macro), 840 spi_flash_guard_start_func_t (C++ type), SPI_DMA_CH_AUTO (C++ enumerator), 835 1301 spi_dma_chan_t (C++ type), 834 spi_flash_host_driver_s (C++ class), 1303 SPI_DMA_DISABLED (C++ enumerator), 834 spi_flash_host_driver_s::check_suspend SPI_EV_BUF_RX (C++ enumerator), 831 (C++ member), 1304 SPI_EV_BUF_TX (C++ enumerator), 831 spi_flash_host_driver_s::common_command SPI_EV_CMD9 (C++ enumerator), 832 (C++ member), 1303 SPI_EV_CMDA (C++ enumerator), 832 spi_flash_host_driver_s::configure_host_io_mode SPI_EV_RECV (C++ enumerator), 831 (C++ member), 1304 SPI_EV_RECV_DMA_READY (C++ enumerator), 831 spi_flash_host_driver_s::dev_config SPI_EV_SEND (C++ enumerator), 831 (C++ member), 1303 SPI_EV_SEND_DMA_READY (C++ enumerator), 831 spi_flash_host_driver_s::erase_block SPI_EV_TRANS (C++ enumerator), 832 (C++ member), 1303 spi_event_t (C++ enum), 831 spi_flash_host_driver_s::erase_chip spi_flash_cache2phys (C++ function), 1299 (C++ member), 1303 SPI_FLASH_CACHE2PHYS_FAIL (C macro), 1301 spi_flash_host_driver_s::erase_sector spi_flash_cache_enabled (C++ function), (C++ member), 1303 1299 spi_flash_host_driver_s::flush_cache spi_flash_chip_t (C++ type), 1296 (C++ member), 1304 SPI_FLASH_CONFIG_CONF_BITS (C macro), 1305 spi_flash_host_driver_s::host_status SPI_FLASH_DIO (C++ enumerator), 1306 (C++ member), 1304 SPI_FLASH_DOUT (C++ enumerator), 1305 spi_flash_host_driver_s::poll_cmd_done spi_flash_enable_cache (C++ function), 1299 (C++ member), 1304 spi_flash_encryption_t (C++ class), 1302 spi_flash_host_driver_s::program_page spi_flash_encryption_t::flash_encryption_check(C++ member), 1303 (C++ member), 1303 spi_flash_host_driver_s::read (C++ spi_flash_encryption_t::flash_encryption_data_mpermebpera)r, 1e304 (C++ member), 1302 spi_flash_host_driver_s::read_data_slicer spi_flash_encryption_t::flash_encryption_destr(Co+y+ member), 1304 (C++ member), 1303 spi_flash_host_driver_s::read_id (C++ spi_flash_encryption_t::flash_encryption_disabmleember), 1303 (C++ member), 1302 spi_flash_host_driver_s::read_status spi_flash_encryption_t::flash_encryption_done (C++ member), 1303 Espressif Systems 2215 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index spi_flash_host_driver_s::resume (C++ member), 1302 member), 1304 spi_flash_sus_cmd_conf::sus_mask (C++ spi_flash_host_driver_s::set_write_protect member), 1302 (C++ member), 1303 SPI_FLASH_TRANS_FLAG_BYTE_SWAP (C spi_flash_host_driver_s::supports_direct_read macro), 1304 (C++ member), 1304 SPI_FLASH_TRANS_FLAG_CMD16 (C macro), 1304 spi_flash_host_driver_s::supports_direcStP_Iw_rFiLtAeSH_TRANS_FLAG_IGNORE_BASEIO (C (C++ member), 1303 macro), 1304 spi_flash_host_driver_s::sus_setup spi_flash_trans_t (C++ class), 1301 (C++ member), 1304 spi_flash_trans_t::address (C++ member), spi_flash_host_driver_s::suspend (C++ 1302 member), 1304 spi_flash_trans_t::address_bitlen spi_flash_host_driver_s::write_data_slicer (C++ member), 1302 (C++ member), 1304 spi_flash_trans_t::command (C++ member), spi_flash_host_driver_t (C++ type), 1305 1302 spi_flash_host_inst_t (C++ class), 1303 spi_flash_trans_t::dummy_bitlen (C++ spi_flash_host_inst_t::driver (C++ member), 1302 member), 1303 spi_flash_trans_t::flags (C++ member), spi_flash_init (C++ function), 1296 1302 spi_flash_is_safe_write_address_t spi_flash_trans_t::io_mode (C++ member), (C++ type), 1301 1302 spi_flash_mmap (C++ function), 1298 spi_flash_trans_t::miso_data (C++ mem- SPI_FLASH_MMAP_DATA (C++ enumerator), 1301 ber), 1302 spi_flash_mmap_dump (C++ function), 1298 spi_flash_trans_t::miso_len (C++ mem- spi_flash_mmap_get_free_pages (C++ func- ber), 1302 tion), 1299 spi_flash_trans_t::mosi_data (C++ mem- spi_flash_mmap_handle_t (C++ type), 1301 ber), 1302 SPI_FLASH_MMAP_INST (C++ enumerator), 1301 spi_flash_trans_t::mosi_len (C++ mem- spi_flash_mmap_memory_t (C++ enum), 1301 ber), 1302 spi_flash_mmap_pages (C++ function), 1298 spi_flash_trans_t::reserved (C++ mem- SPI_FLASH_MMU_PAGE_SIZE (C macro), 1300 ber), 1302 spi_flash_munmap (C++ function), 1298 spi_flash_wrap_mode_t (C++ enum), 1301 spi_flash_op_lock_func_t (C++ type), 1301 spi_flash_wrap_set (C++ function), 1296 spi_flash_op_unlock_func_t (C++ type), spi_flash_write (C++ function), 1297 1301 spi_flash_write_encrypted (C++ function), SPI_FLASH_OPI_DTR (C++ enumerator), 1306 1297 SPI_FLASH_OPI_FLAG (C macro), 1305 SPI_FLASH_YIELD_REQ_SUSPEND (C macro), SPI_FLASH_OPI_STR (C++ enumerator), 1306 1296 spi_flash_os_yield_t (C++ type), 1301 SPI_FLASH_YIELD_REQ_YIELD (C macro), 1296 spi_flash_phys2cache (C++ function), 1299 SPI_FLASH_YIELD_STA_RESUME (C macro), 1296 SPI_FLASH_QIO (C++ enumerator), 1306 spi_get_actual_clock (C++ function), 837 SPI_FLASH_QOUT (C++ enumerator), 1306 spi_get_freq_limit (C++ function), 838 spi_flash_read (C++ function), 1297 spi_get_timing (C++ function), 838 spi_flash_read_encrypted (C++ function), spi_host_device_t (C++ enum), 831 1297 SPI_HOST_MAX (C++ enumerator), 831 SPI_FLASH_READ_MODE_MAX (C++ enumerator), spi_line_mode_t (C++ class), 831 1306 spi_line_mode_t::addr_lines (C++ mem- SPI_FLASH_READ_MODE_MIN (C macro), 1305 ber), 831 SPI_FLASH_SEC_SIZE (C macro), 1300 spi_line_mode_t::cmd_lines (C++ member), SPI_FLASH_SLOWRD (C++ enumerator), 1305 831 spi_flash_sus_cmd_conf (C++ class), 1302 spi_line_mode_t::data_lines (C++ mem- spi_flash_sus_cmd_conf::cmd_rdsr (C++ ber), 831 member), 1302 SPI_MASTER_FREQ_10M (C macro), 840 spi_flash_sus_cmd_conf::res_cmd (C++ SPI_MASTER_FREQ_11M (C macro), 840 member), 1302 SPI_MASTER_FREQ_13M (C macro), 840 spi_flash_sus_cmd_conf::reserved (C++ SPI_MASTER_FREQ_16M (C macro), 840 member), 1302 SPI_MASTER_FREQ_20M (C macro), 840 spi_flash_sus_cmd_conf::sus_cmd (C++ SPI_MASTER_FREQ_26M (C macro), 840 Espressif Systems 2216 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index SPI_MASTER_FREQ_40M (C macro), 840 spi_transaction_ext_t::base (C++ mem- SPI_MASTER_FREQ_80M (C macro), 840 ber), 840 SPI_MASTER_FREQ_8M (C macro), 840 spi_transaction_ext_t::command_bits SPI_MASTER_FREQ_9M (C macro), 840 (C++ member), 840 SPI_MAX_DMA_LEN (C macro), 833 spi_transaction_ext_t::dummy_bits SPI_SLAVE_BIT_LSBFIRST (C macro), 848 (C++ member), 840 spi_slave_free (C++ function), 845 spi_transaction_t (C++ class), 839 spi_slave_get_trans_result (C++ function), spi_transaction_t (C++ type), 842 846 spi_transaction_t::addr (C++ member), 839 spi_slave_initialize (C++ function), 845 spi_transaction_t::cmd (C++ member), 839 spi_slave_interface_config_t (C++ class), spi_transaction_t::flags (C++ member), 847 839 spi_slave_interface_config_t::flags spi_transaction_t::length (C++ member), (C++ member), 847 839 spi_slave_interface_config_t::mode spi_transaction_t::rx_buffer (C++ mem- (C++ member), 847 ber), 840 spi_slave_interface_config_t::post_setuspp_ic_btransaction_t::rx_data (C++ member), (C++ member), 847 840 spi_slave_interface_config_t::post_transsp_ic_btransaction_t::rxlength (C++ mem- (C++ member), 847 ber), 839 spi_slave_interface_config_t::queue_sizsepi_transaction_t::tx_buffer (C++ mem- (C++ member), 847 ber), 840 spi_slave_interface_config_t::spics_io_snpuim_transaction_t::tx_data (C++ member), (C++ member), 847 840 spi_slave_queue_trans (C++ function), 846 spi_transaction_t::user (C++ member), 839 SPI_SLAVE_RXBIT_LSBFIRST (C macro), 848 SPICOMMON_BUSFLAG_DUAL (C macro), 834 spi_slave_transaction_t (C++ class), 847 SPICOMMON_BUSFLAG_GPIO_PINS (C macro), spi_slave_transaction_t (C++ type), 848 834 spi_slave_transaction_t::length (C++ SPICOMMON_BUSFLAG_IO4_IO7 (C macro), 834 member), 847 SPICOMMON_BUSFLAG_IOMUX_PINS (C macro), spi_slave_transaction_t::rx_buffer 834 (C++ member), 847 SPICOMMON_BUSFLAG_MASTER (C macro), 834 spi_slave_transaction_t::trans_len SPICOMMON_BUSFLAG_MISO (C macro), 834 (C++ member), 847 SPICOMMON_BUSFLAG_MOSI (C macro), 834 spi_slave_transaction_t::tx_buffer SPICOMMON_BUSFLAG_NATIVE_PINS (C macro), (C++ member), 847 834 spi_slave_transaction_t::user (C++ SPICOMMON_BUSFLAG_OCTAL (C macro), 834 member), 847 SPICOMMON_BUSFLAG_QUAD (C macro), 834 spi_slave_transmit (C++ function), 846 SPICOMMON_BUSFLAG_SCLK (C macro), 834 SPI_SLAVE_TXBIT_LSBFIRST (C macro), 848 SPICOMMON_BUSFLAG_SLAVE (C macro), 834 SPI_SWAP_DATA_RX (C macro), 834 SPICOMMON_BUSFLAG_WPHD (C macro), 834 SPI_SWAP_DATA_TX (C macro), 833 StaticRingbuffer_t (C++ type), 1513 SPI_TRANS_CS_KEEP_ACTIVE (C macro), 841 StreamBufferHandle_t (C++ type), 1489 SPI_TRANS_MODE_DIO (C macro), 841 SUB_OPCODE_ALU_CNT (C macro), 1639 SPI_TRANS_MODE_DIOQIO_ADDR (C macro), 841 SUB_OPCODE_ALU_IMM (C macro), 1639 SPI_TRANS_MODE_OCT (C macro), 841 SUB_OPCODE_ALU_REG (C macro), 1639 SPI_TRANS_MODE_QIO (C macro), 841 SUB_OPCODE_B (C macro), 1640 SPI_TRANS_MULTILINE_ADDR (C macro), 842 SUB_OPCODE_BS (C macro), 1640 SPI_TRANS_MULTILINE_CMD (C macro), 841 SUB_OPCODE_BX (C macro), 1640 SPI_TRANS_USE_RXDATA (C macro), 841 SUB_OPCODE_END (C macro), 1640 SPI_TRANS_USE_TXDATA (C macro), 841 SUB_OPCODE_MACRO_BRANCH (C macro), 1640 SPI_TRANS_VARIABLE_ADDR (C macro), 841 SUB_OPCODE_MACRO_LABEL (C macro), 1640 SPI_TRANS_VARIABLE_CMD (C macro), 841 SUB_OPCODE_MACRO_LABELPC (C macro), 1640 SPI_TRANS_VARIABLE_DUMMY (C macro), 841 SUB_OPCODE_SLEEP (C macro), 1640 spi_transaction_ext_t (C++ class), 840 SUB_OPCODE_ST (C macro), 1639 spi_transaction_ext_t::address_bits SUB_OPCODE_ST_AUTO (C macro), 1639 (C++ member), 840 SUB_OPCODE_ST_OFFSET (C macro), 1639 Espressif Systems 2217 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index T tinyusb_config_cdcacm_t::cdc_port taskDISABLE_INTERRUPTS (C macro), 1423 (C++ member), 915 taskENABLE_INTERRUPTS (C macro), 1423 tinyusb_config_cdcacm_t::rx_unread_buf_sz taskENTER_CRITICAL (C macro), 1423 (C++ member), 915 taskENTER_CRITICAL_FROM_ISR (C macro), tinyusb_config_cdcacm_t::usb_dev (C++ 1423 member), 915 taskENTER_CRITICAL_ISR (C macro), 1423 tinyusb_config_t (C++ class), 912 taskEXIT_CRITICAL (C macro), 1423 tinyusb_config_t::configuration_descriptor taskEXIT_CRITICAL_FROM_ISR (C macro), 1423 (C++ member), 913 taskEXIT_CRITICAL_ISR (C macro), 1423 tinyusb_config_t::descriptor (C++ mem- TaskHandle_t (C++ type), 1425 ber), 913 TaskHookFunction_t (C++ type), 1425 tinyusb_config_t::device_descriptor taskSCHEDULER_NOT_STARTED (C macro), 1423 (C++ member), 913 taskSCHEDULER_RUNNING (C macro), 1423 tinyusb_config_t::external_phy (C++ taskSCHEDULER_SUSPENDED (C macro), 1423 member), 913 taskYIELD (C macro), 1422 tinyusb_config_t::string_descriptor temperature_sensor_config_t (C++ class), (C++ member), 913 851 tinyusb_driver_install (C++ function), 912 temperature_sensor_get_celsius (C++ TINYUSB_USBDEV_0 (C++ enumerator), 913 function), 850 tinyusb_usbdev_t (C++ enum), 913 temperature_sensor_handle_t (C++ type), tls_keep_alive_cfg (C++ class), 90 851 tls_keep_alive_cfg::keep_alive_count temperature_sensor_install (C++ function), (C++ member), 90 850 tls_keep_alive_cfg::keep_alive_enable temperature_sensor_start (C++ function), (C++ member), 90 850 tls_keep_alive_cfg::keep_alive_idle temperature_sensor_stop (C++ function), 850 (C++ member), 90 temperature_sensor_uninstall (C++ func- tls_keep_alive_cfg::keep_alive_interval tion), 850 (C++ member), 90 TEMPERAUTRE_SENSOR_CONFIG_DEFAULT (C tls_keep_alive_cfg_t (C++ type), 93 macro), 851 TlsDeleteCallbackFunction_t (C++ type), TimerCallbackFunction_t (C++ type), 1473 1425 TimerHandle_t (C++ type), 1473 tmrCOMMAND_CHANGE_PERIOD (C macro), 1464 TINYUSB_CDC_ACM_0 (C++ enumerator), 916 tmrCOMMAND_CHANGE_PERIOD_FROM_ISR (C TINYUSB_CDC_ACM_1 (C++ enumerator), 916 macro), 1464 TINYUSB_CDC_ACM_MAX (C++ enumerator), 916 tmrCOMMAND_DELETE (C macro), 1464 tinyusb_cdcacm_itf_t (C++ enum), 916 tmrCOMMAND_EXECUTE_CALLBACK (C macro), tinyusb_cdcacm_read (C++ function), 914 1464 tinyusb_cdcacm_register_callback (C++ tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR function), 913 (C macro), 1464 tinyusb_cdcacm_unregister_callback tmrCOMMAND_RESET (C macro), 1464 (C++ function), 913 tmrCOMMAND_RESET_FROM_ISR (C macro), 1464 tinyusb_cdcacm_write_flush (C++ function), tmrCOMMAND_START (C macro), 1464 914 tmrCOMMAND_START_DONT_TRACE (C macro), tinyusb_cdcacm_write_queue (C++ function), 1464 914 tmrCOMMAND_START_FROM_ISR (C macro), 1464 tinyusb_cdcacm_write_queue_char (C++ tmrCOMMAND_STOP (C macro), 1464 function), 914 tmrCOMMAND_STOP_FROM_ISR (C macro), 1464 tinyusb_config_cdcacm_t (C++ class), 915 tmrFIRST_FROM_ISR_COMMAND (C macro), 1464 tinyusb_config_cdcacm_t::callback_line_tcooudcihn_gc_ncth_asnlgoepde_t (C++ enum), 869 (C++ member), 916 TOUCH_DEBOUNCE_CNT_MAX (C macro), 867 tinyusb_config_cdcacm_t::callback_line_tsotuacthe__fcihlatnegre_dconfig (C++ class), 866 (C++ member), 915 touch_filter_config::debounce_cnt tinyusb_config_cdcacm_t::callback_rx (C++ member), 866 (C++ member), 915 touch_filter_config::jitter_step (C++ tinyusb_config_cdcacm_t::callback_rx_wanted_chmaermber), 866 (C++ member), 915 touch_filter_config::mode (C++ member), 866 Espressif Systems 2218 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index touch_filter_config::noise_thr (C++ member), 866 touch_filter_config::smh_lvl (C++ member), 866 touch_filter_config_t (C++ type), 867 touch_filter_mode_t (C++ enum), 871 TOUCH_FSM_MODE_MAX (C++ enumerator), 870 TOUCH_FSM_MODE_SW (C++ enumerator), 869 touch_fsm_mode_t (C++ enum), 869 TOUCH_FSM_MODE_TIMER (C++ enumerator), 869 touch_high_volt_t (C++ enum), 868 TOUCH_HVOLT_2V4 (C++ enumerator), 868 TOUCH_HVOLT_2V5 (C++ enumerator), 868 TOUCH_HVOLT_2V6 (C++ enumerator), 868 TOUCH_HVOLT_2V7 (C++ enumerator), 868 TOUCH_HVOLT_ATTEN_0V (C++ enumerator), 869 TOUCH_HVOLT_ATTEN_0V5 (C++ enumerator), 869 TOUCH_HVOLT_ATTEN_1V (C++ enumerator), 869 TOUCH_HVOLT_ATTEN_1V5 (C++ enumerator), 869 TOUCH_HVOLT_ATTEN_KEEP (C++ enumerator), 868 TOUCH_HVOLT_ATTEN_MAX (C++ enumerator), 869 TOUCH_HVOLT_KEEP (C++ enumerator), 868 TOUCH_HVOLT_MAX (C++ enumerator), 868 TOUCH_JITTER_STEP_MAX (C macro), 867 touch_low_volt_t (C++ enum), 868 TOUCH_LVOLT_0V5 (C++ enumerator), 868 TOUCH_LVOLT_0V6 (C++ enumerator), 868 TOUCH_LVOLT_0V7 (C++ enumerator), 868 TOUCH_LVOLT_0V8 (C++ enumerator), 868 TOUCH_LVOLT_KEEP (C++ enumerator), 868 TOUCH_LVOLT_MAX (C++ enumerator), 868 TOUCH_NOISE_THR_MAX (C macro), 867 TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD (C macro), 866 TOUCH_PAD_BIT_MASK_ALL (C macro), 866 TOUCH_PAD_BIT_MASK_MAX (C macro), 866 touch_pad_clear_channel_mask (C++ func- tion), 855 touch_pad_clear_status (C++ function), 864 touch_pad_config (C++ function), 855 TOUCH_PAD_CONN_GND (C++ enumerator), 871 TOUCH_PAD_CONN_HIGHZ (C++ enumerator), 871 TOUCH_PAD_CONN_MAX (C++ enumerator), 871 touch_pad_conn_type_t (C++ enum), 871 touch_pad_deinit (C++ function), 862 touch_pad_denoise (C++ class), 865 touch_pad_denoise::cap_level (C++ mem- ber), 865 touch_pad_denoise::grade (C++ member), 865 TOUCH_PAD_DENOISE_BIT10 (C++ enumerator), 870 TOUCH_PAD_DENOISE_BIT12 (C++ enumerator), 870 TOUCH_PAD_DENOISE_BIT4 (C++ enumerator), 870 TOUCH_PAD_DENOISE_BIT8 (C++ enumerator), 870 TOUCH_PAD_DENOISE_CAP_L0 (C++ enumerator), 870 TOUCH_PAD_DENOISE_CAP_L1 (C++ enumerator), 870 TOUCH_PAD_DENOISE_CAP_L2 (C++ enumerator), 871 TOUCH_PAD_DENOISE_CAP_L3 (C++ enumerator), 871 TOUCH_PAD_DENOISE_CAP_L4 (C++ enumerator), 871 TOUCH_PAD_DENOISE_CAP_L5 (C++ enumerator), 871 TOUCH_PAD_DENOISE_CAP_L6 (C++ enumerator), 871 TOUCH_PAD_DENOISE_CAP_L7 (C++ enumerator), 871 TOUCH_PAD_DENOISE_CAP_MAX (C++ enumerator), 871 touch_pad_denoise_cap_t (C++ enum), 870 touch_pad_denoise_disable (C++ function), 858 touch_pad_denoise_enable (C++ function), 858 touch_pad_denoise_get_config (C++ func- tion), 858 touch_pad_denoise_grade_t (C++ enum), 870 TOUCH_PAD_DENOISE_MAX (C++ enumerator), 870 touch_pad_denoise_read_data (C++ func- tion), 858 touch_pad_denoise_set_config (C++ func- tion), 858 touch_pad_denoise_t (C++ type), 867 touch_pad_filter_disable (C++ function), 858 touch_pad_filter_enable (C++ function), 858 touch_pad_filter_get_config (C++ func- tion), 858 TOUCH_PAD_FILTER_IIR_128 (C++ enumerator), 872 TOUCH_PAD_FILTER_IIR_16 (C++ enumerator), 872 TOUCH_PAD_FILTER_IIR_256 (C++ enumerator), 872 TOUCH_PAD_FILTER_IIR_32 (C++ enumerator), 872 TOUCH_PAD_FILTER_IIR_4 (C++ enumerator), 872 TOUCH_PAD_FILTER_IIR_64 (C++ enumerator), 872 TOUCH_PAD_FILTER_IIR_8 (C++ enumerator), 872 TOUCH_PAD_FILTER_JITTER (C++ enumerator), 872 TOUCH_PAD_FILTER_MAX (C++ enumerator), 872 touch_pad_filter_read_smooth (C++ func- tion), 857 Espressif Systems 2219 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index touch_pad_filter_set_config (C++ function), 857 touch_pad_fsm_start (C++ function), 854 touch_pad_fsm_stop (C++ function), 854 touch_pad_get_channel_mask (C++ function), 855 touch_pad_get_cnt_mode (C++ function), 863 touch_pad_get_current_meas_channel (C++ function), 856 touch_pad_get_fsm_mode (C++ function), 864 touch_pad_get_idle_channel_connect (C++ function), 854 touch_pad_get_meas_time (C++ function), 854 touch_pad_get_status (C++ function), 864 touch_pad_get_thresh (C++ function), 855 touch_pad_get_voltage (C++ function), 863 touch_pad_get_wakeup_status (C++ func- tion), 863 TOUCH_PAD_GPIO10_CHANNEL (C macro), 865 TOUCH_PAD_GPIO11_CHANNEL (C macro), 865 TOUCH_PAD_GPIO12_CHANNEL (C macro), 865 TOUCH_PAD_GPIO13_CHANNEL (C macro), 865 TOUCH_PAD_GPIO14_CHANNEL (C macro), 865 TOUCH_PAD_GPIO1_CHANNEL (C macro), 864 TOUCH_PAD_GPIO2_CHANNEL (C macro), 864 TOUCH_PAD_GPIO3_CHANNEL (C macro), 864 TOUCH_PAD_GPIO4_CHANNEL (C macro), 864 TOUCH_PAD_GPIO5_CHANNEL (C macro), 865 TOUCH_PAD_GPIO6_CHANNEL (C macro), 865 TOUCH_PAD_GPIO7_CHANNEL (C macro), 865 TOUCH_PAD_GPIO8_CHANNEL (C macro), 865 TOUCH_PAD_GPIO9_CHANNEL (C macro), 865 TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD (C macro), 866 TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT (C macro), 866 touch_pad_init (C++ function), 862 touch_pad_intr_clear (C++ function), 856 touch_pad_intr_disable (C++ function), 856 touch_pad_intr_enable (C++ function), 856 TOUCH_PAD_INTR_MASK_ACTIVE (C++ enumera- tor), 870 TOUCH_PAD_INTR_MASK_ALL (C macro), 867 TOUCH_PAD_INTR_MASK_DONE (C++ enumerator), 870 TOUCH_PAD_INTR_MASK_INACTIVE (C++ enu- merator), 870 TOUCH_PAD_INTR_MASK_PROXI_MEAS_DONE (C++ enumerator), 870 TOUCH_PAD_INTR_MASK_SCAN_DONE (C++ enu- merator), 870 touch_pad_intr_mask_t (C++ enum), 870 TOUCH_PAD_INTR_MASK_TIMEOUT (C++ enumer- ator), 870 touch_pad_io_init (C++ function), 862 touch_pad_isr_deregister (C++ function), 863 touch_pad_isr_register (C++ function), 856 TOUCH_PAD_LOW_VOLTAGE_THRESHOLD (C macro), 866 TOUCH_PAD_MAX (C++ enumerator), 868 touch_pad_meas_is_done (C++ function), 864 TOUCH_PAD_MEASURE_CYCLE_DEFAULT (C macro), 867 TOUCH_PAD_NUM0 (C++ enumerator), 867 TOUCH_PAD_NUM1 (C++ enumerator), 867 TOUCH_PAD_NUM10 (C++ enumerator), 868 TOUCH_PAD_NUM10_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM11 (C++ enumerator), 868 TOUCH_PAD_NUM11_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM12 (C++ enumerator), 868 TOUCH_PAD_NUM12_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM13 (C++ enumerator), 868 TOUCH_PAD_NUM13_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM14 (C++ enumerator), 868 TOUCH_PAD_NUM14_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM1_GPIO_NUM (C macro), 864 TOUCH_PAD_NUM2 (C++ enumerator), 867 TOUCH_PAD_NUM2_GPIO_NUM (C macro), 864 TOUCH_PAD_NUM3 (C++ enumerator), 867 TOUCH_PAD_NUM3_GPIO_NUM (C macro), 864 TOUCH_PAD_NUM4 (C++ enumerator), 867 TOUCH_PAD_NUM4_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM5 (C++ enumerator), 867 TOUCH_PAD_NUM5_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM6 (C++ enumerator), 867 TOUCH_PAD_NUM6_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM7 (C++ enumerator), 867 TOUCH_PAD_NUM7_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM8 (C++ enumerator), 867 TOUCH_PAD_NUM8_GPIO_NUM (C macro), 865 TOUCH_PAD_NUM9 (C++ enumerator), 868 TOUCH_PAD_NUM9_GPIO_NUM (C macro), 865 touch_pad_proximity_enable (C++ function), 859 touch_pad_proximity_get_count (C++ func- tion), 859 touch_pad_proximity_get_data (C++ func- tion), 860 touch_pad_proximity_set_count (C++ func- tion), 859 touch_pad_read_benchmark (C++ function), 857 touch_pad_read_intr_status_mask (C++ function), 856 touch_pad_read_raw_data (C++ function), 857 touch_pad_reset (C++ function), 856 touch_pad_reset_benchmark (C++ function), 857 touch_pad_set_channel_mask (C++ function), 855 touch_pad_set_cnt_mode (C++ function), 863 touch_pad_set_fsm_mode (C++ function), 864 touch_pad_set_idle_channel_connect (C++ function), 854 touch_pad_set_meas_time (C++ function), 854 Espressif Systems 2220 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index touch_pad_set_thresh (C++ function), 855 TOUCH_PAD_SLOPE_DEFAULT (C macro), 866 touch_pad_set_voltage (C++ function), 862 TOUCH_PAD_SLOPE_MAX (C++ enumerator), 869 touch_pad_shield_driver_t (C++ enum), 871 TOUCH_PAD_SMOOTH_IIR_2 (C++ enumerator), TOUCH_PAD_SHIELD_DRV_L0 (C++ enumerator), 872 871 TOUCH_PAD_SMOOTH_IIR_4 (C++ enumerator), TOUCH_PAD_SHIELD_DRV_L1 (C++ enumerator), 872 871 TOUCH_PAD_SMOOTH_IIR_8 (C++ enumerator), TOUCH_PAD_SHIELD_DRV_L2 (C++ enumerator), 872 871 TOUCH_PAD_SMOOTH_MAX (C++ enumerator), 872 TOUCH_PAD_SHIELD_DRV_L3 (C++ enumerator), TOUCH_PAD_SMOOTH_OFF (C++ enumerator), 872 871 touch_pad_sw_start (C++ function), 854 TOUCH_PAD_SHIELD_DRV_L4 (C++ enumerator), touch_pad_t (C++ enum), 867 871 TOUCH_PAD_THRESHOLD_MAX (C macro), 866 TOUCH_PAD_SHIELD_DRV_L5 (C++ enumerator), TOUCH_PAD_TIE_OPT_DEFAULT (C macro), 866 871 TOUCH_PAD_TIE_OPT_HIGH (C++ enumerator), TOUCH_PAD_SHIELD_DRV_L6 (C++ enumerator), 869 871 TOUCH_PAD_TIE_OPT_LOW (C++ enumerator), 869 TOUCH_PAD_SHIELD_DRV_L7 (C++ enumerator), TOUCH_PAD_TIE_OPT_MAX (C++ enumerator), 869 871 touch_pad_timeout_resume (C++ function), TOUCH_PAD_SHIELD_DRV_MAX (C++ enumerator), 857 871 touch_pad_timeout_set (C++ function), 856 touch_pad_sleep_channel_enable (C++ touch_pad_waterproof (C++ class), 865 function), 860 touch_pad_waterproof::guard_ring_pad touch_pad_sleep_channel_enable_proximity (C++ member), 866 (C++ function), 860 touch_pad_waterproof::shield_driver touch_pad_sleep_channel_get_info (C++ (C++ member), 866 function), 860 touch_pad_waterproof_disable (C++ func- touch_pad_sleep_channel_read_benchmark tion), 859 (C++ function), 861 touch_pad_waterproof_enable (C++ func- touch_pad_sleep_channel_read_data tion), 859 (C++ function), 861 touch_pad_waterproof_get_config (C++ touch_pad_sleep_channel_read_proximity_cnt function), 859 (C++ function), 861 touch_pad_waterproof_set_config (C++ touch_pad_sleep_channel_read_smooth function), 859 (C++ function), 861 touch_pad_waterproof_t (C++ type), 867 touch_pad_sleep_channel_reset_benchmarkTOUCH_PROXIMITY_MEAS_NUM_MAX (C macro), (C++ function), 861 867 touch_pad_sleep_channel_set_work_time touch_smooth_mode_t (C++ enum), 872 (C++ function), 862 touch_tie_opt_t (C++ enum), 869 touch_pad_sleep_channel_t (C++ class), 866 TOUCH_TRIGGER_ABOVE (C++ enumerator), 870 touch_pad_sleep_channel_t::en_proximityTOUCH_TRIGGER_BELOW (C++ enumerator), 870 (C++ member), 866 TOUCH_TRIGGER_MAX (C++ enumerator), 870 touch_pad_sleep_channel_t::touch_num touch_trigger_mode_t (C++ enum), 870 (C++ member), 866 TOUCH_TRIGGER_SOURCE_BOTH (C++ enumera- TOUCH_PAD_SLEEP_CYCLE_DEFAULT (C macro), tor), 870 867 TOUCH_TRIGGER_SOURCE_MAX (C++ enumerator), touch_pad_sleep_get_threshold (C++ func- 870 tion), 861 TOUCH_TRIGGER_SOURCE_SET1 (C++ enumera- touch_pad_sleep_set_threshold (C++ func- tor), 870 tion), 860 touch_trigger_src_t (C++ enum), 870 TOUCH_PAD_SLOPE_0 (C++ enumerator), 869 touch_volt_atten_t (C++ enum), 868 TOUCH_PAD_SLOPE_1 (C++ enumerator), 869 transaction_cb_t (C++ type), 842 TOUCH_PAD_SLOPE_2 (C++ enumerator), 869 tskDEFAULT_INDEX_TO_NOTIFY (C macro), 1422 TOUCH_PAD_SLOPE_3 (C++ enumerator), 869 tskIDLE_PRIORITY (C macro), 1422 TOUCH_PAD_SLOPE_4 (C++ enumerator), 869 tskKERNEL_VERSION_BUILD (C macro), 1422 TOUCH_PAD_SLOPE_5 (C++ enumerator), 869 tskKERNEL_VERSION_MAJOR (C macro), 1422 TOUCH_PAD_SLOPE_6 (C++ enumerator), 869 tskKERNEL_VERSION_MINOR (C macro), 1422 TOUCH_PAD_SLOPE_7 (C++ enumerator), 869 tskKERNEL_VERSION_NUMBER (C macro), 1422 Espressif Systems 2221 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index tskMPU_REGION_DEVICE_MEMORY (C macro), 1422 tskMPU_REGION_EXECUTE_NEVER (C macro), 1422 tskMPU_REGION_NORMAL_MEMORY (C macro), 1422 tskMPU_REGION_READ_ONLY (C macro), 1422 tskMPU_REGION_READ_WRITE (C macro), 1422 tskNO_AFFINITY (C macro), 1422 tusb_cdc_acm_init (C++ function), 913 tusb_cdc_acm_initialized (C++ function), 914 tusb_cdcacm_callback_t (C++ type), 916 tusb_run_task (C++ function), 917 tusb_stop_task (C++ function), 917 twai_clear_receive_queue (C++ function), 886 twai_clear_transmit_queue (C++ function), 886 twai_driver_install (C++ function), 884 twai_driver_uninstall (C++ function), 884 TWAI_ERR_PASS_THRESH (C macro), 883 TWAI_EXTD_ID_MASK (C macro), 883 twai_filter_config_t (C++ class), 883 twai_filter_config_t::acceptance_code (C++ member), 883 twai_filter_config_t::acceptance_mask (C++ member), 883 twai_filter_config_t::single_filter (C++ member), 883 TWAI_FRAME_EXTD_ID_LEN_BYTES (C macro), 883 TWAI_FRAME_MAX_DLC (C macro), 883 TWAI_FRAME_STD_ID_LEN_BYTES (C macro), 883 twai_general_config_t (C++ class), 886 twai_general_config_t::alerts_enabled (C++ member), 887 twai_general_config_t::bus_off_io (C++ member), 887 twai_general_config_t::clkout_divider (C++ member), 887 twai_general_config_t::clkout_io (C++ member), 886 twai_general_config_t::intr_flags (C++ member), 887 twai_general_config_t::mode (C++ mem- ber), 886 twai_general_config_t::rx_io (C++ mem- ber), 886 twai_general_config_t::rx_queue_len (C++ member), 887 twai_general_config_t::tx_io (C++ mem- ber), 886 twai_general_config_t::tx_queue_len (C++ member), 887 twai_get_status_info (C++ function), 886 twai_initiate_recovery (C++ function), 886 TWAI_IO_UNUSED (C macro), 887 twai_message_t (C++ class), 882 twai_message_t::data (C++ member), 882 twai_message_t::data_length_code (C++ member), 882 twai_message_t::dlc_non_comp (C++ mem- ber), 882 twai_message_t::extd (C++ member), 882 twai_message_t::flags (C++ member), 882 twai_message_t::identifier (C++ member), 882 twai_message_t::reserved (C++ member), 882 twai_message_t::rtr (C++ member), 882 twai_message_t::self (C++ member), 882 twai_message_t::ss (C++ member), 882 TWAI_MODE_LISTEN_ONLY (C++ enumerator), 883 TWAI_MODE_NO_ACK (C++ enumerator), 883 TWAI_MODE_NORMAL (C++ enumerator), 883 twai_mode_t (C++ enum), 883 twai_read_alerts (C++ function), 885 twai_receive (C++ function), 885 twai_reconfigure_alerts (C++ function), 885 twai_start (C++ function), 884 TWAI_STATE_BUS_OFF (C++ enumerator), 888 TWAI_STATE_RECOVERING (C++ enumerator), 888 TWAI_STATE_RUNNING (C++ enumerator), 888 TWAI_STATE_STOPPED (C++ enumerator), 888 twai_state_t (C++ enum), 887 twai_status_info_t (C++ class), 887 twai_status_info_t::arb_lost_count (C++ member), 887 twai_status_info_t::bus_error_count (C++ member), 887 twai_status_info_t::msgs_to_rx (C++ member), 887 twai_status_info_t::msgs_to_tx (C++ member), 887 twai_status_info_t::rx_error_counter (C++ member), 887 twai_status_info_t::rx_missed_count (C++ member), 887 twai_status_info_t::rx_overrun_count (C++ member), 887 twai_status_info_t::state (C++ member), 887 twai_status_info_t::tx_error_counter (C++ member), 887 twai_status_info_t::tx_failed_count (C++ member), 887 TWAI_STD_ID_MASK (C macro), 883 twai_stop (C++ function), 884 twai_timing_config_t (C++ class), 882 twai_timing_config_t::brp (C++ member), 882 twai_timing_config_t::sjw (C++ member), 882 twai_timing_config_t::triple_sampling Espressif Systems 2222 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 882 twai_timing_config_t::tseg_1 (C++ mem- ber), 882 twai_timing_config_t::tseg_2 (C++ mem- ber), 882 twai_transmit (C++ function), 884 U uart_at_cmd_t (C++ class), 905 uart_at_cmd_t::char_num (C++ member), 906 uart_at_cmd_t::cmd_char (C++ member), 906 uart_at_cmd_t::gap_tout (C++ member), 906 uart_at_cmd_t::post_idle (C++ member), 906 uart_at_cmd_t::pre_idle (C++ member), 906 UART_BITRATE_MAX (C macro), 905 UART_BREAK (C++ enumerator), 905 UART_BUFFER_FULL (C++ enumerator), 905 uart_clear_intr_status (C++ function), 896 uart_config_t (C++ class), 906 uart_config_t::baud_rate (C++ member), 906 uart_config_t::data_bits (C++ member), 906 uart_config_t::flow_ctrl (C++ member), 906 uart_config_t::parity (C++ member), 906 uart_config_t::rx_flow_ctrl_thresh (C++ member), 906 uart_config_t::source_clk (C++ member), 906 uart_config_t::stop_bits (C++ member), 906 uart_config_t::use_ref_tick (C++ mem- ber), 906 UART_CTS_GPIO16_DIRECT_CHANNEL (C macro), 909 UART_CTS_GPIO20_DIRECT_CHANNEL (C macro), 909 UART_DATA (C++ enumerator), 905 UART_DATA_5_BITS (C++ enumerator), 907 UART_DATA_6_BITS (C++ enumerator), 907 UART_DATA_7_BITS (C++ enumerator), 907 UART_DATA_8_BITS (C++ enumerator), 907 UART_DATA_BITS_MAX (C++ enumerator), 907 UART_DATA_BREAK (C++ enumerator), 905 uart_disable_intr_mask (C++ function), 897 uart_disable_pattern_det_intr (C++ func- tion), 900 uart_disable_rx_intr (C++ function), 897 uart_disable_tx_intr (C++ function), 897 uart_driver_delete (C++ function), 894 uart_driver_install (C++ function), 894 uart_enable_intr_mask (C++ function), 897 uart_enable_pattern_det_baud_intr (C++ function), 901 uart_enable_rx_intr (C++ function), 897 uart_enable_tx_intr (C++ function), 897 UART_EVENT_MAX (C++ enumerator), 905 uart_event_t (C++ class), 904 uart_event_t::size (C++ member), 904 uart_event_t::timeout_flag (C++ member), 904 uart_event_t::type (C++ member), 904 uart_event_type_t (C++ enum), 905 UART_FIFO_LEN (C macro), 905 UART_FIFO_OVF (C++ enumerator), 905 uart_flush (C++ function), 900 uart_flush_input (C++ function), 900 UART_FRAME_ERR (C++ enumerator), 905 uart_get_baudrate (C++ function), 896 uart_get_buffered_data_len (C++ function), 900 uart_get_collision_flag (C++ function), 902 uart_get_hw_flow_ctrl (C++ function), 896 uart_get_parity (C++ function), 895 uart_get_stop_bits (C++ function), 895 uart_get_wakeup_threshold (C++ function), 903 uart_get_word_length (C++ function), 895 UART_GPIO15_DIRECT_CHANNEL (C macro), 909 UART_GPIO16_DIRECT_CHANNEL (C macro), 909 UART_GPIO17_DIRECT_CHANNEL (C macro), 909 UART_GPIO18_DIRECT_CHANNEL (C macro), 909 UART_GPIO19_DIRECT_CHANNEL (C macro), 909 UART_GPIO20_DIRECT_CHANNEL (C macro), 909 UART_GPIO43_DIRECT_CHANNEL (C macro), 909 UART_GPIO44_DIRECT_CHANNEL (C macro), 909 uart_hw_flowcontrol_t (C++ enum), 908 UART_HW_FLOWCTRL_CTS (C++ enumerator), 908 UART_HW_FLOWCTRL_CTS_RTS (C++ enumerator), 908 UART_HW_FLOWCTRL_DISABLE (C++ enumerator), 908 UART_HW_FLOWCTRL_MAX (C++ enumerator), 908 UART_HW_FLOWCTRL_RTS (C++ enumerator), 908 uart_intr_config (C++ function), 899 uart_intr_config_t (C++ class), 904 uart_intr_config_t::intr_enable_mask (C++ member), 904 uart_intr_config_t::rx_timeout_thresh (C++ member), 904 uart_intr_config_t::rxfifo_full_thresh (C++ member), 904 uart_intr_config_t::txfifo_empty_intr_thresh (C++ member), 904 uart_is_driver_installed (C++ function), 894 uart_isr_handle_t (C++ type), 905 UART_MODE_IRDA (C++ enumerator), 907 UART_MODE_RS485_APP_CTRL (C++ enumerator), 907 UART_MODE_RS485_COLLISION_DETECT (C++ enumerator), 907 UART_MODE_RS485_HALF_DUPLEX (C++ enumer- ator), 907 Espressif Systems 2223 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index uart_mode_t (C++ enum), 907 UART_MODE_UART (C++ enumerator), 907 UART_NUM_0 (C macro), 904 UART_NUM_0_CTS_DIRECT_GPIO_NUM (C macro), 909 UART_NUM_0_RTS_DIRECT_GPIO_NUM (C macro), 909 UART_NUM_0_RXD_DIRECT_GPIO_NUM (C macro), 909 UART_NUM_0_TXD_DIRECT_GPIO_NUM (C macro), 909 UART_NUM_1 (C macro), 904 UART_NUM_1_CTS_DIRECT_GPIO_NUM (C macro), 909 UART_NUM_1_RTS_DIRECT_GPIO_NUM (C macro), 909 UART_NUM_1_RXD_DIRECT_GPIO_NUM (C macro), 909 UART_NUM_1_TXD_DIRECT_GPIO_NUM (C macro), 909 UART_NUM_2 (C macro), 904 UART_NUM_MAX (C macro), 904 uart_param_config (C++ function), 898 UART_PARITY_DISABLE (C++ enumerator), 907 UART_PARITY_ERR (C++ enumerator), 905 UART_PARITY_EVEN (C++ enumerator), 907 UART_PARITY_ODD (C++ enumerator), 908 uart_parity_t (C++ enum), 907 UART_PATTERN_DET (C++ enumerator), 905 uart_pattern_get_pos (C++ function), 901 uart_pattern_pop_pos (C++ function), 901 uart_pattern_queue_reset (C++ function), 901 UART_PIN_NO_CHANGE (C macro), 905 uart_port_t (C++ type), 907 uart_read_bytes (C++ function), 900 UART_RTS_GPIO15_DIRECT_CHANNEL (C macro), 909 UART_RTS_GPIO19_DIRECT_CHANNEL (C macro), 910 UART_RXD_GPIO18_DIRECT_CHANNEL (C macro), 909 UART_RXD_GPIO44_DIRECT_CHANNEL (C macro), 909 UART_SCLK_APB (C++ enumerator), 908 UART_SCLK_RTC (C++ enumerator), 908 uart_sclk_t (C++ enum), 908 UART_SCLK_XTAL (C++ enumerator), 908 uart_set_always_rx_timeout (C++ function), 904 uart_set_baudrate (C++ function), 895 uart_set_dtr (C++ function), 898 uart_set_hw_flow_ctrl (C++ function), 896 uart_set_line_inverse (C++ function), 896 uart_set_loop_back (C++ function), 903 uart_set_mode (C++ function), 902 uart_set_parity (C++ function), 895 uart_set_pin (C++ function), 898 uart_set_rts (C++ function), 898 uart_set_rx_full_threshold (C++ function), 902 uart_set_rx_timeout (C++ function), 902 uart_set_stop_bits (C++ function), 895 uart_set_sw_flow_ctrl (C++ function), 896 uart_set_tx_empty_threshold (C++ func- tion), 902 uart_set_tx_idle_num (C++ function), 898 uart_set_wakeup_threshold (C++ function), 903 uart_set_word_length (C++ function), 895 UART_SIGNAL_CTS_INV (C++ enumerator), 908 UART_SIGNAL_DSR_INV (C++ enumerator), 908 UART_SIGNAL_DTR_INV (C++ enumerator), 908 UART_SIGNAL_INV_DISABLE (C++ enumerator), 908 uart_signal_inv_t (C++ enum), 908 UART_SIGNAL_IRDA_RX_INV (C++ enumerator), 908 UART_SIGNAL_IRDA_TX_INV (C++ enumerator), 908 UART_SIGNAL_RTS_INV (C++ enumerator), 908 UART_SIGNAL_RXD_INV (C++ enumerator), 908 UART_SIGNAL_TXD_INV (C++ enumerator), 908 UART_STOP_BITS_1 (C++ enumerator), 907 UART_STOP_BITS_1_5 (C++ enumerator), 907 UART_STOP_BITS_2 (C++ enumerator), 907 UART_STOP_BITS_MAX (C++ enumerator), 907 uart_stop_bits_t (C++ enum), 907 uart_sw_flowctrl_t (C++ class), 906 uart_sw_flowctrl_t::xoff_char (C++ member), 906 uart_sw_flowctrl_t::xoff_thrd (C++ member), 906 uart_sw_flowctrl_t::xon_char (C++ mem- ber), 906 uart_sw_flowctrl_t::xon_thrd (C++ mem- ber), 906 uart_tx_chars (C++ function), 899 UART_TXD_GPIO17_DIRECT_CHANNEL (C macro), 909 UART_TXD_GPIO43_DIRECT_CHANNEL (C macro), 909 uart_wait_tx_done (C++ function), 899 uart_wait_tx_idle_polling (C++ function), 903 UART_WAKEUP (C++ enumerator), 905 uart_word_length_t (C++ enum), 907 uart_write_bytes (C++ function), 899 uart_write_bytes_with_break (C++ func- tion), 899 UINT16 (C++ type), 329 UINT32 (C++ type), 329 UINT64 (C++ type), 329 UINT8 (C++ type), 329 ulp_insn (C++ union), 1635 ulp_insn::adc (C++ member), 1638 Espressif Systems 2224 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index ulp_insn::addr (C++ member), 1637 ulp_insn::alu_cnt (C++ member), 1637 ulp_insn::alu_imm (C++ member), 1637 ulp_insn::alu_reg (C++ member), 1637 ulp_insn::b (C++ member), 1637 ulp_insn::bx (C++ member), 1637 ulp_insn::cmp (C++ member), 1637 ulp_insn::cycles (C++ member), 1635 ulp_insn::data (C++ member), 1637 ulp_insn::delay (C++ member), 1636 ulp_insn::dreg (C++ member), 1636 ulp_insn::end (C++ member), 1638 ulp_insn::halt (C++ member), 1636 ulp_insn::high (C++ member), 1637 ulp_insn::high_bits (C++ member), 1638 ulp_insn::i2c (C++ member), 1638 ulp_insn::i2c_addr (C++ member), 1638 ulp_insn::i2c_sel (C++ member), 1638 ulp_insn::imm (C++ member), 1637 ulp_insn::label (C++ member), 1636 ulp_insn::ld (C++ member), 1636 ulp_insn::low (C++ member), 1637 ulp_insn::low_bits (C++ member), 1638 ulp_insn::macro (C++ member), 1638 ulp_insn::mux (C++ member), 1637 ulp_insn::offset (C++ member), 1636 ulp_insn::opcode (C++ member), 1635 ulp_insn::periph_sel (C++ member), 1637 ulp_insn::rd_reg (C++ member), 1637 ulp_insn::rd_upper (C++ member), 1636 ulp_insn::reg (C++ member), 1637 ulp_insn::reserved (C++ member), 1638 ulp_insn::rw (C++ member), 1638 ulp_insn::sar_sel (C++ member), 1638 ulp_insn::sel (C++ member), 1637 ulp_insn::sign (C++ member), 1637 ulp_insn::sreg (C++ member), 1636 ulp_insn::st (C++ member), 1636 ulp_insn::sub_opcode (C++ member), 1636 ulp_insn::treg (C++ member), 1637 ulp_insn::tsens (C++ member), 1638 ulp_insn::type (C++ member), 1637 ulp_insn::unused (C++ member), 1635 ulp_insn::unused1 (C++ member), 1636 ulp_insn::unused2 (C++ member), 1636 ulp_insn::unused3 (C++ member), 1637 ulp_insn::upper (C++ member), 1636 ulp_insn::wait_delay (C++ member), 1638 ulp_insn::wakeup (C++ member), 1638 ulp_insn::wr_reg (C++ member), 1637 ulp_insn::wr_way (C++ member), 1636 ulp_insn_t (C++ type), 1651 ulp_load_binary (C++ function), 1650 ulp_process_macros_and_load (C++ func- tion), 1650 ulp_riscv_cfg_t (C++ class), 1655 ulp_riscv_config_and_run (C++ function), 1655 ULP_RISCV_DEFAULT_CONFIG (C macro), 1655 ulp_riscv_halt (C++ function), 1655 ulp_riscv_load_binary (C++ function), 1655 ulp_riscv_run (C++ function), 1655 ulp_riscv_timer_resume (C++ function), 1655 ulp_riscv_timer_stop (C++ function), 1655 ULP_RISCV_WAKEUP_SOURCE_GPIO (C++ enu- merator), 1655 ulp_riscv_wakeup_source_t (C++ enum), 1655 ULP_RISCV_WAKEUP_SOURCE_TIMER (C++ enu- merator), 1655 ulp_run (C++ function), 1650 ulp_set_wakeup_period (C++ function), 1651 ulp_timer_resume (C++ function), 1652 ulp_timer_stop (C++ function), 1651 ulTaskGenericNotifyTake (C++ function), 1419 ulTaskGenericNotifyValueClear (C++ func- tion), 1420 ulTaskGetIdleRunTimeCounter (C++ func- tion), 1414 ulTaskNotifyTake (C macro), 1425 ulTaskNotifyTakeIndexed (C macro), 1425 ulTaskNotifyValueClear (C macro), 1425 ulTaskNotifyValueClearIndexed (C macro), 1425 USB_B_DESCRIPTOR_TYPE_BOS (C macro), 941 USB_B_DESCRIPTOR_TYPE_CONFIGURATION (C macro), 941 USB_B_DESCRIPTOR_TYPE_CS_RADIO_CONTROL (C macro), 941 USB_B_DESCRIPTOR_TYPE_DEBUG (C macro), 941 USB_B_DESCRIPTOR_TYPE_DEVICE (C macro), 941 USB_B_DESCRIPTOR_TYPE_DEVICE_CAPABILITY (C macro), 941 USB_B_DESCRIPTOR_TYPE_DEVICE_QUALIFIER (C macro), 941 USB_B_DESCRIPTOR_TYPE_ENCRYPTION_TYPE (C macro), 941 USB_B_DESCRIPTOR_TYPE_ENDPOINT (C macro), 941 USB_B_DESCRIPTOR_TYPE_INTERFACE (C macro), 941 USB_B_DESCRIPTOR_TYPE_INTERFACE_ASSOCIATION (C macro), 941 USB_B_DESCRIPTOR_TYPE_INTERFACE_POWER (C macro), 941 USB_B_DESCRIPTOR_TYPE_KEY (C macro), 941 USB_B_DESCRIPTOR_TYPE_OTG (C macro), 941 USB_B_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIGURATION (C macro), 941 USB_B_DESCRIPTOR_TYPE_PIPE_USAGE (C macro), 942 USB_B_DESCRIPTOR_TYPE_RPIPE (C macro), 941 Espressif Systems 2225 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index USB_B_DESCRIPTOR_TYPE_SECURITY (C USB_BM_ATTRIBUTES_XFER_ISOC (C macro), macro), 941 944 USB_B_DESCRIPTOR_TYPE_STRING (C macro), USB_BM_ATTRIBUTES_XFERTYPE_MASK (C 941 macro), 944 USB_B_DESCRIPTOR_TYPE_WIRE_ADAPTER (C USB_BM_REQUEST_TYPE_DIR_IN (C macro), 942 macro), 941 USB_BM_REQUEST_TYPE_DIR_OUT (C macro), USB_B_DESCRIPTOR_TYPE_WIRELESS_ENDPOINT_COMP 942 (C macro), 941 USB_BM_REQUEST_TYPE_RECIP_DEVICE (C USB_B_ENDPOINT_ADDRESS_EP_DIR_MASK (C macro), 942 macro), 944 USB_BM_REQUEST_TYPE_RECIP_ENDPOINT (C USB_B_ENDPOINT_ADDRESS_EP_NUM_MASK (C macro), 942 macro), 944 USB_BM_REQUEST_TYPE_RECIP_INTERFACE (C USB_B_REQUEST_CLEAR_FEATURE (C macro), macro), 942 942 USB_BM_REQUEST_TYPE_RECIP_MASK (C USB_B_REQUEST_GET_CONFIGURATION (C macro), 942 macro), 942 USB_BM_REQUEST_TYPE_RECIP_OTHER (C USB_B_REQUEST_GET_DESCRIPTOR (C macro), macro), 942 942 USB_BM_REQUEST_TYPE_TYPE_CLASS (C USB_B_REQUEST_GET_INTERFACE (C macro), macro), 942 942 USB_BM_REQUEST_TYPE_TYPE_MASK (C macro), USB_B_REQUEST_GET_STATUS (C macro), 942 942 USB_B_REQUEST_SET_ADDRESS (C macro), 942 USB_BM_REQUEST_TYPE_TYPE_RESERVED (C USB_B_REQUEST_SET_CONFIGURATION (C macro), 942 macro), 942 USB_BM_REQUEST_TYPE_TYPE_STANDARD (C USB_B_REQUEST_SET_DESCRIPTOR (C macro), macro), 942 942 USB_BM_REQUEST_TYPE_TYPE_VENDOR (C USB_B_REQUEST_SET_FEATURE (C macro), 942 macro), 942 USB_B_REQUEST_SET_INTERFACE (C macro), USB_CLASS_APP_SPEC (C macro), 943 942 USB_CLASS_AUDIO (C macro), 943 USB_B_REQUEST_SYNCH_FRAME (C macro), 942 USB_CLASS_AUDIO_VIDEO (C macro), 943 USB_BM_ATTRIBUTES_BATTERY (C macro), 944 USB_CLASS_BILLBOARD (C macro), 943 USB_BM_ATTRIBUTES_ONE (C macro), 944 USB_CLASS_CDC_DATA (C macro), 943 USB_BM_ATTRIBUTES_SELFPOWER (C macro), USB_CLASS_COMM (C macro), 943 944 USB_CLASS_CONTENT_SEC (C macro), 943 USB_BM_ATTRIBUTES_SYNC_ADAPTIVE (C USB_CLASS_CSCID (C macro), 943 macro), 944 USB_CLASS_HID (C macro), 943 USB_BM_ATTRIBUTES_SYNC_ASYNC (C macro), USB_CLASS_HUB (C macro), 943 944 USB_CLASS_MASS_STORAGE (C macro), 943 USB_BM_ATTRIBUTES_SYNC_NONE (C macro), USB_CLASS_MISC (C macro), 943 944 USB_CLASS_PER_INTERFACE (C macro), 943 USB_BM_ATTRIBUTES_SYNC_SYNC (C macro), USB_CLASS_PERSONAL_HEALTHCARE (C macro), 944 943 USB_BM_ATTRIBUTES_SYNCTYPE_MASK (C USB_CLASS_PHYSICAL (C macro), 943 macro), 944 USB_CLASS_PRINTER (C macro), 943 USB_BM_ATTRIBUTES_USAGE_DATA (C macro), USB_CLASS_STILL_IMAGE (C macro), 943 944 USB_CLASS_USB_TYPE_C_BRIDGE (C macro), USB_BM_ATTRIBUTES_USAGE_FEEDBACK (C 943 macro), 944 USB_CLASS_VENDOR_SPEC (C macro), 943 USB_BM_ATTRIBUTES_USAGE_IMPLICIT_FB (C USB_CLASS_VIDEO (C macro), 943 macro), 944 USB_CLASS_WIRELESS_CONTROLLER (C macro), USB_BM_ATTRIBUTES_USAGETYPE_MASK (C 943 macro), 944 USB_CONFIG_DESC_SIZE (C macro), 944 USB_BM_ATTRIBUTES_WAKEUP (C macro), 944 usb_config_desc_t (C++ union), 939 USB_BM_ATTRIBUTES_XFER_BULK (C macro), usb_config_desc_t::bConfigurationValue 944 (C++ member), 939 USB_BM_ATTRIBUTES_XFER_CONTROL (C usb_config_desc_t::bDescriptorType macro), 944 (C++ member), 939 USB_BM_ATTRIBUTES_XFER_INT (C macro), 944 usb_config_desc_t::bLength (C++ member), Espressif Systems 2226 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index 939 usb_device_info_t::str_desc_manufacturer usb_config_desc_t::bmAttributes (C++ (C++ member), 934 member), 939 usb_device_info_t::str_desc_product usb_config_desc_t::bMaxPower (C++ mem- (C++ member), 934 ber), 939 usb_device_info_t::str_desc_serial_num usb_config_desc_t::bNumInterfaces (C++ member), 934 (C++ member), 939 USB_DEVICE_STATE_ADDRESS (C++ enumerator), usb_config_desc_t::iConfiguration 945 (C++ member), 939 USB_DEVICE_STATE_ATTACHED (C++ enumera- usb_config_desc_t::USB_DESC_ATTR (C++ tor), 945 member), 939 USB_DEVICE_STATE_CONFIGURED (C++ enumer- usb_config_desc_t::val (C++ member), 939 ator), 945 usb_config_desc_t::wTotalLength (C++ USB_DEVICE_STATE_DEFAULT (C++ enumerator), member), 939 945 USB_DESC_ATTR (C macro), 941 USB_DEVICE_STATE_NOT_ATTACHED (C++ enu- USB_DEVICE_DESC_SIZE (C macro), 943 merator), 945 usb_device_desc_t (C++ union), 938 USB_DEVICE_STATE_POWERED (C++ enumerator), usb_device_desc_t::bcdDevice (C++ mem- 945 ber), 938 USB_DEVICE_STATE_SUSPENDED (C++ enumera- usb_device_desc_t::bcdUSB (C++ member), tor), 945 938 usb_device_state_t (C++ enum), 945 usb_device_desc_t::bDescriptorType USB_EP_DESC_GET_EP_DIR (C macro), 944 (C++ member), 938 USB_EP_DESC_GET_EP_NUM (C macro), 944 usb_device_desc_t::bDeviceClass (C++ USB_EP_DESC_GET_MPS (C macro), 944 member), 938 USB_EP_DESC_GET_XFERTYPE (C macro), 944 usb_device_desc_t::bDeviceProtocol USB_EP_DESC_SIZE (C macro), 944 (C++ member), 938 usb_ep_desc_t (C++ union), 940 usb_device_desc_t::bDeviceSubClass usb_ep_desc_t::bDescriptorType (C++ (C++ member), 938 member), 940 usb_device_desc_t::bLength (C++ member), usb_ep_desc_t::bEndpointAddress (C++ 938 member), 940 usb_device_desc_t::bMaxPacketSize0 usb_ep_desc_t::bInterval (C++ member), (C++ member), 938 940 usb_device_desc_t::bNumConfigurations usb_ep_desc_t::bLength (C++ member), 940 (C++ member), 938 usb_ep_desc_t::bmAttributes (C++ mem- usb_device_desc_t::idProduct (C++ mem- ber), 940 ber), 938 usb_ep_desc_t::USB_DESC_ATTR (C++ mem- usb_device_desc_t::idVendor (C++ mem- ber), 941 ber), 938 usb_ep_desc_t::val (C++ member), 941 usb_device_desc_t::iManufacturer (C++ usb_ep_desc_t::wMaxPacketSize (C++ member), 938 member), 940 usb_device_desc_t::iProduct (C++ mem- USB_ESPRESSIF_VID (C macro), 913 ber), 938 usb_host_client_config_t (C++ class), 930 usb_device_desc_t::iSerialNumber (C++ usb_host_client_config_t::callback_arg member), 938 (C++ member), 931 usb_device_desc_t::USB_DESC_ATTR (C++ usb_host_client_config_t::client_event_callback member), 938 (C++ member), 931 usb_device_desc_t::val (C++ member), 939 usb_host_client_config_t::is_synchronous usb_device_handle_t (C++ type), 936 (C++ member), 931 usb_device_info_t (C++ class), 934 usb_host_client_config_t::max_num_event_msg usb_device_info_t::bConfigurationValue (C++ member), 931 (C++ member), 934 usb_host_client_deregister (C++ function), usb_device_info_t::bMaxPacketSize0 926 (C++ member), 934 usb_host_client_event_cb_t (C++ type), 931 usb_device_info_t::dev_addr (C++ mem- USB_HOST_CLIENT_EVENT_DEV_GONE (C++ ber), 934 enumerator), 931 usb_device_info_t::speed (C++ member), usb_host_client_event_msg_t (C++ class), 934 930 Espressif Systems 2227 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index usb_host_client_event_msg_t::address (C++ member), 930 usb_host_client_event_msg_t::dev_hdl (C++ member), 930 usb_host_client_event_msg_t::event (C++ member), 930 USB_HOST_CLIENT_EVENT_NEW_DEV (C++ enumerator), 931 usb_host_client_event_t (C++ enum), 931 usb_host_client_handle_events (C++ func- tion), 926 usb_host_client_handle_t (C++ type), 931 usb_host_client_register (C++ function), 926 usb_host_client_unblock (C++ function), 926 usb_host_config_t (C++ class), 930 usb_host_config_t::intr_flags (C++ member), 930 usb_host_config_t::skip_phy_setup (C++ member), 930 usb_host_device_addr_list_fill (C++ function), 927 usb_host_device_close (C++ function), 926 usb_host_device_free_all (C++ function), 927 usb_host_device_info (C++ function), 927 usb_host_device_open (C++ function), 926 usb_host_endpoint_clear (C++ function), 929 usb_host_endpoint_flush (C++ function), 928 usb_host_endpoint_halt (C++ function), 928 usb_host_get_active_config_descriptor (C++ function), 927 usb_host_get_device_descriptor (C++ function), 927 usb_host_install (C++ function), 925 usb_host_interface_claim (C++ function), 928 usb_host_interface_release (C++ function), 928 USB_HOST_LIB_EVENT_FLAGS_ALL_FREE (C macro), 931 USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS (C macro), 931 usb_host_lib_handle_events (C++ function), 925 usb_host_lib_info (C++ function), 925 usb_host_lib_info_t (C++ class), 930 usb_host_lib_info_t::num_clients (C++ member), 930 usb_host_lib_info_t::num_devices (C++ member), 930 usb_host_lib_unblock (C++ function), 925 usb_host_transfer_alloc (C++ function), 929 usb_host_transfer_free (C++ function), 929 usb_host_transfer_submit (C++ function), 929 usb_host_transfer_submit_control (C++ function), 929 usb_host_uninstall (C++ function), 925 USB_IAD_DESC_SIZE (C macro), 944 usb_iad_desc_t (C++ union), 939 usb_iad_desc_t::bDescriptorType (C++ member), 939 usb_iad_desc_t::bFirstInterface (C++ member), 939 usb_iad_desc_t::bFunctionClass (C++ member), 939 usb_iad_desc_t::bFunctionProtocol (C++ member), 939 usb_iad_desc_t::bFunctionSubClass (C++ member), 939 usb_iad_desc_t::bInterfaceCount (C++ member), 939 usb_iad_desc_t::bLength (C++ member), 939 usb_iad_desc_t::iFunction (C++ member), 940 usb_iad_desc_t::USB_DESC_ATTR (C++ member), 940 usb_iad_desc_t::val (C++ member), 940 USB_INTF_DESC_SIZE (C macro), 944 usb_intf_desc_t (C++ union), 940 usb_intf_desc_t::bAlternateSetting (C++ member), 940 usb_intf_desc_t::bDescriptorType (C++ member), 940 usb_intf_desc_t::bInterfaceClass (C++ member), 940 usb_intf_desc_t::bInterfaceNumber (C++ member), 940 usb_intf_desc_t::bInterfaceProtocol (C++ member), 940 usb_intf_desc_t::bInterfaceSubClass (C++ member), 940 usb_intf_desc_t::bLength (C++ member), 940 usb_intf_desc_t::bNumEndpoints (C++ member), 940 usb_intf_desc_t::iInterface (C++ mem- ber), 940 usb_intf_desc_t::USB_DESC_ATTR (C++ member), 940 usb_intf_desc_t::val (C++ member), 940 usb_isoc_packet_desc_t (C++ class), 934 usb_isoc_packet_desc_t::actual_num_bytes (C++ member), 934 usb_isoc_packet_desc_t::num_bytes (C++ member), 934 usb_isoc_packet_desc_t::status (C++ member), 934 usb_parse_endpoint_descriptor_by_address (C++ function), 933 usb_parse_endpoint_descriptor_by_index (C++ function), 932 usb_parse_interface_descriptor (C++ function), 932 usb_parse_interface_number_of_alternate Espressif Systems 2228 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ function), 932 usb_parse_next_descriptor (C++ function), 931 usb_parse_next_descriptor_of_type (C++ function), 932 usb_print_config_descriptor (C++ func- tion), 933 usb_print_device_descriptor (C++ func- tion), 933 usb_print_string_descriptor (C++ func- tion), 933 usb_round_up_to_mps (C++ function), 933 USB_SETUP_PACKET_INIT_GET_CONFIG (C macro), 943 USB_SETUP_PACKET_INIT_GET_CONFIG_DESC (C macro), 943 USB_SETUP_PACKET_INIT_GET_DEVICE_DESC (C macro), 943 USB_SETUP_PACKET_INIT_GET_STR_DESC (C macro), 943 USB_SETUP_PACKET_INIT_SET_ADDR (C macro), 942 USB_SETUP_PACKET_INIT_SET_CONFIG (C macro), 943 USB_SETUP_PACKET_INIT_SET_INTERFACE (C macro), 943 USB_SETUP_PACKET_SIZE (C macro), 942 usb_setup_packet_t (C++ union), 937 usb_setup_packet_t::bmRequestType (C++ member), 937 usb_setup_packet_t::bRequest (C++ mem- ber), 937 usb_setup_packet_t::val (C++ member), 937 usb_setup_packet_t::wIndex (C++ member), 937 usb_setup_packet_t::wLength (C++ mem- ber), 937 usb_setup_packet_t::wValue (C++ member), 937 usb_setup_packet_t::[anonymous] (C++ member), 937 USB_SPEED_FULL (C++ enumerator), 936 USB_SPEED_LOW (C++ enumerator), 936 usb_speed_t (C++ enum), 936 USB_STANDARD_DESC_SIZE (C macro), 943 usb_standard_desc_t (C++ union), 938 usb_standard_desc_t::bDescriptorType (C++ member), 938 usb_standard_desc_t::bLength (C++ mem- ber), 938 usb_standard_desc_t::USB_DESC_ATTR (C++ member), 938 usb_standard_desc_t::val (C++ member), 938 USB_STR_DESC_SIZE (C macro), 944 usb_str_desc_t (C++ union), 941 usb_str_desc_t::bDescriptorType (C++ member), 941 usb_str_desc_t::bLength (C++ member), 941 usb_str_desc_t::USB_DESC_ATTR (C++ member), 941 usb_str_desc_t::val (C++ member), 941 usb_str_desc_t::wData (C++ member), 941 USB_STRING_DESCRIPTOR_ARRAY_SIZE (C macro), 913 USB_SUBCLASS_VENDOR_SPEC (C macro), 944 usb_transfer_cb_t (C++ type), 936 USB_TRANSFER_FLAG_ZERO_PACK (C macro), 935 usb_transfer_s (C++ class), 935 usb_transfer_s::actual_num_bytes (C++ member), 935 usb_transfer_s::bEndpointAddress (C++ member), 935 usb_transfer_s::callback (C++ member), 935 usb_transfer_s::context (C++ member), 935 usb_transfer_s::data_buffer (C++ mem- ber), 935 usb_transfer_s::data_buffer_size (C++ member), 935 usb_transfer_s::device_handle (C++ member), 935 usb_transfer_s::flags (C++ member), 935 usb_transfer_s::isoc_packet_desc (C++ member), 935 usb_transfer_s::num_bytes (C++ member), 935 usb_transfer_s::num_isoc_packets (C++ member), 935 usb_transfer_s::status (C++ member), 935 usb_transfer_s::timeout_ms (C++ member), 935 USB_TRANSFER_STATUS_CANCELED (C++ enu- merator), 937 USB_TRANSFER_STATUS_COMPLETED (C++ enu- merator), 937 USB_TRANSFER_STATUS_ERROR (C++ enumera- tor), 937 USB_TRANSFER_STATUS_NO_DEVICE (C++ enu- merator), 937 USB_TRANSFER_STATUS_OVERFLOW (C++ enu- merator), 937 USB_TRANSFER_STATUS_SKIPPED (C++ enumer- ator), 937 USB_TRANSFER_STATUS_STALL (C++ enumera- tor), 937 usb_transfer_status_t (C++ enum), 937 USB_TRANSFER_STATUS_TIMED_OUT (C++ enu- merator), 937 usb_transfer_t (C++ type), 936 USB_TRANSFER_TYPE_BULK (C++ enumerator), 937 USB_TRANSFER_TYPE_CTRL (C++ enumerator), 936 USB_TRANSFER_TYPE_INTR (C++ enumerator), Espressif Systems 2229 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index 937 USB_TRANSFER_TYPE_ISOCHRONOUS (C++ enu- merator), 936 usb_transfer_type_t (C++ enum), 936 USB_W_VALUE_DT_CONFIG (C macro), 942 USB_W_VALUE_DT_DEVICE (C macro), 942 USB_W_VALUE_DT_DEVICE_QUALIFIER (C macro), 942 USB_W_VALUE_DT_ENDPOINT (C macro), 942 USB_W_VALUE_DT_INTERFACE (C macro), 942 USB_W_VALUE_DT_INTERFACE_POWER (C macro), 942 USB_W_VALUE_DT_OTHER_SPEED_CONFIG (C macro), 942 USB_W_VALUE_DT_STRING (C macro), 942 uxQueueMessagesWaiting (C++ function), 1429 uxQueueMessagesWaitingFromISR (C++ func- tion), 1432 uxQueueSpacesAvailable (C++ function), 1429 uxSemaphoreGetCount (C macro), 1456 uxTaskGetNumberOfTasks (C++ function), 1409 uxTaskGetStackHighWaterMark (C++ func- tion), 1409 uxTaskGetStackHighWaterMark2 (C++ func- tion), 1409 uxTaskGetSystemState (C++ function), 1411 uxTaskPriorityGet (C++ function), 1402 uxTaskPriorityGetFromISR (C++ function), 1403 uxTimerGetReloadMode (C++ function), 1463 V vApplicationGetIdleTaskMemory (C++ function), 1411 vApplicationGetTimerTaskMemory (C++ function), 1464 vendor_ie_data_t (C++ class), 567 vendor_ie_data_t::element_id (C++ mem- ber), 567 vendor_ie_data_t::length (C++ member), 567 vendor_ie_data_t::payload (C++ member), 567 vendor_ie_data_t::vendor_oui (C++ mem- ber), 567 vendor_ie_data_t::vendor_oui_type (C++ member), 567 vEventGroupDelete (C++ function), 1479 vMessageBufferDelete (C macro), 1495 vprintf_like_t (C++ type), 1559 vQueueAddToRegistry (C++ function), 1432 vQueueDelete (C++ function), 1429 vQueueUnregisterQueue (C++ function), 1432 vRingbufferDelete (C++ function), 1511 vRingbufferGetInfo (C++ function), 1512 vRingbufferReturnItem (C++ function), 1511 vRingbufferReturnItemFromISR (C++ func- tion), 1511 vSemaphoreCreateBinary (C macro), 1444 vSemaphoreDelete (C macro), 1456 vStreamBufferDelete (C++ function), 1486 vTaskAllocateMPURegions (C++ function), 1398 vTaskDelay (C++ function), 1401 vTaskDelayUntil (C macro), 1423 vTaskDelete (C++ function), 1400 vTaskEndScheduler (C++ function), 1407 vTaskGenericNotifyGiveFromISR (C++ func- tion), 1418 vTaskGetInfo (C++ function), 1403 vTaskGetRunTimeStats (C++ function), 1413 vTaskList (C++ function), 1413 vTaskNotifyGiveFromISR (C macro), 1424 vTaskNotifyGiveIndexedFromISR (C macro), 1424 vTaskPrioritySet (C++ function), 1404 vTaskResume (C++ function), 1405 vTaskSetApplicationTaskTag (C++ function), 1410 vTaskSetThreadLocalStoragePointer (C++ function), 1410 vTaskSetThreadLocalStoragePointerAndDelCallback (C++ function), 1411 vTaskSetTimeOutState (C++ function), 1421 vTaskStartScheduler (C++ function), 1406 vTaskSuspend (C++ function), 1405 vTaskSuspendAll (C++ function), 1407 vTimerSetReloadMode (C++ function), 1463 vTimerSetTimerID (C++ function), 1461 W wifi_action_rx_cb_t (C++ type), 576 wifi_action_tx_req_t (C++ class), 571 wifi_action_tx_req_t::data (C++ member), 571 wifi_action_tx_req_t::data_len (C++ member), 571 wifi_action_tx_req_t::dest_mac (C++ member), 571 wifi_action_tx_req_t::ifx (C++ member), 571 wifi_action_tx_req_t::no_ack (C++ mem- ber), 571 wifi_action_tx_req_t::rx_cb (C++ mem- ber), 571 wifi_active_scan_time_t (C++ class), 563 wifi_active_scan_time_t::max (C++ mem- ber), 563 wifi_active_scan_time_t::min (C++ mem- ber), 563 WIFI_ALL_CHANNEL_SCAN (C++ enumerator), 579 WIFI_AMPDU_RX_ENABLED (C macro), 561 WIFI_AMPDU_TX_ENABLED (C macro), 561 WIFI_AMSDU_TX_ENABLED (C macro), 561 WIFI_ANT_ANT0 (C++ enumerator), 579 WIFI_ANT_ANT1 (C++ enumerator), 579 Espressif Systems 2230 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index wifi_ant_config_t (C++ class), 570 wifi_ant_config_t::enabled_ant0 (C++ member), 571 wifi_ant_config_t::enabled_ant1 (C++ member), 571 wifi_ant_config_t::rx_ant_default (C++ member), 570 wifi_ant_config_t::rx_ant_mode (C++ member), 570 wifi_ant_config_t::tx_ant_mode (C++ member), 570 wifi_ant_gpio_config_t (C++ class), 570 wifi_ant_gpio_config_t::gpio_cfg (C++ member), 570 wifi_ant_gpio_t (C++ class), 570 wifi_ant_gpio_t::gpio_num (C++ member), 570 wifi_ant_gpio_t::gpio_select (C++ mem- ber), 570 WIFI_ANT_MAX (C++ enumerator), 579 WIFI_ANT_MODE_ANT0 (C++ enumerator), 581 WIFI_ANT_MODE_ANT1 (C++ enumerator), 581 WIFI_ANT_MODE_AUTO (C++ enumerator), 581 WIFI_ANT_MODE_MAX (C++ enumerator), 581 wifi_ant_mode_t (C++ enum), 581 wifi_ant_t (C++ enum), 579 wifi_ap_config_t (C++ class), 565 wifi_ap_config_t::authmode (C++ member), 565 wifi_ap_config_t::beacon_interval (C++ member), 565 wifi_ap_config_t::channel (C++ member), 565 wifi_ap_config_t::ftm_responder (C++ member), 565 wifi_ap_config_t::max_connection (C++ member), 565 wifi_ap_config_t::pairwise_cipher (C++ member), 565 wifi_ap_config_t::password (C++ member), 565 wifi_ap_config_t::pmf_cfg (C++ member), 565 wifi_ap_config_t::ssid (C++ member), 565 wifi_ap_config_t::ssid_hidden (C++ member), 565 wifi_ap_config_t::ssid_len (C++ member), 565 wifi_ap_record_t (C++ class), 564 wifi_ap_record_t::ant (C++ member), 564 wifi_ap_record_t::authmode (C++ member), 564 wifi_ap_record_t::bssid (C++ member), 564 wifi_ap_record_t::country (C++ member), 564 wifi_ap_record_t::ftm_initiator (C++ member), 564 wifi_ap_record_t::ftm_responder (C++ member), 564 wifi_ap_record_t::group_cipher (C++ member), 564 wifi_ap_record_t::pairwise_cipher (C++ member), 564 wifi_ap_record_t::phy_11b (C++ member), 564 wifi_ap_record_t::phy_11g (C++ member), 564 wifi_ap_record_t::phy_11n (C++ member), 564 wifi_ap_record_t::phy_lr (C++ member), 564 wifi_ap_record_t::primary (C++ member), 564 wifi_ap_record_t::reserved (C++ member), 564 wifi_ap_record_t::rssi (C++ member), 564 wifi_ap_record_t::second (C++ member), 564 wifi_ap_record_t::ssid (C++ member), 564 wifi_ap_record_t::wps (C++ member), 564 WIFI_AUTH_MAX (C++ enumerator), 577 wifi_auth_mode_t (C++ enum), 577 WIFI_AUTH_OPEN (C++ enumerator), 577 WIFI_AUTH_WAPI_PSK (C++ enumerator), 577 WIFI_AUTH_WEP (C++ enumerator), 577 WIFI_AUTH_WPA2_ENTERPRISE (C++ enumera- tor), 577 WIFI_AUTH_WPA2_PSK (C++ enumerator), 577 WIFI_AUTH_WPA2_WPA3_PSK (C++ enumerator), 577 WIFI_AUTH_WPA3_PSK (C++ enumerator), 577 WIFI_AUTH_WPA_PSK (C++ enumerator), 577 WIFI_AUTH_WPA_WPA2_PSK (C++ enumerator), 577 wifi_bandwidth_t (C++ enum), 580 WIFI_BW_HT20 (C++ enumerator), 580 WIFI_BW_HT40 (C++ enumerator), 580 WIFI_CACHE_TX_BUFFER_NUM (C macro), 561 WIFI_CIPHER_TYPE_AES_CMAC128 (C++ enu- merator), 579 WIFI_CIPHER_TYPE_AES_GMAC128 (C++ enu- merator), 579 WIFI_CIPHER_TYPE_AES_GMAC256 (C++ enu- merator), 579 WIFI_CIPHER_TYPE_CCMP (C++ enumerator), 579 WIFI_CIPHER_TYPE_GCMP (C++ enumerator), 579 WIFI_CIPHER_TYPE_GCMP256 (C++ enumerator), 579 WIFI_CIPHER_TYPE_NONE (C++ enumerator), 578 WIFI_CIPHER_TYPE_SMS4 (C++ enumerator), 579 wifi_cipher_type_t (C++ enum), 578 WIFI_CIPHER_TYPE_TKIP (C++ enumerator), 579 WIFI_CIPHER_TYPE_TKIP_CCMP (C++ enumera- tor), 579 WIFI_CIPHER_TYPE_UNKNOWN (C++ enumerator), 579 Espressif Systems 2231 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index WIFI_CIPHER_TYPE_WEP104 (C++ enumerator), (C++ member), 574 579 wifi_event_action_tx_status_t::ifx WIFI_CIPHER_TYPE_WEP40 (C++ enumerator), (C++ member), 574 579 wifi_event_action_tx_status_t::status wifi_config_t (C++ union), 562 (C++ member), 575 wifi_config_t::ap (C++ member), 562 wifi_event_ap_probe_req_rx_t (C++ class), wifi_config_t::sta (C++ member), 562 573 WIFI_CONNECT_AP_BY_SECURITY (C++ enumer- wifi_event_ap_probe_req_rx_t::mac ator), 579 (C++ member), 573 WIFI_CONNECT_AP_BY_SIGNAL (C++ enumera- wifi_event_ap_probe_req_rx_t::rssi tor), 579 (C++ member), 573 WIFI_COUNTRY_POLICY_AUTO (C++ enumerator), WIFI_EVENT_AP_PROBEREQRECVED (C++ enu- 577 merator), 583 WIFI_COUNTRY_POLICY_MANUAL (C++ enumera- WIFI_EVENT_AP_STACONNECTED (C++ enumera- tor), 577 tor), 583 wifi_country_policy_t (C++ enum), 577 wifi_event_ap_staconnected_t (C++ class), wifi_country_t (C++ class), 563 573 wifi_country_t::cc (C++ member), 563 wifi_event_ap_staconnected_t::aid wifi_country_t::max_tx_power (C++ mem- (C++ member), 573 ber), 563 wifi_event_ap_staconnected_t::is_mesh_child wifi_country_t::nchan (C++ member), 563 (C++ member), 573 wifi_country_t::policy (C++ member), 563 wifi_event_ap_staconnected_t::mac wifi_country_t::schan (C++ member), 563 (C++ member), 573 wifi_csi_cb_t (C++ type), 562 WIFI_EVENT_AP_STADISCONNECTED (C++ enu- wifi_csi_config_t (C++ class), 569 merator), 583 wifi_csi_config_t::channel_filter_en wifi_event_ap_stadisconnected_t (C++ (C++ member), 569 class), 573 wifi_csi_config_t::htltf_en (C++ mem- wifi_event_ap_stadisconnected_t::aid ber), 569 (C++ member), 573 wifi_csi_config_t::lltf_en (C++ member), wifi_event_ap_stadisconnected_t::is_mesh_child 569 (C++ member), 573 wifi_csi_config_t::ltf_merge_en (C++ wifi_event_ap_stadisconnected_t::mac member), 569 (C++ member), 573 wifi_csi_config_t::manu_scale (C++ WIFI_EVENT_AP_START (C++ enumerator), 583 member), 570 WIFI_EVENT_AP_STOP (C++ enumerator), 583 wifi_csi_config_t::shift (C++ member), wifi_event_bss_rssi_low_t (C++ class), 573 570 wifi_event_bss_rssi_low_t::rssi (C++ wifi_csi_config_t::stbc_htltf2_en member), 573 (C++ member), 569 WIFI_EVENT_FTM_REPORT (C++ enumerator), 583 WIFI_CSI_ENABLED (C macro), 561 wifi_event_ftm_report_t (C++ class), 574 wifi_csi_info_t (C++ class), 570 wifi_event_ftm_report_t::dist_est wifi_csi_info_t::buf (C++ member), 570 (C++ member), 574 wifi_csi_info_t::first_word_invalid wifi_event_ftm_report_t::ftm_report_data (C++ member), 570 (C++ member), 574 wifi_csi_info_t::len (C++ member), 570 wifi_event_ftm_report_t::ftm_report_num_entries wifi_csi_info_t::mac (C++ member), 570 (C++ member), 574 wifi_csi_info_t::rx_ctrl (C++ member), wifi_event_ftm_report_t::peer_mac 570 (C++ member), 574 WIFI_DEFAULT_RX_BA_WIN (C macro), 561 wifi_event_ftm_report_t::rtt_est (C++ WIFI_DYNAMIC_TX_BUFFER_NUM (C macro), 561 member), 574 wifi_err_reason_t (C++ enum), 577 wifi_event_ftm_report_t::rtt_raw (C++ WIFI_EVENT_ACTION_TX_STATUS (C++ enumer- member), 574 ator), 583 wifi_event_ftm_report_t::status (C++ wifi_event_action_tx_status_t (C++ member), 574 class), 574 WIFI_EVENT_MASK_ALL (C macro), 576 wifi_event_action_tx_status_t::context WIFI_EVENT_MASK_AP_PROBEREQRECVED (C (C++ member), 574 macro), 576 wifi_event_action_tx_status_t::da WIFI_EVENT_MASK_NONE (C macro), 576 Espressif Systems 2232 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index WIFI_EVENT_MAX (C++ enumerator), 583 WIFI_EVENT_STA_WPS_ER_PIN (C++ enumera- WIFI_EVENT_ROC_DONE (C++ enumerator), 583 tor), 583 wifi_event_roc_done_t (C++ class), 575 wifi_event_sta_wps_er_pin_t (C++ class), wifi_event_roc_done_t::context (C++ 572 member), 575 wifi_event_sta_wps_er_pin_t::pin_code WIFI_EVENT_SCAN_DONE (C++ enumerator), 582 (C++ member), 572 WIFI_EVENT_STA_AUTHMODE_CHANGE (C++ WIFI_EVENT_STA_WPS_ER_SUCCESS (C++ enu- enumerator), 583 merator), 583 wifi_event_sta_authmode_change_t (C++ wifi_event_sta_wps_er_success_t (C++ class), 572 class), 572 wifi_event_sta_authmode_change_t::new_mwoidfei_event_sta_wps_er_success_t::ap_cred (C++ member), 572 (C++ member), 573 wifi_event_sta_authmode_change_t::old_mwoidfei_event_sta_wps_er_success_t::ap_cred_cnt (C++ member), 572 (C++ member), 573 WIFI_EVENT_STA_BEACON_TIMEOUT (C++ enu- wifi_event_sta_wps_er_success_t::passphrase merator), 583 (C++ member), 573 WIFI_EVENT_STA_BSS_RSSI_LOW (C++ enumer- wifi_event_sta_wps_er_success_t::ssid ator), 583 (C++ member), 573 WIFI_EVENT_STA_CONNECTED (C++ enumerator), WIFI_EVENT_STA_WPS_ER_TIMEOUT (C++ enu- 583 merator), 583 wifi_event_sta_connected_t (C++ class), wifi_event_sta_wps_fail_reason_t (C++ 571 enum), 583 wifi_event_sta_connected_t::authmode wifi_event_t (C++ enum), 582 (C++ member), 572 WIFI_EVENT_WIFI_READY (C++ enumerator), 582 wifi_event_sta_connected_t::bssid WIFI_FAST_SCAN (C++ enumerator), 579 (C++ member), 572 wifi_ftm_initiator_cfg_t (C++ class), 571 wifi_event_sta_connected_t::channel wifi_ftm_initiator_cfg_t::burst_period (C++ member), 572 (C++ member), 571 wifi_event_sta_connected_t::ssid (C++ wifi_ftm_initiator_cfg_t::channel member), 572 (C++ member), 571 wifi_event_sta_connected_t::ssid_len wifi_ftm_initiator_cfg_t::frm_count (C++ member), 572 (C++ member), 571 WIFI_EVENT_STA_DISCONNECTED (C++ enumer- wifi_ftm_initiator_cfg_t::resp_mac ator), 583 (C++ member), 571 wifi_event_sta_disconnected_t (C++ wifi_ftm_report_entry_t (C++ class), 573 class), 572 wifi_ftm_report_entry_t::dlog_token wifi_event_sta_disconnected_t::bssid (C++ member), 574 (C++ member), 572 wifi_ftm_report_entry_t::rssi (C++ wifi_event_sta_disconnected_t::reason member), 574 (C++ member), 572 wifi_ftm_report_entry_t::rtt (C++ mem- wifi_event_sta_disconnected_t::ssid ber), 574 (C++ member), 572 wifi_ftm_report_entry_t::t1 (C++ mem- wifi_event_sta_disconnected_t::ssid_len ber), 574 (C++ member), 572 wifi_ftm_report_entry_t::t2 (C++ mem- wifi_event_sta_scan_done_t (C++ class), ber), 574 571 wifi_ftm_report_entry_t::t3 (C++ mem- wifi_event_sta_scan_done_t::number ber), 574 (C++ member), 571 wifi_ftm_report_entry_t::t4 (C++ mem- wifi_event_sta_scan_done_t::scan_id ber), 574 (C++ member), 571 wifi_ftm_status_t (C++ enum), 584 wifi_event_sta_scan_done_t::status WIFI_IF_AP (C++ enumerator), 577 (C++ member), 571 WIFI_IF_STA (C++ enumerator), 577 WIFI_EVENT_STA_START (C++ enumerator), 582 WIFI_INIT_CONFIG_DEFAULT (C macro), 562 WIFI_EVENT_STA_STOP (C++ enumerator), 582 WIFI_INIT_CONFIG_MAGIC (C macro), 561 WIFI_EVENT_STA_WPS_ER_FAILED (C++ enu- wifi_init_config_t (C++ class), 559 merator), 583 wifi_init_config_t::ampdu_rx_enable WIFI_EVENT_STA_WPS_ER_PBC_OVERLAP (C++ member), 560 (C++ enumerator), 583 wifi_init_config_t::ampdu_tx_enable Espressif Systems 2233 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index (C++ member), 560 WIFI_PHY_RATE_2M_S (C++ enumerator), 581 wifi_init_config_t::amsdu_tx_enable WIFI_PHY_RATE_36M (C++ enumerator), 581 (C++ member), 560 WIFI_PHY_RATE_48M (C++ enumerator), 581 wifi_init_config_t::beacon_max_len WIFI_PHY_RATE_54M (C++ enumerator), 581 (C++ member), 560 WIFI_PHY_RATE_5M_L (C++ enumerator), 581 wifi_init_config_t::cache_tx_buf_num WIFI_PHY_RATE_5M_S (C++ enumerator), 581 (C++ member), 560 WIFI_PHY_RATE_6M (C++ enumerator), 581 wifi_init_config_t::csi_enable (C++ WIFI_PHY_RATE_9M (C++ enumerator), 581 member), 560 WIFI_PHY_RATE_LORA_250K (C++ enumerator), wifi_init_config_t::dynamic_rx_buf_num 582 (C++ member), 559 WIFI_PHY_RATE_LORA_500K (C++ enumerator), wifi_init_config_t::dynamic_tx_buf_num 582 (C++ member), 560 WIFI_PHY_RATE_MAX (C++ enumerator), 582 wifi_init_config_t::feature_caps (C++ WIFI_PHY_RATE_MCS0_LGI (C++ enumerator), member), 560 581 wifi_init_config_t::magic (C++ member), WIFI_PHY_RATE_MCS0_SGI (C++ enumerator), 560 582 wifi_init_config_t::mgmt_sbuf_num WIFI_PHY_RATE_MCS1_LGI (C++ enumerator), (C++ member), 560 582 wifi_init_config_t::nano_enable (C++ WIFI_PHY_RATE_MCS1_SGI (C++ enumerator), member), 560 582 wifi_init_config_t::nvs_enable (C++ WIFI_PHY_RATE_MCS2_LGI (C++ enumerator), member), 560 582 wifi_init_config_t::osi_funcs (C++ WIFI_PHY_RATE_MCS2_SGI (C++ enumerator), member), 559 582 wifi_init_config_t::rx_ba_win (C++ WIFI_PHY_RATE_MCS3_LGI (C++ enumerator), member), 560 582 wifi_init_config_t::sta_disconnected_pmWIFI_PHY_RATE_MCS3_SGI (C++ enumerator), (C++ member), 560 582 wifi_init_config_t::static_rx_buf_num WIFI_PHY_RATE_MCS4_LGI (C++ enumerator), (C++ member), 559 582 wifi_init_config_t::static_tx_buf_num WIFI_PHY_RATE_MCS4_SGI (C++ enumerator), (C++ member), 560 582 wifi_init_config_t::tx_buf_type (C++ WIFI_PHY_RATE_MCS5_LGI (C++ enumerator), member), 559 582 wifi_init_config_t::wifi_task_core_id WIFI_PHY_RATE_MCS5_SGI (C++ enumerator), (C++ member), 560 582 wifi_init_config_t::wpa_crypto_funcs WIFI_PHY_RATE_MCS6_LGI (C++ enumerator), (C++ member), 559 582 wifi_interface_t (C++ enum), 577 WIFI_PHY_RATE_MCS6_SGI (C++ enumerator), WIFI_MGMT_SBUF_NUM (C macro), 561 582 WIFI_MODE_AP (C++ enumerator), 576 WIFI_PHY_RATE_MCS7_LGI (C++ enumerator), WIFI_MODE_APSTA (C++ enumerator), 577 582 WIFI_MODE_MAX (C++ enumerator), 577 WIFI_PHY_RATE_MCS7_SGI (C++ enumerator), WIFI_MODE_NULL (C++ enumerator), 576 582 WIFI_MODE_STA (C++ enumerator), 576 wifi_phy_rate_t (C++ enum), 581 wifi_mode_t (C++ enum), 576 WIFI_PKT_CTRL (C++ enumerator), 580 WIFI_NANO_FORMAT_ENABLED (C macro), 561 WIFI_PKT_DATA (C++ enumerator), 580 WIFI_NVS_ENABLED (C macro), 561 WIFI_PKT_MGMT (C++ enumerator), 580 WIFI_OFFCHAN_TX_CANCEL (C macro), 575 WIFI_PKT_MISC (C++ enumerator), 580 WIFI_OFFCHAN_TX_REQ (C macro), 575 wifi_pkt_rx_ctrl_t (C++ class), 567 WIFI_PHY_RATE_11M_L (C++ enumerator), 581 wifi_pkt_rx_ctrl_t::__pad0__ (C++ mem- WIFI_PHY_RATE_11M_S (C++ enumerator), 581 ber), 567 WIFI_PHY_RATE_12M (C++ enumerator), 581 wifi_pkt_rx_ctrl_t::__pad10__ (C++ WIFI_PHY_RATE_18M (C++ enumerator), 581 member), 569 WIFI_PHY_RATE_1M_L (C++ enumerator), 581 wifi_pkt_rx_ctrl_t::__pad11__ (C++ WIFI_PHY_RATE_24M (C++ enumerator), 581 member), 569 WIFI_PHY_RATE_2M_L (C++ enumerator), 581 wifi_pkt_rx_ctrl_t::__pad12__ (C++ Espressif Systems 2234 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index member), 569 wifi_pkt_rx_ctrl_t::__pad13__ (C++ member), 569 wifi_pkt_rx_ctrl_t::__pad1__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::__pad2__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::__pad3__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::__pad4__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::__pad5__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::__pad6__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::__pad7__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::__pad8__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::__pad9__ (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::aggregation (C++ member), 568 wifi_pkt_rx_ctrl_t::ampdu_cnt (C++ member), 568 wifi_pkt_rx_ctrl_t::ant (C++ member), 569 wifi_pkt_rx_ctrl_t::channel (C++ mem- ber), 568 wifi_pkt_rx_ctrl_t::cwb (C++ member), 568 wifi_pkt_rx_ctrl_t::fec_coding (C++ member), 568 wifi_pkt_rx_ctrl_t::mcs (C++ member), 568 wifi_pkt_rx_ctrl_t::noise_floor (C++ member), 568 wifi_pkt_rx_ctrl_t::not_sounding (C++ member), 568 wifi_pkt_rx_ctrl_t::rate (C++ member), 567 wifi_pkt_rx_ctrl_t::rssi (C++ member), 567 wifi_pkt_rx_ctrl_t::rx_state (C++ mem- ber), 569 wifi_pkt_rx_ctrl_t::secondary_channel (C++ member), 568 wifi_pkt_rx_ctrl_t::sgi (C++ member), 568 wifi_pkt_rx_ctrl_t::sig_len (C++ mem- ber), 569 wifi_pkt_rx_ctrl_t::sig_mode (C++ mem- ber), 567 wifi_pkt_rx_ctrl_t::smoothing (C++ member), 568 wifi_pkt_rx_ctrl_t::stbc (C++ member), 568 wifi_pkt_rx_ctrl_t::timestamp (C++ member), 568 wifi_pmf_config_t (C++ class), 565 wifi_pmf_config_t::capable (C++ member), 565 wifi_pmf_config_t::required (C++ mem- ber), 565 WIFI_PROMIS_CTRL_FILTER_MASK_ACK (C macro), 576 WIFI_PROMIS_CTRL_FILTER_MASK_ALL (C macro), 575 WIFI_PROMIS_CTRL_FILTER_MASK_BA (C macro), 575 WIFI_PROMIS_CTRL_FILTER_MASK_BAR (C macro), 575 WIFI_PROMIS_CTRL_FILTER_MASK_CFEND (C macro), 576 WIFI_PROMIS_CTRL_FILTER_MASK_CFENDACK (C macro), 576 WIFI_PROMIS_CTRL_FILTER_MASK_CTS (C macro), 576 WIFI_PROMIS_CTRL_FILTER_MASK_PSPOLL (C macro), 576 WIFI_PROMIS_CTRL_FILTER_MASK_RTS (C macro), 576 WIFI_PROMIS_CTRL_FILTER_MASK_WRAPPER (C macro), 575 WIFI_PROMIS_FILTER_MASK_ALL (C macro), 575 WIFI_PROMIS_FILTER_MASK_CTRL (C macro), 575 WIFI_PROMIS_FILTER_MASK_DATA (C macro), 575 WIFI_PROMIS_FILTER_MASK_DATA_AMPDU (C macro), 575 WIFI_PROMIS_FILTER_MASK_DATA_MPDU (C macro), 575 WIFI_PROMIS_FILTER_MASK_FCSFAIL (C macro), 575 WIFI_PROMIS_FILTER_MASK_MGMT (C macro), 575 WIFI_PROMIS_FILTER_MASK_MISC (C macro), 575 wifi_promiscuous_cb_t (C++ type), 562 wifi_promiscuous_filter_t (C++ class), 569 wifi_promiscuous_filter_t::filter_mask (C++ member), 569 wifi_promiscuous_pkt_t (C++ class), 569 wifi_promiscuous_pkt_t::payload (C++ member), 569 wifi_promiscuous_pkt_t::rx_ctrl (C++ member), 569 wifi_promiscuous_pkt_type_t (C++ enum), 580 WIFI_PROTOCOL_11B (C macro), 575 WIFI_PROTOCOL_11G (C macro), 575 WIFI_PROTOCOL_11N (C macro), 575 WIFI_PROTOCOL_LR (C macro), 575 wifi_prov_cb_event_t (C++ enum), 1230 wifi_prov_cb_func_t (C++ type), 1230 wifi_prov_config_data_handler (C++ func- tion), 1232 wifi_prov_config_get_data_t (C++ class), Espressif Systems 2235 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index 1232 tion), 1227 wifi_prov_config_get_data_t::conn_info wifi_prov_mgr_endpoint_register (C++ (C++ member), 1232 function), 1227 wifi_prov_config_get_data_t::fail_reasownifi_prov_mgr_endpoint_unregister (C++ member), 1232 (C++ function), 1227 wifi_prov_config_get_data_t::wifi_statewifi_prov_mgr_get_wifi_disconnect_reason (C++ member), 1232 (C++ function), 1228 wifi_prov_config_handlers (C++ class), wifi_prov_mgr_get_wifi_state (C++ func- 1233 tion), 1227 wifi_prov_config_handlers::apply_configw_ihfain_dplreorv_mgr_init (C++ function), 1224 (C++ member), 1233 wifi_prov_mgr_is_provisioned (C++ func- wifi_prov_config_handlers::ctx (C++ tion), 1225 member), 1233 wifi_prov_mgr_reset_provisioning (C++ wifi_prov_config_handlers::get_status_handler function), 1228 (C++ member), 1233 wifi_prov_mgr_reset_sm_state_on_failure wifi_prov_config_handlers::set_config_handler (C++ function), 1228 (C++ member), 1233 wifi_prov_mgr_set_app_info (C++ function), wifi_prov_config_handlers_t (C++ type), 1226 1233 wifi_prov_mgr_start_provisioning (C++ wifi_prov_config_set_data_t (C++ class), function), 1225 1233 wifi_prov_mgr_stop_provisioning (C++ wifi_prov_config_set_data_t::bssid function), 1225 (C++ member), 1233 wifi_prov_mgr_wait (C++ function), 1226 wifi_prov_config_set_data_t::channel wifi_prov_scheme (C++ class), 1228 (C++ member), 1233 wifi_prov_scheme::delete_config (C++ wifi_prov_config_set_data_t::password member), 1229 (C++ member), 1233 wifi_prov_scheme::new_config (C++ mem- wifi_prov_config_set_data_t::ssid ber), 1229 (C++ member), 1233 wifi_prov_scheme::prov_start (C++ mem- WIFI_PROV_CRED_FAIL (C++ enumerator), 1230 ber), 1229 WIFI_PROV_CRED_RECV (C++ enumerator), 1230 wifi_prov_scheme::prov_stop (C++ mem- WIFI_PROV_CRED_SUCCESS (C++ enumerator), ber), 1229 1230 wifi_prov_scheme::set_config_endpoint wifi_prov_ctx_t (C++ type), 1233 (C++ member), 1229 WIFI_PROV_DEINIT (C++ enumerator), 1230 wifi_prov_scheme::set_config_service WIFI_PROV_END (C++ enumerator), 1230 (C++ member), 1229 WIFI_PROV_EVENT_HANDLER_NONE (C macro), wifi_prov_scheme::wifi_mode (C++ mem- 1230 ber), 1229 wifi_prov_event_handler_t (C++ class), wifi_prov_scheme_ble_event_cb_free_ble 1228 (C++ function), 1231 wifi_prov_event_handler_t::event_cb wifi_prov_scheme_ble_event_cb_free_bt (C++ member), 1228 (C++ function), 1231 wifi_prov_event_handler_t::user_data wifi_prov_scheme_ble_event_cb_free_btdm (C++ member), 1228 (C++ function), 1231 WIFI_PROV_INIT (C++ enumerator), 1230 WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE wifi_prov_mgr_config_t (C++ class), 1229 (C macro), 1231 wifi_prov_mgr_config_t::app_event_handlWeIrFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT (C++ member), 1229 (C macro), 1231 wifi_prov_mgr_config_t::scheme (C++ WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM member), 1229 (C macro), 1231 wifi_prov_mgr_config_t::scheme_event_hawnidflie_rprov_scheme_ble_set_mfg_data (C++ member), 1229 (C++ function), 1231 wifi_prov_mgr_configure_sta (C++ func- wifi_prov_scheme_ble_set_service_uuid tion), 1228 (C++ function), 1231 wifi_prov_mgr_deinit (C++ function), 1224 wifi_prov_scheme_softap_set_httpd_handle wifi_prov_mgr_disable_auto_stop (C++ (C++ function), 1232 function), 1226 wifi_prov_scheme_t (C++ type), 1230 wifi_prov_mgr_endpoint_create (C++ func- wifi_prov_security (C++ enum), 1230 Espressif Systems 2236 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index WIFI_PROV_SECURITY_0 (C++ enumerator), 1230 WIFI_PROV_SECURITY_1 (C++ enumerator), 1230 wifi_prov_security_t (C++ type), 1230 WIFI_PROV_STA_AP_NOT_FOUND (C++ enumera- tor), 1234 WIFI_PROV_STA_AUTH_ERROR (C++ enumerator), 1234 wifi_prov_sta_conn_info_t (C++ class), 1232 wifi_prov_sta_conn_info_t::auth_mode (C++ member), 1232 wifi_prov_sta_conn_info_t::bssid (C++ member), 1232 wifi_prov_sta_conn_info_t::channel (C++ member), 1232 wifi_prov_sta_conn_info_t::ip_addr (C++ member), 1232 wifi_prov_sta_conn_info_t::ssid (C++ member), 1232 WIFI_PROV_STA_CONNECTED (C++ enumerator), 1234 WIFI_PROV_STA_CONNECTING (C++ enumerator), 1233 WIFI_PROV_STA_DISCONNECTED (C++ enumera- tor), 1234 wifi_prov_sta_fail_reason_t (C++ enum), 1234 wifi_prov_sta_state_t (C++ enum), 1233 WIFI_PROV_START (C++ enumerator), 1230 WIFI_PS_MAX_MODEM (C++ enumerator), 580 WIFI_PS_MIN_MODEM (C++ enumerator), 580 WIFI_PS_NONE (C++ enumerator), 580 wifi_ps_type_t (C++ enum), 580 WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT (C++ enumerator), 578 WIFI_REASON_802_1X_AUTH_FAILED (C++ enumerator), 578 WIFI_REASON_AKMP_INVALID (C++ enumerator), 578 WIFI_REASON_AP_TSF_RESET (C++ enumerator), 578 WIFI_REASON_ASSOC_EXPIRE (C++ enumerator), 577 WIFI_REASON_ASSOC_FAIL (C++ enumerator), 578 WIFI_REASON_ASSOC_LEAVE (C++ enumerator), 577 WIFI_REASON_ASSOC_NOT_AUTHED (C++ enu- merator), 578 WIFI_REASON_ASSOC_TOOMANY (C++ enumera- tor), 577 WIFI_REASON_AUTH_EXPIRE (C++ enumerator), 577 WIFI_REASON_AUTH_FAIL (C++ enumerator), 578 WIFI_REASON_AUTH_LEAVE (C++ enumerator), 577 WIFI_REASON_BEACON_TIMEOUT (C++ enumera- tor), 578 WIFI_REASON_BSS_TRANSITION_DISASSOC (C++ enumerator), 578 WIFI_REASON_CIPHER_SUITE_REJECTED (C++ enumerator), 578 WIFI_REASON_CONNECTION_FAIL (C++ enumerator), 578 WIFI_REASON_DISASSOC_PWRCAP_BAD (C++ enumerator), 578 WIFI_REASON_DISASSOC_SUPCHAN_BAD (C++ enumerator), 578 WIFI_REASON_GROUP_CIPHER_INVALID (C++ enumerator), 578 WIFI_REASON_GROUP_KEY_UPDATE_TIMEOUT (C++ enumerator), 578 WIFI_REASON_HANDSHAKE_TIMEOUT (C++ enumerator), 578 WIFI_REASON_IE_IN_4WAY_DIFFERS (C++ enumerator), 578 WIFI_REASON_IE_INVALID (C++ enumerator), 578 WIFI_REASON_INVALID_PMKID (C++ enumerator), 578 WIFI_REASON_INVALID_RSN_IE_CAP (C++ enumerator), 578 WIFI_REASON_MIC_FAILURE (C++ enumerator), 578 WIFI_REASON_NO_AP_FOUND (C++ enumerator), 578 WIFI_REASON_NOT_ASSOCED (C++ enumerator), 577 WIFI_REASON_NOT_AUTHED (C++ enumerator), 577 WIFI_REASON_PAIRWISE_CIPHER_INVALID (C++ enumerator), 578 WIFI_REASON_ROAMING (C++ enumerator), 578 WIFI_REASON_UNSPECIFIED (C++ enumerator), 577 WIFI_REASON_UNSUPP_RSN_IE_VERSION (C++ enumerator), 578 WIFI_ROC_CANCEL (C macro), 575 WIFI_ROC_REQ (C macro), 575 wifi_scan_config_t (C++ class), 563 wifi_scan_config_t::bssid (C++ member), 563 wifi_scan_config_t::channel (C++ mem- ber), 563 wifi_scan_config_t::scan_time (C++ member), 564 wifi_scan_config_t::scan_type (C++ member), 563 wifi_scan_config_t::show_hidden (C++ member), 563 wifi_scan_config_t::ssid (C++ member), 563 wifi_scan_method_t (C++ enum), 579 wifi_scan_threshold_t (C++ class), 564 wifi_scan_threshold_t::authmode (C++ member), 565 Espressif Systems 2237 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index wifi_scan_threshold_t::rssi (C++ member), 565 wifi_scan_time_t (C++ class), 563 wifi_scan_time_t::active (C++ member), 563 wifi_scan_time_t::passive (C++ member), 563 WIFI_SCAN_TYPE_ACTIVE (C++ enumerator), 578 WIFI_SCAN_TYPE_PASSIVE (C++ enumerator), 578 wifi_scan_type_t (C++ enum), 578 WIFI_SECOND_CHAN_ABOVE (C++ enumerator), 578 WIFI_SECOND_CHAN_BELOW (C++ enumerator), 578 WIFI_SECOND_CHAN_NONE (C++ enumerator), 578 wifi_second_chan_t (C++ enum), 578 WIFI_SOFTAP_BEACON_MAX_LEN (C macro), 561 wifi_sort_method_t (C++ enum), 579 wifi_sta_config_t (C++ class), 566 wifi_sta_config_t::bssid (C++ member), 566 wifi_sta_config_t::bssid_set (C++ mem- ber), 566 wifi_sta_config_t::btm_enabled (C++ member), 566 wifi_sta_config_t::channel (C++ member), 566 wifi_sta_config_t::listen_interval (C++ member), 566 wifi_sta_config_t::mbo_enabled (C++ member), 566 wifi_sta_config_t::password (C++ mem- ber), 566 wifi_sta_config_t::pmf_cfg (C++ member), 566 wifi_sta_config_t::reserved (C++ mem- ber), 566 wifi_sta_config_t::rm_enabled (C++ member), 566 wifi_sta_config_t::scan_method (C++ member), 566 wifi_sta_config_t::sort_method (C++ member), 566 wifi_sta_config_t::ssid (C++ member), 566 wifi_sta_config_t::threshold (C++ mem- ber), 566 WIFI_STA_DISCONNECTED_PM_ENABLED (C macro), 561 wifi_sta_info_t (C++ class), 566 wifi_sta_info_t::is_mesh_child (C++ member), 567 wifi_sta_info_t::mac (C++ member), 566 wifi_sta_info_t::phy_11b (C++ member), 566 wifi_sta_info_t::phy_11g (C++ member), 566 wifi_sta_info_t::phy_11n (C++ member), 567 wifi_sta_info_t::phy_lr (C++ member), 567 wifi_sta_info_t::reserved (C++ member), 567 wifi_sta_info_t::rssi (C++ member), 566 wifi_sta_list_t (C++ class), 567 wifi_sta_list_t::num (C++ member), 567 wifi_sta_list_t::sta (C++ member), 567 WIFI_STATIC_TX_BUFFER_NUM (C macro), 561 WIFI_STATIS_ALL (C macro), 576 WIFI_STATIS_BUFFER (C macro), 576 WIFI_STATIS_DIAG (C macro), 576 WIFI_STATIS_HW (C macro), 576 WIFI_STATIS_PS (C macro), 576 WIFI_STATIS_RXTX (C macro), 576 WIFI_STORAGE_FLASH (C++ enumerator), 580 WIFI_STORAGE_RAM (C++ enumerator), 580 wifi_storage_t (C++ enum), 580 WIFI_TASK_CORE_ID (C macro), 561 WIFI_VENDOR_IE_ELEMENT_ID (C macro), 575 wifi_vendor_ie_id_t (C++ enum), 580 wifi_vendor_ie_type_t (C++ enum), 580 WIFI_VND_IE_ID_0 (C++ enumerator), 580 WIFI_VND_IE_ID_1 (C++ enumerator), 580 WIFI_VND_IE_TYPE_ASSOC_REQ (C++ enumera- tor), 580 WIFI_VND_IE_TYPE_ASSOC_RESP (C++ enumer- ator), 580 WIFI_VND_IE_TYPE_BEACON (C++ enumerator), 580 WIFI_VND_IE_TYPE_PROBE_REQ (C++ enumera- tor), 580 WIFI_VND_IE_TYPE_PROBE_RESP (C++ enumer- ator), 580 wl_erase_range (C++ function), 1333 wl_handle_t (C++ type), 1334 WL_INVALID_HANDLE (C macro), 1334 wl_mount (C++ function), 1333 wl_read (C++ function), 1334 wl_sector_size (C++ function), 1334 wl_size (C++ function), 1334 wl_unmount (C++ function), 1333 wl_write (C++ function), 1333 WPS_FAIL_REASON_MAX (C++ enumerator), 583 WPS_FAIL_REASON_NORMAL (C++ enumerator), 583 WPS_FAIL_REASON_RECV_M2D (C++ enumerator), 583 X xEventGroupClearBits (C++ function), 1476 xEventGroupClearBitsFromISR (C macro), 1480 xEventGroupCreate (C++ function), 1474 xEventGroupCreateStatic (C++ function), 1474 xEventGroupGetBits (C macro), 1481 Espressif Systems 2238 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index xEventGroupGetBitsFromISR (C++ function), 1479 xEventGroupSetBits (C++ function), 1477 xEventGroupSetBitsFromISR (C macro), 1480 xEventGroupSync (C++ function), 1478 xEventGroupWaitBits (C++ function), 1475 xMessageBufferCreate (C macro), 1489 xMessageBufferCreateStatic (C macro), 1490 xMessageBufferIsEmpty (C macro), 1496 xMessageBufferIsFull (C macro), 1495 xMessageBufferNextLengthBytes (C macro), 1496 xMessageBufferReceive (C macro), 1493 xMessageBufferReceiveCompletedFromISR (C macro), 1497 xMessageBufferReceiveFromISR (C macro), 1494 xMessageBufferReset (C macro), 1496 xMessageBufferSend (C macro), 1491 xMessageBufferSendCompletedFromISR (C macro), 1496 xMessageBufferSendFromISR (C macro), 1492 xMessageBufferSpaceAvailable (C macro), 1496 xMessageBufferSpacesAvailable (C macro), 1496 xQueueAddToSet (C++ function), 1433 xQueueCreate (C macro), 1434 xQueueCreateSet (C++ function), 1432 xQueueCreateStatic (C macro), 1435 xQueueGenericCreate (C++ function), 1432 xQueueGenericCreateStatic (C++ function), 1432 xQueueGenericSend (C++ function), 1426 xQueueGenericSendFromISR (C++ function), 1429 xQueueGiveFromISR (C++ function), 1430 xQueueIsQueueEmptyFromISR (C++ function), 1431 xQueueIsQueueFullFromISR (C++ function), 1431 xQueueOverwrite (C macro), 1439 xQueueOverwriteFromISR (C macro), 1441 xQueuePeek (C++ function), 1427 xQueuePeekFromISR (C++ function), 1428 xQueueReceive (C++ function), 1428 xQueueReceiveFromISR (C++ function), 1430 xQueueRemoveFromSet (C++ function), 1433 xQueueReset (C macro), 1443 xQueueSelectFromSet (C++ function), 1433 xQueueSelectFromSetFromISR (C++ function), 1434 xQueueSend (C macro), 1438 xQueueSendFromISR (C macro), 1443 xQueueSendToBack (C macro), 1437 xQueueSendToBackFromISR (C macro), 1441 xQueueSendToFront (C macro), 1436 xQueueSendToFrontFromISR (C macro), 1440 xRingbufferAddToQueueSetRead (C++ func- tion), 1511 xRingbufferCanRead (C++ function), 1512 xRingbufferCreate (C++ function), 1507 xRingbufferCreateNoSplit (C++ function), 1507 xRingbufferCreateStatic (C++ function), 1507 xRingbufferGetCurFreeSize (C++ function), 1511 xRingbufferGetMaxItemSize (C++ function), 1511 xRingbufferPrintInfo (C++ function), 1512 xRingbufferReceive (C++ function), 1509 xRingbufferReceiveFromISR (C++ function), 1509 xRingbufferReceiveSplit (C++ function), 1509 xRingbufferReceiveSplitFromISR (C++ function), 1510 xRingbufferReceiveUpTo (C++ function), 1510 xRingbufferReceiveUpToFromISR (C++ func- tion), 1510 xRingbufferRemoveFromQueueSetRead (C++ function), 1512 xRingbufferSend (C++ function), 1508 xRingbufferSendAcquire (C++ function), 1508 xRingbufferSendComplete (C++ function), 1509 xRingbufferSendFromISR (C++ function), 1508 xSemaphoreCreateBinary (C macro), 1444 xSemaphoreCreateBinaryStatic (C macro), 1444 xSemaphoreCreateCounting (C macro), 1452 xSemaphoreCreateCountingStatic (C macro), 1455 xSemaphoreCreateMutex (C macro), 1451 xSemaphoreCreateMutexStatic (C macro), 1451 xSemaphoreGetMutexHolder (C macro), 1456 xSemaphoreGetMutexHolderFromISR (C macro), 1456 xSemaphoreGive (C macro), 1447 xSemaphoreGiveFromISR (C macro), 1449 xSemaphoreGiveRecursive (C macro), 1448 xSemaphoreTake (C macro), 1445 xSemaphoreTakeFromISR (C macro), 1451 xSemaphoreTakeRecursive (C macro), 1446 xSTATIC_RINGBUFFER (C++ class), 1512 xStreamBufferBytesAvailable (C++ func- tion), 1486 xStreamBufferCreate (C macro), 1487 xStreamBufferCreateStatic (C macro), 1488 xStreamBufferIsEmpty (C++ function), 1486 xStreamBufferIsFull (C++ function), 1486 xStreamBufferReceive (C++ function), 1484 xStreamBufferReceiveCompletedFromISR (C++ function), 1487 Espressif Systems 2239 Release v5.0-dev-2349-g4350e6fef8 Submit Document Feedback Index xStreamBufferReceiveFromISR (C++ function), 1485 xStreamBufferReset (C++ function), 1486 xStreamBufferSend (C++ function), 1481 xStreamBufferSendCompletedFromISR (C++ function), 1487 xStreamBufferSendFromISR (C++ function), 1483 xStreamBufferSetTriggerLevel (C++ func- tion), 1486 xStreamBufferSpacesAvailable (C++ func- tion), 1486 xTaskAbortDelay (C++ function), 1402 xTaskCallApplicationTaskHook (C++ func- tion), 1411 xTaskCatchUpTicks (C++ function), 1422 xTaskCheckForTimeOut (C++ function), 1421 xTaskCreate (C++ function), 1395 xTaskCreatePinnedToCore (C++ function), 1394 xTaskCreateStatic (C++ function), 1396 xTaskCreateStaticPinnedToCore (C++ func- tion), 1396 xTaskDelayUntil (C++ function), 1401 xTaskGenericNotify (C++ function), 1414 xTaskGenericNotifyFromISR (C++ function), 1415 xTaskGenericNotifyStateClear (C++ func- tion), 1420 xTaskGenericNotifyWait (C++ function), 1417 xTaskGetApplicationTaskTag (C++ function), 1410 xTaskGetApplicationTaskTagFromISR (C++ function), 1410 xTaskGetHandle (C++ function), 1409 xTaskGetIdleTaskHandle (C++ function), 1411 xTaskGetTickCount (C++ function), 1409 xTaskGetTickCountFromISR (C++ function), 1409 xTaskNotify (C macro), 1423 xTaskNotifyAndQuery (C macro), 1423 xTaskNotifyAndQueryFromISR (C macro), 1424 xTaskNotifyAndQueryIndexed (C macro), 1423 xTaskNotifyAndQueryIndexedFromISR (C macro), 1423 xTaskNotifyFromISR (C macro), 1423 xTaskNotifyGive (C macro), 1424 xTaskNotifyGiveIndexed (C macro), 1424 xTaskNotifyIndexed (C macro), 1423 xTaskNotifyIndexedFromISR (C macro), 1423 xTaskNotifyStateClear (C macro), 1425 xTaskNotifyStateClearIndexed (C macro), 1425 xTaskNotifyWait (C macro), 1424 xTaskNotifyWaitIndexed (C macro), 1424 xTaskResumeAll (C++ function), 1408 xTaskResumeFromISR (C++ function), 1406 xtensa_perfmon_config (C++ class), 1588 xtensa_perfmon_config::call_function (C++ member), 1589 xtensa_perfmon_config::call_params (C++ member), 1588 xtensa_perfmon_config::callback (C++ member), 1589 xtensa_perfmon_config::callback_params (C++ member), 1589 xtensa_perfmon_config::counters_size (C++ member), 1589 xtensa_perfmon_config::max_deviation (C++ member), 1588 xtensa_perfmon_config::repeat_count (C++ member), 1588 xtensa_perfmon_config::select_mask (C++ member), 1589 xtensa_perfmon_config::tracelevel (C++ member), 1589 xtensa_perfmon_config_t (C++ type), 1589 xtensa_perfmon_dump (C++ function), 1588 xtensa_perfmon_exec (C++ function), 1588 xtensa_perfmon_init (C++ function), 1587 xtensa_perfmon_overflow (C++ function), 1587 xtensa_perfmon_reset (C++ function), 1587 xtensa_perfmon_start (C++ function), 1587 xtensa_perfmon_stop (C++ function), 1587 xtensa_perfmon_value (C++ function), 1587 xtensa_perfmon_view_cb (C++ function), 1588 xTimerChangePeriod (C macro), 1465 xTimerChangePeriodFromISR (C macro), 1471 xTimerCreate (C++ function), 1456 xTimerCreateStatic (C++ function), 1458 xTimerDelete (C macro), 1467 xTimerGetExpiryTime (C++ function), 1464 xTimerGetPeriod (C++ function), 1464 xTimerGetTimerDaemonTaskHandle (C++ function), 1461 xTimerIsTimerActive (C++ function), 1461 xTimerPendFunctionCall (C++ function), 1463 xTimerPendFunctionCallFromISR (C++ func- tion), 1461 xTimerReset (C macro), 1467 xTimerResetFromISR (C macro), 1472 xTimerStart (C macro), 1464 xTimerStartFromISR (C macro), 1469 xTimerStop (C macro), 1465 xTimerStopFromISR (C macro), 1470 Espressif Systems 2240 Release v5.0-dev-2349-g4350e6fef8 Submit Document FeedbackLaTeX with hyperref xdvipdfmx (20190824)