25.6 ESP-IDF 开发环境

25.6.1 ESP 系列芯片概述

除 STM32 平台外，乐鑫科技（Espressif）的 ESP 系列芯片也是物联网（IoT）开发领域的主流选择，该系列芯片集成度高、功耗低，具备 Wi‑Fi 和蓝牙连接能力。

ESP-IDF 是乐鑫（Espressif）官方为 ESP32、ESP32-S、ESP32-C、ESP32-H、ESP32-P 等系列 SoC 提供的开发框架。ESP8266 和 ESP8285 使用独立的 RTOS SDK，不在 ESP-IDF 支持范围内。ESP-IDF 框架包含完整的 Wi‑Fi/Bluetooth 协议栈、FreeRTOS 实时操作系统内核、各类外设驱动程序、功能组件库以及丰富的示例代码。

警告
ESP-IDF 官方还未正式支持 FreeBSD 平台，其官方文档仅列出了 Windows、Linux、macOS 三大平台的支持说明。
在 ESP-IDF 仓库的 tools/idf_tools.py 文件中存在以下配置：
python
'FreeBSD-amd64': PLATFORM_LINUX64,
'FreeBSD-i386': PLATFORM_LINUX32,
1
2
但这仅为将 FreeBSD 平台映射至 Linux 平台的兼容性映射方式，并非官方意义上的直接支持。
尽管通过一定的技术手段可在 FreeBSD 上成功编译 ESP-IDF，但其稳定性仍不及官方支持平台，且可能出现未预期的错误，因此不建议在生产环境中采用此配置。

25.6.2 安装 `esptool` 与编译工具链

在开始使用 ESP-IDF 之前，需先安装固件烧录工具与交叉编译工具链。

使用 pkg 二进制包管理器安装：

# pkg install py311-esptool xtensa-esp-elf

或者使用 ports 构建：

# cd /usr/ports/comms/py-esptool && make install clean          # ESP 烧录工具
# cd /usr/ports/devel/xtensa-esp-elf && make install clean     # ESP32/ESP-IDF 编译工具链

25.6.3 安装 ESP-IDF

25.6.3.1 下载最新的 ESP-IDF RELEASE 压缩包

$ fetch https://github.com/espressif/esp-idf/releases/download/v5.5.3/esp-idf-v5.5.3.zip

注意
本节中出现的 esp-idf-v5.5.3、espidf.constraints.v5.5.txt 等文件名和路径均与特定版本绑定，请将其替换为自己实际安装的 ESP-IDF 版本号。

技巧
ESP-IDF 的版本可能会更新，请检查 ESP-IDF 的 GitHub 仓库以获取最新版。

25.6.3.2 安装必要工具

使用 pkg 安装：

# pkg install rust cmake ninja pkgconf libffi openssl libxml2 unzip

或者使用 ports 构建：

# cd /usr/ports/lang/rust && make install clean      # 项目构建需使用 Cargo
# cd /usr/ports/devel/cmake && make install clean      # 项目构建系统核心
# cd /usr/ports/devel/ninja && make install clean      # 高效的构建工具
# cd /usr/ports/devel/pkgconf && make install clean      # 提供 pkg-config 功能
# cd /usr/ports/devel/libffi && make install clean      # Python cffi 模块的底层依赖
# cd /usr/ports/security/openssl && make install clean      # 提供加密算法支持
# cd /usr/ports/textproc/libxml2 && make install clean      # XML 解析库
# cd /usr/ports/archivers/unzip && make install clean      # 终端解压缩工具

25.6.4 初次运行 ESP-IDF 安装程序

下载完 ESP-IDF 后，运行安装脚本配置环境：

$ unzip /path/to/esp-idf-v5.5.3.zip          # 解压 ESP-IDF
$ cd esp-idf-v5.5.3
$ ./install.sh                               # 运行 ESP-IDF 安装脚本（使其生成 espidf.constraints.v5.5.txt 文件）

此时脚本会自动下载这些工具：

~/.espressif/
└── dist/
    ├── esp-rom-elfs-20241011.tar.gz
    ├── esp32ulp-elf-2.38_20240113-linux-amd64.tar.gz
    ├── openocd-esp32-linux-amd64-0.12.0-esp32-20251215.tar.gz
    ├── openocd-esp32-linux-amd64-0.12.0-esp32-20251215.tar.gz.tmp
    ├── riscv32-esp-elf-14.2.0_20251107-x86_64-linux-gnu.tar.xz
    ├── riscv32-esp-elf-14.2.0_20251107-x86_64-linux-gnu.tar.xz.tmp
    ├── riscv32-esp-elf-gdb-16.3_20250913-x86_64-linux-gnu.tar.gz
    ├── xtensa-esp-elf-14.2.0_20251107-x86_64-linux-gnu.tar.xz
    └── xtensa-esp-elf-gdb-16.3_20250913-x86_64-linux-gnu.tar.gz

技巧
如果下载速度较慢，可复制终端中的下载链接，使用工具加速下载。

注意
首次运行 ./install.sh 命令将在 Python 包安装阶段停滞并产生错误：

ERROR: Cannot install cryptography because these package versions have conflicting dependencies.
...（省略一些非必要信息）
ERROR: ResolutionImpossible

原因：

PyPI 和 Espressif 的 extra-index 中不包含 FreeBSD-amd64 的预编译 wheel（官方只提供了 linux-amd64、win-amd64、macosx 等）。同时 espidf.constraints.v5.5.txt 文件中还强制指定了 --only-binary cryptography 和 --only-binary tree-sitter-c，导致 pip 拒绝从源代码编译。

解决方法：修改 constraints 文件：

$ sed -i '' 's/^--only-binary /#--only-binary /' ~/.espressif/espidf.constraints.v5.5.txt

该命令旨在解除源代码编译限制，将文件中所有 --only-binary 全部注释，允许 pip 从源代码编译 cryptography、tree-sitter-c 等包。

修改完成后，重新执行：

$ ./install.sh

重新执行后，安装脚本即可顺利完成 Python 环境阶段。

安装完成后，即可激活 ESP-IDF 环境：

对于 sh / Bash / Zsh 用户：

$ cd ~/Downloads/esp-idf-v5.5.3
$ ./export.sh

对于 fish 用户：

$ cd ~/Downloads/esp-idf-v5.5.3
$ ./export.fish

25.6.5 编译和烧录示例

配置开发环境后，即可开始编译和烧录示例程序。

25.6.5.1 擦除整个 Flash

警告
erase_flash 将擦除芯片上的全部 Flash 内容，包括现有固件、分区表和所有存储数据。擦除后设备将无法启动，直至重新烧录固件。

在烧录新固件前，通常需先擦除芯片上的 Flash 存储空间，确保新固件可正常运行。

esptool.py --chip esp32 --port /dev/cuaU0 erase_flash

参数说明：

参数	说明
`--chip`	改为实际的芯片型号，如 `esp32s3`、`esp32c3`
`--port`	端口可根据 `dmesg \| grep usb` 或 `usbconfig` 查找，通常是 `/dev/cuaU0` 或 `/dev/ttyU0`

更多子命令帮助请使用：esptool.py {子命令} --help，例如 esptool.py write_flash --help。

25.6.5.2 编译项目

擦除 Flash 后，创建并编译 ESP-IDF 项目：

$ mkdir -p /path/to/new/project      # 创建文件夹来存储示例项目
$ cd /path/to/new/project    # 进入该目录
$ idf.py create-project hello_world      # 创建名为 hello_world 的 ESP-IDF 项目
$ idf.py set-target esp32          # 设定目标芯片型号，可改为 esp32s3 等
$ idf.py build                     # 使用 xtensa-esp-elf-gcc 编译

25.6.5.3 烧录固件

使用 esptool.py 烧录：

$ esptool.py --chip esp32 --port /dev/cuaU0 --baud 921600 write_flash -z 0x1000 bootloader.bin

参数说明：

参数	说明
`-z`	压缩模式，可提升传输速度
`0x1000`	应用程序起始地址
`bootloader.bin`	要烧录的应用程序固件

额外说明：

组件	地址
bootloader	`0x1000`
partition table	`0x8000`
app (factory)	`0x10000`

警告
不同型号的刷写地址不一定一致，请务必参考官方文档核查。参见：乐鑫科技. 获取不同软件开发平台的固件烧录信息（开发阶段）[EB/OL]. (n.d.)[2026-04-19]. https://docs.espressif.com/projects/esp-techpedia/zh_CN/latest/esp-friends/get-started/try-firmware/get-firmware-address.html.

或者使用 idf.py 烧录：

$ idf.py -p /dev/cuaU0 flash       # 自动调用 esptool.py 烧录

25.6.6 参考文献

Espressif Systems. ESP-IDF 编程指南：分区表[EB/OL]. [2026-04-19]. https://docs.espressif.com/projects/esp-idf/zh_CN/v6.0/esp32/api-guides/partition-tables.html. 官方分区表介绍。
Espressif Systems. Flashing Firmware — ESP32 esptool documentation[EB/OL]. [2026-04-19]. https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/flashing-firmware.html. 官方刷写固件的方法。

25.6 ESP-IDF 开发环境 ​

25.6.1 ESP 系列芯片概述 ​

25.6.2 安装 esptool 与编译工具链 ​

25.6.3 安装 ESP-IDF ​

25.6.3.1 下载最新的 ESP-IDF RELEASE 压缩包 ​

25.6.3.2 安装必要工具 ​

25.6.4 初次运行 ESP-IDF 安装程序 ​

25.6.5 编译和烧录示例 ​

25.6.5.1 擦除整个 Flash ​

25.6.5.2 编译项目 ​

25.6.5.3 烧录固件 ​

25.6.6 参考文献 ​