ESP32-S3环境配置完整记录

ESP32-S3环境配置完整记录

1. ESP-IDF环境搭建

1.1 基础安装

1
2
3
4
5
6
7
8
9
# 克隆ESP-IDF仓库v4.4版本
git clone -b release/v4.4 --recursive https://github.com/espressif/esp-idf.git

# 安装工具链
cd esp-idf
./install.sh

# 配置环境变量
. ./export.sh

1.2 自启动脚本配置

最初尝试创建类似Windows下的快捷方式，但发现在Ubuntu中直接修改当前shell更合适。

最终验证可用的脚本(hello_world.sh):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#!/bin/bash

# 加载 conda 命令
source ~/anaconda3/etc/profile.d/conda.sh

# 激活环境
conda activate dl_env

# 配置 ESP-IDF 环境
source ~/esp/esp-idf/export.sh

# 设置开发板和端口
idf.py set-target esp32s3
export ESPPORT=/dev/ttyCH341USB0

# 切换目录
cd ~/esp/esp-idf/examples/get-started/hello_world

echo "Conda 环境已激活，ESP-IDF 已配置为 esp32s3，串口设备为 ${ESPPORT}"

重要说明: 必须使用 source hello_world.sh 运行脚本，而不是直接执行 ./hello_world.sh，否则环境变量无法在当前shell中生效。

1.3 Python环境问题处理

运行脚本时遇到的Python依赖错误:

1
2
3
4
5
6
7
8
Error: The following Python requirements are not satisfied:
click>=7.0
future>=0.15.2
pyserial>=3.3
pyparsing>=2.0.3,<2.4.0
pyelftools>=0.22
...
construct 2.10.68 requires python<3.11

解决步骤:

  1. 确保Python版本正确（必须 <= 3.10）：

    1
    2
    3
    # 创建新的conda环境
    conda create -n esp-idf-env python=3.10
    conda activate esp-idf-env

  2. 安装所需依赖:

    1
    pip install -r ~/esp/esp-idf/requirements.txt

2. CH341串口驱动安装配置

2.1 驱动安装过程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 1. 卸载旧版本驱动
rm -rf /lib/modlues/$(uname -r)/kernel/drivers/usb/serial/ch341.ko

# 2. 解压驱动
unzip driver.zip
cd CH341SER_LINUX/driver

# 3. 编译驱动
make

# 4. 首次加载尝试
sudo insmod ch341.ko
或
sudo make load
# 错误: ERROR: could not insert module ch341.ko: Key was rejected by service

# 5. 强制加载驱动（如果首次加载失败其实强制加载也会失败，最终通过关闭bios中的secure boot解决，成功安装）
sudo modprobe -f ch341

# 6. 开机自动加载驱动
sudo cp ch341.ko /lib/modules/$(uname -r)/kernel/drivers/usb/serial/
sudo depmod

2.2 串口权限和验证

  1. 添加用户到dialout组（需要注销重新登录生效）：

    1
    2
    sudo usermod -a -G dialout $USER
    groups  # 验证用户组

  2. 如果权限问题仍然存在：

    1
    2
    3
    4
    5
    6
    # 检查设备权限
    ls -l /dev/ttyUSB0
    # 输出: crw-rw---- 1 root dialout 188, 0 日期 时间 /dev/ttyUSB0

    # 临时修改权限
    sudo chmod 666 /dev/ttyCH341USB0

  3. 验证驱动加载和设备识别：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    # 检查驱动状态
    lsmod | grep ch341

    # 检查设备文件
    ls /dev/ttyCH341USB*
    # 应显示: /dev/ttyCH341USB0

    # 查看系统日志
    dmesg | grep tty
    # 应包含:
    # ch341-uart converter now attached to ttyUSB0
    # ttyCH341USB0: ch341 USB device

3. ESP32开发操作

3.1 编译和烧录

1
2
3
4
5
6
7
8
9
10
11
# 不指定串口时会报错
idf.py flash
# 错误: No serial ports found. Connect a device, or use '-p PORT' option to set a specific port.

# 正确的串口指定方式：
# 方式1: 直接指定串口
idf.py -p /dev/ttyCH341USB0 flash

# 方式2: 设置环境变量(推荐，已包含在启动脚本中)
export ESPPORT=/dev/ttyCH341USB0
idf.py flash

3.2 串口监控操作

1
2
3
4
5
6
# 启动监控
idf.py monitor  # 会使用ESPPORT环境变量
# 或
idf.py -p /dev/ttyCH341USB0 monitor

# 退出监控: Ctrl + ]

3.3 设备连接管理

断开设备前的注意事项：

  1. 使用 Ctrl + ] 退出监控状态
  2. 确认没有正在进行的数据传输或固件烧录
  3. 确认完成后可以直接拔出USB连接线

重新连接后：

1
2
# 检查设备是否被正确识别
ls /dev/ttyCH341USB*

4. 常见问题和解决方案

4.1 设备识别问题

当设备无法被识别时：

1
2
ls /dev/ttyUSB*
# 报错: ls: cannot access '/dev/ttyUSB*': No such file or directory

解决步骤：

  1. 重新插拔设备
  2. 尝试其他USB端口
  3. 使用ls /dev/ttyCH341USB*
  4. 按之前的步骤重新检查驱动状态

4.2 编译和烧录失败

可能的原因和解决方案：

  1. 目标板设置错误：

    1
    idf.py set-target esp32s3

  2. 烧录失败：

  • 检查ESPPORT环境变量是否正确
  • 验证串口权限
  • 确认USB连接稳定

4.3 监控问题处理

  1. 如果无法启动监控：
  • 确认没有其他程序占用串口
  • 检查串口权限和设备状态
  1. 监控退出：
  • 始终使用 Ctrl + ] 正常退出
  • 避免直接关闭终端窗口
ai chat
ESP32-S3环境配置完整记录
https://blakehansen130.github.io/2024/11/20/esp32-notes-nodup/
发布于
2024年11月20日
许可协议