FreeBSD 中文社区
搜索 K

主题

26.8 ESP-IDF 开发环境 ​

26.8.1 ESP 系列芯片概述 ​

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

乐鑫科技 Espressif 的核心开发项目为 ESP-IDF，这是该公司为 ESP8266、ESP32 等芯片系列提供的官方开发框架，以 Apache 2.0 许可证开源发布。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,

但这仅为将 FreeBSD 平台映射至 Linux 平台的兼容性处理手段，并非官方意义上的直接支持。

尽管通过一定的技术手段可在 FreeBSD 上成功编译 ESP-IDF，但其稳定性仍不及官方支持平台，且可能出现未预期的错误，因此不建议在生产环境中采用此配置。

26.8.2 安装 esptool 与编译工具链 ​

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

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

sh
# pkg install py311-esptool xtensa-esp-elf

或者使用 ports 构建：

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

26.8.3 安装 ESP-IDF ​

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

sh
$ 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 仓库 以获取最新版。

26.8.3.2 安装必要工具 ​

使用 pkg 安装：

sh
# pkg install rust cmake ninja pkgconf libffi openssl libxml2 unzip

或者使用 ports 构建：

sh
# 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      # 终端解压缩工具

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

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

sh
$ 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 文件）

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

sh
~/.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 包安装阶段停滞并产生错误：

sh
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 文件：

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

这行命令旨在放开源代码编译限制，将文件中所有 --only-binary 都注释掉，允许 pip 从源代码编译 cryptography、tree-sitter-c 等包。

修改完成后，重新执行：

sh
$ ./install.sh

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

成功编译后，即可激活 ESP-IDF 环境：

对于 sh / Bash / Zsh 用户：

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

对于 fish 用户：

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

26.8.5 编译和烧写示例 ​

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

26.8.5.1 擦除整个 Flash ​

警告

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

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

sh
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。

26.8.5.2 编译项目 ​

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

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

26.8.5.3 烧录固件 ​

使用 esptool.py 烧录：

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

参数说明：

  • -z：压缩模式，速度更快。
  • 0x1000：应用程序起始地址。
  • bootloader.bin：要烧录的应用程序固件。

额外说明：

组件地址
bootloader0x1000
partition table0x8000
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 烧录：

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

26.8.6 参考文献 ​