【产出】 > 在 Arduino IDE 里装好 ESP32 开发板支持包,把第一个程序烧进开发板,并能看懂上传失败时的几类报错。
【版本】 > 适用于 Arduino IDE 2.x 与 arduino-esp32 3.x 支持包;ESP32、ESP32-S3、ESP32-C3 开发板步骤相同,只是开发板型号选择不同。
一、准备
| 项目 | 说明 |
|---|---|
| 开发板 | 任意 ESP32 DevKit(板载 USB 转串口芯片,常见 CP2102 或 CH340) |
| 数据线 | 一定要能传数据的 USB 线。很多充电线只有电源线,插上去电脑没反应 |
| 电脑 | Windows 10/11、macOS 或 Linux,能联网 |
| 软件 | Arduino IDE 2.x(arduino.cc 官网下载) |
【注意】 > 仅支持充电的数据线是新手最常见的"装了驱动也找不到端口"原因。换一根确定能传文件的线再排查其他问题。
二、安装 USB 串口驱动
把开发板插到电脑上,先确认电脑认出了串口:
- Windows:打开"设备管理器 → 端口 (COM 和 LPT)",应出现
Silicon Labs CP210x ... (COMx)或USB-SERIAL CH340 (COMx)。如果出现在"其他设备"里且带黄色感叹号,按板子上芯片丝印去芯片厂商官网下载驱动:CP210x 找 Silicon Labs,CH340 找沁恒(WCH)。 - macOS:终端执行
ls /dev/cu.*,应出现cu.usbserial-xxxx或cu.SLAB_USBtoUART。 - Linux:执行
ls /dev/ttyUSB* /dev/ttyACM*。如果上传时报权限错误,把当前用户加入dialout组后重新登录:
sudo usermod -a -G dialout $USER
ESP32-S3、ESP32-C3 等带原生 USB 的芯片,如果 USB 线直接接在芯片的 USB 引脚上(板子上常标 USB 而不是 UART),系统会识别为 USB CDC 设备,一般不需要额外驱动。
三、添加 ESP32 开发板支持包
- 打开 Arduino IDE,进入"文件 → 首选项"(macOS 为"Arduino IDE → Settings")。
- 在"其他开发板管理器地址"一栏填入乐鑫官方稳定版地址,多个地址之间用英文逗号分隔:
https://espressif.github.io/arduino-esp32/package_esp32_index.json
- 打开"工具 → 开发板 → 开发板管理器",搜索
esp32,安装作者为 Espressif Systems 的那一个(不要装名字相近的第三方包)。 - 安装完成后重启 IDE。
【提示】 > 国内网络下载失败时,乐鑫提供了极狐(Jihulab)镜像地址:
https://jihulab.com/esp-mirror/espressif/arduino-esp32/-/raw/gh-pages/package_esp32_index_cn.json。使用镜像时请选择带-cn后缀的版本,官方说明这类版本不能自动更新,需要手动升级。
四、选择开发板和端口
| 菜单 | 怎么选 |
|---|---|
| 工具 → 开发板 | 普通 ESP32 选 ESP32 Dev Module;S3 选 ESP32S3 Dev Module;C3 选 ESP32C3 Dev Module。有具体型号(如 Seeed XIAO)就选对应型号 |
| 工具 → 端口 | 选第二步看到的那个 COM 口 / /dev/cu.* / /dev/ttyUSB0 |
| 工具 → Upload Speed | 默认 921600;不稳定时改成 115200 |
| 工具 → USB CDC On Boot(S3/C3) | 用原生 USB 口看串口输出时设为 Enabled,否则串口监视器看不到打印 |
五、烧录第一个程序
新建文件,粘贴下面的代码。它让板载 LED 闪烁,并每秒在串口打印一次运行时间。
// 多数 DevKit 的板载 LED 在 GPIO2;你的板子不同就改这里
const int LED_PIN = 2;
void setup() {
Serial.begin(115200);
pinMode(LED_PIN, OUTPUT);
Serial.println("ESP32 启动完成");
}
void loop() {
digitalWrite(LED_PIN, HIGH);
delay(500);
digitalWrite(LED_PIN, LOW);
delay(500);
Serial.printf("已运行 %lu 秒\n", millis() / 1000);
}
点击"上传"。编译完成后底部输出出现 Connecting....,接着显示写入进度,最后出现 Hard resetting via RTS pin... 即为成功。打开"工具 → 串口监视器",右下角波特率选 115200,就能看到打印。
【注意】 > 串口监视器开着时,有些系统会占用端口导致下一次上传失败。上传前先关掉串口监视器,或者用 IDE 2.x 自带的那个(它会在上传时自动让出端口)。
六、上传失败怎么排查
上传由 esptool 完成,报错信息基本都来自它。下表按 esptool 官方排查文档整理:
| 报错信息 | 含义 | 处理 |
|---|---|---|
Failed to connect to ESP32 | 芯片没有进入下载模式 | 确认端口选对;关掉占用端口的程序;把波特率降到 115200 再试;拔掉 GPIO 上外接的模块 |
Wrong boot mode detected (0xXX)! The chip needs to be in download mode. | 串口通信正常,但自动复位电路没把芯片切进下载模式 | 手动进入:按住 BOOT 键,点一下 EN(RST)键,松开 BOOT,再点上传 |
No serial data received. | 电脑完全收不到芯片的数据 | 硬件问题:换线、换 USB 口,检查板子是否损坏 |
Invalid head of packet | 串口数据有噪声或被破坏 | 换质量好的短线;不要经过 USB Hub;降低波特率;检查供电 |
A serial exception error occurred | 端口被占用、不存在或没有权限 | 关掉串口监视器等程序;Linux 下检查 dialout 组权限;重装驱动 |
一些板子在 Connecting.... 处一直出点不动,基本都属于第二种情况,手动按键进入下载模式即可。如果每次都要手动按,说明这块板子的自动下载电路(EN、IO0 上的电容和三极管)有问题,可以在 EN 引脚和 GND 之间加一个 1–10 µF 电容延长复位时间,这是社区常用的做法。
七、供电问题
esptool 文档给出的供电要求是:持续约 70 mA,Wi-Fi 发射时峰值 200–300 mA。下面几种情况容易出现烧录到一半中断或运行中反复重启(串口出现 Brownout detector was triggered):
- 用 USB 转 TTL 模块(如 FT232R)的 3.3 V 脚给裸模组供电,电流不够。
- 面包板接触不良,或电源线太长太细。
- 同一个 USB 口还带了舵机、电机等大电流负载。
处理方法:改用独立的 3.3 V 稳压电源(建议能输出 500 mA 以上),在模组电源脚附近加 10 µF + 0.1 µF 电容,缩短电源线。
八、下一步
- 想用乐鑫原生框架做更复杂的项目,可以安装 ESP-IDF(VS Code 插件安装最省事)。
- Arduino 支持包里带了大量例程,在"文件 → 示例 → ESP32"下,Wi-Fi 扫描、蓝牙、深度睡眠都有现成代码可改。
参考资料
- 乐鑫 arduino-esp32 安装文档:https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html
- esptool 故障排查:https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html
- Arduino IDE 下载:https://www.arduino.cc/en/software
评价 (0)