ESP-IDF 编程指南 Choose target... Choose version... 快速入门 API 参考 H/W 硬件参考 API 指南 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 ESP-IDF 编程指南 在 GitHub 上编辑 ESP-IDF 编程指南 [English] 这里是乐鑫 IoT 开发框架 (esp-idf) 的文档中心。ESP-IDF 是 ESP32、ESP32-S、ESP32-C、ESP32-H 和 ESP32-P 系列芯片的官方开发框架。 本文档仅包含针对 ESP32 芯片的 ESP-IDF 使用。如需了解其他芯片，请在页面左上方的下拉菜单中选择你的目标芯片。 快速入门 API 参考 API 指南 此文档对您有帮助吗？ 反馈已收到，谢谢！ 如果您有其他意见，欢迎填写乐鑫文档反馈表。 我们重视您的反馈。 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。 下一页 © 版权所有 2016 - 2025 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download HTML ESP-IDF 编程指南 Choose target... Choose version... 快速入门 概述 准备工作 硬件： ESP32-DevKitC ESP32-DevKitM-1 ESP-WROVER-KIT ESP32-PICO-KIT ESP32-Ethernet-Kit ESP32-PICO-KIT-1 ESP32-PICO-DevKitM-2 软件： 安装 IDE 手动安装 Windows Installer Linux and macOS 编译第一个工程 卸载 ESP-IDF API 参考 H/W 硬件参考 API 指南 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 快速入门 在 GitHub 上编辑 快速入门 [English] 本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。 备注 这是ESP-IDF 稳定版本 v5.4.2 的文档，还有其他版本的文档 ESP-IDF 版本简介 供参考。 概述 ESP32 SoC 芯片支持以下功能： 2.4 GHz Wi-Fi 蓝牙 高性能 Xtensa® 32 位 LX6 双核处理器 超低功耗协处理器 多种外设 ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用场景和不同功耗需求。 乐鑫为用户提供完整的软、硬件资源，进行 ESP32 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。 准备工作 硬件： 一款 ESP32 开发板 USB 数据线 （A 转 Micro-B） 电脑（Windows、Linux 或 macOS） 备注 目前一些开发板使用的是 USB Type C 接口。请确保使用合适的数据线来连接开发板！ 以下是 ESP32 官方开发板，点击链接可了解更多硬件信息。 ESP32-DevKitC ESP32-DevKitM-1 ESP-WROVER-KIT ESP32-PICO-KIT ESP32-Ethernet-Kit ESP32-PICO-KIT-1 ESP32-PICO-DevKitM-2 软件： 如需在 ESP32 上使用 ESP-IDF，请安装以下软件： 设置 工具链，用于编译 ESP32 代码； 编译构建工具 —— CMake 和 Ninja 编译构建工具，用于编译 ESP32 应用程序； 获取 ESP-IDF 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 工具链 的脚本； 安装 为安装所需软件，乐鑫提供了以下方法，可根据需要选择其中之一。 IDE 备注 建议通过自己喜欢的集成开发环境 (IDE) 安装 ESP-IDF。 Eclipse Plugin VSCode Extension 手动安装 请根据操作系统，选择对应的手动安装流程。 Windows Installer Linux and macOS 编译第一个工程 如果已经安装好 ESP-IDF，且没有使用集成开发环境 (IDE)，请在命令提示行中，按照 在 Windows 中开始创建工程 或 在 Linux 和 macOS 中开始创建工程 编译第一个工程。 卸载 ESP-IDF 如需卸载 ESP-IDF，请参考 卸载 ESP-IDF。 此文档对您有帮助吗？ 反馈已收到，谢谢！ 如果您有其他意见，欢迎填写乐鑫文档反馈表。 我们重视您的反馈。 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。 上一页 下一页 © 版权所有 2016 - 2025 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download HTML ESP-IDF 编程指南 Choose target... Choose version... 快速入门 API 参考 H/W 硬件参考 API 指南 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 发布版本 我该选择哪个版本？ 版本管理 支持期限 查看当前版本 Git 工作流 更新 ESP-IDF 更新至一个稳定发布版本 更新至一个预发布版本 更新至 master 分支 更新至一个发布分支 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 ESP-IDF 版本简介 在 GitHub 上编辑 ESP-IDF 版本简介 [English] ESP-IDF 的 GitHub 仓库时常更新，特别是用于开发新特性的 master 分支。 如有量产需求，请使用稳定版本。 发布版本 通过以下链接，可以访问各个版本的配套文档： 最新稳定版 ESP-IDF：https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ 最新版 ESP-IDF（即 master 分支）：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/ ESP-IDF 在 GitHub 平台上的完整发布历史请见 发布说明页面。该页面支持查看各个版本的发布说明、配套文档及相应获取方式。 此外，也可以直接前往文档页面，查看不同 ESP-IDF 版本的配套文档，具体可点击页面左上角中版本的下拉菜单（在目标下拉菜单和搜索栏之间），实现在不同版本间切换。 旧版本的文档也仍然可用： 我该选择哪个版本？ 如有量产需求，请使用 最新稳定版本 。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 版本管理 ）。请访问 发布说明页面 界面查看每一个稳定发布版本。另外，为确保使用的 ESP-IDF 版本与需生产的芯片版本兼容，可参考 ESP-IDF 版本与乐鑫芯片版本兼容性。 如需尝试/测试 ESP-IDF 的最新特性，请使用 最新版本（在 master 分支上）。最新版本包含 ESP-IDF 的所有最新特性，已通过自动化测试，但尚未全部完成人工测试（因此存在一定风险）。 如需使用稳定版本中没有的新特性，但同时又不希望受到 master 分支更新的影响，可以按照需求选择一个最适合的稳定版本，将其 更新至一个预发布版本 或 更新至一个发布分支。 如需使用其他基于 ESP-IDF 的项目，请先查看该项目的文档，以确定其兼容的 ESP-IDF 版本。 有关如何更新 ESP-IDF 本地副本的内容，请参考 更新 ESP-IDF 章节。 版本管理 ESP-IDF 采用了 语义版本管理方法，你可以从字面含义理解每个版本的差异。其中 主要版本（例 v3.0）代表有重大更新，包括增加新特性、改变现有特性及移除已弃用的特性。 升级至一个新的主要版本（例 v2.1 升级至 v3.0）意味着你可能需要更新工程代码，并重新测试工程，具体可参考 发布说明页面 的重大变更 (Breaking Change) 部分。 次要版本（例 v3.1）代表有新增特性和 bug 修复，但现有特性不受影响，公开 API 的使用也不受影响。 升级至一个新的次要版本（例 v3.0 升级至 v3.1）意味着你可能不需要更新工程代码，但需重新测试工程，特别是 发布说明页面 中专门提到的部分。 Bugfix 版本（例 v3.0.1）仅修复 bug，并不增加任何新特性。 升级至一个新的 Bugfix 版本（例 v3.0 升级至 v3.0.1）意味着你不需要更新工程代码，仅需测试与本次发布修复 bug（列表见 发布说明页面）直接相关的特性。 支持期限 ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持期限满后，版本停止更新维护，将不再提供支持。 支持期限政策 对此有具体描述，并介绍了每个版本的支持期限是如何界定的。 发布说明页面 界面上的每一个发布版本都提供了该版本的支持期限信息。 一般而言： 如果你刚开始一个新项目，建议使用最新稳定版本。 如果你有 GitHub 账号，请点击 发布说明页面 界面右上角的 "Watch" 按键，并选中 "Releases only" 选项。GitHub 将会在新版本发布的时候发送通知。当你所使用的版本有 Bugfix 版本发布时，请做好升级至该 Bugfix 版本的规划。 如可能，请定期（如每年一次）将项目的 IDF 版本升级至一个新的主要版本或次要版本。对于次要版本更新，更新过程应该比较简单，但对于主要版本更新，可能需要细致查看发布说明并做对应的更新规划。 请确保你所使用的版本停止更新维护前，已做好升级至新版本的规划。 ESP-IDF 的每个主要版本和次要版本（V4.1、V4.2 等）的支持期限为 30 个月，从最初的稳定版发布日算起。 在支持期限内意味着 ESP-IDF 团队将继续在 GitHub 的发布分支上进行 bug 修复、安全修复等，并根据需要定期发布新的 Bugfix 版本。 支持期限分为“服务期”和“维护期”： 周期 时长 是否推荐新工程使用 服务期 12 个月 是 维护期 18 个月 否 在服务期内，Bugfix 版本的发布更为频繁。某些情况下，在服务期内会增加新特性，这些特性主要是为了满足新产品特定监管要求或标准，并且回归风险非常低。 在维护期内，该版本仍受支持，但只会对严重性较高的问题或安全问题进行 bug 修复。 当开始一个新项目时，建议使用在服务期内的版本。 鼓励用户在所用版本支持期限结束之前，将所有的工程升级到最新的 ESP-IDF 版本。在版本支持期限满后，我们将不再继续进行 bug 修复。 支持期限不包括预发布版本（betas、预览版、 -rc 和 -dev 版等），有时会将某个特性在发布版中标记为“预览版”，这意味着该特性也不在支持期限内。 关于 不同版本的 ESP-IDF （主要版本、次要版本、Bugfix 版本等）的更多信息，请参考 ESP-IDF 编程指南。 查看当前版本 查看 ESP-IDF 本地副本的版本，请使用 idf.py 命令: idf.py --version 此外，由于 ESP-IDF 的版本也已编译至固件中，因此你也可以使用宏 IDF_VER 查看 ESP-IDF 的版本（以字符串的格式）。ESP-IDF 默认引导加载程序会在设备启动时打印 ESP-IDF 的版本。请注意，在 GitHub 仓库中的代码更新时，代码中的版本信息仅会在源代码重新编译或在清除编译时才会更新，因此打印出来的版本可能并不是最新的。 如果编写的代码需要支持多个 ESP-IDF 版本，可以在编译时使用 compile-time macros 检查版本。 几个 ESP-IDF 版本的例子： 版本字符串 含义 v3.2-dev-306-gbeb3611ca master 分支上的预发布版本。 - v3.2-dev：为 v3.2 进行的开发。 - 306：v3.2 开发启动后的 commit 数量。 - beb3611ca：commit 标识符。 v3.0.2 稳定版本，标签为 v3.0.2。 v3.1-beta1-75-g346d6b0ea v3.1 的 beta 测试版本（可参考 更新至一个发布分支）。 - v3.1-beta1 - 预发布标签。 - 75：添加预发布 beta 标签后的 commit 数量。 - 346d6b0ea：commit 标识符。 v3.0.1-dirty 稳定版本，标签为 v3.0.1。 - dirty 代表 ESP-IDF 的本地副本有修改。 Git 工作流 乐鑫 ESP-IDF 团队的 (Git) 开发工作流程如下： 新的改动总是在 master 分支（最新版本）上进行。master 分支上的 ESP-IDF 版本总带有 -dev 标签，表示“正在开发中”，例 v3.1-dev。 这些改动将首先在乐鑫的内部 Git 仓库进行代码审阅与测试，而后在自动化测试完成后推至 GitHub。 新版本一旦完成特性开发（在 master 分支上进行）并达到进入 beta 测试的标准，则将该版本切换至一个新分支（例 release/v3.1）。此外，该分支还打上预发布标签（例 v3.1-beta1）。你可以在 GitHub 平台上查看 ESP-IDF 的完整 分支列表 和 标签列表。Beta 预发布版本可能仍存在大量“已知问题”(Known Issue)。 随着对 beta 版本的不断测试，bug 修复将同时增加至该发布分支和 master 分支。而且，master 分支可能也已经开始为下个版本开发新特性了。 当测试快结束时，该发布分支上将增加一个 rc 标签，代表候选发布 (Release Candidate) ，例 v3.1-rc1。此时，该分支仍属于预发布版本。 如果一直未发现或报告重大 bug，则该预发布版本将最终增加“主要版本”（例 v4.0）或“次要版本”标记（例 v3.1），成为正式发布版本，并体现在 发布说明页面 。 后续，发布版本中发现的 bug 都将在该发布分支上进行修复。 发布分支上会定期进行 bug 修复，人工测试完成后，该分支将增加一个 Bugfix 版本标签（例 v3.1.1），并体现在 发布说明页面 。 更新 ESP-IDF 请根据实际情况，对 ESP-IDF 进行更新。 如有量产用途，建议参考 更新至一个稳定发布版本。 如需测试/研发/尝试最新特性，建议参考 更新至 master 分支 。 两者折衷建议参考 更新至一个发布分支。 备注 在参考本指南时，请首先获得 ESP-IDF 的本地副本，具体步骤请参考 入门指南 中的介绍。 更新至一个稳定发布版本 对于量产用户，推荐更新至一个新的 ESP-IDF 发布版本，请参考以下步骤： 请定期查看 发布说明页面 ，了解最新发布情况。 如有新发布的 Bugfix 版本（例 v3.0.1 或 v3.0.2）时，请将新的 Bugfix 版本更新至你的 ESP-IDF 目录。 在 Linux 或 macOS 系统中，请运行如下命令将分支更新至 vX.Y.Z： cd $IDF_PATH git fetch git checkout vX.Y.Z git submodule update --init --recursive 在 Windows 系统中，需要将 cd $IDF_PATH 替换为 cd %IDF_PATH%。 在主要版本或次要版本新发布时，请查看发布说明中的具体描述，并决定是否升级版本。具体命令与上方描述一致。 备注 如果你在安装 ESP-IDF 时使用的是 zip 文件包，而非通过 Git 命令，则将无法使用 Git 命令进行版本升级，此属正常情况。这种情况下，请重新下载最新 zip 文件包，并替换掉之前 IDF_PATH 下的全部内容。 更新至一个预发布版本 你也可以将你的本地副本切换（命令 git checkout）至一个预发布版本或 rc 版本，具体方法请参考 更新至一个稳定发布版本 中的描述。 预发布版本通常不体现在 发布说明页面。更多详情，请查看完整 标签列表。使用预发布版本的注意事项，请参考 更新至一个发布分支 中的描述。 更新至 master 分支 备注 ESP-IDF 中 master 分支上的代码会时时更新，因此使用 master 分支相当在“流血的边缘试探”，存在一定风险。 如需使用 ESP-IDF 的 master 分支，请参考以下步骤： 在 Linux 或 macOS 系统中，使用如下命令在本地切换至 master 分支： cd $IDF_PATH git checkout master git pull git submodule update --init --recursive 在 Windows 系统中，需要将 cd $IDF_PATH 替换为 cd %IDF_PATH%。 此外，你还应在后续工作中不时使用 git pull 命令，将远端 master 上的更新同步到本地。注意，在更新 master 分支后，你可能需要更改工程代码，也可能遇到新的 bug。 如需从 master 分支切换至一个发布分支或稳定版本，请使用 git checkout 命令。 重要 强烈建议定期使用 git pull 和 git submodule update --init --recursive 命令，确保本地副本得到及时更新。旧的 master 分支相当于一个“快照”，可能存在未记录的问题，且无法获得支持。对于半稳定版本，请参考 更新至一个发布分支。 更新至一个发布分支 从稳定性来说，使用“发布分支”相当于在使用 master 分支和稳定版本之间进行折衷，包含一些 master 分支上的新特性，但也同时保证可通过 beta 测试且基本完成了 bug 修复。 更多详情，请前往 GitHub 查看完整 标签列表。 例如，在 Linux 或 macOS 系统中，可以运行以下命令更新至 ESP-IDF v3.1，随时关注该分支上的 Bugfix 版本发布（如 v3.1.1 等）： cd $IDF_PATH git fetch git checkout release/v3.1 git pull git submodule update --init --recursive 在 Windows 系统中，需要将 cd $IDF_PATH 替换为 cd %IDF_PATH%。 每次在该分支上使用 git pull 时，都相当于把最新的 Bugfix 版本发布更新至你的本地副本中。 备注 发布分支并不会有专门的配套文档，建议使用与本分支最接近版本的文档。 此文档对您有帮助吗？ 反馈已收到，谢谢！ 如果您有其他意见，欢迎填写乐鑫文档反馈表。 我们重视您的反馈。 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。 上一页 下一页 © 版权所有 2016 - 2025 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download HTML ESP-IDF 编程指南 Choose target... Choose version... 快速入门 API 参考 API 约定 应用层协议 蓝牙 API 错误代码参考 连网 API 外设 API 项目配置 配网 API 存储 API 系统 API 应用程序镜像格式 引导加载程序镜像的格式 应用级追踪 使用外部堆栈调用函数 芯片版本 控制台终端 eFuse 管理器 错误代码和辅助函数 ESP HTTPS OTA 升级 事件循环库 FreeRTOS 概述 FreeRTOS (IDF) FreeRTOS（附加功能） 堆内存分配 基于 MMU 的存储管理 堆内存调试 ESP 定时器（高分辨率定时器） 内部 API 和不稳定的 API 处理器间调用 (IPC) 中断分配 日志库 杂项系统 API 软件复位 复位原因 堆内存 MAC 地址 芯片版本 SDK 版本 应用程序版本 应用示例 API 参考 空中升级 (OTA) 性能监视器 电源管理 POSIX 支持（包括 POSIX 线程支持） 随机数发生器 睡眠模式 SoC 功能 系统时间 Himem ULP 协处理器编程 看门狗 H/W 硬件参考 API 指南 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 API 参考 系统 API 杂项系统 API 在 GitHub 上编辑 杂项系统 API [English] 软件复位 函数 esp_restart() 用于执行芯片的软件复位。调用此函数时，程序停止执行，两个 CPU 均复位，应用程序由引导加载程序加载并重启。 函数 esp_register_shutdown_handler() 用于注册复位前会自动调用的例程（复位过程由 esp_restart() 函数触发），这与 atexit POSIX 函数的功能类似。 复位原因 ESP-IDF 应用程序启动或复位的原因有多种。调用 esp_reset_reason() 函数可获取最近一次复位的原因。复位的所有可能原因，请查看 esp_reset_reason_t 中的描述。 堆内存 ESP-IDF 中有两个与堆内存相关的函数： 函数 esp_get_free_heap_size() 用于查询当前可用的堆内存大小。 函数 esp_get_minimum_free_heap_size() 用于查询整个过程中可用的最小堆内存大小（例如应用程序生命周期内可用的最小堆内存大小）。 请注意，ESP-IDF 支持功能不同的的多个堆。上文中函数返回的堆内存大小可使用 malloc 函数族来进行分配。有关堆内存的更多信息，请参阅 堆内存分配。 MAC 地址 以下 API 用于查询和自定义支持的网络接口（如 Wi-Fi、蓝牙、以太网）的 MAC 地址。 要获取特定接口（如 Wi-Fi、蓝牙、以太网）的 MAC 地址，请调用函数 esp_read_mac()。 在 ESP-IDF 中，各个网络接口的 MAC 地址是根据单个 基准 MAC 地址 (Base MAC address) 计算出来的。默认情况下使用乐鑫指定的基准 MAC 地址，该基准地址在产品生产过程中已预烧录至 ESP32 eFuse。 接口 MAC 地址（默认 4 个全局地址） MAC 地址（2 个全局地址） Wi-Fi Station base_mac base_mac Wi-Fi SoftAP base_mac 最后一组字节后加 1 本地 MAC （由 Wi-Fi Station MAC 生成） 蓝牙 base_mac 最后一组字节后加 2 base_mac 最后一组字节后加 1 以太网 base_mac 最后一组字节后加 3 本地 MAC （由蓝牙 MAC 生成） 备注 配置选项 配置了乐鑫提供的全局 MAC 地址的数量。 自定义接口 MAC 有时用户可能需要自定义 MAC 地址，这些地址并不由基准 MAC 地址生成。如需设置自定义接口 MAC 地址，请使用 esp_iface_mac_addr_set() 函数。该函数用于覆盖由基准 M