ESP32 Dev Kitc Development Board

Información del producto

Presupuesto

Product: ESP32
Programming Guide: ESP-IDF
Release Version: v5.0.9
Fabricante: Espressif Sistemas
Fecha de lanzamiento: 16 de mayo de 2025

Instrucciones de uso del producto

1. Comience ahora

Before starting with the ESP32, familiarize yourself with the
siguiente:

1.1 Introducción

Learn about the basic functionalities and capabilities of the
ESP32.

1.2 Lo que necesitas

Ensure you have the necessary hardware and software:

Hardware: Check the list of required hardware
Componentes.
Software: Install the required software
Componentes.

1.3 Instalación

Follow these steps to install the IDE and set up the
ambiente:

IDE: Install the recommended IDE for
programming the ESP32.
Instalación manual: Manually set up the
environment if needed.

1.4 Build Your First Project

Create and build your initial project using the ESP32.

1.5 Uninstall ESP-IDF

If needed, learn how to uninstall the ESP-IDF from your
sistema.

2. Referencia de API

Refer to the API documentation for detailed information on
application protocols, error handling, and configuration
estructuras.

Preguntas frecuentes (FAQ)

Q: How can I troubleshoot common issues with ESP32?

A: Refer to the troubleshooting section in the programming guide
o visite el fabricante webSitio para recursos de soporte.

Q: Can I use ESP-IDF with other microcontrollers?

A: ESP-IDF is specifically designed for ESP32, but you may find
compatibility with other Espressif microcontrollers.

View Fullscreen

ESP32
Guía de programación ESP-IDF
Release v5.0.9 Espressif Systems May 16, 2025

Tabla de contenido

1 Empiece

1.1 Introducción . ...

1.2 What You Need . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2.1 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2.2 Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.3.1 IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.3.2 Manual Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.4 Build Your First Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

1.5 Uninstall ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

2 API Reference

2.1 API Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

2.1.1 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

2.1.2 Configuration structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

2.1.3 Private APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

2.1.4 Components in example projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

2.1.5 API Stability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

2.2 Application Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

2.2.1 ASIO port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

2.2.2 ESP-Modbus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

2.2.3 ESP-MQTT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

2.2.4 ESP-TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

2.2.5 ESP HTTP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

2.2.6 ESP Local Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

2.2.7 ESP Serial Slave Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

2.2.8 ESP x509 Certificate Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

2.2.9 HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

2.2.10 HTTPS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

2.2.11 ICMP Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

2.2.12 mDNS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

2.2.13 Mbed TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

2.2.14 IP Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

2.3 Bluetooth API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

2.3.1 Bluetooth® Common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

2.3.2 Bluetooth® Low Energy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

2.3.3 Bluetooth® Classic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

2.3.4 Controller & HCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

2.3.5 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

2.3.6 NimBLE-based host APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767

2.4 Error Codes Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769

2.5 Networking APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776

2.5.1 Wi-Fi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776

2.5.2 Ethernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899

2.5.3 Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936

2.5.4 ESP-NETIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942 2.5.5 IP Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974 2.5.6 Application Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976 2.6 Peripherals API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977 2.6.1 Analog to Digital Converter (ADC) Oneshot Mode Driver . . . . . . . . . . . . . . . . . 977 2.6.2 Analog to Digital Converter (ADC) Continuous Mode Driver . . . . . . . . . . . . . . . 986 2.6.3 Analog to Digital Converter (ADC) Calibration Driver . . . . . . . . . . . . . . . . . . . 993 2.6.4 Clock Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997 2.6.5 Digital To Analog Converter (DAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004 2.6.6 GPIO & RTC GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008 2.6.7 General Purpose Timer (GPTimer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027 2.6.8 Inter-Integrated Circuit (I2C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039 2.6.9 Inter-IC Sound (I2S) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056 2.6.10 LCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090 2.6.11 LED Control (LEDC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107 2.6.12 Motor Control Pulse Width Modulator (MCPWM) . . . . . . . . . . . . . . . . . . . . . 1126 2.6.13 Pulse Counter (PCNT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178 2.6.14 Remote Control Transceiver (RMT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193 2.6.15 SD Pull-up Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220 2.6.16 SDMMC Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223 2.6.17 SD SPI Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229 2.6.18 SDIO Card Slave Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234 2.6.19 Sigma-Delta Modulation (SDM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1244 2.6.20 SPI Master Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249 2.6.21 SPI Slave Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274 2.6.22 ESP32-WROOM-32SE (Secure Element) . . . . . . . . . . . . . . . . . . . . . . . . . 1281 2.6.23 Touch Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1282 2.6.24 Two-Wire Automotive Interface (TWAI) . . . . . . . . . . . . . . . . . . . . . . . . . . 1299 2.6.25 Universal Asynchronous Receiver/Transmitter (UART) . . . . . . . . . . . . . . . . . . 1317 2.7 Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 2.7.1 Introducción . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 2.7.2 Project Configuration Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 2.7.3 Using sdkconfig.defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 2.7.4 Kconfig Formatting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343 2.7.5 Backward Compatibility of Kconfig Options . . . . . . . . . . . . . . . . . . . . . . . . 1343 2.7.6 Configuration Options Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343 2.8 Provisioning API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647 2.8.1 Protocol Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647 2.8.2 Unified Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665 2.8.3 Wi-Fi Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669 2.9 Storage API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filesystem Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1691 2.9.2 Manufacturing Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699 2.9.3 Non-volatile Storage Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703 2.9.4 NVS Partition Generator Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725 2.9.5 SD/SDIO/MMC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730 2.9.6 SPI Flash API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744 2.9.7 SPIFFS Filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1780 2.9.8 Virtual filesystem component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784 2.9.9 Wear Levelling API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800 2.10 System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1803 2.10.1 App Image Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1803 2.10.2 Application Level Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808 2.10.3 Call function with external stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813 2.10.4 Chip Revision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815 2.10.5 Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817 2.10.6 eFuse Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1826 2.10.7 Error Codes and Helper Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846
ii

2.10.8 ESP HTTPS OTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1849 2.10.9 Event Loop Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856 2.10.10 FreeRTOS (Overview) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869 2.10.11 FreeRTOS (ESP-IDF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871 2.10.12 FreeRTOS (Supplemental Features) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1988 2.10.13 Heap Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2008 2.10.14 Heap Memory Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021 2.10.15 High Resolution Timer (ESP Timer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032 2.10.16 Internal and Unstable APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2038 2.10.17 Inter-Processor Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2040 2.10.18 Interrupt allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2045 2.10.19 Logging library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2051 2.10.20 Miscellaneous System APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2058 2.10.21 Over The Air Updates (OTA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2073 2.10.22 Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2084 2.10.23 Power Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087 2.10.24 POSIX Threads Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093 2.10.25 Random Number Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097 2.10.26 Sleep Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2099 2.10.27 SoC Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111 2.10.28 System Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2121 2.10.29 The himem allocation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126 2.10.30 ULP Coprocessor programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129 2.10.31 Watchdogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2161

3 Referencia de hardware

2167

3.1 Chip Series Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2167

3.1.1 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2170

4 API Guides

2171

4.1 Application Level Tracing library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171

4.1.1 Másview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171

4.1.2 Modes of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171

4.1.3 Configuration Options and Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . 2172

4.1.4 How to Use This Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2173

4.2 Application Startup Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2181

4.2.1 Primerostage bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2182

4.2.2 segundostage bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2182

4.2.3 Application startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2183

4.3 Bluetooth® Classic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2184

4.3.1 Másview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2184

4.4 Bluetooth® Low Energy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186

4.4.1 Másview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186

4.4.2 Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2191

4.4.3 Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2240

4.5 Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2284

4.5.1 Bootloader compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285

4.5.2 Log Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285

4.5.3 Factory reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2286

4.5.4 Boot from Test Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2286

4.5.5 Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287

4.5.6 Watchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287

4.5.7 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287

4.5.8 Fast boot from Deep Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287

4.5.9 Custom bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287

4.6 Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288

4.6.1 Másview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288

4.6.2 Using the Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2289

iii

4.6.3 Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291 4.6.4 Project CMakeLists File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291 4.6.5 Component CMakeLists Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2293 4.6.6 Component Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2295 4.6.7 Preprocessor Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2295 4.6.8 Component Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2295 4.6.9 Overriding Parts of the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2299 4.6.10 Configuration-Only Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2300 4.6.11 Debugging CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2300 4.6.12 Example Component CMakeLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301 4.6.13 Custom sdkconfig defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305 4.6.14 Flash arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305 4.6.15 Building the Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306 4.6.16 Writing Pure CMake Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306 4.6.17 Using Third-Party CMake Projects with Components . . . . . . . . . . . . . . . . . . . 2306 4.6.18 Using Prebuilt Libraries with Components . . . . . . . . . . . . . . . . . . . . . . . . . 2307 4.6.19 Using ESP-IDF in Custom CMake Projects . . . . . . . . . . . . . . . . . . . . . . . . . 2307 4.6.20 ESP-IDF CMake Build System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308 4.6.21 File Globbing & Incremental Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312 4.6.22 Build System Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313 4.6.23 Build System Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313 4.6.24 Migrating from ESP-IDF GNU Make System . . . . . . . . . . . . . . . . . . . . . . . 2315 4.7 Core Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2316 4.7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2316 4.7.2 Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317 4.7.3 Save core dump to flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317 4.7.4 Print core dump to UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318 4.7.5 ROM Functions in Backtraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318 4.7.6 Dumping variables on demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318 4.7.7 Running espcoredump.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2319 4.8 Deep Sleep Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2322 4.8.1 Rules for Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2322 4.8.2 Implementing A Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2322 4.8.3 Loading Code Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2322 4.8.4 Loading Data Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2323 4.8.5 CRC Check For Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2323 4.8.6 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2323 4.9 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2324 4.9.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2324 4.9.2 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2324 4.9.3 Converting error codes to error messages . . . . . . . . . . . . . . . . . . . . . . . . . . 2324 4.9.4 ESP_ERROR_CHECK macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2325 4.9.5 ESP_ERROR_CHECK_WITHOUT_ABORT macro . . . . . . . . . . . . . . . . . . . . . 2325 4.9.6 ESP_RETURN_ON_ERROR macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2325 4.9.7 ESP_GOTO_ON_ERROR macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2325 4.9.8 ESP_RETURN_ON_FALSE macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2325 4.9.9 ESP_GOTO_ON_FALSE macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2325 4.9.10 CHECK MACROS Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2326 4.9.11 Error handling patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2326 4.9.12 C++ Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2327 4.10 ESP-WIFI-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2327 4.10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2327 4.10.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2328 4.10.3 ESP-WIFI-MESH Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2329 4.10.4 Building a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2334 4.10.5 Managing a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2339 4.10.6 Data Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2342 4.10.7 Channel Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2344
iv

4.10.8 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2347 4.10.9 Further Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2348 4.11 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2348 4.11.1 Wi-Fi, Ethernet, and IP Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2348 4.11.2 Mesh Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2349 4.11.3 Bluetooth Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2350 4.12 Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2350 4.12.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2350 4.12.2 Panic Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2350 4.12.3 Register Dump and Backtrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2351 4.12.4 GDB Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2353 4.12.5 RTC Watchdog Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2354 4.12.6 Guru Meditation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2354 4.12.7 Other Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2356 4.13 Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2358 4.13.1 Introducción . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359 4.13.2 Relevant eFuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359 4.13.3 Flash Encryption Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2360 4.13.4 Flash Encryption Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2360 4.13.5 Possible Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2366 4.13.6 ESP32 Flash Encryption Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2368 4.13.7 Reading and Writing Data in Encrypted Flash . . . . . . . . . . . . . . . . . . . . . . . 2368 4.13.8 Updating Encrypted Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2369 4.13.9 Disabling Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2369 4.13.10 Key Points About Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2370 4.13.11 Limitations of Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2370 4.13.12 Flash Encryption and Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2371 4.13.13 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2371 4.13.14 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2373 4.14 Hardware Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2373 4.14.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2374 4.14.2 LL (Low Level) Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2375 4.14.3 HAL (Hardware Abstraction Layer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2376 4.15 High-Level Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2377 4.15.1 Interrupt Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2377 4.15.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TAG Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2378 4.16.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2378 4.16.2 How it Works? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2379 4.16.3 Selecting JTAG Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2380 4.16.4 Setup of OpenOCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2380 4.16.5 Configuring ESP32 Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2380 4.16.6 Launching Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2386 4.16.7 Debugging Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2386 4.16.8 Building OpenOCD from Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2386 4.16.9 Tips and Quirks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2391 4.16.10 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2396 4.17 Linker Script Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2421 4.17.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2421 4.17.2 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2421 4.17.3 Linker Script Generation Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2424 4.18 lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2430 4.18.1 Supported APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2430 4.18.2 BSD Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2431 4.18.3 Netconn API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2435 4.18.4 lwIP FreeRTOS Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2435 4.18.5 IPv6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2435 4.18.6 esp-lwip custom modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2436
v

4.18.7 Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2438 4.19 Memory Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2439
4.19.1 DRAM (Data RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2439 4.19.2 IRAM (Instruction RAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2440 4.19.3 IROM (code executed from flash) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2441 4.19.4 DROM (data stored in flash) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2441 4.19.5 RTC Slow memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2441 4.19.6 RTC FAST memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2441 4.19.7 DMA Capable Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2441 4.19.8 DMA Buffer in the stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2442 4.20 OpenThread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2442 4.20.1 Modes of the OpenThread stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2443 4.20.2 How to Write an OpenThread Application . . . . . . . . . . . . . . . . . . . . . . . . . 2443 4.20.3 The OpenThread Border Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2444 4.21 Partition Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2444 4.21.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2445 4.21.2 Built-in Partition Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2445 4.21.3 Creating Custom Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2445 4.21.4 Generating Binary Partition Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2448 4.21.5 Partition Size Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2448 4.21.6 Flashing the partition table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2449 4.21.7 Partition Tool (parttool.py) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2449 4.22 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2450 4.22.1 How to Optimize Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2450 4.22.2 Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2451 4.23 RF calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2468 4.23.1 Partial calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2468 4.23.2 Full calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2469 4.23.3 No calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2469 4.23.4 PHY initialization data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2469 4.23.5 API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2469 4.24 Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2472 4.24.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2472 4.24.2 Secure Boot Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2473 4.24.3 Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2473 4.24.4 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2474 4.24.5 How To Enable Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2474 4.24.6 Re-Flashable Software Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2475 4.24.7 Generating Secure Boot Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2475 4.24.8 Remote Signing of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2475 4.24.9 Secure Boot Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2476 4.24.10 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2476 4.24.11 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2477 4.24.12 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 2478 4.24.13 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2478 4.25 Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2478 4.25.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2479 4.25.2 Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2479 4.25.3 Secure Boot V2 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2479 4.25.4 Signature Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2480 4.25.5 Secure Padding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2480 4.25.6 Verifying a Signature Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481 4.25.7 Verifying an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481 4.25.8 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481 4.25.9 eFuse usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481 4.25.10 How To Enable Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481 4.25.11 Restrictions after Secure Boot is enabled . . . . . . . . . . . . . . . . . . . . . . . . . . 2482 4.25.12 Generating Secure Boot Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2482
vi

4.25.13 Remote Signing of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2483 4.25.14 Secure Boot Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2484 4.25.15 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2484 4.25.16 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2484 4.25.17 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 2484 4.25.18 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2485 4.26 Support for External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2485 4.26.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2485 4.26.2 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2485 4.26.3 Configuring External RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2486 4.26.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2487 4.26.5 Failure to initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2488 4.26.6 Chip Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2488 4.27 Thread Local Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2488 4.27.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2488 4.27.2 FreeRTOS Native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2489 4.27.3 Pthread API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2489 4.27.4 C11 Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2489 4.28 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2489 4.28.1 IDF Frontend – idf.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2489 4.28.2 IDF Docker Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2493 4.28.3 IDF Windows Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2495 4.28.4 IDF Component Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2496 4.28.5 IDF Clang Tidy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2497 4.28.6 Downloadable Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2498 4.29 Unit Testing in ESP32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2512 4.29.1 Normal Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2512 4.29.2 Multi-device Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2513 4.29.3 Multi-stage Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2514 4.29.4 Tests For Different Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2514 4.29.5 Building Unit Test App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2515 4.29.6 Running Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2515 4.29.7 Timing Code with Cache Compensated Timer . . . . . . . . . . . . . . . . . . . . . . . 2516 4.29.8 Mocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2517 4.30 Unit Testing on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2519 4.30.1 Embedded Software Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2519 4.30.2 IDF Unit Tests on Linux Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2520 4.31 Wi-Fi Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521 4.31.1 ESP32 Wi-Fi Feature List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521 4.31.2 How To Write a Wi-Fi Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521 4.31.3 ESP32 Wi-Fi API Error Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2522 4.31.4 ESP32 Wi-Fi API Parameter Initialization . . . . . . . . . . . . . . . . . . . . . . . . . 2522 4.31.5 ESP32 Wi-Fi Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2522 4.31.6 ESP32 Wi-Fi Event Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2523 4.31.7 ESP32 Wi-Fi Station General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 2526 4.31.8 ESP32 Wi-Fi AP General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2529 4.31.9 ESP32 Wi-Fi Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2529 4.31.10 ESP32 Wi-Fi Station Connecting Scenario . . . . . . . . . . . . . . . . . . . . . . . . . 2536 4.31.11 ESP32 Wi-Fi Station Connecting When Multiple APs Are Found . . . . . . . . . . . . . 2543 4.31.12 Wi-Fi Reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543 4.31.13 Wi-Fi Beacon Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543 4.31.14 ESP32 Wi-Fi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543 4.31.15 Wi-Fi Easy ConnectTM (DPP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549 4.31.16 Wireless Network Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549 4.31.17 Radio Resource Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549 4.31.18 Fast BSS Transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2550 4.31.19 ESP32 Wi-Fi Power-saving Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2550 4.31.20 ESP32 Wi-Fi Throughput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
viii

4.31.21 Wi-Fi 80211 Packet Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2552 4.31.22 Wi-Fi Sniffer Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2554 4.31.23 Wi-Fi Multiple Antennas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2554 4.31.24 Wi-Fi Channel State Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2556 4.31.25 Wi-Fi Channel State Information Configure . . . . . . . . . . . . . . . . . . . . . . . . . 2557 4.31.26 Wi-Fi HT20/40 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2557 4.31.27 Wi-Fi QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2557 4.31.28 Wi-Fi AMSDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2558 4.31.29 Wi-Fi Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2558 4.31.30 WPS Enrollee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2558 4.31.31 Wi-Fi Buffer Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2558 4.31.32 How to Improve Wi-Fi Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2559 4.31.33 Wi-Fi Menuconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2562 4.31.34 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2565 4.32 Wi-Fi Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2568 4.32.1 ESP32 Wi-Fi Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2568 4.32.2 Protected Management Frames (PMF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 2571 4.32.3 WiFi Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2572 4.32.4 WPA3-Personal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2572 4.32.5 Wi-Fi Enhanced OpenTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2573 4.33 RF Coexistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2573 4.33.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2574 4.33.2 Supported Coexistence Scenario for ESP32 . . . . . . . . . . . . . . . . . . . . . . . . . 2574 4.33.3 Coexistence Mechanism and Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2574 4.33.4 How to Use the Coexistence Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2576 4.34 Reproducible Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2577 4.34.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2577 4.34.2 Reasons for non-reproducible builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2577 4.34.3 Enabling reproducible builds in ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . 2577 4.34.4 How reproducible builds are achieved . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2578 4.34.5 Reproducible builds and debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2578 4.34.6 Factors which still affect reproducible builds . . . . . . . . . . . . . . . . . . . . . . . . 2578 4.35 Low Power Mode User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2578

5 Migration Guides

2579

5.1 ESP-IDF 5.x Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2579

5.1.1 Migration from 4.4 to 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2579

6 Libraries and Frameworks

2611

6.1 Cloud Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611

6.1.1 ESP RainMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611

6.1.2 AWS IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611

6.1.3 Azure IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611

6.1.4 Google IoT Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611

6.1.5 Aliyun IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611

6.1.6 Joylink IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611

6.1.7 Tencent IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2612

6.1.8 Tencentyun IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2612

6.1.9 Baidu IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2612

6.2 Espressifns Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2612

6.2.1 Espressif Audio Development Framework . . . . . . . . . . . . . . . . . . . . . . . . . 2612

6.2.2 ESP-CSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2612

6.2.3 Espressif DSP Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2612

6.2.4 ESP-WIFI-MESH Development Framework . . . . . . . . . . . . . . . . . . . . . . . . 2613

6.2.5 ESP-WHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2613

6.2.6 ESP RainMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2613

6.2.7 ESP-IoT-Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2613

6.2.8 ESP-Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2613

viii

6.2.9 ESP-BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2614

7 Contributions Guide

2615

7.1 How to Contribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2615

7.2 Before Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2615

7.3 Pull Request Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2615

7.4 Legal Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2616

7.5 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2616

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

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

7.5.3 Documenting Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2624

7.5.4 Creating Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2629

7.5.5 API Documentation Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2630

7.5.6 Contributor Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2632

7.5.7 Copyright Header Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2634

7.5.8 ESP-IDF Tests with Pytest Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2635

8 Versiones ESP-IDF

2645

8.1 Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2645

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

8.3 Versioning Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2645

8.4 Support Periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2646

8.5 Checking the Current Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2647

8.6 Git Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2648

8.7 Updating ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2648

8.7.1 Updating to Stable Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2649

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

8.7.3 Updating to Master Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2649

8.7.4 Updating to a Release Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2650

9 Recursos

2651

9.1 PlatformIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2651

9.1.1 What is PlatformIO? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2651

9.1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2651

9.1.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2652

9.1.4 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2652

9.1.5 Project Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2652

9.1.6 Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2652

9.2 Useful Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2652

10 Copyrights and Licenses

2653

10.1 Software Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2653

10.1.1 Firmware Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2653

10.1.2 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2654

10.2 ROM Source Code Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2654

10.3 Xtensa libhal MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2655

10.4 TinyBasic Plus MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2655

10.5 TJpgDec License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2655

11 Acerca de

2657

12 Switch Between Languages

2659

Índice

2661

Índice

2661

Tabla de contenido
This is the documentation for Espressif IoT Development Framework (esp-idf). ESP-IDF is the official development framework for the ESP32, ESP32-S and ESP32-C Series SoCs. This document describes using ESP-IDF with the ESP32 SoC.

Empezar

Referencia API

API Guides

Sistemas Espressif

1 Submit Document Feedback

Versión v5.0.9

Tabla de contenido

Sistemas Espressif

2 Submit Document Feedback

Versión v5.0.9

Capítulo 1
Empezar
This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif. After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then for building and flashing firmware onto an ESP32 board.
Note: This is documentation for stable version v5.0.9 of ESP-IDF. Other ESP-IDF Versions are also available.
1.1 Introducción
ESP32 is a system on a chip that integrates the following features: · Wi-Fi (2.4 GHz band) · Bluetooth · Dual high performance Xtensa® 32-bit LX6 CPU cores · Ultra Low Power co-processor · Multiple peripherals
Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internetof-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features.
1.2 Lo que necesitas
1.2.1 Hardware
· An ESP32 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!
If you have one of ESP32 official development boards listed below, you can click on the link to learn more about the hardware.
3

Chapter 1. Get Started
ESP32-DevKitS(-R)
This user guide provides information on ESP32-DevKitS(-R), an ESP32-based flashing board produced by Espressif. ESP32-DevKitS(-R) is a combination of two board names: ESP32-DevKitS and ESP32-DevKitS-R. S stands for springs, and R stands for WROVER.

ESP32-DevKitS

ESP32-DevKitS-R

The document consists of the following major sections: · Getting Started: Provides an overview of ESP32-DevKitS(-R) and hardware/software setup instructions to get started. · Hardware Reference: Provides more detailed information about ESP32-DevKitS(-R)ns hardware. · Related Documents: Gives links to related documentation.

Getting Started This section describes how to get started with ESP32-DevKitS(-R). It begins with a few introductory sections about ESP32-DevKitS(-R), then Section How to Flash a Board provides instructions on how to mount a module onto ESP32-DevKitS(-R), get it ready, and flash firmware onto it.

Encimaview ESP32-DevKitS(-R) is Espressifns flashing board designed specifically for ESP32. It can be used to flash an ESP32 module without soldering the module to the power supply and signal lines. With a module mounted, ESP32-DevKitS(-R) can also be used as a mini development board like ESP32-DevKitC.
ESP32-DevKitS and ESP32-DevKitS-R boards vary only in layout of spring pins to fit the following ESP32 modules.
· ESP32-DevKitS: ESP32-WROOM-32 ESP32-WROOM-32D ESP32-WROOM-32U ESP32-SOLO-1 ESP32-WROOM-32E ESP32-WROOM-32UE
· ESP32-DevKitS-R: ESP32-WROVER (PCB & IPEX) ESP32-WROVER-B (PCB & IPEX) ESP32-WROVER-E ESP32-WROVER-IE
For information about above modules, please refer to ESP32 Series Modules.

Descripción de componentes

Sistemas Espressif

4 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Fig. 1: ESP32-DevKitS – front

Sistemas Espressif

Fig. 2: ESP32-DevKitS-R – front 5
Enviar comentarios sobre el documento

Versión v5.0.9

Chapter 1. Get Started

Key Component Spring Pins 2.54 mm Female Headers
USB-to-UART Bridge LDO Micro-USB Connector/Micro USB Port EN Button Boot Button
LED de encendido

Description Click the module in. The pins will fit into the modulens castellated holes. These female headers are connected to pins of the module mounted on this board. For description of female headers, please refer to Header Blocks. Single-chip USB to UART bridge provides transfer rates of up to 3 Mbps.
5V-to-3.3V low-dropout voltage regulator (LDO).
USB interface. Power supply for the board as well as the communication interface between a computer and the board.
Botón de reinicio.
Download button. Holding down Boot and then pressing EN initiates Firmware Download mode for downloading firmware through the serial port.
Turns on when the USB or power supply is connected to the board.

How to Flash a Board Before powering up your ESP32-DevKitS(-R), please make sure that it is in good condition with no obvious signs of damage.
Required Hardware · An ESP32 module of your choice · USB 2.0 cable (Standard-A to Micro-B) · Computer running Windows, Linux, or macOS
Hardware Setup Please mount a module of your choice onto your ESP32-DevKitS(-R) according to the following steps:
· Gently put your module on the ESP32-DevKitS(-R) board. Make sure that castellated holes on your module are aligned with spring pins on the board.
· Press your module down into the board until it clicks. · Check whether all spring pins are inserted into castellated holes. If there are some misaligned spring pins,
place them into castellated holes with tweezers.
Configuración de software
Preferred Method The ESP-IDF development framework provides a preferred way of flashing binaries onto ESP32-DevKitS(-R). Please proceed to Get Started, where Section Installation will quickly help you set up the development environment and then flash an application example onto your ESP32-DevKitS(-R).
Alternative Method As an alternative, Windows users can flash binaries using the Flash Download Tool. Just download it, unzip it, and follow the instructions inside the doc folder.
Note: 1. To flash binary files, ESP32 should be set to Firmware Download mode. This can be done either by the flash tool automatically, or by holding down the Boot button and tapping the EN button. 2. After flashing binary files, the Flash Download Tool restarts your ESP32 module and boots the flashed application by default.

Board Dimensions Contents and Packaging

Sistemas Espressif

6 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started Fig. 3: ESP32-DevKitS board dimensions – back

Sistemas Espressif

Fig. 4: ESP32-DevKitS-R board dimensions – back 7
Enviar comentarios sobre el documento

Versión v5.0.9

Chapter 1. Get Started
Retail orders If you order a few samples, each ESP32-DevKitS(-R) comes in an individual package in either antistatic bag or any packaging depending on a retailer. For retail orders, please go to https://www.espressif.com/en/contact-us/get-sampLes.
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.
Referencia de hardware
Block Diagram A block diagram below shows the components of ESP32-DevKitS(-R) and their interconnections.

Fig. 5: ESP32-DevKitS(-R) (click to enlarge)
Power Supply Options There are three mutually exclusive ways to provide power to the board: · Micro USB port, default power supply · 5V and GND header pins · 3V3 and GND header pins
It is advised to use the first option: micro USB port.

Sistemas Espressif

Label Signal

L1 3V3 VDD 3V3

L2 EN CHIP_PU

L3 VP SENSOR_VP

L4 VN SENSOR_VN

Nivel 5 34

GPIO34

Nivel 6 35

GPIO35

Nivel 7 32

GPIO32

Nivel 8 33

GPIO33

continues on next page

8 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Tabla 1 continuación de la página anterior

Label Signal

Nivel 9 25

GPIO25

Nivel 10 26

GPIO26

Nivel 11 27

GPIO27

Nivel 12 14

GPIO14

Nivel 13 12

GPIO12

L14 GND GND

Nivel 15 13

GPIO13

L16 D2 SD_DATA2

L17 D3 SD_DATA3

L18 CMD SD_CMD

L19 5V

5V externo

R1 GND GND

R2 23

GPIO23

R3 22

GPIO22

R4 TX U0TXD

R5 RX U0RXD

R6 21

GPIO21

R7 GND GND

R8 19

GPIO19

R9 18

GPIO18

R10 5

GPIO5

R11 17

GPIO17

R12 16

GPIO16

R13 4

GPIO4

R14 0

GPIO0

R15 2

GPIO2

R16 15

GPIO15

R17 D1 SD_DATA1

R18 D0 SD_DATA0

R19 CLK SD_CLK

Header Blocks For the image of header blocks, please refer to Description of Components.

Documentos relacionados
· ESP32-DevKitS(-R) Schematics (PDF) · ESP32 Datasheet (PDF) · ESP32-WROOM-32 Datasheet (PDF) · ESP32-WROOM-32D & ESP32-WROOM-32U Datasheet (PDF) · ESP32-SOLO-1 Datasheet (PDF) · ESP32-WROVER Datasheet (PDF) · ESP32-WROVER-B Datasheet (PDF) · ESP Product Selector

ESP32-DevKitM-1

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

Sistemas Espressif

9 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

ESP32-DevKitM-1 – frontal

ESP32-DevKitM-1 – isometric

The document consists of the following major sections: · Getting started: Provides an overview of the ESP32-DevKitM-1 and hardware/software setup instructions to get started. · Hardware reference: Provides more detailed information about the ESP32-DevKitM-1ns hardware. · Related Documents: Gives links to related documentaiton.

Getting Started This section describes how to get started with ESP32-DevKitM-1. It begins with a few introductory sections about the ESP32-DevKitM-1, then Section Start Application Development provides instructions on how to do the initial hardware setup and then how to flash firmware onto the ESP32-DevKitM-1.

Encimaview Esta es una placa de desarrollo pequeña y conveniente que incluye:
· ESP32-MINI-1, or ESP32-MINI-1U module · USB-to-serial programming interface that also provides power supply for the board · pin headers · pushbuttons for reset and activation of Firmware Download mode · a few other components

Contenido y embalaje

Retail orders If you order a few samples, each ESP32-DevKitM-1 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/contact-us/get-sampLes.

Wholesale Orders If you order in bulk, the boards come in large cardboard boxes. For wholesale orders, please go to https://www.espressif.com/en/contact-us/sales-questions.

Description of Components The following figure and the table below describe the key components, interfaces and controls of the ESP32-DevKitM-1 board. We take the board with a ESP32-MINI-1 module as an example en las siguientes secciones.

Sistemas Espressif

10 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Fig. 6: ESP32-DevKitM-1 – front

Key Component On-board module
5 V to 3.3 V LDO Boot Button
Reset Button Micro-USB Port
USB-to-UART Bridge 3.3 V Power On LED
Conector de E/S

Descripción
ESP32-MINI-1 module or ESP32-MINI-1U module. ESP32-MINI-1 comes with an on-board PCB antenna. ESP32-MINI-1U comes with an external antenna connector. The two modules both have a 4 MB flash in chip package. For details, please see ESP32-MINI-1 & ESP32-MINI-1U Datasheet.
El regulador de potencia convierte 5 V a 3.3 V.
Download button. Holding down Boot and then pressing Reset initiates Firmware Download mode for downloading firmware through the serial port.
Botón de reinicio
Interfaz USB. Fuente de alimentación para la placa así como interfaz de comunicación entre una computadora y el chip ESP32.
El chip puente USB-UART único proporciona velocidades de transferencia de hasta 3 Mbps.
Turns on when the USB is connected to the board. For details, please see the schematics in Related Documents. All available GPIO pins (except for the SPI bus for flash) are broken out to the pin headers on the board. Users can program ESP32 chip to enable multiple functions.

Start Application Development Before powering up your ESP32-DevKitM-1, please make sure that it is in good condition with no obvious signs of damage.
Required Hardware · ESP32-DevKitM-1 · USB 2.0 cable (Standard-A to Micro-B) · Computer running Windows, Linux, or macOS
Software Setup Please proceed to Get Started, where Section Installation will quickly help you set up the development environment and then flash an application examparchivo en su ESP32-DevKitM-1.

Sistemas Espressif

11 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
Attention: ESP32-DevKitM-1 boards manufactured before December 2, 2021 have a single core module installed. To verify what module you have, please check module marking information in PCN-2021-021 . If your board has a single core module installed, please enable single core mode (CONFIG_FREERTOS_UNICORE) in menuconfig before flashing your applications.
Hardware Reference Block Diagram A block diagram below shows the components of ESP32-DevKitM-1 and their interconnections.

Fig. 7: ESP32-DevKitM-1
Power Source Select There are three mutually exclusive ways to provide power to the board: · Micro USB port, default power supply · 5V and GND header pins · 3V3 and GND header pins
Warning: · The power supply must be provided using one and only one of the options above, otherwise the board and/or the power supply source can be damaged. · Power supply by micro USB port is recommended.

Pin Descriptions The table below provides the Name and Function of pins on both sides of the board. For peripheral pin configurations, please refer to ESP32 Datasheet.

No.

Nombre

Tipo

Tierra

3V3

Function Ground 3.3 V power supply

continues on next page

Sistemas Espressif

12 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Tabla 2 continuación de la página anterior

No.

Nombre

Tipo

Función

I36

GPIO36... ADC1_CH0... RTC_GPIO0

I37

GPIO37... ADC1_CH1... RTC_GPIO1

I38

GPIO38... ADC1_CH2... RTC_GPIO2

I39

GPIO39... ADC1_CH3... RTC_GPIO3

Primera vez

Reiniciar; Alto: habilitar; Bajo: se apaga

I34

GPIO34... ADC1_CH6... RTC_GPIO4

I35

GPIO35... ADC1_CH7... RTC_GPIO5

IO32

E/S

GPIO32, XTAL_32K_P (32.768 kHz crystal oscillator input),

ADC1_CH4, TOQUE9, RTC_GPIO9

IO33

E/S

GPIO33, XTAL_32K_N (salida de oscilador de cristal de 32.768 kHz),

ADC1_CH5, TOQUE8, RTC_GPIO8

IO25

E/S

GPIO25... DAC_1... ADC2_CH8... RTC_GPIO6... EMAC_RXD0

IO26

E/S

GPIO26... DAC_2... ADC2_CH9... RTC_GPIO7... EMAC_RXD1

IO27

E/S

GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17, EMAC_RX_DV

IO14

E/S

GPIO14, ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK,

HS2_CLK, SD_CLK, EMAC_TXD2

Fuente de alimentación de 5 V

IO12

E/S

GPIO12, ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI, HSPIQ,

HS2_DATA2, SD_DATA2, EMAC_TXD3

IO13

E/S

GPIO13, ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID,

HS2_DATA3, SD_DATA3, EMAC_RX_ER

IO15

E/S

GPIO15, ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO, HSPICS0,

HS2_CMD, SD_CMD, EMAC_RXD3

IO2

E/S

GPIO2, ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP,

HS2_DATA0, SD_DATA0

IO0

E/S

GPIO0, ADC2_CH1, TOQUE1, RTC_GPIO11, CLK_OUT1,

EMAC_TX_CLK

IO4

E/S

GPIO4, ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD,

HS2_DATA1, SD_DATA1, EMAC_TX_ER

IO9

E/S

GPIO9, HS1_DATA2, U1RXD, SD_DATA2

IO10

E/S

GPIO10, HS1_DATA3, U1TXD, SD_DATA3

IO5

E/S

GPIO5, HS1_DATA6, VSPICS0, EMAC_RX_CLK

IO18

E/S

GPIO18, HS1_DATA7, VSPICLK

IO23

E/S

GPIO23, HS1_STROBE, VSPID

IO19

E/S

GPIO19... VSPIQ... U0CTS... EMAC_TXD0

IO22

E/S

GPIO22... VSPIWP... U0RTS EMAC_TXD1

IO21

E/S

GPIO21, VSPIHD, EMAC_TX_ES

TXD0

E/S

GPIO1, U0TXD, CLK_OUT3, EMAC_RXD2

RXD0

E/S

GPIO3, U0RXD, CLK_OUT2

Hardware Revision Details No previous versions available.
Documentos relacionados
· ESP32-MINI-1 & ESP32-MINI-1U Datasheet (PDF) · ESP32-DevKitM-1 Schematics (PDF) · ESP32-DevKitM-1 PCB layout (PDF) · ESP32-DevKitM-1 layout (DXF) – You can view it with Autodesk Viewer online · ESP32 Datasheet (PDF) · ESP Product Selector
For other design documentation for the board, please contact us at sales@espressif.com.

Sistemas Espressif

13 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
Software 1.2.2
To start using ESP-IDF on ESP32, install the following software: · Toolchain to compile code for ESP32 · Build tools – CMake and Ninja to build a full Application for ESP32 · ESP-IDF that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the Toolchain

1.3 Instalación
To install all the required software, we offer some different ways to facilitate this task. Choose from one of the available options.
1.3.1 IDE

Note: We highly recommend installing the ESP-IDF through your favorite IDE.
· Eclipse Plugin · VSCode Extension

1.3.2 Instalación manual
For the manual procedure, please select according to your operating system.

Sistemas Espressif

14 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
Configuración estándar de Toolchain para 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 Plugin 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%Desktopesp-idf where %userprofile% is your home directory.

Sistemas Espressif

15 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
Launching ESP-IDF Environment At the end of the installation process you can check out option Run ESP-IDF PowerShell Environment or Run ESP-IDF Command Prompt (cmd.exe). The installer will launch ESP-IDF environment in selected prompt. Run ESP-IDF PowerShell Environment:

Fig. 8: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF PowerShell Environment
Run ESP-IDF Command Prompt (cmd.exe):
Using the Command Prompt For the remaining Getting Started steps, wenre going to use the Windows Command Prompt. ESP-IDF Tools Installer also creates a shortcut in the Start menu to launch the ESP-IDF Command Prompt. This shortcut launches the Command Prompt (cmd.exe) and runs export.bat script to set up the environment variables (PATH, IDF_PATH and others). Inside this command prompt, all the installed tools are available. 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 since all requirements are met, the next topic will guide you on how to start your first project.

Sistemas Espressif

16 Submit Document Feedback

Versión v5.0.9

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

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

Sistemas Espressif

17 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Fig. 11: ESP-IDF Command Prompt

Sistemas Espressif

18 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
This guide will help you on the first steps using ESP-IDF. Follow this guide to start a new project on the ESP32 and build, flash, and monitor the device output. Note: If you have not yet installed ESP-IDF, please go to Installation and follow the instruction in order to get all the software needed to use this guide.

Start a Project Now you are ready to prepare your application for ESP32. You can start with getstarted/hello_world project from exampdirectorio de archivos en ESP-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: cd %userprofile%esp xcopy /e /i %IDF_PATH%examplesget-startedhello_world hello_world
Note: There is a range of example proyectos en el exampdirectorio de archivos en ESP-IDF. Puede copiar cualquier proyecto de la misma manera que se presentó anteriormente y ejecutarlo. También es posible construir examples in-place without copying them first.

Connect Your Device Now connect your ESP32 board to the computer and check under which serial port the board is visible. Serial port names start with COM in Windows. If you are not sure how to check the serial port name, please refer to Establish Serial Connection with ESP32 for full details.
Nota: Tenga a mano el nombre del puerto, ya que lo necesitará en los próximos pasos.

Configure Your Project Navigate to your hello_world directory, set ESP32 as the target, and run the project configuration utility menuconfig.
Windows cd %userprofile%esphello_world idf.py set-target esp32 idf.py menuconfig
After opening a new project, you should first set the target with idf.py set-target esp32. Note that existing builds and configurations in the project, if any, will be cleared and initialized in this process. The target may be saved in the environment variable to skip this step at all. See Select the Target Chip: set-target for additional information. If the previous steps have been done correctly, the following menu appears: 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, since this example runs with default configuration.
Attention: If you use ESP32-DevKitC board with the ESP32-SOLO-1 module, or ESP32-DevKitM-1 board with the ESP32-MIN1-1(1U) module, please enable single core mode (CONFIG_FREERTOS_UNICORE) in menuconfig before flashing exampLes.

Sistemas Espressif

19 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Fig. 12: Project configuration – Home window
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.
If you are using one of the supported development boards, you can speed up your development by using Board Support Package. See Additional Tips for more information.
Build the Project Build the project by running:
compilación idf.py
Este comando compilará la aplicación y todos los componentes de ESP-IDF, luego generará el gestor de arranque, la tabla de particiones y los archivos binarios de la aplicación.
$ 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: …
… (más líneas de salida del sistema de compilación)
[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’
Si no hay errores, la compilación finalizará generando el binario de firmware .bin files.

Sistemas Espressif

20 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
Flash onto the Device Flash the binaries that you just built (bootloader.bin, partition-table.bin and hello_world.bin) onto your ESP32 board by running: idf.py -p PORT [-b BAUD] flash
Replace PORT with your ESP32 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 automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see Establish Serial Connection with ESP32). The DTR and RTS control lines are in turn connected to GPIO0 and CHIP_PU (EN) pins of ESP32, thus changes in the voltage levels of DTR and RTS will boot ESP32 into Firmware Download mode. As an example, check the schematic for the ESP32 DevKitC development board.
In general, you should have no problems with the official esp-idf development boards. However, esptool.py is not able to reset your hardware automatically in the following cases:
· Your hardware does not have the DTR and RTS lines connected to GPIO0 and CHIP_PU · The DTR and RTS lines are configured differently · There are no such serial control lines at all
Depending on the kind of hardware you have, it may also be possible to manually put your ESP32 board into Firmware Download mode (reset).
· For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an ESP-IDF development board, hold down the Boot button (GPIO0) and press the EN button (CHIP_PU).
· For other types of hardware, try pulling GPIO0 down.

Sistemas Espressif

21 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
(continued from previous page) Configuring flash size… Compressed 3072 bytes to 103… Writing at 0x00008000… (100 %) Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 5962.8 kbit/s)… Hash of data verified. Compressed 26096 bytes to 15408… Writing at 0x00001000… (100 %) Wrote 26096 bytes (15408 compressed) at 0x00001000 in 0.4 seconds (effective 546.7 kbit/s)… Hash of data verified. Compressed 147104 bytes to 77364… Writing at 0x00010000… (20 %) Writing at 0x00014000… (40 %) Writing at 0x00018000… (60 %) Writing at 0x0001c000… (80 %) Writing at 0x00020000… (100 %) Wrote 147104 bytes (77364 compressed) at 0x00010000 in 1.9 seconds (effective 615. 5 kbit/s)… Hash of data verified.
Dejando... Restablecimiento completo a través del pin RTS... Listo
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 Eclipse Plugin, VSCode Extension.
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).
Este comando inicia la aplicación IDF Monitor:
$ 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 …
Después de que los registros de inicio y diagnóstico se desplacen hacia arriba, debería ver "¡Hola mundo!" impreso por la aplicación.
… Hello world! Restarting in 10 seconds… This is esp32 chip with 2 CPU core(s), WiFi/BT/BLE, silicon revision 1, 2MB external flash Minimum free heap size: 298968 bytes Restarting in 9 seconds… Restarting in 8 seconds… Restarting in 7 seconds…
Para salir del monitor IDF use el atajo Ctrl+].

Sistemas Espressif

22 Submit Document Feedback

Versión v5.0.9

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

If you have such a problem, do the following: 1. Exit the monitor. 2. Go back to menuconfig. 3. Go to Component config > Hardware Settings > Main XTAL Config > Main XTAL frequency, then change CONFIG_XTAL_FREQ_SEL to 26 MHz. 4. After that, build and flash the application again.
In the current version of ESP-IDF, main XTAL frequencies supported by ESP32 are as follows:
· 26 MHz · 40 MHz
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! Now you are ready to try some other examples, or go straight to developing your own applications.
Important: Some of examples do not support ESP32 because required hardware is not included in ESP32 so it cannot be supported. If building an example, please check the README file for the Supported Targets table. If this is present including ESP32 target, or the table does not exist at all, the example will work on ESP32.
Consejos adicionales
Permission issues /dev/ttyUSB0 With some Linux distributions, you may get the Failed to open port /dev/ttyUSB0 error message when flashing the ESP32. This can be solved by adding the current user to the dialout group.
Python compatibility ESP-IDF supports Python 3.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.
Start with Board Support Package To speed up prototyping on some development boards, you can use Board Support Packages (BSPs), which makes initialization of a particular board as easy as few function calls.

Sistemas Espressif

23 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

A BSP typically supports all of the hardware components provided on development board. Apart from the pinout definition and initialization functions, a BSP ships with drivers for the external components such as sensors, displays, audio codecs etc. The BSPs are distributed via IDF Component Manager, so they can be found in IDF Component Registry. Herens an example of how to add ESP-WROVER-KIT BSP to your project: idf.py add-dependency esp_wrover_kit
Más examples of BSP usage can be found in BSP exampcarpeta de archivos.
Related Documents For advanced users who want to customize the install process: · Updating ESP-IDF tools on Windows · Establish Serial Connection with ESP32 · Eclipse Plugin · VSCode Extension · IDF Monitor
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:
instalar.bat
For Powershell, change to the directory where ESP-IDF is installed. Then run:
install.ps1
This will download and install the tools necessary to use ESP-IDF. If the specific version of the tool is already installed, no action will be taken. The tools are downloaded and installed into a directory specified during ESP-IDF Tools Installer process. By default, this is C:Usersusername.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 % usuarioprofile%espesp-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 This section provides guidance how to establish serial connection between ESP32 and PC.

Sistemas Espressif

24 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
Connect ESP32 to PC Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them. Below is the list of USB to serial converter chips installed on most of the ESP32 boards produced by Espressif together with links to the drivers:
· CP210x: CP210x USB to UART Bridge VCP Drivers · FTDI: FTDI Virtual COM Port Drivers Please check the board user guide for specific USB to serial converter chip used. The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with an operating system and automatically installed upon connecting the board to the PC.
Check port on Windows Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again. Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT

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

Check port on Linux and macOS To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need: Linux
ls /dev/tty*
macOS

Sistemas Espressif

25 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

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

Sistemas Espressif

26 Submit Document Feedback

Versión v5.0.9

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. See Section Connect ESP32 to PC for links to drivers. 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 marcación $USUARIO
En Arch Linux esto se hace agregando el usuario al grupo uucp con el siguiente comando:
sudo usermod -a -G uucp $USUARIO
Asegúrese de volver a iniciar sesión para habilitar los permisos de lectura y escritura para el puerto serie.
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 resetting ESP32. The default console baud rate on ESP32 is 115200.
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 programs and set communication parameters like below. Run terminal and set identified serial port. Baud rate = 115200 (if needed, change this to the default baud rate of the chip in use), data bits = 8, stop bits = 1, and parity = N. Below are example screenshots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above. Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32, see Example Output.
Note: Close the serial terminal after verification that communication is working. If you keep the terminal session open, the serial port will be inaccessible for uploading firmware later.

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 (if needed, change o115200pto the default baud rate of the chip in use):

screen /dev/cu.device_name 115200 Replace device_name with the name found running ls /dev/cu.*.

Sistemas Espressif

27 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Fig. 15: Setting Serial Communication in PuTTY on Windows

Sistemas Espressif

28 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Fig. 16: Setting Serial Communication in PuTTY on Linux

Sistemas Espressif

29 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
· What you are looking for is some log displayed by the screen. The log contents will depend on application loaded to ESP32, see Example Output. To exit the screen session type Ctrl-A + .
Note: Do not forget to exit the screen session after verifying that the communication is working. If you fail to do it and just close the terminal window, the serial port will be inaccessible for uploading firmware later.
Example Output An example log is shown below. Reset the board if you do not see anything. ets Jun 8 2016 00:22:57
rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) configsip: 0, SPIWP:0x00 clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 mode:DIO, clock div:2 load:0x3fff0008,len:8 load:0x3fff0010,len:3464 load:0x40078000,len:7828 load:0x40080000,len:252 entry 0x40080034 I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader I (45) boot: compile time 18:48:10
…
If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
Note: For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) do not have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the esptool documentation for more details.
If you got here from Step 5. First Steps on ESP-IDF when installing s/w for ESP32 development, then you can continue with Step 5. First Steps on ESP-IDF.
IDF Monitor IDF Monitor 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. IDF Monitor 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.

Sistemas Espressif

30 Submit Document Feedback

Versión v5.0.9

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

Acción

Descripción

Exit the program Menu escape key Send the menu character itself to remote
Send the exit character itself to remote
Reset target into bootloader to pause app via RTS line
Reset target board via RTS
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

impresión

Mostrar todos los atajos del teclado

Press and follow it by one of the keys given below.
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).
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 –timestamp-format command line argument.

Salir del programa

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:

Sistemas Espressif

31 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

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

unhandled.

: 0x400f360d PS

: 0x00060330 A0

: 0x800dbf56 A1

0x3ffb7e00

: 0x3ffb136c A3

: 0x00000005 A4

: 0x00000000 A5

0x00000000

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

: 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

: 0x3ffb136c A3

: 0x00000005 A4

: 0x00000000 A5

0x00000000

: 0x00000000 A7

: 0x00000080 A8

: 0x00000000 A9

0x3ffb7dd0

A10

: 0x00000003 A11

: 0x00060f23 A12

: 0x00060f20 A13

0x3ffba6d0

A14

: 0x00000047 A15

: 0x0000000f SAR

: 0x00000019 EXCCAUSE:

0x0000001d

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

0x00000000

Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90 0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/ hello_world/main/./hello_world_main.c:57 (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_ world/main/./hello_world_main.c:52 0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_ world/main/./hello_world_main.c:47 0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/ main/./hello_world_main.c:42 0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/ ./hello_world_main.c:33 0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254

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

Note: Set environment variable ESP_MONITOR_DECODE to 0 or call idf_monitor.py with specific command line

Sistemas Espressif

32 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
option: idf_monitor.py –disable-address-decoding to disable address decoding.
Target Reset on Connection By default, IDF Monitor will reset the target when connecting to it. The reset of the target chip is performed using the DTR and RTS serial lines. To prevent IDF Monitor from automatically resetting the target on connection, call IDF Monitor with the –no-reset option (e.g., idf_monitor.py –no-reset).
Note: The –no-reset option applies the same behavior even when connecting IDF Monitor to a particular port (e.g., idf.py monitor –no-reset -p [PORT]).
Launching GDB with GDBStub GDBStub is a useful runtime debugging feature that runs on the target and connects to the host over the serial port to receive debugging commands. GDBStub supports commands such as reading memory and variables, examining call stack frames etc. Although GDBStub is less versatile than JTAG debugging, it does not require any special hardware (such as a JTAG to USB bridge) as communication is done entirely over the serial port. A target can be configured to run GDBStub in the background by setting the CONFIG_ESP_SYSTEM_PANIC to GDBStub on runtime. GDBStub will run in the background until a Ctrl+C message is sent over the serial port and causes the GDBStub to break (i.e., stop the execution of) the program, thus allowing GDBStub to handle debugging commands. Furthermore, the panic handler can be configured to run GDBStub on a crash by setting the CONFIG_ESP_SYSTEM_PANIC to GDBStub on panic. When a crash occurs, GDBStub will output a special string pattern over the serial port to indicate that it is running. In both cases (i.e., sending the Ctrl+C message, or receiving the special string pattern), IDF Monitor will automatically launch GDB in order to allow the user to send debugging commands. After GDB exits, the target is reset via the RTS serial line. If this line is not connected, users can reset their target (by pressing the boardns Reset button).
Note: In the background, IDF Monitor runs the following command to launch GDB:
xtensa-esp32-elf-gdb -ex “set serial baud BAUD” -ex “target remote PORT” -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`

Output Filtering IDF monitor can be invoked as idf.py monitor –print-filter=”xyz”, where –print-filter is the parameter for output filtering. The default value is an empty string, which means that everything is printed.
Restrictions on what to print can be specified as a series of <tag>:<log_level> items where <tag> is the tag string and <log_level> is a character from the set {N, E, W, I, D, V, *} referring to a level for logging.
Por ejemploample, 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).

Sistemas Espressif

33 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
Examples of Filtering Rules:
· * can be used to match any tags. However, the string PRINT_FILTER=”*:I tag1:E” with regards to tag1 prints errors only, because the rule for tag1 has a higher priority over the rule for *.
· The default (empty) rule is equivalent to *:V because matching every tag at the Verbose level or lower means matching everything.
· “*:N” suppresses not only the outputs from logging functions, but also the prints made by printf, etc. To avoid this, use *:E or a higher verbosity level.
· Rules “tag1:V”, “tag1:v”, “tag1:”, “tag1:*”, and “tag1” are equivalent. · Rule “tag1: W tag1:E” is equivalent to “tag1:E” because any consequent occurrence of the same tag
name overwrites the previous one. · Rule “tag1:yo tag2:W” only prints tag1 at the Info verbosity level or lower and tag2 at the Warning
verbosity level or lower. · Rule “tag1:yo tag2: W tag3:N” is essentially equivalent to the previous one because tag3:N specifies
eso tag3 should not be printed. · tag3:N in the rule “tag1:yo tag2: W tag3:N *:V” is more meaningful because without tag3:N the
tag3 messages could have been printed; the errors for tag1 y 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.

Sistemas Espressif

34 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started 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. · 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
Step 1. Install Prerequisites In order to use ESP-IDF with the ESP32, 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 python3venv 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 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 cmake ninja ccache dfu-util libusb
Note: · CMake version 3.16 or newer is required for use with ESP-IDF. Run otools/idf_tools.py install cmakepto install a suitable version if your OS versions doesnnt have one. · 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 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.

Sistemas Espressif

35 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
· It is strongly recommended to also install ccache for faster builds. If you have HomeBrew, this can be done via brew install ccache or sudo port install ccache on MacPorts.
Note: If an error like this is shown during any step: xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
Then you will need to install the XCode command line tools to continue. You can install these by running xcode-select –install.
Apple M1 Users If you use Apple M1 platform and see an error like this: WARNING: directory for tool xtensa-esp32-elf version esp-2021r2-patch3-8.4.0 is present, but tool was not found ERROR: tool xtensa-esp32-elf has no installed versions. Please run ‘install.sh’ to install it.
or: zsh: bad CPU type in executable: ~/.espressif/tools/xtensa-esp32-elf/esp-2021r2patch3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc
Then you will need to install Apple Rosetta 2 by running /usr/sbin/softwareupdate –install-rosetta –agree-to-license
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, 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:

Sistemas Espressif

36 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

mkdir -p ~/esp cd ~/esp git clone -b v5.0.9 –recursive https://github.com/espressif/esp-idf.git
ESP-IDF se descargará en ~/esp/esp-idf. Consulte Versiones de ESP-IDF para obtener información sobre qué versión de ESP-IDF usar en una situación determinada.
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. cd ~/esp/esp-idf ./install.sh esp32
or with Fish shell cd ~/esp/esp-idf ./install.fish esp32
The above commands install tools for ESP32 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: cd ~/esp/esp-idf ./install.sh all
or with Fish shell cd ~/esp/esp-idf ./install.fish all
Note: For macOS users, if an error like this is shown during any step: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:xxx)
You may run Install Certificates.command in the Python folder of your computer to install certificates. For details, see Download Error While Installing ESP-IDF Tools.

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

Sistemas Espressif

37 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

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/exportar.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],
por ejemploample, 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.
Step 5. First Steps on ESP-IDF Now since all requirements are 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 and build, flash, and monitor the device output.
Note: If you have not yet installed ESP-IDF, please go to Installation and follow the instruction in order to get all the software needed to use this guide.

Start a Project Now you are ready to prepare your application for ESP32. You can start with getstarted/hello_world project from exampdirectorio de archivos en ESP-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:

Sistemas Espressif

38 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
cd ~/esp cp -r $IDF_PATH/examples/comenzar/hola_mundo .
Note: There is a range of example proyectos en el exampdirectorio de archivos en ESP-IDF. Puede copiar cualquier proyecto de la misma manera que se presentó anteriormente y ejecutarlo. También es posible construir examples in-place without copying them first.
Connect Your Device Now connect your ESP32 board to the computer and check under which serial port the board is visible. Serial ports have the following naming patterns:
· Linux: starting with /dev/tty · macOS: starting with /dev/cu. If you are not sure how to check the serial port name, please refer to Establish Serial Connection with ESP32 for full details.
Nota: Tenga a mano el nombre del puerto, ya que lo necesitará en los próximos pasos.
Configure Your Project Navigate to your hello_world directory, set ESP32 as the target, and run the project configuration utility menuconfig. cd ~/esp/hello_world idf.py set-target esp32 idf.py menuconfig
After opening a new project, you should first set the target with idf.py set-target esp32. Note that existing builds and configurations in the project, if any, will be cleared and initialized in this process. The target may be saved in the environment variable to skip this step at all. See Select the Target Chip: set-target for additional information. If the previous steps have been done correctly, the following menu appears:

Fig. 17: 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 forohello_worldp, since this example runs with

Sistemas Espressif

39 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
configuración predeterminada.
Attention: If you use ESP32-DevKitC board with the ESP32-SOLO-1 module, or ESP32-DevKitM-1 board with the ESP32-MIN1-1(1U) module, please enable single core mode (CONFIG_FREERTOS_UNICORE) in menuconfig before flashing exampLes.
Note: The colors of the menu could be different in your terminal. You can change the appearance with the option –style. Please run idf.py menuconfig –help for further information.
If you are using one of the supported development boards, you can speed up your development by using Board Support Package. See Additional Tips for more information.
Build the Project Build the project by running:
compilación idf.py
Este comando compilará la aplicación y todos los componentes de ESP-IDF, luego generará el gestor de arranque, la tabla de particiones y los archivos binarios de la aplicación.
$ 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: …
… (más líneas de salida del sistema de compilación)
[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’
Si no hay errores, la compilación finalizará generando el binario de firmware .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 board by running:
idf.py -p PUERTO [-b BAUDIOS] flash
Replace PORT with your ESP32 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.

Sistemas Espressif

40 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started

Normal Operation When flashing, you will see the output log similar to the following:
… esptool.py –chip esp32 -p /dev/ttyUSB0 -b 460800 –before=default_reset -after=hard_reset write_flash –flash_mode dio –flash_freq 40m –flash_size 2MB 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 hello_world.bin esptool.py v3.0-dev Serial port /dev/ttyUSB0 Connecting…….._ Chip is ESP32D0WDQ6 (revision 0) Features: WiFi, BT, Dual Core, Coding Scheme None Crystal is 40MHz MAC: 24:0a:c4:05:b9:14 Uploading stub… Running stub… Stub running… Changing baud rate to 460800 Changed. Configuring flash size… Compressed 3072 bytes to 103… Writing at 0x00008000… (100 %) Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 5962.8 kbit/s)… Hash of data verified. Compressed 26096 bytes to 15408… Writing at 0x00001000… (100 %) Wrote 26096 bytes (15408 compressed) at 0x00001000 in 0.4 seconds (effective 546.7 kbit/s)… Hash of data verified. Compressed 147104 bytes to 77364… Writing at 0x00010000… (20 %) Writing at 0x00014000… (40 %) Writing at 0x00018000… (60 %) Writing at 0x0001c000… (80 %)
(continúa en la página siguiente)

Sistemas Espressif

41 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
(continued from previous page) Writing at 0x00020000… (100 %) Wrote 147104 bytes (77364 compressed) at 0x00010000 in 1.9 seconds (effective 615. 5 kbit/s)… Hash of data verified.
Dejando... Restablecimiento completo a través del pin RTS... Listo
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 Eclipse Plugin, VSCode Extension.
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 …
Después de que los registros de inicio y diagnóstico se desplacen hacia arriba, debería ver "¡Hola mundo!" impreso por la aplicación.
… Hello world! Restarting in 10 seconds… This is esp32 chip with 2 CPU core(s), WiFi/BT/BLE, silicon revision 1, 2MB external flash Minimum free heap size: 298968 bytes Restarting in 9 seconds… Restarting in 8 seconds… Restarting in 7 seconds…
To exit IDF monitor use the shortcut Ctrl+]. If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26 MHz crystal. Most development board designs use 40 MHz, so ESP-IDF uses this frequency as a default value.

Sistemas Espressif

42 Submit Document Feedback

Versión v5.0.9

Chapter 1. Get Started
In the current version of ESP-IDF, main XTAL frequencies supported by ESP32 are as follows:
· 26 MHz · 40 MHz
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! Now you are ready to try some other examples, or go straight to developing your own applications.
Important: Some of examples do not support ESP32 because required hardware is not included in ESP32 so it cannot be supported. If building an example, please check the README file for the Supported Targets table. If this is present including ESP32 target, or the table does not exist at all, the example will work on ESP32.
Consejos adicionales
Permission issues /dev/ttyUSB0 With some Linux distributions, you may get the Failed to open port /dev/ttyUSB0 error message when flashing the ESP32. This can be solved by adding the current user to the dialout group.
Python compatibility ESP-IDF supports Python 3.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.
Start with Board Support Package To speed up prototyping on some development boards, you can use Board Support Packages (BSPs), which makes initialization of a particular board as easy as few function calls. A BSP typically supports all of the hardware components provided on development board. Apart from the pinout definition and initialization functions, a BSP ships with drivers for the external components such as sensors, displays, audio codecs etc. The BSPs are distributed via IDF Component Manager, so they can be found in IDF Component Registry. Herens an example of how to add ESP-WROVER-KIT BSP to your project: idf.py add-dependency esp_wrover_kit
Más examples of BSP usage can be found in BSP exampcarpeta de archivos.
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.

Sistemas Espressif

43 Submit Document Feedback

Versión v5.0.9

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 · Establish Serial Connection with ESP32 · Eclipse Plugin · VSCode Extension · IDF Monitor
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 the Start a Project on Windows or Start a Project on Linux and macOS.
1.5 Uninstall ESP-IDF
If you want to remove ESP-IDF, please follow Uninstall ESP-IDF.

Sistemas Espressif

44 Submit Document Feedback

Versión v5.0.9

Capítulo 2
Referencia API
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 Manejo de errores
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 exampen:
45

Chapter 2. API Reference

const esp_timer_create_args_t my_timer_args = { .callback = &my_timer_callback, .arg = callback_arg, .name = “my_timer”
}; esp_timer_handle_t my_timer; esp_err_t err = esp_timer_create(&my_timer_args, &my_timer);
Initialization functions never store the pointer to the configuration structure, so it is safe to allocate the structure on the stack.
The application must initialize all fields of the structure. The following is incorrect:
esp_timer_create_args_t my_timer_args; my_timer_args.callback = &my_timer_callback; /* Incorrect! Fields .arg and .name are not initialized */ esp_timer_create(&my_timer_args, &my_timer);
Most ESP-IDF examples use C99 designated initializers for structure initialization, since they provide a concise way of setting a subset of fields, and zero-initializing the remaining fields:
const esp_timer_create_args_t my_timer_args = { .callback = &my_timer_callback, /* Correct, fields .arg and .name are zero-initialized */
};
C++ language 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 examplos proyectos
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.

Sistemas Espressif

46 Submit Document Feedback

Versión v5.0.9

Chapter 2. API Reference
This includes components located

Documentos / Recursos

Espressif Systems ESP32 Dev Kitc Development Board [pdf] Guía del usuario
ESP32 Dev Kitc Development Board, ESP32, Dev Kitc Development Board, Kitc Development Board, Development Board, Board

Referencias

Manual de usuario

Espressif Systems ESP32 Dev Kitc Development Board User Guide

ESP32 Dev Kitc Development Board

Información del producto

Presupuesto

Instrucciones de uso del producto

1. Comience ahora

1.1 Introducción

1.2 Lo que necesitas

1.3 Instalación

1.4 Build Your First Project

1.5 Uninstall ESP-IDF

2. Referencia de API

Preguntas frecuentes (FAQ)

Q: How can I troubleshoot common issues with ESP32?

Q: Can I use ESP-IDF with other microcontrollers?

Documentos / Recursos

Referencias

Deja un comentario

Cancelar respuesta