ESP-IDF 编程指南 Choose target... Choose version... 快速入门 API 参考 H/W 硬件参考 API 指南 应用层跟踪库 应用程序的启动流程 蓝牙® 架构 概述 经典蓝牙® 低功耗蓝牙® ESP-BLE-MESH 引导加载程序 (Bootloader) 构建系统 Build System v2 RF 共存 C 支持 C++ 支持 Code Quality 核心转储 测量模组功耗 Deep-sleep 唤醒存根 错误处理 ESP-WIFI-MESH 片外 RAM 严重错误 文件系统注意事项 硬件抽象 高优先级中断处理程序 JTAG 调试 Project Configuration 链接器脚本生成机制 低功耗模式 lwIP 存储器类型 OpenThread 分区表 性能 可重复构建 RF 校准 标准 I/O 与控制台输出 线程局部存储 工具 ESP32 中的单元测试 在主机上运行 ESP-IDF 应用程序 Wi-Fi 驱动程序 Wi-Fi 安全性 Wi-Fi Expansion PHY 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 API 指南 蓝牙® 架构 在 GitHub 上编辑 蓝牙® 架构 [English] 概述 芯片蓝牙能力总览 蓝牙协议栈 蓝牙运行环境 Bluedroid 此文档对您有帮助吗？ 反馈已收到，谢谢！ 如果您有其他意见，欢迎填写乐鑫文档反馈表。 我们重视您的反馈。 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download HTML ESP-IDF 编程指南 Choose target... Choose version... 快速入门 API 参考 H/W 硬件参考 API 指南 应用层跟踪库 应用程序的启动流程 蓝牙® 架构 概述 芯片蓝牙能力总览 蓝牙协议栈 蓝牙运行环境 Bluedroid 经典蓝牙® 低功耗蓝牙® ESP-BLE-MESH 引导加载程序 (Bootloader) 构建系统 Build System v2 RF 共存 C 支持 C++ 支持 Code Quality 核心转储 测量模组功耗 Deep-sleep 唤醒存根 错误处理 ESP-WIFI-MESH 片外 RAM 严重错误 文件系统注意事项 硬件抽象 高优先级中断处理程序 JTAG 调试 Project Configuration 链接器脚本生成机制 低功耗模式 lwIP 存储器类型 OpenThread 分区表 性能 可重复构建 RF 校准 标准 I/O 与控制台输出 线程局部存储 工具 ESP32 中的单元测试 在主机上运行 ESP-IDF 应用程序 Wi-Fi 驱动程序 Wi-Fi 安全性 Wi-Fi Expansion PHY 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 API 指南 蓝牙® 架构 概述 在 GitHub 上编辑 概述 [English] 蓝牙® 无线技术是一种短距离通信标准，具备高可靠性、低功耗和低成本等特点。主要分为两种类型： 经典蓝牙: 优化用于连续的高吞吐量数据流，适用于音频传输等应用。 低功耗蓝牙 (Bluetooth LE): 针对低功耗间歇性数据传输设计，适合用于传感器和可穿戴设备等。 ESP32 支持双模蓝牙，即同时支持经典蓝牙和低功耗蓝牙。 芯片蓝牙能力总览 下表总结了 ESP-IDF 中支持蓝牙的 ESP 芯片及其蓝牙类型支持情况（Y = 支持，N = 不支持）。 芯片 经典蓝牙 (BR/EDR) 低功耗蓝牙 (LE) ESP32 Y Y ESP32-S3 N Y ESP32-C2 N Y ESP32-C3 N Y ESP32-C5 N Y ESP32-C6 N Y ESP32-C61 N Y ESP32-H2 N Y 蓝牙协议栈 蓝牙协议栈是一种分层通信架构，定义了蓝牙设备如何发现彼此、建立连接、交换数据，并确保通信安全可靠。如图 蓝牙核心系统架构（来源：蓝牙核心规范） 所示，协议栈主要分为控制器（Controller）和主机（Host）两大部分，两者通过 HCI 接口进行通信。 蓝牙核心系统架构（来源：蓝牙核心规范） 控制器 控制器负责硬件层面的操作和底层链路控制，包含： PHY (物理层): 处理 2.4 GHz ISM 频段的蓝牙信号收发。 基带 (Baseband): 管理底层时序和控制功能，包括跳频、数据包格式化和纠错。 链路控制器 (Link Controller): 处理设备连接/断开的链路状态机、流控和重传机制。 链路管理器 (Link Manager): 管理链路设置、身份验证、加密和功率控制。 设备管理器 (Device Manager): 管理设备状态，处理寻呼/查询流程，存储安全密钥。 主机 主机实现应用交互所需的高层协议，包含： L2CAP (逻辑链路控制与适配协议): 处理数据分段、重组和复用。 SMP (安全管理协议): 管理身份验证、加密和安全配对。 GAP (通用访问规范): 管理设备发现、连接建立，并定义蓝牙设备的角色和模式。 ATT/GATT (属性协议/通用属性规范): 通过服务和特征实现基于属性的数据交换，主要用于低功耗蓝牙。 SDP (服务发现协议): 允许设备广播和发现可用服务，主要用于经典蓝牙。 蓝牙主机和控制器可以集成在同一设备上，也可以在不同设备上实现。ESP32 可以支持上述两种方式，下图 ESP32 蓝牙主机与控制器的关系结构图 展示了典型的应用结构： ESP32 蓝牙主机与控制器的关系结构图 场景 1（ESP-IDF 默认设置） 使用 Bluedroid 作为蓝牙主机，通过 VHCI（软件实现的虚拟 HCI）实现主机与控制器之间的通信。Bluedroid 和控制器运行在同一设备上（即 ESP32 芯片），无需外部主机设备。 场景 2（仅控制器模式） ESP32 仅作为蓝牙控制器。外部主机设备（如运行 BlueZ 的 Linux PC 或运行 Bluedroid 的 Android 设备）负责蓝牙操作。 场景 3（测试/认证） 类似于场景 2，但用于蓝牙认证机构（BQB）控制器测试或认证。ESP32 芯片通过 UART 连接到测试工具。 蓝牙运行环境 ESP-IDF 蓝牙协议栈运行在 FreeRTOS 环境中，蓝牙任务根据功能和优先级进行分配。由于实时性要求，控制器任务具有最高优先级（部分跨核通信 IPC 任务除外）。 ESP32 的运行环境为双核 FreeRTOS，控制器任务的优先级最高，仅次于用于双核 CPU 之间通信的 IPC 任务。默认的蓝牙主机 Bluedroid 包含三个任务：BTC、BTU 和 HCI。 Bluedroid ESP-Bluedroid 是基于 Android 蓝牙协议栈 Bluedroid 的修改版， 支持经典蓝牙和低功耗蓝牙。由两层组成： 蓝牙上层 (BTU): 实现核心协议（L2CAP、GATT、SMP 等）。 蓝牙传输控制器层 (BTC): 提供应用层 API， 并管理配置文件。 使用场景: 推荐用于同时需要经典蓝牙和蓝牙低能耗的应用。 操作系统适配 Bluedroid 通过适配系统相关功能与 FreeRTOS 集成： Timer (Alarm): FreeRTOS 的 Timer 封装成 Alarm，⽤于启动定时器，触发某些特定任务。 Task (Thread): FreeRTOS 的 Task 取代 POSIX Thread，并使用 FreeRTOS 的 Queue 来触发任务的运行（唤醒）。 Future Await/Ready (Semaphore): xSemaphoreTake 封装成 future_await，xSemphoreGive 封装成 future_ready。 future_await 和 future_ready 不能在同一任务中调用。 Allocator (malloc/free): 标准库中的 malloc/free 被封装为 Allocator，用于分配 (malloc) 或释放 (free) 内存。 Bluedroid 目录结构 ESP-IDF 目录 component/bt/host/bluedroid 包含如下子文件夹： ├── api ├── bta ├── btc ├── common/include/common ├── config ├── device ├── external/sbc ├── hci ├── main ├── stack └── Kconfig.in 子文件夹的具体说明见下表: ESP-IDF component/bt/host/bluedroid 目录描述 子文件夹 说明 api API 目录，所有的 API（除 Controller 相关）都在此目录下。 bta 蓝牙适配层，适配一些主机底层协议的接口。 btc 蓝牙控制层，控制主机上层协议（包括规范）以及杂项的处理。 common 协议栈的通用头文件。 config 为协议栈配置一些参数。 device 与控制器设备控制相关的，如控制器基本设置的 HCI CMD 流程等。 external 与蓝⽛⾃身⽆关，但⼜要使⽤的代码，如 SBC codec 软件程序等。 hci HCI 层协议。 main 主程序⽬录（主要为启动、关闭流程）。 stack 主机底层协议栈（GAP/ ATT/ GATT/ SDP/ SMP 等）。 Kconfig.in Menuconfig 文件。 此文档对您有帮助吗？ 反馈已收到，谢谢！ 如果您有其他意见，欢迎填写乐鑫文档反馈表。 我们重视您的反馈。 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download HTML ESP-IDF 编程指南 Choose target... Choose version... 快速入门 概述 准备工作 硬件： ESP32-DevKitC ESP32-DevKitM-1 ESP32-Ethernet-Kit ESP32-PICO-KIT-1 ESP32-PICO-DevKitM-2 ESP32-LCDKit 软件： 安装 在 Windows 上安装 ESP-IDF 及工具链 在 Linux 上安装 ESP-IDF 及工具链 在 macOS 上安装 ESP-IDF 及工具链 构建首个项目 在 IDE 中构建 通过命令行构建 在 Windows 上通过命令行构建项目 在 Linux 或 macOS 上通过命令行构建项目 卸载 ESP-IDF 使用 EIM GUI 卸载 使用 EIM CLI 卸载 相关文档 API 参考 H/W 硬件参考 API 指南 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 快速入门 在 GitHub 上编辑 快速入门 [English] 本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。 备注 这是 ESP-IDF master 分支（最新版本）的文档，该版本在持续开发中。还有 稳定版本 的文档，以及其他版本的文档 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 ESP32-Ethernet-Kit ESP32-PICO-KIT-1 ESP32-PICO-DevKitM-2 ESP32-LCDKit 软件： 如需在 ESP32 上使用 ESP-IDF，请安装以下软件： 设置 工具链，用于编译 ESP32 代码； 编译构建工具 —— CMake 和 Ninja 编译构建工具，用于编译 ESP32 应用程序； 获取 ESP-IDF 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 工具链 的脚本； 安装 请使用 ESP-IDF 安装管理器 (EIM) 来安装 ESP-IDF、构建工具和相关工具链，该管理器支持多种操作系统。 EIM 提供两种安装方式： 图形用户界面 (GUI)：用户友好，适合大多数用户。 命令行界面 (CLI)：适用于 CI/CD 流水线和自动化安装。 在 Windows 上安装 ESP-IDF 及工具链 在 Linux 上安装 ESP-IDF 及工具链 在 macOS 上安装 ESP-IDF 及工具链 构建首个项目 安装 ESP-IDF 后，您可选择在集成开发环境 (IDE) 中或通过命令行来构建首个项目。 在 IDE 中构建 通过 EIM 安装的 ESP-IDF 版本可搭配以下 IDE 使用，获得图形化开发体验： 基于 Eclipse CDT 的 Espressif-IDE 该 IDE 已集成 IDF Eclipse 插件、必备 Eclipse CDT 插件和其他 Eclipse 平台插件，可支持 ESP-IDF 应用的开发和构建。 安装 ESP-IDF 拓展 的 Visual Studio Code 通过安装拓展，您可直接在 Visual Studio Code 中开发、构建、烧录和监视 ESP-IDF 应用程序。 关于 IDE 的具体配置与使用方法，请参阅上述对应的文档。 通过命令行构建 如果使用命令行构建项目、构建、烧录至 ESP32、监视设备输出，请根据您的操作系统参考以下说明： 在 Windows 上通过命令行构建项目 在 Linux 或 macOS 上通过命令行构建项目 备注 如果尚未安装 ESP-IDF，请跳转至 安装，按照说明先安装所有必需的软件。 卸载 ESP-IDF 如需卸载通过 EIM 安装的 ESP-IDF 及相关工具，可使用图形用户界面 (GUI) 或命令行界面 (CLI) 两种方式。 使用 EIM GUI 卸载 启动 ESP-IDF 安装管理器。在 管理安装 下，点击 打开仪表板。 EIM 打开仪表板 如需删除特定 ESP-IDF 版本，请在该版本下点击 移除 按键。 如果删除所有 ESP-IDF 版本，请点击页面底部的 清除所有 按键。 EIM 卸载 ESP-IDF 使用 EIM CLI 卸载 如需删除特定 ESP-IDF 版本，例如 v5.4.2，请在终端中运行以下命令： eim uninstall v5.4.2 如需删除所有 ESP-IDF 版本，请在终端中运行以下命令： eim purge 相关文档 ESP-IDF 安装管理器 (EIM) 文档 Espressif-IDE (ESP-IDF Eclipse 插件) GitHub 仓库 VSCode ESP-IDF 扩展 GitHub 仓库 此文档对您有帮助吗？ 反馈已收到，谢谢！ 如果您有其他意见，欢迎填写乐鑫文档反馈表。 我们重视您的反馈。 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 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 进