ESP32 Dev Kitc 开发板

产品信息

规格

产品：ESP32
编程指南：ESP-IDF
发布版本：v5.0.9
制造商：乐鑫系统
发布日期：16 年 2025 月 XNUMX 日

产品使用说明

1. 开始

在开始使用 ESP32 之前，请先熟悉
下列的：

1.1 简介

了解
ESP32。

1.2 您需要什么

确保您拥有必要的硬件和软件：

硬件： 检查所需硬件列表
成分。
软件： 安装所需的软件
成分。

1.3 安装

按照以下步骤安装 IDE 并设置
环境：

集成开发环境（IDE）： 安装推荐的 IDE
对 ESP32 进行编程。
手动安装： 手动设置
如果需要的话。

1.4 构建你的第一个项目

使用 ESP32 创建并构建您的初始项目。

1.5 卸载 ESP-IDF

如果需要，请了解如何从您的
系统。

2. API 参考

有关以下方面的详细信息，请参阅 API 文档
应用程序协议、错误处理和配置
结构。

常见问题 (FAQ)

问：如何解决 ESP32 的常见问题？

答：请参阅编程指南中的故障排除部分
或访问制造商的 web支持资源网站。

问：我可以将 ESP-IDF 与其他微控制器一起使用吗？

答：ESP-IDF 是专门为 ESP32 设计的，但您可能会发现
与其他 Espressif 微控制器兼容。

View Fullscreen

ESP32
ESP-IDF 编程指南
乐鑫系统 2025 年 5 月 16 日发布 v5.0.9

1 开始

1.1 简介 .................................................................................................................................................................................................................................................................. 3

1.2 您需要什么 . ...

1.2.1 硬件................ ...

1.2.2 软件................ ...

1.3 安装................ ...

1.3.1 集成开发环境。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。 14

1.3.2 手动安装......................................................................................................................................................................................................14

1.4 构建您的第一个项目 . ...

1.5 卸载 ESP-IDF . ...

2 API 参考

2.1 API 约定................ ...

2.1.1 错误处理......................................................................................................................................................................................................................45

2.1.2 配置结构......................................................................................................................................................................................................45

2.1.3 私有 API ...................................................................................................................................................................................... 46

2.1.4 ex中的组件amp项目. ...

2.1.5 API 稳定性......................................................................................................................................................................................................47

2.2 应用协议................ ...

2.2.1 ASIO 端口。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。 48

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

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

2.2.4 ESP-TLS . ...

2.2.5 ESP HTTP 客户端. ...

2.2.6 ESP 本地控制. ...

2.2.7 ESP 串行从属链路. ...

2.2.8 ESP x509 证书包. ...

2.2.9 HTTP 服务器................................................................................................................................................................................................................................................................123

2.2.10 HTTPS 服务器. ...

2.2.11 ICMP 回显. ...

2.2.12 mDNS 服务 . ...

2.2.13 Mbed TLS . ...

2.2.14 IP 网络层................ ...

2.3 蓝牙 API .................................................................................................................................................................................................. 161

2.3.1 蓝牙® 通用 . ...

2.3.2 低功耗蓝牙® . ...

2.3.3 经典蓝牙® . ...

2.3.4 控制器和 HCI . ...

2.3.5 ESP-BLE-MESH . ...

2.3.6 基于 NimBLE 的主机 API . ...

2.4 错误代码参考. ...

2.5 网络 API . ...

2.5.1 无线网络。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。第776章

2.5.2 以太网................................................................................................................................................................................................899

2.5.3 线程................................................................................................................................................................................................................936

2.5.4 ESP-NETIF。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942 2.5.5 IP网络层. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974 2.5.6 应用层. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976 2.6 外围设备 API。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977 2.6.1 模数转换器 (ADC) 单触发模式驱动器. . . . . . . . . . . . . . . . . 977 2.6.2 模数转换器 (ADC) 连续模式驱动器. . . . . . . . . . . . . . . 986 2.6.3 模数转换器 (ADC) 校准驱动器. . . . . . . . . . . . . . . . . . . 993 2.6.4 时钟树. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997 2.6.5 数模转换器 (DAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004 2.6.6 GPIO 和 RTC GPIO。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008 2.6.7 通用计时器（GPTimer）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027 2.6.8 内部集成电路（I2C）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039 2.6.9 集成电路间声音（I2S）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056 2.6.10 液晶显示器。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090 2.6.11 LED控制（LEDC）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107 2.6.12 电机控制脉冲宽度调制器（MCPWM）. . . . . . . . . . . . . . . . . . . . . 1126 2.6.13 脉冲计数器（PCNT）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178 2.6.14 远程控制收发器（RMT）. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193 2.6.15 SD 上拉要求. ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220 2.6.16 SDMMC 主机驱动程序. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223 2.6.17 SD SPI 主机驱动程序. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229 2.6.18 SDIO 卡从属驱动程序. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234 2.6.19 Sigma-Delta调制（SDM）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1244 2.6.20 SPI 主驱动程序. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249 2.6.21 SPI 从属驱动程序. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274 2.6.22 ESP32-WROOM-32SE（安全元件）。 . . . . . . . . . . . . . . . . . . . . . . . . 1281 2.6.23 触摸传感器. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1282 2.6.24 双线汽车接口（TWAI）. . . . . . . . . . . . . . . . . . . . . . . . . . 1299 2.6.25 通用异步接收器/发送器（UART）. . . . . . . . . . . . . . . . . . 1317 2.7 项目配置. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 2.7.1 简介 . ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 2.7.2 项目配置菜单. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 2.7.3 使用 sdkconfig.defaults 。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 2.7.4 Kconfig 格式规则 . ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343 2.7.5 Kconfig 选项的向后兼容性 . ... . . . . . . . . . . . . . . . . . . . . . . . 1343 2.7.6 配置选项参考. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343 2.8 配置 API。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647 2.8.1 协议通信. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647 2.8.2 统一配置. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665 2.8.3 Wi-Fi 配置。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669 2.9 存储 API。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File系统支持. ... 1703 2.9.4 NVS 分区生成器实用程序 . ... . . . . . . . . . . . . . 1744 2.9.7 SPIFFS File系统. ... file系统组件 . ... . ... . ... . ...
ii

2.10.8 ESP HTTPS OTA . ...view) . ... . 1988 2.10.13 堆内存分配. ... . ... . ... . ... 2087 2.10.24 POSIX 线程支持 . ... . ... . ...

3 硬件参考

2167

3.1 芯片系列比较......................................................................................................................................................................................................................2167

3.1.1 相关文件................ ...

4 API 指南

2171

4.1 应用程序级跟踪库. ...

4.1.1 结束view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171个

4.1.2 操作模式................ ...

4.1.3 配置选项和依赖项 . ...

4.1.4 如何使用本库 . ...

4.2 应用程序启动流程................ ...

4.2.1 第一秒tage 引导加载程序. ...

4.2.2 秒tage 引导加载程序. ...

4.2.3 应用程序启动................................................................................................................................................................................................................................2183

4.3 经典蓝牙® . ...

4.3.1 结束view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2184个

4.4 低功耗蓝牙® . ...

4.4.1 结束view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186个

4.4.2 开始使用 . ...

4.4.3 专业版file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2240个

4.5 引导加载程序................ ...

4.5.1 引导加载程序兼容性 . ...

4.5.2 日志级别................ ...

4.5.3 恢复出厂设置................ ...

4.5.4 从测试固件启动 . ...

4.5.5 回滚................ ...

4.5.6 看门狗................ ...

4.5.7 引导加载程序大小. ...

4.5.8 从深度睡眠模式快速启动 . ...

4.5.9 自定义引导加载程序. ...

4.6 构建系统 . ...

4.6.1 结束view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288个

4.6.2 使用构建系统 . ...

三

第4.6.3章ample 项目 . ... File . ... Files . ... 2295 4.6.8 组件要求 . ... 2300 4.6.11 调试 CMake . ...ample 组件 CMakeLists . ... . ... 2306 4.6.18 使用带有组件的预构建库 . ... File 通配符和增量构建 . ... 2313 4.6.24 从 ESP-IDF GNU Make 系统迁移 . ...view . ... . ... . ... . ... . ...ample . ...view . ... . . . 2324 4.9.4 ESP_ERROR_CHECK 宏 . ... 2325 4.9.7 ESP_GOTO_ON_ERROR 宏. ... . 2325 4.9.10 检查宏 Examples . ... 2327 4.10 ESP-WIFI-MESH . ...view . ... . ... . ...
iv

4.10.8 性能 . ... . ... . ...view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2350 4.12.2 紧急处理程序。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2350 4.12.3 寄存器转储和回溯。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2351 4.12.4 GDB 存根。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2353 4.12.5 RTC 看门狗超时。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2354 4.12.6 上师冥想错误。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2354 4.12.7 其他致命错误. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2356 4.13 Flash 加密. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2358 4.13.1 简介 . ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359 4.13.2 相关电子保险丝。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359 4.13.3 Flash加密过程. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2360 4.13.4 Flash 加密配置. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2360 4.13.5 可能的故障. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2366 4.13.6 ESP32 Flash 加密状态. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2368 4.13.7 读取和写入加密闪存中的数据. . . . . . . . . . . . . . . . . . . . . . . 2368 4.13.8 更新加密的 Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2369 4.13.9 禁用 Flash 加密. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2369 4.13.10 关于 Flash 加密的要点 . ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2370 4.13.11 Flash 加密的局限性 . ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2370 4.13.12 Flash 加密和安全启动. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2371 4.13.13 高级功能. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2371 4.13.14 技术细节. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2373 4.14 硬件抽象. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2373 4.14.1 架构。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2374 4.14.2 LL（低级）层。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2375 4.14.3 HAL（硬件抽象层）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2376 4.15 高级中断. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2377 4.15.1 中断级别. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2377 4.15.2 注释。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TAG 调试. ... . ...TAG 适配器. ... ... 2380 4.16.6 启动调试器. ...amples . ... . 2391 4.16.10 相关文档 . ...view . ... . ... . ... . ...
v

4.18.7 性能优化 . ...
4.19.1 DRAM（数据 RAM） . ... . ... . ... . ... . ...view . ... . ... . ... . ... 2468 4.23.1 部分校准. ... . ... . ...view . ... . ... . 2475 4.24.8 远程图像签名 . ... . ... 2478 4.25 安全启动 V2 . ...tages . ... . ... . ... 2481 4.25.10 如何启用安全启动 V2 . ...
vi

4.25.13 远程图像签名 . ... . ... 2485 4.26 对外部 RAM 的支持 . ... . ... . ... . 2488 4.27.1 超过view . ... . ... 2489 4.28.1 IDF 前端 – idf.py . ... . ... . ... 2512 4.29.2 多设备测试用例. ...tag测试用例。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2514 4.29.4 针对不同目标的测试. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2514 4.29.5 构建单元测试应用程序。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2515 4.29.6 运行单元测试. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2515 4.29.7 带有缓存补偿定时器的计时代码。 . . . . . . . . . . . . . . . . . . . . . . 2516 4.29.8 模拟。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2517 4.30 Linux 上的单元测试。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2519 4.30.1 嵌入式软件测试 . ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2519 4.30.2 Linux 主机上的 IDF 单元测试 . ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2520 4.31 Wi-Fi 驱动程序。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521 4.31.1 ESP32 Wi-Fi 功能列表。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521 4.31.2 如何编写 Wi-Fi 应用程序。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521 4.31.3 ESP32 Wi-Fi API 错误代码。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2522 4.31.4 ESP32 Wi-Fi API 参数初始化 . . . . . . . . . . . . . . . . . . . . . . . . . 2522 4.31.5 ESP32 Wi-Fi 编程模型。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2522 4.31.6 ESP32 Wi-Fi 事件描述. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2523 4.31.7 ESP32 Wi-Fi 站通用场景。 . . . . . . . . . . . . . . . . . . . . . . . . . . 2526 4.31.8 ESP32 Wi-Fi AP 通用场景 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2529 4.31.9 ESP32 Wi-Fi 扫描。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2529 4.31.10 ESP32 Wi-Fi 站连接场景. . . . . . . . . . . . . . . . . . . . . . . . . 2536 4.31.11 当发现多个 AP 时，ESP32 Wi-Fi 站进行连接。 . . . . . . . . . . . . 2543 4.31.12 Wi-Fi 重新连接。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543 4.31.13 Wi-Fi 信标超时。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543 4.31.14 ESP32 Wi-Fi 配置。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543 4.31.15 Wi-Fi 轻松连接 (DPP)。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549 4.31.16 无线网络管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549 4.31.17 无线电资源测量. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549 4.31.18 快速 BSS 转换。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2550 4.31.19 ESP32 Wi-Fi 省电模式。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2550 4.31.20 ESP32 Wi-Fi 吞吐量。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
七

4.31.21 Wi-Fi 80211 数据包发送 . ... . ... 。。。。。。。。。。。。。。 2557 4.31.27 Wi-Fi 服务质量。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。 2557 4.31.28 Wi-Fi AMSDU。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。 2558 4.31.29 Wi-Fi 碎片. ... . ... . ... . ... . ...view . ... 2574 4.33.4 如何使用共存功能 . ... . ... . ... . . . 2578

5 个迁移指南

2579

5.1 ESP-IDF 5.x 迁移指南. ...

5.1.1 从 4.4 迁移到 5.0 . ...

6 库和框架

2611

6.1 云框架................ ...

6.1.1 ESP RainMaker . ...

6.1.2 亚马逊AWS 物联网. ...

6.1.3 Azure 物联网......................................................................................................................................................................................................2611

6.1.4 谷歌物联网核心. ...

6.1.5 阿里云物联网。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。 2611

6.1.6 Joylink 物联网......................................................................................................................................................................................2611

6.1.7 腾讯物联网................................................................................................................................................................................2612

6.1.8 腾讯云 IoT................................................................................................................................................................................2612

6.1.9 百度物联网................................................................................................................................................................................2612

6.2 Espressifns 框架 . ...

6.2.1 乐鑫音频开发框架. ...

6.2.2 ESP-CSI . ...

6.2.3 Espressif DSP 库. ...

6.2.4 ESP-WIFI-MESH 开发框架. ...

6.2.5 ESP-WHO . ...

6.2.6 ESP RainMaker . ...

6.2.7 ESP-IoT-解决方案. ...

6.2.8 ESP 协议. ...

八

6.2.9 ESP-BSP . ...

7 贡献指南

2615

7.1 如何贡献 . ...

7.2 贡献之前 . ...

7.3 拉取请求流程 . ...

7.4 法律部分................ ...

7.5 相关文件 .................................................................................................................................................................................................................................. 2616

7.5.1 乐鑫物联网开发框架风格指南. ...

7.5.2 为 ESP-IDF 项目安装 pre-commit Hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2623

7.5.3 记录代码 . ...

7.5.4 创建Examp莱斯。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。 2629

7.5.5 API 文档模板. ...

7.5.6 贡献者协议 . ...

7.5.7 版权标题指南. ...

7.5.8 使用 Pytest 进行 ESP-IDF 测试指南 . ...

8 ESP-IDF 版本

2645

8.1 版本 . ...

8.2 我应该从哪个版本开始？. ...

8.3 版本控制方案 . ...

8.4 支持期 . ...

8.5 检查当前版本 . ...

8.6 Git 工作流程 . ...

8.7 更新 ESP-IDF . ...

8.7.1 更新至稳定版本 . ...

8.7.2 更新至预发布版本 . ...

8.7.3 更新至主分支 . ...

8.7.4 更新至发布分支 . ...

9 资源

2651

9.1 平台 IO . ...

9.1.1 什么是 PlatformIO？..................................................................................................................................................................2651

9.1.2 安装................ ...

9.1.3 配置................ ...

9.1.4 教程................ ...

9.1.5 项目示例amp莱斯。 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2652

9.1.6 后续步骤 . ...

9.2 有用的链接 . ...

10 版权和许可

2653

10.1 软件版权 . ...

10.1.1 固件组件. ...

10.1.2 文档................ ...

10.2 ROM 源代码版权. ...

10.3 Xtensa libhal MIT 许可证。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。 2655

10.4 TinyBasic Plus MIT 许可证。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。 2655

10.5 TJpgDec 许可证. ...

11 关于

2657

12 切换语言

2659

指数

2661

指数

2661

目录
这是乐鑫物联网开发框架 (esp-idf) 的文档。ESP-IDF 是 ESP32、ESP32-S 和 ESP32-C 系列 SoC 的官方开发框架。本文档介绍了如何在 ESP32 SoC 上使用 ESP-IDF。

立即开始

API 参考

API 指南

乐鑫系统

1 提交文档反馈

发布 v5.0.9

乐鑫系统

2 提交文档反馈

发布 v5.0.9

第三章
立即开始
本文档旨在帮助您搭建基于乐鑫 ESP32 芯片的硬件软件开发环境。之后，一个简单的示例ample 将向您展示如何使用 ESP-IDF（Espressif IoT 开发框架）进行菜单配置，然后构建和刷写固件到 ESP32 板上。
注意：本文档适用于 ESP-IDF 稳定版本 v5.0.9。其他 ESP-IDF 版本也可用。
1.1 简介
ESP32 是一款片上系统，集成了以下功能：· Wi-Fi（2.4 GHz 频段）· 蓝牙· 双高性能 Xtensa® 32 位 LX6 CPU 内核· 超低功耗协处理器· 多种外设
ESP32 采用 40 纳米工艺，提供强大且高度集成的平台，有助于满足用户对高效功耗、紧凑设计、安全性、高性能和可靠性的持续需求。乐鑫提供基础硬件和软件资源，帮助应用开发者利用 ESP32 系列硬件实现他们的想法。乐鑫的软件开发框架旨在开发具有 Wi-Fi、蓝牙、电源管理和其他多种系统功能的物联网 (IoT) 应用。
1.2 您需要什么
1.2.1 硬件
· ESP32 开发板。· USB 线 – USB A / micro USB B。· 运行 Windows、Linux 或 macOS 的计算机。
注意：目前部分开发板使用的是 USB Type C 接口。请确保您使用正确的线缆连接开发板！
如果您拥有下面列出的 ESP32 官方开发板之一，您可以点击链接了解有关硬件的更多信息。
3

第 1 章开始
ESP32-DevKitS(-R)
本用户指南介绍了乐鑫基于 ESP32 的烧录板 ESP32-DevKitS(-R)。ESP32-DevKitS(-R) 是两个开发板名称的组合：ESP32-DevKitS 和 ESP32-DevKitS-R。S 代表弹簧，R 代表 WROVER。

ESP32-DevKitS

ESP32-DevKitS-R

本文档由以下主要部分组成：· 入门：提供view ESP32-DevKitS(-R) 的硬件和软件设置说明。· 硬件参考：提供有关 ESP32-DevKitS(-R)ns 硬件的更多详细信息。· 相关文档：提供相关文档的链接。

入门指南本节介绍如何开始使用 ESP32-DevKitS(-R)。首先介绍一下 ESP32-DevKitS(-R)，然后“如何烧写开发板”一节介绍如何将模块安装到 ESP32-DevKitS(-R) 上，准备工作以及如何烧写固件。

超过view ESP32-DevKitS(-R) 是乐鑫专为 ESP32 设计的烧录板。它可用于烧录 ESP32 模组，无需将模组焊接到电源和信号线上。安装模组后，ESP32-DevKitS(-R) 也可以像 ESP32-DevKitC 一样用作迷你开发板。
ESP32-DevKitS 和 ESP32-DevKitS-R 开发板仅在弹簧针的布局上有所不同，以适应以下 ESP32 模块。
· 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
有关以上模块的信息，请参阅 ESP32 系列模块。

组件说明

乐鑫系统

4 提交文档反馈

发布 v5.0.9

第 1 章开始

图 1：ESP32-DevKitS – 正面

乐鑫系统

图 2：ESP32-DevKitS-R – 正面 5
提交文档反馈

发布 v5.0.9

第 1 章开始

关键元件弹簧针 2.54 毫米母头
USB 转 UART 桥接器 LDO Micro-USB 连接器/Micro USB 端口 EN 按钮启动按钮
开机指示灯

描述：将模块卡入。引脚将插入模块的凹槽。这些母头与安装在该板上的模块的引脚相连。有关母头的说明，请参阅“母头块”。单芯片 USB 转 UART 桥接器提供高达 3 Mbps 的传输速率。
5V至3.3V低压差电压tag稳压器（LDO）。
USB接口。为开发板供电，以及作为电脑与开发板之间的通信接口。
重置按钮。
下载按钮。按住 Boot 键，然后按下 EN 键，启动固件下载模式，通过串口下载固件。
当 USB 或电源连接到电路板时亮起。

如何刷写开发板在启动 ESP32-DevKitS(-R) 之前，请确保其状况良好且没有明显损坏迹象。
所需硬件 · 您选择的 ESP32 模块 · USB 2.0 线缆（标准 A 至 Micro-B） · 运行 Windows、Linux 或 macOS 的计算机
硬件设置请按照以下步骤将您选择的模块安装到您的 ESP32-DevKitS(-R) 上：
· 将模块轻轻地放置在 ESP32-DevKitS(-R) 开发板上。确保模块上的齿孔与开发板上的弹簧销对齐。
· 将模块向下按入电路板，直至听到咔嗒声。· 检查所有弹簧销是否已插入槽孔。如果发现某些弹簧销未对准，
用镊子将它们放入城垛孔中。
软件设置
首选方法 ESP-IDF 开发框架提供了一种将二进制文件烧录到 ESP32-DevKitS(-R) 的首选方法。请继续阅读“入门指南”，其中的“安装”部分将帮助您快速设置开发环境，然后烧录应用程序示例。amp到您的 ESP32-DevKitS(-R) 上。
替代方法：Windows 用户可以使用 Flash 下载工具来烧录二进制文件。只需下载、解压，然后按照 doc 文件夹中的说明操作即可。
注意：1. 要烧录二进制文件 files，ESP32 应设置为固件下载模式。这可以通过烧写工具自动完成，也可以通过按住 Boot 按钮并点击 EN 按钮完成。2. 烧写二进制文件后 files，Flash 下载工具会重新启动您的 ESP32 模块并默认启动闪存的应用程序。

电路板尺寸内容和包装

乐鑫系统

6 提交文档反馈

发布 v5.0.9

第 1 章入门图 3：ESP32-DevKitS 开发板尺寸 - 背面

乐鑫系统

图 4：ESP32-DevKitS-R 开发板尺寸 - 背面 7
提交文档反馈

发布 v5.0.9

第 1 章开始
零售订单如果您订购几件amp每个 ESP32-DevKitS(-R) 均采用独立包装，可选防静电袋或零售商指定的其他包装。零售订单请访问 https://www.espressif.com/en/contact-us/get-samp莱斯。
批发订单：如果您批量订购，电路板将装在大纸箱中。批发订单请访问 https://www.espressif.com/en/contact-us/sales-questions。
硬件参考
框图下面的框图显示了 ESP32-DevKitS(-R) 的组件及其互连。

图 5：ESP32-DevKitS(-R)（点击放大）
电源选项有三种互斥的方式为电路板供电：· Micro USB 端口，默认电源· 5V 和 GND 接头引脚· 3V3 和 GND 接头引脚
建议使用第一个选项：micro USB 端口。

乐鑫系统

标签信号

L1 3V3 VDD 3V3

L2 EN 芯片_PU

L3 VP 传感器_VP

L4 VN 传感器_VN

L5 34

GPIO34

L6 35

GPIO35

L7 32

GPIO32

L8 33

GPIO33

下一页继续

8 提交文档反馈

发布 v5.0.9

第 1 章开始

表 1 接上页

标签信号

L9 25

GPIO25

L10 26

GPIO26

L11 27

GPIO27

L12 14

GPIO14

L13 12

GPIO12

L14 接地接地

L15 13

GPIO13

L16 D2 SD_DATA2

L17 D3 SD_DATA3

L18 命令 SD_CMD

L19 5V

外接5V

R1 接地接地

R2 23

GPIO23

R3 22

GPIO22

R4 TX U0TXD

R5 RX U0RXD

R6 21

GPIO21

R7 接地接地

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 时钟 SD_CLK

标题块有关标题块的图像，请参阅组件说明。

相关文件
· ESP32-DevKitS(-R) 原理图 (PDF) · ESP32 技术规格书 (PDF) · ESP32-WROOM-32 技术规格书 (PDF) · ESP32-WROOM-32D 和 ESP32-WROOM-32U 技术规格书 (PDF) · ESP32-SOLO-1 技术规格书 (PDF) · ESP32-WROVER 技术规格书 (PDF) · ESP32-WROVER-B 技术规格书 (PDF) · ESP 产品选型指南

ESP32-DevKitM-1

本用户指南将帮助您开始使用 ESP32-DevKitM-1，并提供更深入的信息。
ESP32-DevKitM-1 是一款基于乐鑫 ESP32-MINI-1(1U) 的开发板。其大部分 I/O 引脚已引出至两侧的排针，方便连接。用户可以使用跳线连接外设，也可以将 ESP32-DevKitM-1 安装到面包板上。

乐鑫系统

9 提交文档反馈

发布 v5.0.9

第 1 章开始

ESP32-DevKitM-1 – 正面

ESP32-DevKitM-1 – 等距视图

本文档由以下主要部分组成：· 入门：提供view ESP32-DevKitM-1 的硬件/软件设置说明，帮助您快速入门。· 硬件参考：提供关于 ESP32-DevKitM-1ns 硬件的更多详细信息。· 相关文档：提供相关文档的链接。

入门指南本节介绍如何开始使用 ESP32-DevKitM-1。首先介绍 ESP32-DevKitM-1，然后“开始应用程序开发”部分介绍如何进行初始硬件设置以及如何将固件烧录到 ESP32-DevKitM-1。

超过view 这是一款小巧方便的开发板，具有以下特点：
· ESP32-MINI-1 或 ESP32-MINI-1U 模块 · USB 转串行编程接口，也为开发板提供电源 · 排针 · 用于重置和激活固件下载模式的按钮 · 一些其他组件

内容和包装

零售订单如果您订购几件amp每个 ESP32-DevKitM-1 均采用独立包装，可以是防静电袋，也可以是其他包装，具体取决于零售商。
对于零售订单，请访问 https://www.espressif.com/en/contact-us/get-samp莱斯。

批发订单：如果您批量订购，电路板将装在大纸箱中。批发订单请访问 https://www.espressif.com/en/contact-us/sales-questions。

组件描述下图和下表描述了 ESP32-DevKitM-1 开发板的主要组件、接口和控制方式。我们以搭载 ESP32-MINI-1 模组的开发板为例。ample 在以下各节中。

乐鑫系统

10 提交文档反馈

发布 v5.0.9

第 1 章开始

图 6：ESP32-DevKitM-1 – 正面

关键部件车载模块
5 V 至 3.3 V LDO 启动按钮
重置按钮 Micro-USB 端口
USB 转 UART 桥接器 3.3 V 电源开启 LED
I/O 连接器

描述
ESP32-MINI-1 模组或 ESP32-MINI-1U 模组。ESP32-MINI-1 模组自带 PCB 板载天线。ESP32-MINI-1U 模组配备外置天线接口。两款模组均内置 4 MB Flash。详情请参阅 ESP32-MINI-1 和 ESP32-MINI-1U 产品规格书。
电源稳压器将 5 V 转换为 3.3 V。
下载按钮。按住 Boot 键，然后按下 Reset 键，即可启动固件下载模式，通过串行端口下载固件。
重置按钮
USB接口。电路板的电源以及计算机与 ESP32 芯片之间的通信接口。
单个 USB-UART 桥接芯片提供高达 3 Mbps 的传输速率。
当 USB 连接到开发板时亮起。详情请参阅相关文档中的原理图。所有可用的 GPIO 引脚（用于闪存的 SPI 总线除外）均已引出至开发板上的排针。用户可以对 ESP32 芯片进行编程以实现多种功能。

开始应用程序开发在启动 ESP32-DevKitM-1 之前，请确保其状况良好且没有明显损坏迹象。
所需硬件 · ESP32-DevKitM-1 · USB 2.0 线缆（Standard-A 转 Micro-B） · 运行 Windows、Linux 或 macOS 的计算机
软件设置请继续进行“开始”，其中的“安装”部分将快速帮助您设置开发环境，然后刷新应用程序示例amp文件到您的 ESP32-DevKitM-1 上。

乐鑫系统

11 提交文档反馈

发布 v5.0.9

第 1 章开始
注意：2021 年 12 月 2 日之前生产的 ESP32-DevKitM-1 开发板安装的是单核模块。如需验证您的模块型号，请查看 PCN-2021-021 中的模块标识信息。如果您的开发板安装了单核模块，请在烧写应用程序之前在 menuconfig 中启用单核模式 (CONFIG_FREERTOS_UNICORE)。
硬件参考框图下面的框图显示了 ESP32-DevKitM-1 的组件及其互连。

图 7：ESP32-DevKitM-1
电源选择有三种互斥的方式为电路板供电：· Micro USB 端口，默认电源· 5V 和 GND 接头引脚· 3V3 和 GND 接头引脚
警告：· 必须使用上述选项之一（且只能使用其中一种）来提供电源，否则可能会损坏电路板和/或电源。· 建议使用微型 USB 端口供电。

引脚说明下表列出了开发板两侧引脚的名称和功能。外围引脚配置请参考 ESP32 Datasheet。

不。

姓名

类型

地线

3V3

功能接地 3.3 V 电源

下一页继续

乐鑫系统

12 提交文档反馈

发布 v5.0.9

第 1 章开始

表 2 接上页

不。

姓名

类型

功能

I36

GPIO36、ADC1_CH0、RTC_GPIO0

I37

GPIO37、ADC1_CH1、RTC_GPIO1

I38

GPIO38、ADC1_CH2、RTC_GPIO2

I39

GPIO39、ADC1_CH3、RTC_GPIO3

恢复时间

重置; 高：启用；低：关机

I34

GPIO34、ADC1_CH6、RTC_GPIO4

I35

GPIO35、ADC1_CH7、RTC_GPIO5

IO32

输入/输出

GPIO32，XTAL_32K_P（32.768 kHz晶体振荡器输入），

ADC1_CH4、TOUCH9、RTC_GPIO9

IO33

输入/输出

GPIO33、XTAL_32K_N（32.768 kHz 晶振输出）、

ADC1_CH5、TOUCH8、RTC_GPIO8

IO25

输入/输出

GPIO25、DAC_1、ADC2_CH8、RTC_GPIO6、EMAC_RXD0

IO26

输入/输出

GPIO26、DAC_2、ADC2_CH9、RTC_GPIO7、EMAC_RXD1

IO27

输入/输出

GPIO27、ADC2_CH7、TOUCH7、RTC_GPIO17、EMAC_RX_DV

IO14

输入/输出

GPIO14、ADC2_CH6、TOUCH6、RTC_GPIO16、MTMS、HSPICLK、

HS2_CLK、SD_CLK、EMAC_TXD2

5 V电源

IO12

输入/输出

GPIO12、ADC2_CH5、TOUCH5、RTC_GPIO15、MTDI、HSPIQ、

HS2_DATA2、SD_DATA2、EMAC_TXD3

IO13

输入/输出

GPIO13、ADC2_CH4、TOUCH4、RTC_GPIO14、MTCK、HSPID、

HS2_DATA3、SD_DATA3、EMAC_RX_ER

IO15

输入/输出

GPIO15、ADC2_CH3、TOUCH3、RTC_GPIO13、MTDO、HSPICS0、

HS2_CMD、SD_CMD、EMAC_RXD3

IO2

输入/输出

GPIO2、ADC2_CH2、TOUCH2、RTC_GPIO12、HSPIWP、

HS2_DATA0，SD_DATA0

IO0

输入/输出

GPIO0、ADC2_CH1、TOUCH1、RTC_GPIO11、CLK_OUT1、

EMAC_TX_CLK

IO4

输入/输出

GPIO4、ADC2_CH0、TOUCH0、RTC_GPIO10、HSPIHD、

HS2_DATA1、SD_DATA1、EMAC_TX_ER

IO9

输入/输出

GPIO9、HS1_DATA2、U1RXD、SD_DATA2

IO10

输入/输出

GPIO10、HS1_DATA3、U1TXD、SD_DATA3

IO5

输入/输出

GPIO5、HS1_DATA6、VSPICS0、EMAC_RX_CLK

IO18

输入/输出

GPIO18、HS1_DATA7、VSPICLK

IO23

输入/输出

GPIO23、HS1_STROBE、VSPID

IO19

输入/输出

GPIO19、VSPIQ、U0CTS、EMAC_TXD0

IO22

输入/输出

GPIO22、VSPIWP、U0RTS、EMAC_TXD1

IO21

输入/输出

GPIO21、VSPIHD、EMAC_TX_EN

发送端0

输入/输出

GPIO1、U0TXD、CLK_OUT3、EMAC_RXD2

RXD0

输入/输出

GPIO3、U0RXD、CLK_OUT2

硬件修订详细信息没有可用的先前版本。
相关文件
· ESP32-MINI-1 和 ESP32-MINI-1U 数据手册 (PDF) · ESP32-DevKitM-1 原理图 (PDF) · ESP32-DevKitM-1 PCB 布局 (PDF) · ESP32-DevKitM-1 布局 (DXF) – 您可以 view 与 Autodesk 合作 View在线 · ESP32 数据表 (PDF) · ESP 产品选择器
如需该板的其他设计文档，请联系我们：sales@espressif.com。

乐鑫系统

13 提交文档反馈

发布 v5.0.9

第 1 章开始
1.2.2软件
要在 ESP32 上开始使用 ESP-IDF，请安装以下软件：· 用于编译 ESP32 代码的工具链· 用于构建 ESP32 完整应用程序的构建工具 - CMake 和 Ninja· ESP-IDF 主要包含 ESP32 的 API（软件库和源代码）以及用于操作工具链的脚本

1.3 安装
为了安装所有必需的软件，我们提供了几种不同的方法。请从可用的选项中选择一种。
1.3.1 IDE

注意：我们强烈建议通过您最喜欢的 IDE 安装 ESP-IDF。
· Eclipse 插件 · VSCode 扩展

1.3.2 手动安装
对于手动过程，请根据您的操作系统进行选择。

乐鑫系统

14 提交文档反馈

发布 v5.0.9

第 1 章开始
Windows 工具链的标准设置
简介 ESP-IDF 需要安装一些必备工具，以便为支持的芯片构建固件。必备工具包括 Python、Git、交叉编译器、CMake 和 Ninja 构建工具。本入门指南将使用命令提示符，但安装 ESP-IDF 后，您可以使用 Eclipse 插件或其他支持 CMake 的图形化 IDE。注意：限制：– ESP-IDF 和 ESP-IDF 工具的安装路径不得超过 90 个字符。安装路径过长可能会导致构建失败。– Python 或 ESP-IDF 的安装路径不得包含空格或括号。– Python 或 ESP-IDF 的安装路径不应包含特殊字符（非 ASCII），除非操作系统配置了 oUnicode UTF-8psupport。系统管理员可以通过控制面板启用支持 - 更改日期、时间或数字格式 - 管理选项卡 - 更改系统区域设置 - 选中选项 oBeta：使用 Unicode UTF-8 提供全球语言支持 - 确定并重新启动计算机。
ESP-IDF 工具安装程序安装 ESP-IDFns 先决条件的最简单方法是下载其中一个 ESP-IDF 工具安装程序。

Windows 安装程序下载
在线和离线安装程序的用途是什么？在线安装程序非常小巧，可以安装所有可用的 ESP-IDF 版本。安装程序在安装过程中只会下载必要的依赖项，包括适用于 Windows 的 Git。安装程序会存储下载的 file缓存目录 %userpro 中的file%. 表达
离线安装程序不需要任何网络连接。安装程序包含所有必需的依赖项，包括适用于 Windows 的 Git。
安装的组件安装程序部署以下组件：
· 嵌入式 Python · 交叉编译器 · OpenOCD · CMake 和 Ninja 构建工具 · ESP-IDF
安装程序还允许重复使用 ESP-IDF 的现有目录。推荐的目录是 %userprofile%Desktopesp-idf 其中 %userprofile% 是您的主目录。

乐鑫系统

15 提交文档反馈

发布 v5.0.9

第 1 章开始
启动 ESP-IDF 环境在安装过程结束时，您可以选择“运行 ESP-IDF PowerShell 环境”或“运行 ESP-IDF 命令提示符 (cmd.exe)”选项。安装程序将在所选的提示符下启动 ESP-IDF 环境。运行 ESP-IDF PowerShell 环境：

图 8：使用“运行 ESP-IDF PowerShell 环境”完成 ESP-IDF 工具设置向导
运行 ESP-IDF 命令提示符 (cmd.exe)：
使用命令提示符在接下来的入门步骤中，我们将使用 Windows 命令提示符。ESP-IDF 工具安装程序还会在“开始”菜单中创建一个快捷方式，用于启动 ESP-IDF 命令提示符。此快捷方式会启动命令提示符 (cmd.exe) 并运行 export.bat 脚本来设置环境变量（PATH、IDF_PATH 等）。在此命令提示符中，所有已安装的工具均可用。请注意，此快捷方式仅适用于 ESP-IDF 工具安装程序中选择的 ESP-IDF 目录。如果您的计算机上有多个 ESP-IDF 目录（例如amp例如，为了与不同版本的 ESP-IDF 配合使用，您有两种使用方式：
1. 创建 ESP-IDF 工具安装程序创建的快捷方式的副本，并将新快捷方式的工作目录更改为您要使用的 ESP-IDF 目录。
2. 或者，运行 cmd.exe，然后切换到要使用的 ESP-IDF 目录，并运行 export.bat。请注意，与上一个选项不同，此方法要求 Python 和 Git 位于 PATH 中。如果您遇到与未找到 Python 或 Git 相关的错误，请使用第一个选项。
ESP-IDF 上的第一步现在所有要求都已满足，下一个主题将指导您如何启动您的第一个项目。

乐鑫系统

16 提交文档反馈

发布 v5.0.9

第 1 章入门图 9：ESP-IDF PowerShell

图 10：通过运行 ESP-IDF 命令提示符 (cmd.exe) 完成 ESP-IDF 工具设置向导

乐鑫系统

17 提交文档反馈

发布 v5.0.9

第 1 章开始

图 11：ESP-IDF 命令提示符

乐鑫系统

18 提交文档反馈

发布 v5.0.9

第 1 章开始
本指南将帮助您快速入门 ESP-IDF。请按照本指南在 ESP32 上创建新项目，并进行编译、烧写和监控设备输出。注意：如果您尚未安装 ESP-IDF，请前往“安装”页面并按照说明操作，以获取使用本指南所需的所有软件。

开始项目现在，您已准备好为 ESP32 准备应用程序。您可以从 ex 中的 getstarted/hello_world 项目开始。ampESP-IDF 中的 .les 目录。
重要提示：ESP-IDF 构建系统不支持 ESP-IDF 或项目路径中的空格。
将项目 get-started/hello_world 复制到 ~/esp 目录：cd %userprofile%esp xcopy /e /i %IDF_PATH%examplesget-startedhello_world hello_world
注意：有一系列的例子amp前的项目ampESP-IDF 中的 .les 目录。您可以以与上述相同的方式复制任何项目并运行它。也可以构建 examp无需先复制它们即可就地保存文件。

连接您的设备现在将您的 ESP32 开发板连接到计算机，并检查开发板在哪个串口下可见。在 Windows 系统中，串口名称以 COM 开头。如果您不确定如何查看串口名称，请参阅与 ESP32 建立串行连接以了解更多详细信息。
注意：请保留端口名称，因为您将在接下来的步骤中使用它。

配置您的项目导航到您的 hello_world 目录，将 ESP32 设置为目标，然后运行项目配置实用程序 menuconfig。
Windows cd %userprofile%esphello_world idf.py 设置目标 esp32 idf.py menuconfig
打开新项目后，首先应使用 idf.py set-target esp32 设置目标芯片。请注意，项目中现有的构建和配置（如有）将在此过程中被清除并初始化。您可以将目标芯片保存在环境变量中，从而完全跳过此步骤。更多信息，请参阅选择目标芯片：set-target。如果上述步骤正确完成，将出现以下菜单：您正在使用此菜单设置项目特定的变量，例如 Wi-Fi 网络名称和密码、处理器速度等。对于 ohello_wordp，可以跳过使用 menuconfig 设置项目的步骤，因为此示例ample 使用默认配置运行。
注意：如果您使用带有 ESP32-SOLO-1 模块的 ESP32-DevKitC 开发板，或使用带有 ESP32-MIN1-1(1U) 模块的 ESP32-DevKitM-1 开发板，请在烧写 ex 之前在 menuconfig 中启用单核模式 (CONFIG_FREERTOS_UNICORE)amp莱斯。

乐鑫系统

19 提交文档反馈

发布 v5.0.9

第 1 章开始

图 12：项目配置 - 主页窗口
注意：您的终端中的菜单颜色可能有所不同。您可以使用选项 –style 更改外观。请运行 idf.py menuconfig –help 获取更多信息。
如果您使用的是受支持的开发板，可以使用板级支持包 (Board Support Package) 来加快开发速度。更多信息，请参阅其他提示。
构建项目通过运行以下命令构建项目：
idf.py 构建
该命令将编译应用程序和所有 ESP-IDF 组件，然后生成引导加载程序、分区表和应用程序二进制文件。
$ idf.py build 在目录 /path/to/hello_world/build 中运行 cmake 执行“cmake -G Ninja –warn-uninitialized /path/to/hello_world”… 警告未初始化的值。— 找到 Git：/usr/bin/git（找到的版本为“2.17.0”）— 由于配置原因，构建了空的 aws_iot 组件 — 组件名称：… — 组件路径：…
…（更多行构建系统输出）
[527/527] 生成 hello_world.bin esptool.py v2.3.1
项目构建已完成。要进行烧写，请运行以下命令：../../../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 或运行“idf.py -p PORT flash”
如果没有错误，构建将通过生成固件二进制文件 .bin 来完成 files.

乐鑫系统

20 提交文档反馈

发布 v5.0.9

第 1 章开始
将您刚刚构建的二进制文件（bootloader.bin、partition-table.bin 和 hello_world.bin）刷入设备，运行以下命令：idf.py -p PORT [-b BAUD] flash
将 PORT 替换为您的 ESP32 boardns 串口名称。您也可以将 BAUD 替换为您所需的波特率，以更改烧写器的波特率。默认波特率为 460800。有关 idf.py 参数的更多信息，请参阅 idf.py。
注意：选项 flash 会自动构建并烧录项目，因此无需运行 idf.py build。

烧写过程中遇到问题？如果您运行给定命令并看到诸如“Failed to connectp”之类的错误，则可能有多种原因。其中一个原因可能是 esptool.py 遇到了问题，该实用程序由构建系统调用，用于重置芯片、与 ROM 引导加载程序交互以及烧写固件。一个简单的解决方案是尝试下面介绍的手动重置，如果此方法无效，您可以在故障排除中找到有关可能问题的更多详细信息。
esptool.py 通过置位 USB 转串口芯片（例如 FTDI 或 CP210x）的 DTR 和 RTS 控制线来自动重置 ESP32（更多信息，请参阅与 ESP32 建立串口连接）。DTR 和 RTS 控制线依次连接到 ESP32 的 GPIO0 和 CHIP_PU (EN) 引脚，因此音量的变化tagDTR 和 RTS 的电平将使 ESP32 进入固件下载模式。例如amp例如，检查 ESP32 DevKitC 开发板的原理图。
一般来说，使用官方的 esp-idf 开发板应该不会有问题。但是，在以下情况下，esptool.py 无法自动重置硬件：
· 您的硬件没有连接到 GPIO0 和 CHIP_PU 的 DTR 和 RTS 线 · DTR 和 RTS 线的配置不同 · 根本没有这样的串行控制线
根据您拥有的硬件类型，您还可以手动将 ESP32 板置于固件下载模式（重置）。
· 对于乐鑫生产的开发板，这些信息可以在相应的入门指南或用户指南中找到。例如amp例如，要手动重置 ESP-IDF 开发板，请按住 Boot 按钮（GPIO0）并按下 EN 按钮（CHIP_PU）。
· 对于其他类型的硬件，请尝试将 GPIO0 拉低。

乐鑫系统

21 提交文档反馈

发布 v5.0.9

第 1 章开始
（接上页）配置闪存大小…已将 3072 字节压缩为 103…正在从 0x00008000 写入…（100%）在 0.0 秒内（有效速率 5962.8 kbit/s）将 3072 字节（压缩后 103）写入 0x00008000…已验证数据哈希值。已将 26096 字节压缩为 15408…正在从 0x00001000 写入…（100%）在 0.4 秒内（有效速率 546.7 kbit/s）将 26096 字节（压缩后 15408）写入 0x00001000…已验证数据哈希值。将 147104 个字节压缩为 77364… 在 0x00010000 处写入…（20 %）在 0x00014000 处写入…（40 %）在 0x00018000 处写入…（60 %）在 0x0001c000 处写入…（80 %）在 0x00020000 处写入…（100 %）在 1.9 秒内（有效 615.5 kbit/s）在 0x00010000 处写入 147104 个字节（压缩后为 77364 个）…数据哈希值已验证。
离开……通过 RTS 引脚硬重置……完成
如果刷写过程结束时没有问题，开发板将重新启动并启动 ohello_worldp 应用程序。如果您想使用 Eclipse 或 VS Code IDE 而不是运行 idf.py，请查看 Eclipse 插件和 VSCode 扩展。
监控输出要检查 ohello_worldpis 是否确实正在运行，请输入 idf.py -p PORT monitor（不要忘记将 PORT 替换为您的串行端口名称）。
此命令启动 IDF Monitor 应用程序：
$ idf.py -p监控在目录 […]/esp/hello_world/build 中运行 idf_monitor 执行“python […]/esp-idf/tools/idf_monitor.py -b 115200 […]/esp/hello_ world/build/hello_world.elf”… — idf_monitor on 115200 —– 退出：Ctrl+] | 菜单：Ctrl+T | 帮助：Ctrl+T，然后按 Ctrl+H –ets 2016 年 6 月 8 日 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) ets 2016年6月8日 00:22:57 …
启动和诊断日志向上滚动后，您应该会看到应用程序打印出 oHello world！。
… 你好，世界！10 秒后重启…… 这是 esp32 芯片，配备 2 个 CPU 核心、WiFi/BT/BLE、芯片版本 1、2MB 外部闪存。最小可用堆大小：298968 字节。9 秒后重启…… 8 秒后重启…… 7 秒后重启……
要退出 IDF 监视器，请使用快捷键 Ctrl+]。

乐鑫系统

22 提交文档反馈

发布 v5.0.9

第 1 章开始
如果 IDF 监视器在上传后不久出现故障，或者您看到的不是上述消息，而是类似于以下内容的随机垃圾信息，则您的开发板很可能使用了 26 MHz 晶振。大多数开发板设计使用 40 MHz，因此 ESP-IDF 使用此频率作为默认值。

如果您遇到此类问题，请执行以下操作：1. 退出监视器。2. 返回 menuconfig。3. 前往“组件配置”>“硬件设置”>“主 XTAL 配置”>“主 XTAL 频率”，然后将 CONFIG_XTAL_FREQ_SEL 更改为 26 MHz。4. 之后，再次构建并烧写应用程序。
在当前版本的 ESP-IDF 中，ESP32 支持的主要 XTAL 频率如下：
· 26 兆赫 · 40 兆赫
注意：您可以通过运行以下命令将构建、烧写和监控合并为一步：idf.py -p PORT flash monitor
另请参阅：· IDF 监视器，了解便捷的快捷方式以及有关使用 IDF 监视器的更多详细信息。· idf.py，了解 idf.py 命令和选项的完整参考。
这就是你开始使用 ESP32 所需的一切！现在你可以尝试一些其他的amples，或者直接开发您自己的应用程序。
重要提示：一些前amp文件不支持 ESP32，因为 ESP32 不包含所需的硬件，因此无法支持。如果构建一个 example，请检查 README file 针对支持的目标平台表。如果包含 ESP32 目标平台，或者该表根本不存在，则ample 将在 ESP32 上运行。
其他提示
/dev/ttyUSB0 权限问题在某些 Linux 发行版中，您可能会在烧写 ESP32 时收到“无法打开端口 /dev/ttyUSB0”的错误消息。此问题可以通过将当前用户添加到 dialout 组来解决。
Python 兼容性 ESP-IDF 支持 Python 3.7 或更高版本。建议将您的操作系统升级到满足此要求的最新版本。其他选项包括从源代码安装 Python 或使用 Python 版本管理系统（例如 pyenv）。
从板级支持包开始为了加快某些开发板上的原型设计，您可以使用板级支持包 (BSP)，这使得特定板的初始化变得像几个函数调用一样简单。

乐鑫系统

23 提交文档反馈

发布 v5.0.9

第 1 章开始

BSP 通常支持开发板上提供的所有硬件组件。除了引脚定义和初始化函数外，BSP 还附带外部组件（例如传感器、显示器、音频编解码器等）的驱动程序。BSP 通过 IDF 组件管理器分发，因此可以在 IDF 组件注册表中找到它们。以下是示例amp如何将 ESP-WROVER-KIT BSP 添加到您的项目：idf.py add-dependency esp_wrover_kit
更多前ampBSP 使用方法可以在 BSP ex 中找到amp文件夹。
相关文档对于想要自定义安装过程的高级用户：· 在 Windows 上更新 ESP-IDF 工具 · 与 ESP32 建立串行连接 · Eclipse 插件 · VSCode 扩展 · IDF 监视器
在 Windows 上更新 ESP-IDF 工具
使用脚本安装 ESP-IDF 工具在 Windows 命令提示符中，切换到 ESPIDF 的安装目录。然后运行：
安装脚本
对于 Powershell，请切换到 ESP-IDF 的安装目录。然后运行：
安装.ps1
这将下载并安装使用 ESP-IDF 所需的工具。如果已安装该工具的特定版本，则不会执行任何操作。工具将下载并安装到 ESP-IDF 工具安装程序过程中指定的目录中。默认情况下，该目录为 C:\Users\username\espressif。
使用导出脚本将 ESP-IDF 工具添加到 PATH 环境变量中。ESP-IDF 工具安装程序会为 ESP-IDF 命令提示符创建一个“开始”菜单快捷方式。此快捷方式会打开一个命令提示符窗口，其中已包含所有工具。
可用。在某些情况下，您可能希望在未使用该快捷方式启动的命令提示符窗口中使用 ESP-IDF。如果是这种情况，请按照以下说明将 ESP-IDF 工具添加到 PATH。在需要使用 ESP-IDF 的命令提示符中，切换到 ESP-IDF 的安装目录，然后执行 export.bat：
cd %userprofile%espesp-idf 导出.bat
或者在需要使用 ESP-IDF 的 Powershell 中，切换到 ESP-IDF 的安装目录，然后执行 export.ps1：
cd ~/esp/esp-idf 导出.ps1
完成后，这些工具将在此命令提示符中可用。
与 ESP32 建立串行连接本节提供如何在 ESP32 和 PC 之间建立串行连接的指导。

乐鑫系统

24 提交文档反馈

发布 v5.0.9

第 1 章开始
将 ESP32 连接到 PC 使用 USB 数据线将 ESP32 开发板连接到 PC。如果设备驱动程序未自动安装，请识别 ESP32 开发板上的 USB 转串口转换芯片（或外部转换器），在互联网上搜索驱动程序并安装。以下列出了乐鑫生产的大多数 ESP32 开发板上安装的 USB 转串口转换芯片及其驱动程序链接：
· CP210x：CP210x USB 转 UART 桥 VCP 驱动程序 · FTDI：FTDI 虚拟 COM 端口驱动程序请查看开发板用户指南，了解所使用的具体 USB 转串口芯片。以上驱动程序仅供参考。通常情况下，驱动程序会随操作系统捆绑安装，并在开发板连接到 PC 时自动安装。
在 Windows 上检查端口：在 Windows 设备管理器中检查已识别的 COM 端口列表。断开 ESP32 的连接并重新连接，以验证哪个端口从列表中消失后又重新显示。下图显示了 ESP32 DevKitC 和 ESP32 WROVER KIT 的串行端口。

图 13：Windows 设备管理器中的 ESP32-DevKitC 的 USB 转 UART 桥接器

检查 Linux 和 macOS 上的端口要检查 ESP32 开发板（或外部转换器加密狗）串行端口的设备名称，请运行此命令两次，第一次拔下开发板/加密狗，然后插入。第二次出现的端口就是您需要的端口：Linux
ls /dev/tty*
macOS

乐鑫系统

25 提交文档反馈

发布 v5.0.9

第 1 章开始

图 14：Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串口

乐鑫系统

26 提交文档反馈

发布 v5.0.9

第 1 章开始

ls /dev/cu.* 注意：macOS 用户：如果您没有看到串行端口，请检查您是否安装了 USB/串行驱动程序。有关驱动程序链接，请参阅“将 ESP32 连接到 PC”部分。对于 macOS High Sierra (10.13)，您可能还需要明确允许加载驱动程序。打开“系统偏好设置”->“安全和隐私”->“通用”，检查此处是否显示有关“来自开发商 lp 的系统软件”的消息，其中开发商名称为 Silicon Labs 或 FTDI。

在 Linux 上将用户添加到 dialout 组：当前登录的用户应该拥有 USB 串口的读写权限。在大多数 Linux 发行版中，可以使用以下命令将用户添加到 dialout 组：
sudo usermod -a -G 拨出 $USER
在 Arch Linux 上，这是通过使用以下命令将用户添加到 uucp 组来完成的：
sudo usermod -a -G uucp $USER
确保您重新登录以启用串行端口的读写权限。
验证串口连接现在验证串口连接是否正常。您可以使用串口终端程序，在重置 ESP32 后检查终端上是否有任何输出。ESP32 的默认控制台波特率为 115200。
Windows 和 Linux 在此示例中amp例如，我们将使用适用于 Windows 和 Linux 的 PuTTY SSH 客户端。您可以使用其他串口程序并设置如下所示的通信参数。运行终端并设置已识别的串口。波特率 = 115200（如有需要，请将其更改为所用芯片的默认波特率），数据位 = 8，停止位 = 1，奇偶校验 = N。以下是示例amp请参阅在 Windows 和 Linux 上设置端口和传输参数（简称为 115200-8-1-N）的屏幕截图。请记住选择与上述步骤中确定的完全相同的串口。然后在终端中打开串口，检查 ESP32 是否打印了任何日志。日志内容取决于加载到 ESP32 的应用程序，请参阅示例ample 输出。
注意：确认通信正常后，请关闭串行终端。如果保持终端会话打开，则稍后将无法访问串行端口来上传固件。

macOS 为了省去安装串行终端程序的麻烦，macOS 提供了 screen 命令。· 如在 Linux 和 macOS 上检查端口中所述，运行：

ls /dev/cu.* · 您应该会看到类似的输出：

/dev/cu.Bluetooth-Incoming-Port /dev/cu.SLAB_USBtoUART USBtoUART7

/dev/cu.SLAB_

· 输出结果会根据连接到电脑的开发板类型和数量而有所不同。然后选择开发板的设备名称并运行（如果需要，请将 o115200p 更改为所用芯片的默认波特率）：

screen /dev/cu.device_name 115200 将 device_name 替换为运行 ls /dev/cu.* 找到的名称。

乐鑫系统

27 提交文档反馈

发布 v5.0.9

第 1 章开始

图 15：在 Windows 上的 PuTTY 中设置串行通信

乐鑫系统

28 提交文档反馈

发布 v5.0.9

第 1 章开始

图 16：在 Linux 上的 PuTTY 中设置串行通信

乐鑫系统

29 提交文档反馈

发布 v5.0.9

第 1 章开始
· 您要查找的是屏幕显示的一些日志。日志内容取决于加载到 ESP32 的应用程序，请参阅示例ample 输出。要退出屏幕会话，请输入 Ctrl-A + 。
注意：确认通信正常后，请不要忘记退出 screen 会话。如果您没有这样做，只是关闭了终端窗口，则稍后将无法访问串行端口来上传固件。
Example 输出 An examp日志如下所示。如果什么都没看到，请重置主板。ets 2016年6月8日 00:22:57
rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) ets 2016年6月8日 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:编译时间 18:48:10
…
如果您可以看到可读的日志输出，则表示串行连接正在工作，您可以继续安装并最终将应用程序上传到 ESP32。
注意：对于某些串口接线配置，需要在终端程序中禁用串行 RTS 和 DTR 引脚，ESP32 才能启动并产生串行输出。这取决于硬件本身，大多数开发板（包括所有 Espressif 开发板）均不存在此问题。如果 RTS 和 DTR 直接连接到 EN 和 GPIO0 引脚，则会出现此问题。有关更多详细信息，请参阅 esptool 文档。
如果您在安装 ESP32 开发软件时从步骤 5. ESP-IDF 上的第一步来到这里，那么您可以继续执行步骤 5. ESP-IDF 上的第一步。
IDF 监视器 IDF 监视器主要是一个串行终端程序，用于在目标设备的串行端口之间中继串行数据。它还提供了一些 IDF 特有的功能。您可以在 IDF 项目中运行 idf.py monitor 来启动 IDF 监视器。
键盘快捷键为了轻松与 IDF 监视器交互，请使用表中给出的键盘快捷键。

乐鑫系统

30 提交文档反馈

发布 v5.0.9

第 1 章开始

键盘快捷键 Ctrl+] Ctrl+T
· Ctrl+T
· Ctrl+] · Ctrl+P
· Ctrl+R
· Ctrl+F
· Ctrl+A（或 A）
· Ctrl+Y
· Ctrl+L
· Ctrl+I（或 I）
· Ctrl+H（或 H）
· Ctrl+X（或 X）
Ctrl+C

行动

描述

退出程序菜单退出键将菜单字符本身发送到远程
将退出字符本身发送到远程
将目标重置到引导加载程序中以通过 RTS 线路暂停应用程序
通过 RTS 重置目标板
构建并刷新项目

仅构建并刷新应用程序

停止/恢复屏幕上的日志输出打印

停止/恢复日志输出保存至 file

停止/恢复时间amps

印刷

显示所有键盘快捷键

按下并按照下面给出的其中一个键进行操作。
重置目标板，通过 RTS 线（如果已连接）进入引导加载程序，使开发板不运行任何程序。当需要等待其他设备启动时非常有用。重置目标板并通过 RTS 线（如果已连接）重新启动应用程序。
暂停 idf_monitor 以运行项目 flash 目标，然后恢复 idf_monitor。任何更改的源 files 会被重新编译并重新烧写。如果 idf_monitor 启动时使用了 -E 参数，则运行目标 encrypted-flash。暂停 idf_monitor 以运行 app-flash 目标，然后恢复 idf_monitor。与 flash 目标类似，但只构建并重新烧写主应用程序。如果 idf_monitor 启动时使用了 -E 参数，则运行目标 encrypted-app-flash。激活时丢弃所有传入的串行数据。允许快速暂停并检查日志输出，而无需退出监视器。创建一个 file 在项目目录中，输出写入该目录 file 直到使用相同的键盘快捷键禁用此功能（或退出 IDF 监视器）。IDF 监视器可以打印时间戳amp 在每行的开头。最amp 格式可以通过-timest更改amp-format 命令行参数。

退出程序

中断正在运行的应用程序

暂停 IDF 监视器并运行 GDB 项目调试器以在运行时调试应用程序。这需要启用 :ref:CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME 选项。

除 Ctrl-] 和 Ctrl-T 之外的任何按下的键都将通过串行端口发送。

IDF 特定功能

自动地址解码每当 ESP-IDF 输出形式为 0x4_______ 的十六进制代码地址时，IDF Monitor 都会使用 addr2line_ 在源代码中查找位置并找到函数名称。
如果 ESP-IDF 应用程序崩溃并出现问题，则会生成寄存器转储和回溯，如下所示：

乐鑫系统

31 提交文档反馈

发布 v5.0.9

第 1 章开始

Guru Meditation 核心 0 上发生 StoreProhibited 类型的错误。异常是

未處理。

寄存器转储：

：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 特区

: 0x00000019 借口:

0x0000001d

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

0x00000000

Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90

IDF Monitor 为转储添加了更多详细信息：

Guru Meditation 核心 0 上发生 StoreProhibited 类型的错误。异常是

未處理。

寄存器转储：

：0x400f360d PS

：0x00060330 A0

：0x800dbf56 A1

0x3ffb7e00

0x400f360d: 在 /home/gus/esp/32/idf/ex 发生 do_something_to_crashamples/开始/

hello_world/main/./hello_world_main.c:57

（内联）inner_dont_crash at /home/gus/esp/32/idf/examples/开始/hello_

世界/主/./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 特区

: 0x00000019 借口:

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（内联）inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_ world/main/./hello_world_main.c:52 0x400dbf56: still_dont_crash 在 /home/gus/esp/32/idf/examples/get-started/hello_ world/main/./hello_world_main.c:47 0x400dbf5e: dont_crash 在 /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42 0x400dbf82: app_main 位于 /home/gus/esp/32/idf/examples/get-started/hello_world/main/ ./hello_world_main.c:33 0x400d071d: main_task 位于 /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254

为了解码每个地址，IDF Monitor 在后台运行以下命令：xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS

注意：将环境变量 ESP_MONITOR_DECODE 设置为 0 或使用特定命令行调用 idf_monitor.py

乐鑫系统

32 提交文档反馈

发布 v5.0.9

第 1 章开始
选项：idf_monitor.py –disable-address-decoding 禁用地址解码。
连接时重置目标默认情况下，IDF Monitor 会在连接到目标时重置目标芯片。目标芯片的重置通过 DTR 和 RTS 串行线进行。为了防止 IDF Monitor 在连接时自动重置目标芯片，请在调用 IDF Monitor 时使用 –no-reset 选项（例如，idf_monitor.py –no-reset）。
注意：即使将 IDF Monitor 连接到特定端口，–no-reset 选项也会应用相同的行为（例如，idf.py monitor –no-reset -p [PORT]）。
使用 GDBStub 启动 GDB GDBStub 是一个实用的运行时调试功能，它在目标上运行，并通过串行端口连接到主机以接收调试命令。GDBStub 支持读取内存和变量、检查调用堆栈帧等命令。虽然 GDBStub 的功能不如 JTAG 调试时，它不需要任何特殊的硬件（例如 JTAG 由于通信完全通过串口进行，因此无法将其配置为在 USB 桥接器上运行。通过在运行时将 CONFIG_ESP_SYSTEM_PANIC 设置为 GDBStub，可以将目标板配置为在后台运行 GDBStub。GDBStub 将在后台运行，直到通过串口发送 Ctrl+C 消息并导致 GDBStub 中断（即停止执行）程序，从而允许 GDBStub 处理调试命令。此外，还可以将恐慌处理程序配置为在崩溃时运行 GDBStub，方法是在发生恐慌时将 CONFIG_ESP_SYSTEM_PANIC 设置为 GDBStub。发生崩溃时，GDBStub 会通过串口输出一个特殊的字符串模式，以指示其正在运行。在这两种情况下（即发送 Ctrl+C 消息或接收特殊字符串模式），IDF Monitor 都会自动启动 GDB，以便用户发送调试命令。GDB 退出后，目标板将通过 RTS 串口线重置。如果此线未连接，用户可以重置目标板（通过按下 boardns 上的 Reset 按钮）。
注意：在后台，IDF Monitor 运行以下命令来启动 GDB：
xtensa-esp32-elf-gdb -ex “设置串行波特率 BAUD” -ex “目标远程端口” -ex 中断构建/PROJECT.elf :idf_target:`Hello NAME chip`

输出过滤 IDF 监视器可以通过 idf.py monitor –print-filter=”xyz” 调用，其中 –print-filter 是输出过滤的参数。默认值为空字符串，表示打印所有内容。
可以将打印内容的限制指定为一系列tag>：项目tag> 是 tag 字符串和是集合 {N, E, W, I, D, V, *} 中的一个字符，表示日志记录的级别。
例如amp例如，PRINT_FILTER=”tag1:W” 匹配并仅打印使用 ESP_LOGW(“tag1”，...）或较低详细程度，即 ESP_LOGE（“tag1″，……）。未指定或使用 * 默认为详细级别。
注意：使用主日志记录可以在编译时通过日志记录库禁用不需要的输出。使用 IDF 监视器进行输出过滤是辅助解决方案，它有助于调整过滤选项，而无需重新编译应用程序。
您的应用 tags 不得包含空格、星号 * 或冒号 : 以便与输出过滤功能兼容。
如果应用程序中输出的最后一行没有回车符，输出过滤可能会出现混乱，例如，监视器开始打印该行，但后来发现该行不应该被写入。这是一个已知问题，可以通过始终添加回车符来避免（尤其是在没有输出紧随其后的情况下）。

乐鑫系统

33 提交文档反馈

发布 v5.0.9

第 1 章开始
Examp过滤规则：
· * 可用于匹配任何 tags。但是，字符串 PRINT_FILTER=”*:I tag1:E”关于 tag1 仅打印错误，因为 tag1 的优先级高于 * 的规则。
· 默认（空）规则相当于 *:V，因为匹配每个 tag 详细级别或更低级别意味着匹配所有内容。
· “*:N” 不仅会抑制日志函数的输出，还会抑制 printf 等函数的打印。为了避免这种情况，请使用 *:E 或更高详细级别。
·规则“tag1：V”，“tag1：v”，“tag1：”，“tag1:*”和“tag1” 是等价的。· 规则“tag1：W tag1:E” 相当于“tag1:E”，因为任何随之而来的相同 tag
名称会覆盖前一个名称。·规则“tag1：我 tag2:W” 仅打印 tag1 信息详细级别或更低，并且 tag2 警告
详细程度级别或更低。·规则“tag1：我 tag2：W tag3:N” 本质上等同于前一个，因为 tag3:N 指定
那 tag3 不应打印。· tag规则中的 3:N “tag1：我 tag2：W tag3:N *:V” 更有意义，因为没有 tag3：N
tag可以打印 3 条消息；错误 tag1和 tag2 将以指定（或更低）的详细程度打印，其他所有内容将默认打印。
更复杂的过滤示例ample 以下日志片段是在没有任何过滤选项的情况下获取的：
load:0x40078000，len:13564 条目 0x40078d4c E (31) esp_image: 位于 0x30000 处的图像具有无效的魔法字节 W (31) esp_image: 位于 0x30000 处的图像具有无效的 SPI 模式 255 E (39) boot: 工厂应用程序分区不可启动 I (568) cpu_start: Pro CPU 启动。I (569) heap_init: 正在初始化。可用于动态分配的 RAM：I (603) cpu_start: Pro CPU 启动用户代码 D (309) light_driver: [light_init, 74]:status: 1，模式：2 D (318) vfs: esp_vfs_register_fd_range 在范围 <54 内成功； 64) 和 VFS ID 1 I (328) wifi: wifi 驱动程序任务: 3ffdbf84, prio:23, stack:4096, core=0
过滤选项 PRINT_FILTER=”wifi esp_image:E light_driver:I” 的捕获输出如下：
E（31）esp_image：位于 0x30000 处的图像具有无效的魔法字节 I（328）wifi：wifi 驱动程序任务：3ffdbf84，prio：23，堆栈：4096，核心=0
选项“PRINT_FILTER=”light_driver:D esp_image:N boot:N cpu_start:N vfs:N wifi:N *:V”显示以下输出：
load:0x40078000,len:13564 entry 0x40078d4c I (569) heap_init: 正在初始化。可用于动态分配的 RAM：D (309) light_driver: [light_init, 74]:status: 1, mode: 2
IDF 监视器的已知问题
在 Windows 上观察到的问题
· 由于 Windows 控制台的限制，箭头键以及一些其他按键在 GDB 中不起作用。· 有时，当 oidf.pyp 退出时，它可能会暂停长达 30 秒，然后 IDF 监视器才会恢复。· 当 ogdbpis 运行时，它可能会短暂暂停，然后才开始与 GDBStub 通信。

乐鑫系统

34 提交文档反馈

发布 v5.0.9

第 1 章 Linux 和 macOS 的标准工具链设置入门

安装步骤这是一份详细的路线图，可指导您完成安装过程。
设置开发环境这些是为您的 ESP32 设置 ESP-IDF 的步骤。· 步骤 1. 安装先决条件· 步骤 2. 获取 ESP-IDF· 步骤 3. 设置工具· 步骤 4. 设置环境变量· 步骤 5. ESP-IDF 上的初始步骤
步骤 1. 安装先决条件：为了将 ESP-IDF 与 ESP32 一起使用，您需要根据您的操作系统安装一些软件包。本安装指南将帮助您在 Linux 和 macOS 系统上安装所有软件包。
对于 Linux 用户：要使用 ESP-IDF 进行编译，您需要获取以下软件包。运行的命令取决于您使用的 Linux 发行版：
· Ubuntu 和 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 仍然受支持，但为了获得更好的用户体验，建议使用 CentOS 8 版本。· Arch：sudo pacman -S –needed gcc git make flex bison gperf python cmake ninja ccache dfu-util libusb
注意：· 使用 ESP-IDF 需要 CMake 3.16 或更高版本。如果您的操作系统版本没有合适的版本，请运行 otools/idf_tools.py install cmakep 来安装。· 如果您在上面的列表中没有看到您的 Linux 发行版，请查看其文档，了解应该使用哪个命令来安装软件包。
对于 macOS 用户，ESP-IDF 将使用 macOS 上默认安装的 Python 版本。· 安装 CMake 和 Ninja 构建：如果您有 HomeBrew，您可以运行：brew install cmake ninja dfu-util 如果您有 MacPorts，您可以运行：sudo port install cmake ninja dfu-util 否则，请查阅 CMake 和 Ninja 主页以获取 macOS 安装下载。

乐鑫系统

35 提交文档反馈

发布 v5.0.9

第 1 章开始
· 强烈建议同时安装 ccache 以加快构建速度。如果您有 HomeBrew，可以通过 brew install ccache 或在 MacPorts 上使用 sudo port install ccache 来完成。
注意：如果在任何步骤中出现类似这样的错误：xcrun：错误：无效的活动开发人员路径（/Library/Developer/CommandLineTools），缺少 xcrun：/Library/Developer/CommandLineTools/usr/bin/xcrun
然后，您需要安装 XCode 命令行工具才能继续。您可以通过运行 xcode-select –install 来安装它们。
Apple M1 用户如果您使用 Apple M1 平台并看到类似以下错误：警告：存在工具 xtensa-esp32-elf 版本 esp-2021r2-patch3-8.4.0 的目录，但未找到工具。错误：工具 xtensa-esp32-elf 没有安装版本。请运行“install.sh”进行安装。
或者：zsh：可执行文件中的 CPU 类型错误：~/.espressif/tools/xtensa-esp32-elf/esp-2021r2patch3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc
然后，您需要通过运行 /usr/sbin/softwareupdate –install-rosetta –agree-to-license 安装 Apple Rosetta 2
安装 Python 3。根据 macOS Catalina 10.15 的发行说明，不建议使用 Python 2.7，并且在未来版本的 macOS 中将不再默认包含 Python 2.7。请检查您当前使用的 Python 版本：python –version
如果输出类似 Python 2.7.17，则表示你的默认解释器是 Python 2.7。如果是这样，请检查你的计算机上是否已安装 Python 3：python3 –version
如果上述命令返回错误，则表示未安装 Python 3。下面是一个view 安装 Python 3 的步骤。
· 使用 HomeBrew 安装可以按如下方式完成：brew install python3
· 如果你有 MacPorts，你可以运行：sudo port install python38
步骤 2：获取 ESP-IDF 要为 ESP32 构建应用程序，您需要使用乐鑫在 ESP-IDF 仓库中提供的软件库。要获取 ESP-IDF，请导航到您的安装目录，并使用 git clone 命令克隆仓库，具体操作步骤请参考以下针对您操作系统的说明。打开终端，运行以下命令：

乐鑫系统

36 提交文档反馈

发布 v5.0.9

第 1 章开始

mkdir -p ~/esp cd ~/esp git clone -b v5.0.9 –recursive https://github.com/espressif/esp-idf.git
ESP-IDF 将被下载到 ~/esp/esp-idf。有关在给定情况下使用哪个 ESP-IDF 版本的信息，请参阅 ESP-IDF 版本。
步骤 3. 设置工具除了 ESP-IDF 之外，对于支持 ESP32 的项目，您还需要安装 ESP-IDF 使用的工具，例如编译器、调试器、Python 软件包等。cd ~/esp/esp-idf ./install.sh esp32
或者使用 Fish shell cd ~/esp/esp-idf ./install.fish esp32
上述命令仅安装适用于 ESP32 的工具。如果您打算开发更多芯片目标的项目，则应列出所有目标芯片并运行以下命令：amp例如：cd ~/esp/esp-idf ./install.sh esp32,esp32s2
或者使用 Fish shell cd ~/esp/esp-idf ./install.fish esp32,esp32s2
为了为所有支持的目标安装工具，请运行以下命令：cd ~/esp/esp-idf ./install.sh all
或者使用 Fish shell cd ~/esp/esp-idf ./install.fish all
注意：对于 macOS 用户，如果在任何步骤中出现这样的错误：url打开错误[SSL:CERTIFICATE_VERIFY_FAILED]证书验证失败:无法获取本地颁发者证书(_ssl.c:xxx)
您可以在计算机的 Python 文件夹中运行 Install Certificates.command 来安装证书。详情请参阅安装 ESP-IDF 工具时出现下载错误。

选择 File 下载工具安装程序会下载许多 file已附加到 GitHub Releases。如果访问 GitHub 速度较慢，可以设置环境变量，优先使用 Espressifns 下载服务器下载 GitHub 资源。

注意：此设置仅控制从 GitHub 版本下载的单个工具，它不会更改 URL用于访问任何 Git 存储库。

要在安装工具时优先使用 Espressif 下载服务器，请在运行 install.sh 时使用以下命令序列：

乐鑫系统

37 提交文档反馈

发布 v5.0.9

第 1 章开始

cd ~/esp/esp-idf 导出 IDF_GITHUB_ASSETS=”dl.espressif.com/github_assets” ./install.sh
自定义工具安装路径本步骤中介绍的脚本会将 ESP-IDF 所需的编译工具安装在用户主目录：Linux 上的 $HOME/.espressif。如果您希望将工具安装到其他目录，请在运行安装脚本之前设置环境变量 IDF_TOOLS_PATH。请确保您的用户帐户具有足够的权限来读写此路径。如果更改 IDF_TOOLS_PATH，请确保每次执行安装脚本（install.bat、install.ps1 或 install.sh）和导出脚本（export.bat、export.ps1 或 export.sh）时都将其设置为相同的值。
步骤 4：设置环境变量已安装的工具尚未添加到 PATH 环境变量中。为了使这些工具可以在命令行中使用，必须设置一些环境变量。ESP-IDF 提供了另一个脚本来执行此操作。在要使用 ESP-IDF 的终端中，运行：
。 $HOME/esp/esp-idf/export.sh
或者对于 fish（仅支持 fish 版本 3.0.0）：
.$HOME/esp/esp-idf/export.fish
注意前导点和路径之间的空格！如果您打算频繁使用 esp-idf，可以创建一个执行 export.sh 的别名：
1. 复制并粘贴以下命令到你的shellns profile （.profile、.bashrc、.zprofile， ETC。）
alias get_idf='.$HOME/esp/esp-idf/export.sh' 2. 通过重新启动终端会话或运行 source [path to profile],
例如ample，source ~/.bashrc。现在，您可以在任何终端会话中运行 get_idf 来设置或刷新 ESP-IDF 环境。从技术上讲，您可以将 export.sh 添加到您的 shellns pro 中file 直接启用；但是，不建议这样做。这样做会在每个终端会话（包括不需要 IDF 的会话）中激活 IDF 虚拟环境，从而违背虚拟环境的初衷，并可能影响其他软件。
步骤 5：ESP-IDF 入门指南现在所有要求都已满足，下一主题将指导您如何开始您的第一个项目。本指南将帮助您完成使用 ESP-IDF 的第一步。请按照本指南在 ESP32 上创建一个新项目，并进行编译、烧写和监控设备输出。
注意：如果您尚未安装 ESP-IDF，请转至安装并按照说明获取使用本指南所需的所有软件。

开始项目现在，您已准备好为 ESP32 准备应用程序。您可以从 ex 中的 getstarted/hello_world 项目开始。ampESP-IDF 中的 .les 目录。

重要提示：ESP-IDF 构建系统不支持 ESP-IDF 或项目路径中的空格。

将项目 get-started/hello_world 复制到 ~/esp 目录：

乐鑫系统

38 提交文档反馈

发布 v5.0.9

第 1 章开始
cd ~/esp cp -r $IDF_PATH/examples/get-started/hello_world 。
注意：有一系列的例子amp前的项目ampESP-IDF 中的 .les 目录。您可以以与上述相同的方式复制任何项目并运行它。也可以构建 examp无需先复制它们即可就地保存文件。
连接您的设备现在将您的 ESP32 开发板连接到计算机，并检查开发板在哪个串口下可见。串口的命名模式如下：
· Linux：以 /dev/tty 开头 · macOS：以 /dev/cu 开头。如果您不确定如何查看串口名称，请参阅与 ESP32 建立串行连接以了解详细信息。
注意：请保留端口名称，因为您将在接下来的步骤中使用它。
配置您的项目导航到您的 hello_world 目录，将 ESP32 设置为目标，然后运行项目配置实用程序 menuconfig。cd ~/esp/hello_world idf.py set-target esp32 idf.py menuconfig
打开新项目后，首先应使用 idf.py set-target esp32 设置目标芯片。请注意，项目中现有的构建和配置（如有）将在此过程中被清除并初始化。您可以将目标芯片保存在环境变量中，以完全跳过此步骤。更多信息，请参阅选择目标芯片：set-target。如果上述步骤正确完成，将出现以下菜单：

图 17：项目配置 - 主页窗口您正在使用此菜单设置项目特定变量，例如 Wi-Fi 网络名称和密码、处理器速度等。对于 ohello_worldp，可以跳过使用 menuconfig 设置项目的步骤，因为此示例ample 运行

乐鑫系统

39 提交文档反馈

发布 v5.0.9

第 1 章开始
默认配置。
注意：如果您使用带有 ESP32-SOLO-1 模块的 ESP32-DevKitC 开发板，或使用带有 ESP32-MIN1-1(1U) 模块的 ESP32-DevKitM-1 开发板，请在烧写 ex 之前在 menuconfig 中启用单核模式 (CONFIG_FREERTOS_UNICORE)amp莱斯。
注意：您的终端中的菜单颜色可能有所不同。您可以使用选项 –style 更改外观。请运行 idf.py menuconfig –help 获取更多信息。
如果您使用的是受支持的开发板，可以使用板级支持包 (Board Support Package) 来加快开发速度。更多信息，请参阅其他提示。
构建项目通过运行以下命令构建项目：
idf.py 构建
该命令将编译应用程序和所有 ESP-IDF 组件，然后生成引导加载程序、分区表和应用程序二进制文件。
$ idf.py build 在目录 /path/to/hello_world/build 中运行 cmake 执行“cmake -G Ninja –warn-uninitialized /path/to/hello_world”… 警告未初始化的值。— 找到 Git：/usr/bin/git（找到的版本为“2.17.0”）— 由于配置原因，构建了空的 aws_iot 组件 — 组件名称：… — 组件路径：…
…（更多行构建系统输出）
[527/527] 生成 hello_world.bin esptool.py v2.3.1
项目构建已完成。要进行烧写，请运行以下命令：../../../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 或运行“idf.py -p PORT flash”
如果没有错误，构建将通过生成固件二进制文件 .bin 来完成 files.
将您刚刚构建的二进制文件（bootloader.bin、partition-table.bin 和 hello_world.bin）刷入设备，运行以下命令将该文件刷入您的 ESP32 开发板：
idf.py -p 端口 [-b 波特率] 闪存
将 PORT 替换为您的 ESP32 boardns 串口名称。您也可以将 BAUD 替换为您所需的波特率，以更改烧写器的波特率。默认波特率为 460800。有关 idf.py 参数的更多信息，请参阅 idf.py。
注意：选项 flash 会自动构建并烧录项目，因此无需运行 idf.py build。

乐鑫系统

40 提交文档反馈

发布 v5.0.9

第 1 章开始

正常运行时闪动，会看到类似如下的输出日志：
... 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 串行端口 /dev/ttyUSB0 连接…….._ 芯片是 ESP32D0WDQ6（修订版 0）功能：WiFi、蓝牙、双核、编码方案无晶振为 40MHz MAC：24：0a：c4：05：b9：14 上传存根…… 运行存根…… 存根正在运行…… 将波特率更改为 460800 已更改。配置闪存大小…已将 3072 字节压缩为 103…正在写入 0x00008000…（100%）在 0.0 秒内（有效速度 5962.8 kbit/s）在 0x00008000 写入 3072 字节（压缩后 103）…数据哈希值已验证。已将 26096 字节压缩为 15408…正在写入 0x00001000…（100%）在 0.4 秒内（有效速度 546.7 kbit/s）在 0x00001000 写入 26096 字节（压缩后 15408）…数据哈希值已验证。将 147104 个字节压缩为 77364… 在 0x00010000 处写入…（20%）在 0x00014000 处写入…（40%）在 0x00018000 处写入…（60%）在 0x0001c000 处写入…（80%）
（下页继续）

乐鑫系统

41 提交文档反馈

发布 v5.0.9

第 1 章开始
（接上页）在 0x00020000 处写入...（100%）在 1.9 秒内（有效 615.5 kbit/s）在 0x00010000 处写入 147104 字节（压缩后 77364 个）...数据哈希值已验证。
离开……通过 RTS 引脚硬重置……完成
如果刷写过程结束时没有问题，开发板将重新启动并启动 ohello_worldp 应用程序。如果您想使用 Eclipse 或 VS Code IDE 而不是运行 idf.py，请查看 Eclipse 插件和 VSCode 扩展。
监控输出：要检查 ohello_worldpis 是否正在运行，请输入 idf.py -p PORT monitor （请记得将 PORT 替换为您的串口名称）。此命令将启动 IDF Monitor 应用程序：
$ idf.py -p监控在目录 […]/esp/hello_world/build 中运行 idf_monitor 执行“python […]/esp-idf/tools/idf_monitor.py -b 115200 […]/esp/hello_ world/build/hello_world.elf”… — idf_monitor on 115200 —– 退出：Ctrl+] | 菜单：Ctrl+T | 帮助：Ctrl+T，然后按 Ctrl+H –ets 2016 年 6 月 8 日 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) ets 2016年6月8日 00:22:57 …
启动和诊断日志向上滚动后，您应该会看到应用程序打印出 oHello world！。
… 你好，世界！10 秒后重启…… 这是 esp32 芯片，配备 2 个 CPU 核心、WiFi/BT/BLE、芯片版本 1、2MB 外部闪存。最小可用堆大小：298968 字节。9 秒后重启…… 8 秒后重启…… 7 秒后重启……
要退出 IDF 监视器，请使用快捷键 Ctrl+]。如果 IDF 监视器在上传后不久出现故障，或者您看到的不是上述消息，而是类似于以下内容的随机垃圾信息，则您的开发板可能使用了 26 MHz 晶振。大多数开发板设计使用 40 MHz，因此 ESP-IDF 使用此频率作为默认值。

如果您遇到这样的问题，请执行以下操作：
1. 退出监视器。2. 返回 menuconfig。3. 前往 Component config > Hardware Settings > Main XTAL Config > Main XTAL
频率，然后将 CONFIG_XTAL_FREQ_SEL 更改为 26 MHz。4. 之后，再次构建并刷新应用程序。

乐鑫系统

42 提交文档反馈

发布 v5.0.9

第 1 章开始
在当前版本的 ESP-IDF 中，ESP32 支持的主要 XTAL 频率如下：
· 26 兆赫 · 40 兆赫
注意：您可以通过运行以下命令将构建、烧写和监控合并为一步：idf.py -p PORT flash monitor
另请参阅：· IDF 监视器，了解便捷的快捷方式以及有关使用 IDF 监视器的更多详细信息。· idf.py，了解 idf.py 命令和选项的完整参考。
这就是你开始使用 ESP32 所需的一切！现在你可以尝试一些其他的amples，或者直接开发您自己的应用程序。
重要提示：一些前amp文件不支持 ESP32，因为 ESP32 不包含所需的硬件，因此无法支持。如果构建一个 example，请检查 README file 针对支持的目标平台表。如果包含 ESP32 目标平台，或者该表根本不存在，则ample 将在 ESP32 上运行。
其他提示
/dev/ttyUSB0 权限问题在某些 Linux 发行版中，您可能会在烧写 ESP32 时收到“无法打开端口 /dev/ttyUSB0”的错误消息。此问题可以通过将当前用户添加到 dialout 组来解决。
Python 兼容性 ESP-IDF 支持 Python 3.7 或更高版本。建议将您的操作系统升级到满足此要求的最新版本。其他选项包括从源代码安装 Python 或使用 Python 版本管理系统（例如 pyenv）。
从板级支持包开始。为了加快某些开发板上的原型开发速度，您可以使用板级支持包 (BSP)，这使得特定开发板的初始化变得像几个函数调用一样简单。BSP 通常支持开发板上提供的所有硬件组件。除了引脚定义和初始化函数外，BSP 还附带外部组件（例如传感器、显示器、音频编解码器等）的驱动程序。BSP 通过 IDF 组件管理器分发，因此可以在 IDF 组件注册表中找到它们。这里有一个示例amp如何将 ESP-WROVER-KIT BSP 添加到您的项目：idf.py add-dependency esp_wrover_kit
更多前ampBSP 使用方法可以在 BSP ex 中找到amp文件夹。
提示：更新 ESP-IDF 建议定期更新 ESP-IDF，因为新版本会修复错误并/或提供新功能。请注意，每个 ESP-IDF 主版本和次版本都有相应的支持期限，当某个版本分支即将达到生命周期结束 (EOL) 时，我们鼓励所有用户将其项目升级到较新的 ESP-IDF 版本。要了解更多关于支持期限的信息，请参阅 ESP-IDF 版本。

乐鑫系统

43 提交文档反馈

发布 v5.0.9

第 1 章开始
最简单的更新方法是删除现有的 esp-idf 文件夹并重新克隆，就像执行步骤 2：获取 ESP-IDF 中描述的初始安装一样。另一种解决方案是仅更新已更改的内容。更新过程取决于您使用的 ESP-IDF 版本。更新 ESP-IDF 后，请再次执行 Install 脚本，以防新版本的 ESP-IDF 需要不同版本的工具。请参阅步骤 3：设置工具中的说明。安装新工具后，使用 Export 脚本更新环境变量。请参阅步骤 4：设置环境变量中的说明。
相关文档 · 与 ESP32 建立串口连接 · Eclipse 插件 · VSCode 扩展 · IDF 监视器
1.4 构建你的第一个项目
如果您已经安装了 ESP-IDF 并且没有使用 IDE，您可以按照在 Windows 上启动项目或在 Linux 和 macOS 上启动项目从命令行构建您的第一个项目。
1.5 卸载 ESP-IDF
如果您想删除 ESP-IDF，请按照卸载 ESP-IDF 的步骤操作。

乐鑫系统

44 提交文档反馈

发布 v5.0.9

第三章
API 参考
2.1 API约定
本文档介绍了 ESP-IDF 应用程序编程接口 (API) 的通用约定和假设。ESP-IDF 提供以下几种编程接口：
· 在公共头文件中声明的 C 函数、结构、枚举、类型定义和预处理器宏 fileESPIDF 组件的函数。编程指南的 API 参考部分的各个页面都包含这些函数、结构和类型的描述。
· 构建系统函数、预定义变量和选项。这些内容在构建系统指南中有记录。· Kconfig 选项可以在代码和构建系统中使用（CMakeLists.txt）。 files. · 主机工具及其命令行参数也是 ESP-IDF 接口的一部分。ESP-IDF 由专门为 ESP-IDF 编写的组件以及第三方库组成。在某些情况下，第三方库会添加 ESP-IDF 特定的封装器，以提供更简洁或更好地与其他 ESP-IDF 功能集成的接口。在其他情况下，第三方库的原始 API 会呈现给应用程序开发者。以下章节将介绍 ESP-IDF API 的一些方面及其用法。
2.1.1错误处理
大多数 ESP-IDF API 都会返回 esp_err_t 类型定义的错误代码。有关错误处理方法的更多信息，请参阅错误处理部分。错误代码参考包含 ESP-IDF 组件返回的错误代码列表。
2.1.2 配置结构
重要提示：正确初始化配置结构是使应用程序与 ESP-IDF 未来版本兼容的重要部分。
ESP-IDF 中的大多数初始化或配置函数都以指向配置结构的指针作为参数。例如amp乐：
45

第 2 章 API 参考

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);
初始化函数从不存储指向配置结构的指针，因此在堆栈上分配结构是安全的。
应用程序必须初始化该结构的所有字段。以下说法不正确：
esp_timer_create_args_t my_timer_args; my_timer_args.callback = &my_timer_callback; /* 不正确！字段 .arg 和 .name 未初始化 */ esp_timer_create(&my_timer_args, &my_timer);
大多数 ESP-IDF 示例amples 使用 C99 指定的初始化器进行结构初始化，因为它们提供了一种简洁的方法来设置字段子集，并对剩余字段进行零初始化：
const esp_timer_create_args_t my_timer_args = { .callback = &my_timer_callback, /* 正确，字段 .arg 和 .name 被初始化为零 */
};
C++ 语言在 C++ 20 之前不支持指定初始化器语法，但 GCC 编译器已将其作为扩展部分支持。在 C++ 代码中使用 ESP-IDF API 时，您可以考虑使用以下模式：
esp_timer_create_args_t my_timer_args = {}; /* 所有字段均初始化为零 */ my_timer_args.callback = &my_timer_callback;

默认初始化器
对于某些配置结构，ESP-IDF 提供了用于设置字段默认值的宏：
httpd_config_t config = HTTPD_DEFAULT_CONFIG(); /* HTTPD_DEFAULT_CONFIG 扩展为指定的初始化程序。
现在所有字段都已设置为默认值。任何字段仍然可以修改：*/ config.server_port = 8081; httpd_handle_t server; esp_err_t err = httpd_start(&server, &config);
无论何时为特定配置结构提供默认初始化宏，建议都使用默认初始化宏。

2.1.3 私有 API
某些标题 fileESP-IDF 中的 API 仅供 ESP-IDF 源代码使用，不供应用程序使用。此类标头 file其名称或路径中通常包含 private 或 esp_private。某些组件（例如 hal）仅包含私有 API。私有 API 可能会在次要版本或补丁版本之间以不兼容的方式被删除或更改。

2.1.4 ex中的组件amp项目
ESP-IDF 前amp文件包含各种演示 ESP-IDF API 使用方法的项目。为了减少示例代码中的重复，amples，在组件内部定义了一些常见的帮助器，供多个 ex 使用amp莱斯。

乐鑫系统

46 提交文档反馈

发布 v5.0.9

第 2 章 API 参考
这包括位于

文件/资源

Espressif Systems ESP32 Dev Kitc 开发板 [pdf] 用户指南
ESP32 Dev Kitc 开发板、ESP32、Dev Kitc 开发板、Kitc 开发板、开发板、开发板

参考

用户手册

ESP32 Dev Kitc 开发板

产品信息

规格

产品使用说明

1. 开始

1.1 简介

1.2 您需要什么

1.3 安装

1.4 构建你的第一个项目

1.5 卸载 ESP-IDF

2. API 参考

常见问题 (FAQ)

问：如何解决 ESP32 的常见问题？

问：我可以将 ESP-IDF 与其他微控制器一起使用吗？

文件/资源

参考

发表评论

取消回复