ESP32-C3 BSP 实操指南：从零配置到首次烧录 LED 闪烁

ESP32-C3 BSP 实操指南：从零配置到首次烧录 LED 闪烁

【免费下载链接】rt-threadRT-Thread is an open source IoT Real-Time Operating System (RTOS). https://rt-thread.github.io/rt-thread/项目地址: https://gitcode.com/gh_mirrors/rt/rt-thread

看完这篇，你能在乐鑫 ESP32-C3 上跑通仓库的 ESP32-C3 BSP：scons 编译出固件、esptool 烧录进 Flash、板子默认 1 秒周期闪烁 LED。它覆盖 LUATOS_ESP32C3 与 HX-DK 两款开发板，提供 Docker 一键编译和原生工具链两套环境方案，内核之上靠idf_port适配层复用 ESP-IDF 的驱动和 ROM 代码。

📌 硬件与芯片速查

引脚差异不折腾代码：LUATOS 板 LED 默认 IO12，HX 板 IO8；UART0 的 TX/RX 默认 IO21/IO20，在 驱动 Kconfig 里选板号即自动切换。

🔧 开发环境准备

先做硬件检查，再装软件，顺序别反：

ls /dev/ttyUSB* # 或 /dev/ttyACM*

Linux 下能列出串口设备说明板子接对了；Windows 看设备管理器里有没有新串口。LUATOS_ESP32C3 的 USB 口只走 JTAG 调试，日志要接板子上的 CP2102 串口芯片。

主线方案选 Docker 一键编译，三条命令搞定：

git clone https://gitcode.com/gh_mirrors/rt/rt-thread cd rt-thread/bsp/ESP/ESP32_C3/docker sudo docker build -t rtthread_esp32c3 .

构建参数可加--build-arg HTTP_PROXY/HTTPS_PROXY，否则容器内拉软件包可能卡住。进容器时把串口映射进去：

sudo docker run -it --device=/dev/ttyUSB* rtthread_esp32c3

备选是原生环境，适合正式开发：下载riscv32-esp-elf工具链后pip install esptool。工具链路径只需一行，改 rtconfig.py 里的EXEC_PATH或导出环境变量RTT_EXEC_PATH：

export RTT_EXEC_PATH=/opt/riscv32-esp-elf/bin

环境变量优先于EXEC_PATH默认值，~会自动展开，工具前缀riscv32-esp-elf-。

✅ 首次编译与烧录

Step 1：进 BSP 目录打开 menuconfig，首次会自动下载 env 脚本到~/.env：

scons --menuconfig

预期：终端弹出文本菜单，在 Hardware Drivers Config → Select BSP board 选板号（默认 LUATOS_ESP32C3），保存退出。

Step 2：拉取软件包并编译：

source ~/.env/env.sh pkgs --update scons

pkgs --update会拉取 ESP-IDF 与 FreeRTOS-Wrapper 两个包；预期：编译结尾同时生成rtthread.elf和rtthread.bin，看到这两个文件说明通过。

Step 3：烧录三个文件，偏移地址固定：

esptool.py -b 115200 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 rtthread.bin

参数对应 SConstruct 打包时的 DIO 模式、4MB Flash、80MHz 频率，烧录前别改。预期：Linux 出现Hash of data verified；Windows 用 Flash Download Tools 3.9.4，芯片型号选 ESP32-C3，按上表配三个文件，START 后出现A successful flash has been completed。

📦 按需开启外设：一张开关总表加三个坑

默认只开 GPIO 和 UART，其余按需在 menuconfig 勾选：

坑 1：软件 I2C。现象：开了软件 I2C 后定时器异常。原因：软件 I2C 会占用一个硬件通用定时器。怎么绕：时钟用别的通道，或只开硬件 I2C——但硬件 I2C 目前会丢字节，两者各有所失，以仓库文档描述为准。

坑 2：Wi-Fi 中断里调消息队列。现象：在 ISR 里用rt_mq_recv后系统挂死。原因：Wi-Fi 驱动当前实现有此限制。怎么绕：中断里只置标志位，实际处理放线程。

坑 3：BLE 与 Wi-Fi 互斥。现象：同时开启后互相干扰。原因：射频资源冲突。怎么绕：开 BLE 前在 menuconfig 关掉RT_USING_WIFI和LWIP，并先调esp_timer_init()再进 NimBLE 接口，main.c 里已有这段顺序可参考。

🐛 调试与排错

出事了先查这 5 条：

• 串口权限：ls /dev 能列出设备，esptool 却打不开
• 板号选对没：menuconfig 里 board 选项和实物一致
• 工具链路径：EXEC_PATH 或 RTT_EXEC_PATH 指向真实 bin
• 偏移地址：三个文件烧到 0x0 / 0x8000 / 0x10000
• 软件包：pkgs --update 拉的是不是最新主线

深入排查开BSP_ENABLE_GDBSTUB，芯片出错后自动进 GDB 模式：

sudo riscv32-esp-elf-gdb (gdb) source esp32c3.gpb (gdb) continue

脚本里写好了内存映射、115200 波特率和/dev/ttyACM0，按自己端口改最后一行即可。

⚠️ 已知限制与规避策略

• 硬件 I2C 丢字节 → 硬件控制器在 ESP32-C3 上表现不稳 → 用软件 I2C，接受它吃掉一个硬件定时器。
• Wi-Fi 的 ISR 限制 → 驱动实现未完成 → 消息队列、互斥量一律放线程里处理。
• BLE（NimBLE）长时间运行后出错 → 当前实现问题 → 短任务验证功能，不跑长稳；且 Wi-Fi 必须关闭。

以上均为当前主线分支状态，细节以仓库实际代码为准。

接下来可以试

把主循环的 LED 闪烁换成 UART 打印心跳；开软件 I2C 接一个温湿度传感器；开 SPI2 驱动一块 OLED。维护人：supperthomas、tangzz98、wumingzi，有编译或烧录问题可以联系或在仓库提 Issue。

【免费下载链接】rt-threadRT-Thread is an open source IoT Real-Time Operating System (RTOS). https://rt-thread.github.io/rt-thread/项目地址: https://gitcode.com/gh_mirrors/rt/rt-thread