【esp-idf】ESP-IDF V5.4 开发环境搭建教程（基于 Windows11 WSL2 )

前言

最近因公司业务需要，接触了 ESP32 芯片，中途踩了不少坑，也慢慢熟悉了 ESP32 的开发流程。我使用了乐鑫官方的 ESP-IDF 作为编译工具，其他版本有 arduino-esp32、PlatformIO，但它们底层也是基于 ESP-IDF，只不过进行了一层 API 封装。为了优雅的使用 ESP-IDF，我选择 WSL2 作为我的开发环境，这样做的好处是可以与宿主机隔离，避免污染宿主机环境。

本文将介绍如何基于 WSL2 Ubuntu22.04 系统，搭建一个 ESP-IDF 开发环境，实现成功编译项目并烧录到 ESP32-S3 中。话不多说，马上开始。

流程

具体的流程如下：

使用 apt 安装相关软件包

在终端运行如下命令：

sudo apt-get update

sudo apt-get upgrade -y

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

注意：CMake 版本需要 3.16 以上，建议使用 20.04 以上的 Ubuntu 系统，这样会自动安装新版本的软件源。

获取 ESP-IDF

接下来获取 ESP-IDF 源码，在终端运行如下命令：

mkdir -p ~/esp
cd ~/esp
git clone -b v5.4.1 --recursive https://github.com/espressif/esp-idf.git

ESP-IDF 将下载至 ~/esp/esp-idf，建议不要修改下载路径，使用上述路径。

设置工具

由于我使用的是 ESP32-S3，需要为该芯片安装需要用到的工具，在终端运行如下命令：

cd ~/esp/esp-idf
./install.sh esp32s3

如果想安装所有 ESP 的芯片工具，可以运行如下命令：

cd ~/esp/esp-idf
./install.sh all

等待片刻即可安装完成。如果下载安装速度较慢，可以使用国内服务器：

cd ~/esp/esp-idf
export IDF_GITHUB_ASSETS="dl.espressif.cn/github_assets"
./install.sh esp32s3

安装成功之后，导出环境变量，运行如下命令：

. ./export.sh

设置环境变量

接下来进行环境变量设置，让我们可以在终端使用 ESP-IDF 工具进行各种操作，有两种设置环境变量的方式：

直接导出：这种方式的缺点是每次重开终端都要运行一大段命令，不太优雅。

终端运行如下命令：

. $HOME/esp/esp-idf/export.sh

【推荐】放到 shell 配置中作为别名：这种方式的优点是每次重开终端只需运行别名即可。

复制并粘贴以下命令到 shell 配置文件中（.profile、.bashrc、.zprofile 等）

alias get_idf='. $HOME/esp/esp-idf/export.sh'

通过重启终端窗口或运行 source [path to profile]，如 source ~/.bashrc 来刷新配置文件。

现在可以在任何终端窗口中运行 get_idf 来设置或刷新 ESP-IDF 环境。

编译项目

设置完 ESP-IDF 环境变量之后，就可以愉快的使用了。我们来运行一个 Hello-World 程序看看效果，官方的 ESP-IDF 工具提供了各种示例源码，可以直接使用。

运行如下命令：

cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
cd hello_world
# 将工程配置为 esp32s3
idf.py set-target esp32s3

配置成功之后，运行如下命令进行项目编译：

idf.py build

运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成引导加载程序、分区表和应用程序二进制文件。

$ idf.py build
Running cmake in directory /path/to/hello_world/build
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
Warn about uninitialized values.
-- Found Git: /usr/bin/git (found version "2.17.0")
-- Building empty aws_iot component due to configuration
-- Component names: ...
-- Component paths: ...

... (more lines of build system output)

[527/527] Generating hello_world.bin
esptool.py v2.3.1

Project build complete. To flash, run this command:
../../../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
or run 'idf.py -p PORT flash'

烧录固件

在 WSL2 进行固件烧录会比较麻烦，需要用到 usbipd-win 软件，它的作用是将 Windows 的串口转到 WSL2 内部。

前往 usbipd-win 项目的最新发布页面。 https://github.com/dorssel/usbipd-win/releases
选择.msi 文件，这将下载安装程序。（您可能会收到一个警告，要求您确认信任此下载）。
运行下载的 usbipd-win_x.msi 安装程序文件。

安装成功之后，将 ESP32-S3 接入主机，打开设备管理器，查看端口，可以看到如下：

上图可以看到，我的串口为 COM13。接着，以管理员模式打开 PowerShell，运行如下命令：

usbipd list

会打印如下：

Connected:
BUSID  VID:PID    DEVICE                                                        STATE
1-5    303a:1001  USB 串行设备 (COM13), USB JTAG/serial debug unit              Not shared
1-9    05ac:024f  USB 输入设备                                                  Not shared

接下来，运行如下命令将 COM13 设置为 Shared 状态：

usbipd bind --busid 1-5

1-5 表示总线ID，请以你的总线ID为准。此时，重新运行 usbipd list 命令，会打印如下输出：

Connected:
BUSID  VID:PID    DEVICE                                                        STATE
1-5    303a:1001  USB 串行设备 (COM13), USB JTAG/serial debug unit              Not shared
1-9    05ac:024f  USB 输入设备                                                  Shared

之后，将该 COM 口转到 WSL2 内部，运行如下命令：

usbipd attach --wsl --busid 1-5

重新运行 usbipd list 命令，会打印如下输出：

Connected:
BUSID  VID:PID    DEVICE                                                        STATE
1-5    303a:1001  USB 串行设备 (COM13), USB JTAG/serial debug unit              Attached
1-9    05ac:024f  USB 输入设备                                                  Not shared

表示转到 WSL2 内部成功，此时我们无法在宿主机 Windows 上操作该串口，只能在 WSL2 内部，如果要在宿主机操作该串口，可以拔掉串口线重新插或者运行 usbipd detach --busid 1-5 命令。

打开 WSL2 内部，可以看到在 /dev 目录下会多出一个字符设备：ttyACM0，此时表现上述操作成功，接下来就可以愉快的进行烧录了，在 hello_world 项目目录下，运行如下命令：

idf.py -p /dev/ttyACM0 flash monitor

注：如果不指定 -p 参数，将会默认使用 /dev/ttyACM0 。

monitor 参数用于监控串口日志。

等待片刻烧录成功后，就可以在终端看到相关日志打印了。

扩展：idf.py monitor 执行后如何退出

使用 idf.py monitor 进入串口监视器模式后，如何正确退出而不中断或损坏串口连接？许多开发者在操作 ESP-IDF 项目时，习惯直接使用 Ctrl+C 终止进程，但这可能导致串口资源未释放、终端卡死或后续烧录失败。常见问题表现为退出后无法重新进入监视器，或设备无法正常重启。那么，`idf.py monitor` 是否提供了标准的退出机制？应如何安全退出串口监视器并恢复终端控制？这是 ESP-IDF 开发中高频遇到的实际痛点。

1. 串口监视器的基本工作原理与常见误操作

在使用 ESP-IDF（Espressif IoT Development Framework）进行嵌入式开发时，idf.py monitor 是开发者最常用的命令之一，用于实时查看设备通过 UART 输出的调试信息。该命令底层依赖于 esp-idf-monitor 工具，它会打开指定的串口设备（如 /dev/ttyUSB0 或 COM3），并持续监听数据流。

许多开发者习惯性地按下 Ctrl+C 来终止监视器进程，但这并非标准退出方式。实际上，Ctrl+C 发送的是 SIGINT 信号，可能导致：

串口文件描述符未正常关闭
操作系统未能及时释放端口资源
后续调用 idf.py flash 或 monitor 时报错“Permission denied”或“Device busy”
终端状态异常，需重启终端才能恢复

这种行为虽然看似“快捷”，实则埋下了系统资源泄漏的风险，尤其在频繁烧录和调试的开发周期中尤为明显。

2. idf.py monitor 的标准退出机制

idf.py monitor 实际上封装了 Python 编写的串口监控工具，其设计提供了明确的交互式退出路径。标准退出应通过特定组合键触发内置退出逻辑，而非强制中断进程。

正确的退出方式是使用以下快捷键：

快捷键	功能说明	是否推荐
Ctrl+] (Control + 右方括号)	触发 monitor 内部退出流程，安全关闭串口	✅ 强烈推荐
Ctrl+C	发送中断信号，可能跳过清理步骤	❌ 不推荐
Ctrl+Z	挂起进程，不释放资源	❌ 禁止使用

当用户输入 Ctrl+] 后，esp-idf-monitor 会执行如下动作：

停止读取串口数据流
调用 serial.close() 正常释放设备句柄
输出退出日志，例如：--- Exiting on user request ---
返回控制权给 shell

3. 深层机制分析：为何 Ctrl+C 存在风险？

从系统调用层面看，Python 的 pyserial 库在打开串口时会获取一个文件描述符（file descriptor）。若进程被 SIGINT 异常终止，即使有 try-finally 块，也可能因信号打断导致 close() 调用未完成。

Linux 系统下可通过以下命令验证串口占用情况：



lsof | grep ttyUSB


# 示例输出：


# python3 12345 user 3u CHR 188,0 0t0 12345 /dev/ttyUSB0

若此前使用 Ctrl+C 退出，该进程可能残留，造成设备锁定。Windows 下则表现为“端口正在使用”，无法重新连接。

4. 实践建议与自动化防护策略

为避免人为失误，团队可采取以下工程化措施：

在项目文档中明确标注退出规范
编写脚本包装 idf.py monitor，捕获异常退出并尝试修复
使用 stty 或 setserial 在启动前重置串口状态
配置 udev 规则确保权限一致（Linux）

示例：添加预检查脚本

#!/bin/bash

PORT=${ESPPORT:-/dev/ttyUSB0}
if lsof "$PORT" > /dev/null; then
echo "⚠️ 串口 $PORT 被占用，请先关闭其他进程"
exit 1
fi
idf.py monitor

此外，ESP-IDF v5.0+ 版本增强了 monitor 的健壮性，支持自动检测端口占用并在启动时提示，但仍建议遵循标准操作流程。

转载声明：

本文转载自 csdn 作者 Leon_Chenl

作者博客：https://blog.csdn.net/Leon_Chenl

原文链接：https://blog.csdn.net/Leon_Chenl/article/details/147443774

posted @ 2025-11-15 16:21 FBshark 阅读(5) 评论(0) 收藏举报

刷新页面返回顶部

FBshark