烧录与硬件连接

从一根 USB 线到板子跑起程序：驱动、选板选口、编译、烧录、串口，全流程一次讲清。

LabCode 的硬链路是 写码 → 编译 → 烧录 → 串口。板卡信息统一来自 boardRegistry.ts（单一数据源），当前收录 10 款开发板（5 款 ESP32 + 5 款 STM32）。ESP32 走 Arduino / ESP-IDF 工具链，STM32 走 PlatformIO + OpenOCD（ST-Link SWD）。

1. 安装驱动

1

按芯片选驱动

  • USB 转串口（ESP32 多数板）：CP210x（Silicon Labs）或 CH340（WCH）。设备管理器里出现「USB-SERIAL CH340 / CP210x」即正常。
  • ESP32-S3 / C3 / P4 原生 USB：部分板用芯片自带 USB（VID:PID 共享 303a:1001），免串口驱动，插上即出「USB JTAG/serial」端口。
  • STM32（ST-Link）：装 STSW-LINK009 驱动，连接后出现「ST-Link Debug」。
驱动没装好是最常见的「找不到端口」原因。换根线、换 USB 口、重装驱动后再试。

2. 连接开发板

2

物理连接

  • 用数据线（不是仅充电线）连接电脑与开发板
  • ESP32：接 UART0 对应的 USB（或原生 USB 口）；STM32：接 ST-Link 的 SWD 口（四线：SWCLK / SWDIO / GND / 3.3V）
  • 板载 LED / 电源灯亮起说明供电正常

3. 在「设备」面板选板选口

3

板卡与端口

  • 左侧「设备」面板列出自动检测到的串口；下拉选择开发板（FQBN，如 esp32:esp32:esp32s3）
  • 端口下拉选择刚才出现的 COM 口（Windows）或 /dev/ttyUSB*（Linux）/ /dev/cu.usbserial*（macOS）
  • 板卡与端口是唯一可编辑来源（设备面板订阅 serial.onPortsChanged）
板卡认错是头号坑：若板子被识别成别的型号，编译烧录会白等约 142 秒后被拒。务必在设备面板确认板型与端口后再点上传。

4. 编译

4

选工具链

  • ESP32（Arduino）：arduino-cli-toolchain 插件，首次编译自动装核心
  • ESP32（ESP-IDF）：esp-idf-toolchain 插件，目标芯片随设备面板自动 set_target
  • STM32：PlatformIO + OpenOCD，仅支持 SWD 烧录
  • 工具栏「编译」一键构建；.ino 编译前会自动落盘到工程目录

5. 烧录（上传）

5

一键上传

  • 工具栏「上传」会先关串口 → 编译 → 失败即止 → 烧录 → 恢复串口
  • 烧录前请关闭串口监视器，避免端口被占用导致失败
  • 失败会显式置错误态并清残留，不会卡死
ESP32 原生 USB 烧录偶尔需要按住 BOOT 再点上传，进入下载模式。

6. 串口监视

6

看输出

  • 「串口监视器」独立窗口，实时查看 Serial.print 输出、发送命令
  • 波特率默认 115200，可按板子调整
  • 监视时烧录会被拦（端口占用），先停监视再上传

7. 常见硬件坑

更多排错见 常见问题；接口与插件市场见 接口参考。