ESP32 · 1 day ago · ESP32 ESP-IDF编程指南 Releasev4.2-dev-1206-g741960d 乐鑫信息科技 2020年04月24日

ESP32ESP-IDF编程指南

Release v4.2-dev-1206-g741960d乐鑫信息科技2020年 04月 24日

Table of contents

Table of contents i

1 快速入门 31.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 准备工作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 开发板简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 详细安装步骤 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.4.1 设置开发环境 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4.2 创建您的第一个工程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.5 第一步：安装准备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5.1 Windows平台工具链的标准设置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.5.2 Linux平台工具链的标准设置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.5.3 MacOS平台工具链的标准设置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.6 第二步：获取 ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.6.1 Linux和MacOS操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.6.2 Windows操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.7 第三步：设置工具 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.7.1 Windows操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.7.2 Linux和MacOS操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.7.3 自定义工具安装路径 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.8 第四步：设置环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.8.1 Windows操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.8.2 Linux和MacOS操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.9 第五步：开始创建工程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.9.1 Linux和MacOS操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.9.2 Windows操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.10 第六步：连接设备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.11 第七步：配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.11.1 Linux和MacOS操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.11.2 Windows操作系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.12 第八步：编译工程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.13 第九步：烧录到设备 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.14 第十步：监视器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.15 更新 ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181.16 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1.16.1 与 ESP32创建串口连接 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181.16.2 Eclipse IDE创建和烧录指南 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.16.3 IDF监视器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.16.4 工具链的自定义设置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.16.5 快速入门（传统 GNU Make） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2 API参考 532.1 蓝牙 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

2.1.1 Controller && VHCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532.1.2 BT COMMON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612.1.3 BT LE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652.1.4 CLASSIC BT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

i

2.1.5 NimBLE-based host APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2112.1.6 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

2.2 连网 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4172.2.1 Wi-Fi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4172.2.2 以太网 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4852.2.3 IP网络层协议 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4992.2.4 应用层协议 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514

2.3 外设 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5142.3.1 Analog to Digital Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5142.3.2 Controller Area Network (CAN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5222.3.3 Digital To Analog Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5362.3.4 GPIO & RTC GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5382.3.5 I2C Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5472.3.6 I2S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5572.3.7 LED PWM控制器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5652.3.8 MCPWM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5742.3.9 Pulse Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5912.3.10 RMT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5982.3.11 SDMMC Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6122.3.12 SD SPI Host Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6162.3.13 SDIO Card Slave Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6202.3.14 Sigma-delta Modulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6332.3.15 SPI Master Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6352.3.16 SPI Slave Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6522.3.17 定时器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6592.3.18 触摸传感器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6662.3.19 UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680

2.4 应用层协议 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6992.4.1 mDNS服务 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6992.4.2 ESP-TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7082.4.3 ESP HTTP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7182.4.4 ESP WebSocket Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7302.4.5 HTTP服务器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7342.4.6 HTTPS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7552.4.7 ICMP Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7572.4.8 ASIO port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7612.4.9 ESP-MQTT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7622.4.10 ESP-Modbus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7712.4.11 ESP Local Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7762.4.12 ESP Serial Slave Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7832.4.13 ESP x509 Certificate Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7892.4.14 IP网络层协议 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791

2.5 配网 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7912.5.1 Unified Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7912.5.2 Protocol Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7962.5.3 Wi-Fi Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806

2.6 存储 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8212.6.1 SPI Flash API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8212.6.2 SD/SDIO/MMC驱动程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8392.6.3 非易失性存储库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8482.6.4 NVS分区生成程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8652.6.5 虚拟文件系统组件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8692.6.6 FAT文件系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8802.6.7 磨损均衡 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8842.6.8 SPIFFS文件系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8882.6.9 量产程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891

2.7 System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8952.7.1 App Image Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895

ii

2.7.2 Application Level Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9002.7.3 控制台终端 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9052.7.4 eFuse Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9122.7.5 Error Codes and Helper Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9212.7.6 ESP HTTPS OTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9232.7.7 ESP-pthread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9262.7.8 Event Loop Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9282.7.9 FreeRTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9432.7.10 FreeRTOS Additions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10222.7.11 Heap Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10392.7.12 Heap Memory Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10502.7.13 High Resolution Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10592.7.14 The himem allocation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10632.7.15 Inter-Processor Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10662.7.16 Call function with external stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10672.7.17 Interrupt allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10682.7.18 Logging library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10742.7.19 Miscellaneous System APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10792.7.20 空中升级 (OTA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10852.7.21 Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10942.7.22 电源管理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10972.7.23 Sleep Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11022.7.24 Watchdogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11102.7.25 System Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113

2.8 Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11172.8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11172.8.2 Project Configuration Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11172.8.3 Using sdkconfig.defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11172.8.4 Kconfig Formatting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11172.8.5 Backward Compatibility of Kconfig Options . . . . . . . . . . . . . . . . . . . . . . . . 11182.8.6 Configuration Options Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11182.8.7 Customisations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1283

2.9 Error Codes Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1283

3 ESP32 H/W硬件参考 12893.1 ESP32系列模组和开发板 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289

3.1.1 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12893.2 ESP32模组与开发板（历史版本） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289

3.2.1 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289

4 API指南 12914.1 ESP-IDF编程注意事项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291

4.1.1 应用程序的启动流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12914.1.2 应用程序的内存布局 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12924.1.3 DMA能力要求 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1294

4.2 构建系统（CMake版） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12954.2.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12954.2.2 使用构建系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12964.2.3 示例项目 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12984.2.4 项目 CMakeLists文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12994.2.5 组件 CMakeLists文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13004.2.6 组件配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13024.2.7 预处理器定义 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13024.2.8 组件依赖 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13034.2.9 构建的内部过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13044.2.10 组件 CMakeLists示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13054.2.11 自定义 sdkconfig的默认值 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13094.2.12 Flash参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309

iii

4.2.13 构建 Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13094.2.14 选择“目标”芯片 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13094.2.15 编写纯 CMake组件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13104.2.16 组件中使用第三方 CMake项目 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13104.2.17 在自定义 CMake项目中使用 ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . 13114.2.18 文件通配符 &增量构建 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13114.2.19 构建系统的元数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13124.2.20 从 ESP-IDF GNU Make构建系统迁移到 CMake构建系统 . . . . . . . . . . . . . . . 1312

4.3 构建系统 (传统 GNU Make) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13134.3.1 使用构建系统 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13144.3.2 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13144.3.3 构建 Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323

4.4 错误处理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13234.4.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13234.4.2 错误码 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13234.4.3 错误码到错误消息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13244.4.4 ESP_ERROR_CHECK宏 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13244.4.5 错误处理模式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13244.4.6 C++异常 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325

4.5 严重错误 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13254.5.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13254.5.2 紧急处理程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13264.5.3 寄存器转储与回溯 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13264.5.4 GDB Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13284.5.5 Guru Meditation错误 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13294.5.6 其它严重错误 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330

4.6 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13314.6.1 Wi-Fi, Ethernet, and IP Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13314.6.2 Mesh Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13334.6.3 Bluetooth Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333

4.7 Deep Sleep Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13344.7.1 Rules for Wake Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13344.7.2 Implementing A Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13344.7.3 Loading Code Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13354.7.4 Loading Data Into RTC Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335

4.8 Core Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13364.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13364.8.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13364.8.3 Save core dump to flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13364.8.4 Print core dump to UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13374.8.5 ROM Functions in Backtraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13374.8.6 Running‘espcoredump.py’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1337

4.9 Flash加密 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13384.9.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13384.9.2 Flash加密过程中使用的 eFuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13384.9.3 Flash的加密过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13394.9.4 设置 Flash加密的步骤 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13394.9.5 Flash加密的要点 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13454.9.6 使用加密的 Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13464.9.7 更新加密的 Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13474.9.8 关闭 Flash加密 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13474.9.9 Flash加密的局限性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13474.9.10 Flash加密与安全启动 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13474.9.11 使用无安全启动的 Flash加密 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13474.9.12 Flash加密的高级功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13474.9.13 技术细节 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1349

4.10 ESP-IDF FreeRTOS SMP Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13494.10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1349

iv

4.10.2 Backported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13504.10.3 Tasks and Task Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13504.10.4 Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13514.10.5 Critical Sections & Disabling Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . 13544.10.6 Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13544.10.7 Task Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13554.10.8 Thread Local Storage Pointers & Deletion Callbacks . . . . . . . . . . . . . . . . . . . . 13554.10.9 Configuring ESP-IDF FreeRTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355

4.11 Thread Local Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13564.11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13564.11.2 FreeRTOS Native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13564.11.3 Pthread API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13564.11.4 C11 Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356

4.12 High-Level Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13564.12.1 Interrupt Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13574.12.2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357

4.13 JTAG调试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13574.13.1 引言 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13584.13.2 工作原理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13584.13.3 选择 JTAG适配器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13594.13.4 安装 OpenOCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13594.13.5 配置 ESP32目标板 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13594.13.6 启动调试器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13644.13.7 调试范例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13644.13.8 从源码构建 OpenOCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13654.13.9 注意事项和补充内容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13684.13.10 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372

4.14 引导加载程序（Bootloader） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14044.14.1 恢复出厂设置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14044.14.2 从测试固件启动 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14054.14.3 自定义引导程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405

4.15 分区表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14054.15.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14054.15.2 内置分区表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14054.15.3 创建自定义分区表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14064.15.4 生成二进制分区表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14084.15.5 烧写分区表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14084.15.6 分区工具 (parttool.py) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1408

4.16 Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14104.16.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14104.16.2 Secure Boot Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14104.16.3 Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14114.16.4 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14114.16.5 How To Enable Secure Boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14114.16.6 Re-Flashable Software Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14124.16.7 Generating Secure Boot Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14134.16.8 Remote Signing of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14134.16.9 Secure Boot Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14144.16.10 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14144.16.11 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14154.16.12 Signed App Verification Without Hardware Secure Boot . . . . . . . . . . . . . . . . . . 14154.16.13 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416

4.17 Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14164.17.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14164.17.2 Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14164.17.3 Secure Boot V2 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14174.17.4 Signature Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14174.17.5 Verifying the signature Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417

v

4.17.6 Bootloader Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14184.17.7 eFuse usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14184.17.8 How To Enable Secure Boot V2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14184.17.9 Restrictions after Secure Boot is enabled . . . . . . . . . . . . . . . . . . . . . . . . . . 14194.17.10 Generating Secure Boot Signing Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14194.17.11 Remote Signing of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14204.17.12 Secure Boot Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14204.17.13 Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14204.17.14 Secure Boot & Flash Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14204.17.15 Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421

4.18 ULP协处理器编程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14214.18.1 ESP32 ULP coprocessor instruction set . . . . . . . . . . . . . . . . . . . . . . . . . . . 14214.18.2 Programming ULP coprocessor using C macros . . . . . . . . . . . . . . . . . . . . . . 14344.18.3 安装工具链 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14384.18.4 编译 ULP代码 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14394.18.5 访问 ULP程序变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14394.18.6 启动 ULP程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14404.18.7 ULP程序流 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441

4.19 ULP协处理器 (传统的 GNU Make) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14424.19.1 安装工具链 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14424.19.2 编译 ULP代码 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14424.19.3 访问 ULP程序变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14434.19.4 启动 ULP程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14444.19.5 ULP程序流 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1445

4.20 ESP32中的单元测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14464.20.1 添加常规测试用例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14464.20.2 添加多设备测试用例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14464.20.3 添加多阶段测试用例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14474.20.4 应用于不同芯片的单元测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14484.20.5 编译单元测试程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14494.20.6 运行单元测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449

4.21 单元测试（传统的 GNU Make） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14504.21.1 添加常规测试用例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14504.21.2 添加多设备测试用例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14514.21.3 添加多阶段测试用例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14524.21.4 编译单元测试程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14524.21.5 运行单元测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453

4.22 ESP32 ROM console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14544.22.1 Full list of supported statements and functions . . . . . . . . . . . . . . . . . . . . . . . 14544.22.2 Example programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14554.22.3 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455

4.23 RF calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14554.23.1 Partial calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14564.23.2 Full calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14564.23.3 No calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14564.23.4 PHY initialization data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456

4.24 Wi-Fi Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14564.24.1 ESP32 Wi-Fi Feature List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14564.24.2 How To Write a Wi-Fi Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14574.24.3 ESP32 Wi-Fi API Error Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14574.24.4 ESP32 Wi-Fi API Parameter Initialization . . . . . . . . . . . . . . . . . . . . . . . . . 14584.24.5 ESP32 Wi-Fi Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14584.24.6 ESP32 Wi-Fi Event Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14594.24.7 ESP32 Wi-Fi Station General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 14614.24.8 ESP32 Wi-Fi AP General Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14644.24.9 ESP32 Wi-Fi Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14644.24.10 ESP32 Wi-Fi Station Connecting Scenario . . . . . . . . . . . . . . . . . . . . . . . . . 14724.24.11 ESP32 Wi-Fi Station Connecting When Multiple APs Are Found . . . . . . . . . . . . . 1476

vi

4.24.12 Wi-Fi Reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14764.24.13 Wi-Fi Beacon Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14764.24.14 ESP32 Wi-Fi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14764.24.15 Wi-Fi Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14824.24.16 ESP32 Wi-Fi Power-saving Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14834.24.17 ESP32 Wi-Fi Connect Crypto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14834.24.18 ESP32 Wi-Fi Throughput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14844.24.19 Wi-Fi 80211 Packet Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14844.24.20 Wi-Fi Sniffer Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14874.24.21 Wi-Fi Multiple Antennas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14874.24.22 Wi-Fi Channel State Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14884.24.23 Wi-Fi Channel State Information Configure . . . . . . . . . . . . . . . . . . . . . . . . . 14894.24.24 Wi-Fi HT20/40 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14904.24.25 Wi-Fi QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14904.24.26 Wi-Fi AMSDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14914.24.27 Wi-Fi Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14914.24.28 WPS Enrolle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14914.24.29 Wi-Fi Buffer Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14914.24.30 Wi-Fi Menuconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14924.24.31 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495

4.25 ESP-BLE-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14994.25.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15014.25.2 ESP-BLE-MESH快速入门 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15014.25.3 ESP-BLE-MESH示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15074.25.4 ESP-BLE-MESH演示视频 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15084.25.5 ESP-BLE-MESH常见问题手册 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15084.25.6 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1509

4.26 ESP-MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15354.26.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15354.26.2 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15364.26.3 ESP-MESH概念 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15374.26.4 建立网络 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15414.26.5 管理网络 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15464.26.6 数据传输 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15484.26.7 信道切换 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15514.26.8 性能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15534.26.9 更多注意事项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1554

4.27 BluFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15544.27.1 概览 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15544.27.2 BluFi流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15544.27.3 ESP32配网流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15544.27.4 配网流程图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15564.27.5 BluFi传输格式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15564.27.6 ESP32端的安全实现 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15594.27.7 GATT相关说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1560

4.28 片外 RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15604.28.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15604.28.2 硬件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15604.28.3 配置片外 RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15614.28.4 片外 RAM使用限制 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15624.28.5 Chip revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1562

4.29 链接脚本生成机制 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15634.29.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15634.29.2 快速上手 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15634.29.3 链接脚本生成机制内核 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1566

4.30 lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15714.30.1 Supported APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15714.30.2 BSD Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1571

vii

4.30.3 Netconn API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15754.30.4 lwIP FreeRTOS Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15754.30.5 esp-lwip custom modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15764.30.6 Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576

4.31 工具 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15784.31.1 Downloadable Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15784.31.2 IDF Docker Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1584

5 Libraries and Frameworks 15875.1 Cloud Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1587

5.1.1 AWS IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15875.1.2 Azure IoT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15875.1.3 Google IoT Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1587

6 Contributions Guide 15896.1 How to Contribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15896.2 Before Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15896.3 Pull Request Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15896.4 Legal Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15896.5 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1590

6.5.1 Espressif IoT Development Framework Style Guide . . . . . . . . . . . . . . . . . . . . 15906.5.2 编写代码文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15966.5.3 Documentation Add-ons and Extensions Reference . . . . . . . . . . . . . . . . . . . . . 16026.5.4 创建示例项目 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16056.5.5 API Documentation Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16066.5.6 Contributor Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1608

7 ESP-IDF版本简介 16117.1 发布版本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16117.2 我该选择哪个版本？ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16127.3 版本管理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16127.4 查看当前版本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16137.5 Git工作流 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16137.6 更新 ESP-IDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1614

7.6.1 更新至一个稳定发布版本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16147.6.2 更新至一个预发布版本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16147.6.3 更新至 master分支 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16147.6.4 更新至一个发布分支 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615

8 资源 1617

9 Copyrights and Licenses 16199.1 Software Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619

9.1.1 Firmware Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16199.1.2 Build Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16209.1.3 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620

9.2 ROM Source Code Copyrights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16209.3 Xtensa libhal MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16209.4 TinyBasic Plus MIT License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16219.5 TJpgDec License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1621

10 关于本指南 1623

11 Switch Between Languages/切换语言 1625

索引 1627

索引 1627

viii

Table of contents

[English]这里是乐鑫 IoT开发框架 (esp-idf)的文档中心。ESP-IDF是 ESP32和 ESP32-S2系列芯片的官方开发框架。

ESP-IDF是 ESP32芯片的官方开发框架。

快速入门 API参考 H/W参考

API指南贡献代码相关资源

Espressif Systems 1Submit Document Feedback

Release v4.2-dev-1206-g741960d

../../../en/latest/esp32/index.htmlhttps://github.com/espressif/esp-idfhttps://www.espressif.com/en/products/hardware/socshttps://www.espressif.com/zh-hans/products/hardware/esp32/overviewget-started/index.htmlapi-reference/index.htmlhw-reference/index.htmlget-started/index.htmlapi-reference/index.htmlhw-reference/index.htmlapi-guides/index.htmlcontribute/index.htmlresources.htmlapi-guides/index.htmlcontribute/index.htmlresources.htmlhttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d

Table of contents



https://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d

Chapter 1

快速入门

[English]本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF(Espressif IoT Development Framework)配置菜单，并编译、下载固件至 ESP32开发板等步骤。

注解: 这是 ESP-IDF master分支（最新版本）的文档，该版本在持续开发中。还有 Stable version的文档，以及其他版本的文档ESP-IDF 版本简介供参考。This is documentation for the master branch (latest version)of ESP-IDF. This version is under continual development. Stable version documentation is‘‘available, as well asother ESP-IDF版本简介.

1.1 概述

ESP32采用 40 nm工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用场景和不同功耗需求。

乐鑫为用户提供完整的软、硬件资源，进行 ESP32硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF旨在协助用户快速开发物联网 (IoT)应用，可满足用户对Wi-Fi、蓝牙、低功耗等方面的要求。

1.2 准备工作

硬件：

• 一款 ESP32开发板• USB数据线 (A转Micro-B)• PC（Windows、Linux或Mac OS）

软件：

• 设置工具链，用于编译 ESP32代码；• 编译工具——CMake和 Ninja编译工具，用于编译 ESP32应用程序；• 获取 ESP-IDF软件开发框架。该框架已经基本包含 ESP32使用的 API（软件库和源代码）和运行工具链的脚本；

• 安装 C语言编程（工程）的文本编辑器，例如 Eclipse。

1.3 开发板简介

请点击下方连接，了解有关具体开发板的详细信息。

3

../../../../en/latest/esp32/get-started/index.htmlhttps://docs.espressif.com/projects/esp-idf/zh_CN/stable/https://docs.espressif.com/projects/esp-idf/zh_CN/stable/https://www.eclipse.org/

Chapter 1. 快速入门

图 1: ESP32应用程序开发

1.4 详细安装步骤

请根据下方详细步骤，完成安装过程。

1.4.1 设置开发环境

• 第一步：安装准备（Windows、Linux和macOS）• 第二步：获取 ESP-IDF• 第三步：设置工具• 第四步：设置环境变量

1.4.2 创建您的第一个工程

• 第五步：开始创建工程• 第六步：连接设备• 第七步：配置• 第八步：编译工程• 第九步：烧录到设备• 第十步：监视器

1.5 第一步：安装准备

在正式开始创建工程前，请先完成工具的安装，具体步骤见下：





1.5.1 Windows平台工具链的标准设置

[English]

概述

ESP-IDF需要安装一些必备工具，才能围绕 ESP32构建固件，包括 Python、Git、交叉编译器、menuconfig工具、CMake和 Ninja编译工具等。在本入门指南中，我们通过命令提示符进行有关操作。不过，您在安装 ESP-IDF后还可以使用Eclipse或其他支持 CMake的图形化工具 IDE。

ESP-IDF工具安装器

要安装 ESP-IDF必备工具，最简易的方式是下载 ESP-IDF工具安装器，地址如下：https://dl.espressif.com/dl/esp-idf-tools-setup-2.3.exe本安装器可为您安装所需的交叉编译器、OpenOCD、cmake和 Ninja编译工具，以及一款 mconf-idf配置工具。此外，本安装器还可在有需要时下载、运行 Python 3.7和 Git For Windows的安装器。本安装器还可用于下载任意 ESP-IDF发布版本。

使用命令提示符

在后续步骤中，我们将使用Windows的命令提示符进行操作。ESP-IDF工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF命令提示符窗口的快捷方式。本快捷方式可以打开Windows命令提示符（即 cmd.exe），并运行 export.bat脚本以设置各环境变量（比如PATH，IDF_PATH等）。此外，您可还以通过Windows命令提示符使用各种已经安装的工具。注意，本快捷方式仅适用 ESP-IDF工具安装器中指定的 ESP-IDF路径。如果您的电脑上存在多个 ESP-IDF（比如您需要不同的 ESP-IDF版本）需要使用快捷方式，您可以：

1. 为 ESP-IDF工具安装器创建的快捷方式创建一个副本，并将新快捷方式的“当前路径”指定为您希望使用的 ESP-IDF路径。

2. 运行 cmd.exe，并更新至您希望使用的 ESP-IDF目录，然后运行 export.bat。注意，这种方法要求 PATH中存在 Python和 Git。如果您在使用时遇到有关“找不到 Python或 Git”的错误信息，请使用第一种方法。

后续步骤

当 ESP-IDF工具安装器安装完成后，则开发环境设置也到此结束。后续开发步骤，请前往第五步：开始创建工程查看。

相关文档

想要自定义安装流程的高阶用户可参照：

从零开始设置Windows环境下的工具链 [English]除了使用ESP-IDF工具安装器，用户也可以手动设置Windows环境下的工具链，这也是本文的主要内容。手动安装工具可以更好地控制安装流程，同时也方便高阶用户进行自定义安装。

使用 ESP-IDF工具安装器对工具链及其他工具进行快速标准设置，请参照Windows平台工具链的标准设置。



../../../../en/latest/esp32/get-started/windows-setup.htmlhttps://dl.espressif.com/dl/esp-idf-tools-setup-2.3.exehttps://cmake.org/download/https://ninja-build.org/https://github.com/espressif/kconfig-frontends/releases/https://www.python.org/downloads/windows/../../../../en/latest/esp32/get-started/windows-setup-scratch.htmlhttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


注解: 基于 GNUMake的构建系统要求Windows兼容MSYS2 Unix，基于 CMake的构建系统则无此要求。

获取ESP-IDF注解: 较早版本 ESP-IDF使用了MSYS2 bash终端命令行。目前，基于 CMake的编译系统可使用常见的Windows命令窗口，即本指南中使用的终端。请注意，如果您使用基于 bash的终端或 PowerShell终端，一些命令语法将与下面描述有所不同。

打开命令提示符，运行以下命令：

mkdir %userprofile%\espcd %userprofile%\espgit clone --recursive https://github.com/espressif/esp-idf.git

ESP-IDF将下载至 %userprofile%\esp\esp-idf。请前往ESP-IDF版本简介，查看 ESP-IDF不同版本的具体适用场景。

注解: 此命令将克隆 master分支，该分支保存着 ESP-IDF的最新版本，它功能齐全，每周都会更新一些新功能并修正一些错误。

注解: GitHub中”下载 zip文档”的功能不适用于 ESP-IDF，所以需要使用 git clone命令。作为备份，可以在没有安装 Git的环境中下载 Stable version的 zip归档文件。

注解: 在克隆远程仓库时，不要忘记加上 --recursive选项。否则，请接着运行以下命令，获取所有子模块

cd esp-idfgit submodule update --init

工具

cmake工具下载最新发布的Windows平台稳定版 CMake，并运行安装器。当安装器询问“安装选项”时，选择“Add CMake to the system PATH for all users”（为所有用户的系统路径添加 CMake）或“Add CMake to the system PATH for the current user”（为当前用户的系统路径添加CMake）。

Ninja编译工具注解: 目前，Ninja 仅提供支持 64 位 Windows 版本的 bin 文件。您也可以配合其他编译工具在 32 位Windows版本中使用 CMake和 idf.py，比如 mingw-make。但是目前暂无关于此工具的说明文档。

从（下载页面）下载最新发布的Windows平台稳定版 ninja。适用于Windows平台的 Ninja下载文件是一个.zip文件，包含一个 ninja.exe文件。您需要将该文件解压到目录，并添加到您的路径（或者选择您路径中的已有目录）。



https://www.msys2.org/https://docs.espressif.com/projects/esp-idf/zh_CN/stable/https://cmake.org/download/https://github.com/ninja-build/ninja/releaseshttps://ninja-build.org/https://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


Python 下载并运行适用于Windows安装器的最新版 Python。Python 安装器的“自定义”菜单可为您提供一系列选项，最后一项为“Add python.exe to Path”（添加python.exe到路径中）。请将该选项更改到“Will be installed”（将会安装）。Python安装完成后，从Windows开始菜单中打开“命令提示符”窗口，并运行以下命令:

pip install --user pyserial

适用于 IDF的MConf 从 kconfig-frontends releases page下载配置工具 mconf-idf。此为 mconf配置工具，可针对 ESP-IDF进行少量自定义操作。请将此工具解压到目录，并添加到您的路径。

工具链设置下载预编译的Windows工具链：https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp-2020r1-win32.zip解压压缩包文件到 C:\Program Files（或其他位置）。压缩包文件包含一个 xtensa-esp32-elf目录。

然后，请将该目录下的 bin 子目录添加到您的路径。例如，C:\Program Files\xtensa-esp32-elf\bin。

注解: 如果您已安装MSYS2环境（适用“GNUMake”编译系统），则可以跳过下载那一步，直接添加目录 C:\msys32\opt\xtensa-esp32-elf\bin到路径，因为MSYS2环境已包含工具链。

添加目录到路径在Windows环境下，向 Path环境变量增加任何新目录，请：打开系统“控制面板”，找到环境变量对话框（Windows 10用户请前往“高级系统设置”）。双击 Path变量（选择“用户”或“系统路径”，具体取决于您是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ;。

后续步骤继续设置开发环境，请前往第二步：获取 ESP-IDF 章节。

在Windows环境下更新 ESP-IDF工具

使用脚本安装 ESP-IDF工具请从Windows“命令提示符”窗口，切换至 ESP-IDF的安装目录。然后运行:

install.bat

对于 Powershell，请切换至 ESP-IDF的安装目录。然后运行:

install.ps1

该命令可下载安装 ESP-IDF所需的工具。如您已经安装了某个版本的工具，则该命令将无效。该工具的下载安装位置由 ESP-IDF工具安装器的设置决定，默认情况下为：C:\Users\username\.espressif。

使用“导出脚本”将 ESP-IDF工具添加至 PATH ESP-IDF工具安装器将在“开始菜单”为“ESP-IDF命令提示符”创建快捷方式。点击该快捷方式可打开Windows命令提示符窗口，您可在该窗口使用所有已安装的工具。

有些情况下，您正在使用的 ESP-IDF版本可能并未创建命令提示符快捷方式，此时您可以根据下方步骤将 ESP-IDF工具添加至 PATH。



https://www.python.org/downloads/windows/https://github.com/espressif/kconfig-frontends/releaseshttps://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp-2020r1-win32.ziphttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


首先，请打开需要使用 ESP-IDF的命令提示符窗口，切换至ESP-IDF的安装路径，然后执行 export.bat:

cd %userprofile%\esp\esp-idfexport.bat

对于 Powershell用户，请同样切换至 ESP-IDF的安装路径，然后执行 export.ps1:

cd ~/esp/esp-idfexport.ps1

运行完成后，您就可以通过命令提示符使用 ESP-IDF工具了。

1.5.2 Linux平台工具链的标准设置

[English]

安装准备

编译 ESP-IDF需要以下软件包：• CentOS 7:

sudo yum install git wget flex bison gperf python cmake ninja-build ccache

• Ubuntu和 Debian:

sudo apt-get install git wget flex bison gperf python python-pip python-↪→setuptools cmake ninja-build ccache libffi-dev libssl-dev

• Arch:

sudo pacman -S --needed gcc git make flex bison gperf python-pip python-↪→pyserial cmake ninja ccache

注解: 使用 ESP-IDF需要 CMake 3.5或以上版本。较早版本的 Linux可能需要升级才能向后移植仓库，或安装“cmake3”软件包，而不是安装“cmake”。

其他提示

权限问题 /dev/ttyUSB0 使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 Failed to openport /dev/ttyUSB0 错误消息。此时，可以将当前用户增加至:ref:‘ Linux Dialout 组 ‘。

后续步骤

继续设置开发环境，请前往第二步：获取 ESP-IDF 章节。

相关文档

从零开始设置 Linux环境下的工具链 [English]除了从乐鑫官网直接下载已编译好的二进制工具链外，您还可以按照本文介绍，从头开始设置自己的工具链。如需快速使用已编译好的二进制工具链，可回到Linux平台工具链的标准设置章节。



../../../../en/latest/esp32/get-started/linux-setup.html../../../../en/latest/esp32/get-started/linux-setup-scratch.htmlhttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


安装准备编译 ESP-IDF需要以下软件包：• CentOS 7:

sudo yum install git wget ncurses-devel flex bison gperf python pyserial␣↪→python-pyelftools cmake ninja-build ccache

• Ubuntu和 Debian:

sudo apt-get install git wget libncurses-dev flex bison gperf python python-↪→pip python-setuptools python-serial python-click python-cryptography python-↪→future python-pyparsing python-pyelftools cmake ninja-build ccache libffi-↪→dev libssl-dev

• Arch:

sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pyserial␣↪→python-click python-cryptography python-future python-pyparsing python-↪→pyelftools cmake ninja ccache

注解: 使用 ESP-IDF需要 CMake 3.5或以上版本。较早版本的 Linux可能需要升级才能向后移植仓库，或安装“cmake3”软件包，而不是安装“cmake”。

从源代码编译工具链安装依赖项：

• CentOS 7:

sudo yum install gawk gperf grep gettext ncurses-devel python python-devel␣↪→automake bison flex texinfo help2man libtool make

• Ubuntu pre-16.04:

sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev␣↪→automake bison flex texinfo help2man libtool make

• Ubuntu 16.04或以上

sudo apt-get install gawk gperf grep gettext python python-dev automake bison␣↪→flex texinfo help2man libtool libtool-bin make

• Debian 9:

sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev␣↪→automake bison flex texinfo help2man libtool libtool-bin make

• Arch:

TODO

创建工作目录，并进入该目录:

mkdir -p ~/espcd ~/esp

下载并编译 crosstool-NG：

git clone https://github.com/espressif/crosstool-NG.gitcd crosstool-NGgit checkout esp-2020r1git submodule update --init./bootstrap && ./configure --enable-local && make

编译工具链:





./ct-ng xtensa-esp32-elf

./ct-ng buildchmod -R u+w builds/xtensa-esp32-elf


1.5.3 MacOS平台工具链的标准设置

[English]

安装准备

ESP-IDF将使用Mac OS上默认安装的 Python版本。• 安装 pip:

sudo easy_install pip

• 安装 pyserial:


• 安装 CMake和 Ninja编译工具：– 若有 HomeBrew，您可以运行:

brew install cmake ninja

– 若有MacPorts，您可以运行:

sudo port install cmake ninja

– 若以上均不适用，请访问 CMake和 Ninja主页，查询有关Mac OS平台的下载安装问题。• 强烈建议同时安装 ccache以获得更快的编译速度。如有 HomeBrew，可通过 MacPorts上的 brewinstall ccache或 sudo port install ccache完成安装。

注解: 如您在上述任何步骤中遇到以下错误:

``xcrun: error: invalid active developer path (/Library/Developer/↪→CommandLineTools), missing xcrun at:/Library/Developer/CommandLineTools/usr/bin/↪→xcrun``

则必须安装 XCode命令行工具，具体可运行 xcode-select --install。

后续步骤

继续设置开发环境，请前往第二步：获取 ESP-IDF 章节。

相关文档

从零开始设置MacOS环境下的工具链 [English]

软件包管理器从零开始设置工具链，您需要安装 MacPorts或 homebrew软件包管理器。或者，您也可以直接下载预编译的工具链。

MacPorts需要完整的 XCode软件，而 homebrew只需要安装 XCode命令行工具即可。请参考工具链自定义设置章节，查看可能需要从头开始设置工具链的情况。



../../../../en/latest/esp32/get-started/macos-setup.htmlhttps://brew.sh/https://www.macports.org/install.phphttps://cmake.org/https://ninja-build.org/https://ccache.samba.org/https://brew.sh/https://www.macports.org/install.php../../../../en/latest/esp32/get-started/macos-setup-scratch.htmlhttps://www.macports.org/install.phphttps://brew.sh/https://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


安装准备

• 安装 pip:

sudo easy_install pip

• 安装 pyserial:


• 安装 CMake和 Ninja编译工具：– 若有 HomeBrew，您可以运行:

brew install cmake ninja

– 若有MacPorts，您可以运行:

sudo port install cmake ninja

从源代码编译工具链安装依赖项：

• 对于MacPorts:

sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf␣↪→automake make

• 对于 homebrew:

brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool␣↪→autoconf automake make

创建一个文件系统镜像（区分大小写）:

hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive␣↪→HFS+"

挂载:

hdiutil mount ~/esp/crosstool.dmg

创建指向您工作目录的符号链接:

mkdir -p ~/espln -s /Volumes/ctng ~/esp/ctng-volume

前往新创建的目录

cd ~/esp/ctng-volume

下载并编译 crosstool-NG

git clone https://github.com/espressif/crosstool-NG.gitcd crosstool-NGgit checkout esp-2020r1git submodule update --init./bootstrap && ./configure --enable-local && make

编译工具链:

./ct-ng xtensa-esp32-elf

./ct-ng buildchmod -R u+w builds/xtensa-esp32-elf





编译得到的工具链会被保存到 ~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf。使用工具链前，请将 ~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin添加至 PATH环境变量。


Windows Linux Mac OS

1.6 第二步：获取 ESP-IDF

在围绕 ESP32构建应用程序之前，请先获取乐鑫提供的软件库文件 ESP-IDF仓库。获取 ESP-IDF的本地副本：打开终端，切换到您要保存 ESP-IDF的工作目录，使用 git clone命令克隆远程仓库。针对不同操作系统的详细步骤，请见下文。

注解: 在本文档中，Linux和MacOS操作系统中 ESP-IDF的默认安装路径为 ~/esp；Windows操作系统的默认路径为 %userprofile%\esp。您也可以将 ESP-IDF安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF不支持带有空格的路径。

1.6.1 Linux和MacOS操作系统

打开终端，后运行以下命令：

cd ~/espgit clone --recursive https://github.com/espressif/esp-idf.git

ESP-IDF将下载至 ~/esp/esp-idf。请前往ESP-IDF版本简介，查看 ESP-IDF不同版本的具体适用场景。

1.6.2 Windows操作系统

除了安装必要工具外，第一步中介绍的ESP-IDF工具安装器也能同时下载 ESP-IDF本地副本。请前往ESP-IDF版本简介，查看 ESP-IDF不同版本的具体适用场景。除了使用 ESP-IDF工具安装器，您也可以参考指南手动下载 ESP-IDF。

1.7 第三步：设置工具

除了 ESP-IDF本身，您还需要安装 ESP-IDF使用的各种工具，比如编译器、调试器、Python包等。



../get-started/windows-setup.html../get-started/linux-setup.html../get-started/macos-setup.html../get-started/windows-setup.html../get-started/linux-setup.html../get-started/macos-setup.htmlhttps://github.com/espressif/esp-idfhttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d



请根据第一步中对Windows (ESP-IDF工具安装器)的介绍，安装所有必需工具。除了使用 ESP-IDF工具安装器，您也可以通过命令提示符窗口手动安装这些工具。具体步骤见下：

cd %userprofile%\esp\esp-idfinstall.bat

或使用Windows PowerShell

cd ~/esp/esp-idf./install.ps1


cd ~/esp/esp-idf./install.sh

1.7.3 自定义工具安装路径

本步骤中介绍的脚本将 ESP-IDF所需的编译工具默认安装在用户根文件夹中，即 Linux和MacOS系统中的 $HOME/.espressif和Windows系统的 %USERPROFILE%\.espressif。此外，您可以可以将工具安装到其他目录中，但请在运行安装脚本前，重新设置环境变量 IDF_TOOLS_PATH。注意，请确保您的用户已经具备了读写该路径的权限。

如果修改了 IDF_TOOLS_PATH变量，请确保该变量在每次执行“安装脚本”(install.bat、install.ps1或 install.sh)和导出脚本 (export.bat、export.ps1或 export.sh)均保持一致。

1.8 第四步：设置环境变量

此时，您刚刚安装的工具尚未添加至 PATH环境变量，无法通过“命令窗口”使用这些工具。因此，必须设置一些环境变量，这可以通过 ESP-IDF提供的另一个脚本完成。


Windows安装器（ESP-IDF工具安装器）可在“开始”菜单创建一个“ESP-IDF Command Prompt”快捷方式。该快捷方式可以打开命令提示符窗口，并设置所有环境变量。您可以点击该快捷方式，然后继续下一步。

此外，如果您希望在当下命令提示符窗口使用 ESP-IDF，请使用下方代码：

%userprofile%\esp\esp-idf\export.bat

或使用Windows PowerShell

.$HOME/esp/esp-idf/export.ps1


请在您需要运行 ESP-IDF的“命令提示符”窗口运行以下命令：

. $HOME/esp/esp-idf/export.sh





注意，命令开始的“.”与路径之间应有一个空格！此外，您也可以将这行代码增加至您的 .profile或 .bash_profile脚本中，这样您就可以在任何命令窗口使用 ESP-IDF工具了。

1.9 第五步：开始创建工程

现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 examples 目录下的 get-started/hello_world工程开始。将 get-started/hello_world复制至您本地的 ~/esp目录下：


cd ~/espcp -r $IDF_PATH/examples/get-started/hello_world .


cd %userprofile%\espxcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world

ESP-IDF的 examples目录下有一系列示例工程，都可以按照上面的方法进行创建。您可以按照上述方法复制并运行其中的任何示例，也可以直接编译示例，无需进行复制。

重要: ESP-IDF编译系统不支持带有空格的路径。

1.10 第六步：连接设备

现在，请将您的 ESP32开发板连接到 PC，并查看开发板使用的串口。通常，串口在不同操作系统下显示的名称有所不同：

• Windows操作系统： COM1等• Linux操作系统：以 /dev/tty开始• MacOS操作系统：以 /dev/cu.开始

有关如何查看串口名称的详细信息，请见与 ESP32创建串口连接。

注解: 请记住串口名，您会在下面的步骤中用到。

1.11 第七步：配置

请进入第五步：开始创建工程中提到的 hello_world目录，并运行工程配置工具 menuconfig。


cd ~/esp/hello_worldidf.py menuconfig



https://github.com/espressif/esp-idf/tree/741960d/exampleshttps://github.com/espressif/esp-idf/tree/741960d/examples/get-started/hello_worldhttps://github.com/espressif/esp-idf/tree/741960d/examples/get-started/hello_worldhttps://github.com/espressif/esp-idf/tree/741960d/examples/get-started/hello_worldhttps://github.com/espressif/esp-idf/tree/741960d/exampleshttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d



cd %userprofile%\esp\hello_worldidf.py menuconfig

打开一个新项目后，应首先设置“目标”芯片 idf.py set-target {IDF_TARGET}。注意，此操作将清除并初始化项目之前的编译和配置（如有）。您也可以直接将“目标”配置为环境变量（此时可跳过该步骤）。更多信息，请见选择“目标”芯片。

如果之前的步骤都正确，则会显示下面的菜单：

工程配置—主窗口

menuconfig工具的常见操作见下。

• 上下箭头：移动• 回车：进入子菜单• ESC 键：返回上级菜单或退出• 英文问号：调出帮助菜单（退出帮助菜单，请按回车键）。• 空格 ``或 ``Y 键：选择 [*]配置选项；N 键：禁用 [*]配置选项• 英文问号（查询配置选项）：调出有关该选项的帮助菜单• / 键：寻找配置工程

1.12 第八步：编译工程

请使用以下命令，编译烧录工程：:

idf.py build

运行以上命令可以编译应用程序和所有 ESP-IDF组件，接着生成 bootloader、分区表和应用程序二进制文件。

$ idf.py buildRunning cmake in directory /path/to/hello_world/buildExecuting "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...Warn about uninitialized values.-- Found Git:/usr/bin/git (found version "2.17.0")-- Building empty aws_iot component due to configuration-- Component names: ...

(下页继续)





(续上页)-- Component paths: ...

... (more lines of build system output)

[527/527] Generating hello-world.binesptool.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.binor run 'idf.py -p PORT flash'

如果一切正常，编译完成后将生成.bin文件。

1.13 第九步：烧录到设备

请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32开发板：idf.py -p PORT [-b BAUD] flash

请将 PORT替换为 ESP32开发板的串口名称，具体可见第六步：连接设备。您还可以将 BAUD替换为您希望的烧录波特率。默认波特率为 460800。更多有关 idf.py参数的详情，请见idf.py。

注解: 勾选 flash选项将自动编译并烧录工程，因此无需再运行 idf.py build。

Running esptool.py in directory [...]/esp/hello_worldExecuting "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800␣↪→write_flash @flash_project_args"...esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq␣↪→40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin␣↪→0x10000 hello-world.binesptool.py v2.3.1Connecting....Detecting chip type... ESP32Chip is ESP32D0WDQ6 (revision 1)Features: WiFi, BT, Dual CoreUploading stub...Running stub...Stub running...Changing baud rate to 460800Changed.Configuring flash size...Auto-detected Flash size: 4MBFlash params set to 0x0220Compressed 22992 bytes to 13019...Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9␣↪→kbit/s)...Hash of data verified.Compressed 3072 bytes to 82...Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3␣↪→kbit/s)...Hash of data verified.Compressed 136672 bytes to 67544...

(下页继续)





(续上页)Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.↪→5 kbit/s)...Hash of data verified.

Leaving...Hard resetting via RTS pin...

如果一切顺利，烧录完成后，开发板将会复位，应用程序“hello_world”开始运行。

注解: （目前不支持）如果您希望使用 Eclipse IDE，而非 idf.py，请参考Eclipse指南。

1.14 第十步：监视器

您可以使用 idf.py -p PORT monitor 命令，监视“hello_world”的运行情况。注意，不要忘记将PORT替换为您的串口名称。运行该命令后，IDF监视器应用程序将启动：:

$ idf.py -p /dev/ttyUSB0 monitorRunning idf_monitor in directory [...]/esp/hello_world/buildExecuting "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_↪→world/build/hello-world.elf"...--- idf_monitor on /dev/ttyUSB0 115200 ------ Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---ets Jun 8 2016 00:22:57

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)ets Jun 8 2016 00:22:57...

此时，您就可以在启动日志和诊断日志之后，看到打印的“Hello world!”了。

...Hello world!Restarting in 10 seconds...I (211) cpu_start: Starting scheduler on APP CPU.Restarting in 9 seconds...Restarting in 8 seconds...Restarting in 7 seconds...

您可使用快捷键 Ctrl+]，退出 IDF监视器。

注解: 您也可以运行以下命令，一次性执行构建、烧录和监视过程：idf.py -p PORT flash monitor

此外，

• 请前往IDF监视器，了解更多使用 IDF监视器的快捷键和其他详情。• 请前往idf.py，查看更多 idf.py命令和选项。

恭喜，您已完成 ESP32的入门学习！现在，您可以尝试一些其他 examples，或者直接开发自己的应用程序。



https://github.com/espressif/esp-idf/tree/741960d/exampleshttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


1.15 更新 ESP-IDF

乐鑫会不时推出更新版本的 ESP-IDF，修复 bug或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 esp-idf文件夹，然后按照第二步：获取 ESP-IDF中的指示，重新完成克隆。

此外，您可以仅更新变更部分。具体方式，请前往更新章节查看。

注意，更新完成后，请执行 install.sh（Windows系统中为 install.bat）脚本，避免新版 ESP-IDF所需的工具也有所更新。具体请参考第三步：设置工具。

一旦重新安装好工具，请使用“导出脚本”更新环境，具体请参考第四步：设置环境变量。

1.16 相关文档

1.16.1 与 ESP32创建串口连接

[English]本章节主要介绍如何创建 ESP32和 PC之间的串口连接。

连接 ESP32和 PC

用 USB线将 ESP32开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 ESP32开发板上的USB转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。以下是乐鑫 ESP32开发板驱动程序的链接：

• CP210x: CP210x USB至 UART桥 VCP驱动程序• FTDI: FTDI虚拟 COM端口驱动程序

以上驱动仅用于参考。一般情况下，当上述任一 ESP32开发板与 PC连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。

在Windows上查看端口

检查Windows设备管理器中的 COM端口列表。断开 ESP32与 PC的连接，然后重新连接，查看哪个端口从列表中消失，然后再次出现。

以下为 ESP32 DevKitC和 ESP32 WROVER KIT串口：

在 Linux和MacOS上查看端口

查看 ESP32开发板（或外部转串口适配器）的串口设备名称，请运行两次以下命令。首先，断开开发板或适配器，第一次运行命令；然后，连接开发板或适配器，第二次运行命令。其中，第二次运行命令后出现的端口即是 ESP32对应的串口：Linux

ls /dev/tty*

MacOS

ls /dev/cu.*

注解: 对于MacOS用户：若你没有看到串口，请检查你是否已按照《入门指南》安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13)的用户，你可能还需要手动允许驱动程序的



../../../../en/latest/esp32/get-started/establish-serial-connection.htmlhttps://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivershttps://www.ftdichip.com/Drivers/VCP.htmhttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


图 2: 设备管理器中 ESP32-DevKitC的 USB至 UART桥





图 3: Windows设备管理器中 ESP-WROVER-KIT的两个 USB串行端口





加载，具体可打开系统偏好设置 ->安全和隐私 ->通用，检查是否有信息显示：“来自开发人员的系统软件⋯”，其中开发人员的名称为 Silicon Labs或 FTDI。

在 Linux中添加用户到 dialout

当前登录用户应当可以通过 USB对串口进行读写操作。在多数 Linux版本中，你都可以通过以下命令，将用户添加到 dialout组，来获许读写权限:

sudo usermod -a -G dialout $USER

在 Arch Linux中，需要通过以下命令将用户添加到 uucp组中:

sudo usermod -a -G uucp $USER

请重新登录，确保串口读写权限可以生效。

确认串口连接

现在，请使用串口终端程序，验证串口连接是否可用。在本示例中，我们将使用 PuTTY SSH Client，PuTTYSSH Client既可用于Windows也可用于 Linux。你也可以使用其他串口程序并设置如下的通信参数。运行终端，配置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下截屏分别展示了在Windows和 Linux中配置串口和上述通信参数（如 115200-8-1-N）。注意，这里一定要选择在上述步骤中确认的串口进行配置。

图 4: 在Windows操作系统中使用 PuTTY设置串口通信参数

然后，请检查 ESP32是否有打印日志。如有，请在终端打开串口进行查看。这里，日志内容取决于加载到 ESP32的应用程序，下图即为一个示例。



https://www.putty.org/https://www.putty.org/https://www.putty.org/https://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


图 5: 在 Linux操作系统中使用 PuTTY设置串口通信参数





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:0x00clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00mode:DIO, clock div:2load:0x3fff0008,len:8load:0x3fff0010,len:3464load:0x40078000,len:7828load:0x40080000,len:252entry 0x40080034I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloaderI (45) boot: compile time 18:48:10

...

如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，你可以继续进行安装，并最终将应用程序上载到 ESP32。

注解: 在某些串口接线方式下，在 ESP32启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS＆ DTR引脚。该问题仅存在于将 RTS＆ DTR引脚直接连接到 EN＆ GPIO0引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 esptool文档。

注解: 请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 ESP32。此时，如果串口被占用则无法成功。

如你在安装 ESP32硬件开发的软件环境时，从第六步：连接设备跳转到了这里，请从第七步：配置继续阅读。

1.16.2 Eclipse IDE创建和烧录指南

[English]ESP-IDF V4.0将默认采用基于 CMake的编译系统。对此，我们还推出了针对 CMake编译系统的新 ESP-IDF Eclipse插件。具体操作，请见 ESP-IDF Eclipse插件。

1.16.3 IDF监视器

[English]IDF监视器是一个串行终端程序，用于收发目标设备串口的串行数据，IDF监视器同时还兼具 IDF的其他特性。

在 IDF中调用以下目标函数可以启用此监视器：• 若使用 CMake编译系统，则请调用：idf.py monitor• 若使用传统 GNUMake编译系统，请调用：make monitor

操作快捷键

为了方便与 IDF监视器进行交互，请使用表中给出的快捷键。



https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader../../../../en/latest/esp32/get-started/eclipse-setup.html../../../../../en/latest/esp32/api-guides/tools/idf-monitor.htmlhttps://www.espressif.com/en/company/documents/documentation_feedback?docId=4287&sections=&version=Release v4.2-dev-1206-g741960d


快捷键操作描述Ctrl+] 退出监视器程序Ctrl+T 菜单退出键按下如下给出的任意键�