固件

ESP32-S3 固件的构建、烧录、配置和调试完整指南。

前提条件

ESP-IDF 安装

按照官方指南安装 ESP-IDF v5.x：

mkdir -p ~/esp
cd ~/esp
git clone -b v5.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32s3
source export.sh

micro-ROS 组件

固件依赖 micro-ROS for ESP32。首次构建时 ESP-IDF 组件管理器会自动获取。

USB 驱动

Linux：无需驱动（内核支持 CP2102）
macOS：安装 Silicon Labs CP210x driver
Windows：从 Silicon Labs 安装 CP210x Universal Driver

构建

# 加载 ESP-IDF 环境
. $HOME/esp/esp-idf/export.sh

cd firmware/esp32

# 设置目标芯片
idf.py set-target esp32s3

# （可选）配置选项
idf.py menuconfig

# 构建（默认 SKU：standard）
idf.py build

SKU 变体

可用变体：basic、standard、industrial

# 构建特定 SKU 变体（在 firmware/esp32/ 目录下）
cp sdkconfig.defaults.industrial sdkconfig.defaults
idf.py fullclean && idf.py build

主机端单元测试（无需硬件）

cd firmware/tests
make clean && make
./test_runner

烧录

连接

使用 USB-C 线缆连接计算机和 ESP32-S3 编程端口。

如果使用 UART 排针：

TX -> USB-UART 适配器 RX
RX -> USB-UART 适配器 TX
GND -> GND
按住 BOOT 按钮同时复位以进入下载模式

烧录命令

idf.py -p /dev/ttyUSB0 flash

各平台端口名称：

Linux：/dev/ttyUSB0 或 /dev/ttyACM0
macOS：/dev/cu.usbserial-* 或 /dev/cu.SLAB_USBtoUART
Windows：COM3（查看设备管理器）

监控

idf.py -p /dev/ttyUSB0 monitor

预期启动信息：

I (325) boot: ESP-IDF v5.2
I (330) boot: compile time May 15 2026
I (380) 3we_fw: Firmware version: 0.2.0 (standard)
I (385) 3we_fw: Motor PID initialized (Kp=1.0, Ki=0.5, Kd=0.01)
I (390) 3we_fw: IMU BNO055 detected at 0x28
I (395) 3we_fw: micro-ROS transport: USB-CDC @ 921600 baud
I (400) 3we_fw: Watchdog timeout: 200ms
I (405) 3we_fw: Ready. Waiting for micro-ROS agent...

micro-ROS Agent（Pi 端）

烧录完成后，在 Raspberry Pi 上启动 micro-ROS agent，将串行数据桥接到 ROS 2 话题：

ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyACM0 --baud 921600

或使用内置启动器：

threewe hw start-agent

发布的话题

运行后，ESP32 发布以下话题：

话题	类型	频率	描述
`/wheel_encoders`	`sensor_msgs/JointState`	50 Hz	4 个轮子的编码器计数（FL、FR、BL、BR）
`/imu/raw`	`sensor_msgs/Imu`	100 Hz	BNO055 的原始 IMU 数据
`/battery_voltage`	`std_msgs/Float32`	1 Hz	电池电压读数

订阅的话题

话题	类型	描述
`/cmd_vel`	`geometry_msgs/Twist`	速度指令（转换为轮速）
`/motor_enable`	`std_msgs/Bool`	启用/禁用电机驱动器

配置

编辑 firmware/esp32/main/config.h 进行调整：

#define WHEEL_RADIUS_M       0.0325f   // 65mm diameter wheels
#define WHEEL_BASE_M         0.10f     // distance from center to wheel
#define ENCODER_CPR          11        // counts per revolution
#define PID_KP               1.0f
#define PID_KI               0.5f
#define PID_KD               0.01f
#define IMU_I2C_ADDR         0x28
#define MOTOR_PWM_FREQ       20000     // 20 kHz PWM
#define WATCHDOG_TIMEOUT_MS  200       // Stop motors if no cmd for 200ms
#define MICROROS_BAUD        921600

OTA 更新

对于现场部署的机器人，固件支持 OTA 更新：

# 构建 OTA 镜像
idf.py build
# 通过网络上传（需要 OTA 分区方案）
python scripts/ota_upload.py --ip 192.168.1.100 --file build/3we_firmware.bin

OTA 前检查事项：

电池电压 > 7.0V（3S LiPo）
机器人静止（电机停止）
WiFi 信号强度 > -70 dBm

故障排除

症状	解决方案
USB 未检测到 ESP32	按住 BOOT 按钮同时按 RESET 进入下载模式。
Agent 连接但无话题	检查波特率是否匹配（两端均为 921600）。
IMU 报告全零	验证 I2C 接线（默认配置中 SDA 接 GPIO8，SCL 接 GPIO9）。
电机低速时抖动	增大 `PID_KI` 或降低 `MOTOR_PWM_FREQ`。
编码器计数漂移	确认编码器 CPR 与您的具体电机型号匹配。
构建失败提示 “component not found”	运行 `idf.py reconfigure` 获取 micro-ROS 组件。