esp32-real-hardware-flash

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ESP32 Real Hardware Flash + WiFi

ESP32 真实硬件烧录 + WiFi

Overview

概述

Flash firmware to a physical ESP32 over USB and verify it boots + connects WiFi. Works alongside [wokwi-mcp-testing] (sim) — this skill is for the real board.

通过USB向物理ESP32烧录固件，并验证其启动及WiFi连接情况。可与[wokwi-mcp-testing]（模拟环境）配合使用——本技能针对真实开发板。

When to Use

使用场景

First flash of a new ESP32 (PlatformIO
```
pio run -t upload
```
)
Debug why upload fails to open the serial port
Set up WiFi on real hardware (home SSID, static vs DHCP)
Verify boot: WiFi connect + IP + web server start

首次烧录新ESP32（PlatformIO 命令
```
pio run -t upload
```
）
排查上传时无法打开串口的故障
在真实硬件上配置WiFi（家庭网络SSID、静态IP vs DHCP）
验证启动流程：WiFi连接、IP获取及Web服务器启动

Key Rule: Bash tool cannot open serial O_RDWR on macOS

关键规则：macOS下Bash工具无法以O_RDWR模式打开串口

Claude's Bash tool (even with sandbox disabled) gets

Operation not permitted

(EPERM) opening

/dev/cu.*

with

O_RDWR

— esptool/pyserial need O_RDWR, so uploads fail with "Could not open /dev/cu.usbserial-XXXX, the port doesn't exist" (esptool masks EPERM). Read-only opens (

O_RDONLY

, e.g.

dd

) succeed.

Fix: give the user the commands to run in their own terminal. Do not keep retrying from Bash.

Claude的Bash工具（即使禁用沙箱）在以

O_RDWR

模式打开

/dev/cu.*

时会提示「操作不被允许」（EPERM）——而esptool/pyserial需要O_RDWR模式，因此上传会失败并提示「无法打开/dev/cu.usbserial-XXXX，端口不存在」（esptool会隐藏EPERM错误）。只读模式打开（

O_RDONLY

，例如

dd

命令）可成功执行。

解决方法：提供命令让用户在自己的终端中运行。不要在Bash工具中反复重试。

Flash Workflow (user runs these)

烧录流程（用户执行以下命令）

bash

cd <project>
export PATH="/Users/hoang/.nvm/versions/node/v24.18.0/bin:/opt/miniconda3/bin:$PATH"
~/.platformio/penv/bin/pio run -t upload --upload-port /dev/cu.usbserial-2410

Monitor boot log:

bash

~/.platformio/penv/bin/pio device monitor --port /dev/cu.usbserial-2410 --baud 115200

If no log appears: tell user to press EN/RESET on the board.

bash

cd <project>
export PATH="/Users/hoang/.nvm/versions/node/v24.18.0/bin:/opt/miniconda3/bin:$PATH"
~/.platformio/penv/bin/pio run -t upload --upload-port /dev/cu.usbserial-2410

监控启动日志：

bash

~/.platformio/penv/bin/pio device monitor --port /dev/cu.usbserial-2410 --baud 115200

如果没有日志输出：告知用户按下开发板上的EN/RESET按键。

Identifying the Port

端口识别

Chip on cheap dev boards is usually CH340:
```
VID 0x1a86 PID 0x7523
```
→
```
/dev/cu.usbserial-XXXX
```

Detect:

ls /dev/cu.*

(ignore

cu.Bluetooth-Incoming-Port

), or

system_profiler SPUSBDataType

for VID/PID

Verify
```
pio device list
```
sees it

廉价开发板通常搭载CH340芯片：
```
VID 0x1a86 PID 0x7523
```
→ 对应端口为
```
/dev/cu.usbserial-XXXX
```

检测方式：执行

ls /dev/cu.*

（忽略

cu.Bluetooth-Incoming-Port

），或通过

system_profiler SPUSBDataType

查看VID/PID

验证
```
pio device list
```
是否能识别该端口

WiFi Config (real hardware)

WiFi配置（真实硬件）

cpp

const char* WIFI_SSID = "HOME_SSID";
const char* WIFI_PASS = "pass1234";

Credentials never committed — they sit in source for a local demo; flag before any commit
ESP32 is 2.4GHz only — 5GHz SSID won't connect (symptom:
```
WiFi connect timeout
```
)
Prefer DHCP + mDNS over static IP —
```
esp-light.local
```
name is stable, self-heals on network change, no IP conflict risk. Static IP only if mDNS fails or port-forwarding needs a fixed address
Verify via serial log: expect
```
WiFi connected, IP: 192.168.x.x
```
then
```
HTTP server started
```
; open browser to the IP or mDNS name

cpp

const char* WIFI_SSID = "HOME_SSID";
const char* WIFI_PASS = "pass1234";

凭证切勿提交至版本库——仅在本地演示时保留在源码中；提交前需标记提醒
ESP32仅支持2.4GHz频段——5GHz SSID无法连接（症状：
```
WiFi connect timeout
```
）
优先使用DHCP + mDNS而非静态IP——
```
esp-light.local
```
名称稳定，网络变更时可自动恢复，无IP冲突风险。仅在mDNS失效或端口转发需要固定地址时使用静态IP
通过串口日志验证：预期输出为
```
WiFi connected, IP: 192.168.x.x
```
，随后显示
```
HTTP server started
```
；在浏览器中输入该IP或mDNS名称访问

Common Mistakes

常见错误

Mistake	Fix
Upload fails "port doesn't exist" from Bash	User runs the command in their own terminal (O_RDWR blocked in Bash tool)
No serial output after flash	Press EN/RESET; monitor may need restart
`WiFi connect timeout`	Wrong SSID/pass, or router is 5GHz-only
Committed WiFi password	Strip/guard before commit, or use a config that reads env
Wrong port path	`cu.usbserial-*` (CH340), not Bluetooth port

错误情况	解决方法
Bash工具中上传失败提示「端口不存在」	用户在自己的终端中执行命令（Bash工具被阻止使用O_RDWR模式）
烧录后无串口输出	按下EN/RESET按键；可能需要重启监控工具
`WiFi connect timeout`	SSID/密码错误，或路由器仅支持5GHz频段
WiFi密码被提交至版本库	提交前移除/保护密码，或使用读取环境变量的配置方式
端口路径错误	使用 `cu.usbserial-*` （CH340芯片对应端口），而非蓝牙端口