xiao-esp32s3

通过 arduino-cli 使用 XIAO ESP32S3（Windows）

以下所有内容均已在真实硬件上验证（esp32 core 3.3.10，2026-07）。 严格按此操作，无需排查问题。

以下路径均相对于此技能文件夹。<PORT> 是开发板的 COM 端口，<SKETCH_DIR> 是用户工作区中的草图文件夹。

一次性设置（已满足的步骤可跳过）

arduino-cli version                          # confirm arduino-cli exists
arduino-cli core list                        # is esp32:esp32 3.x installed?
# if not (this downloads ~1 GB and can take several minutes — use a long timeout):
arduino-cli core update-index
arduino-cli core install esp32:esp32

查找开发板

arduino-cli board list

XIAO 通常会显示为无法识别的 “Serial Port (USB)”——该行对应的端口（例如 COM4）就是 <PORT>。如果没有出现端口：开发板可能处于深度睡眠状态（端口仅在唤醒时存在——参见问题 2），或者需要进入引导加载程序模式（插入 USB 时按住 BOOT 按钮；端口号可能会改变）。

标准工作流

# sketch layout rule: folder name and .ino name must match:  my_sketch\my_sketch.ino

# compile (first compile of a session takes 1-3 min; cached after)
arduino-cli compile --fqbn esp32:esp32:XIAO_ESP32S3 <SKETCH_DIR>

# upload
arduino-cli upload -p <PORT> --fqbn esp32:esp32:XIAO_ESP32S3 <SKETCH_DIR>

# read serial for 10 s (NEVER `arduino-cli monitor` — it blocks forever)
powershell -File scripts\read_serial.ps1 -Port <PORT> -Seconds 10

# optional: send a line to the board and read the response
powershell -File scripts\read_serial.ps1 -Port <PORT> -Seconds 10 -Send "hello"

PowerShell 5.1 不支持 &&。请使用 ; 或 if ($?) { ... } 链接命令。

已验证的示例草图

assets/sketches/ 包含 11 个已在真实硬件上成功编译、上传并运行的草图。请将最接近需求的草图复制到用户工作区作为起点，而不是从头编写。请参阅 references/examples.md，了解每个草图的验证内容及其预期输出。

避免错误的草图规则

• 在首次打印前，先调用 Serial.begin(115200);，再执行 delay(3000);——USB CDC 需要时间完成枚举，否则早期输出会被静默丢弃。
• 用户 LED 为 LED_BUILTIN（GPIO21），且为反相：LOW = 开，HIGH = 关。analogWrite(LED_BUILTIN, 0) = 最高亮度。
• ADC：调用 analogReadResolution(12)；使用 analogRead(A0) 读取原始值，使用 analogReadMilliVolts(A0) 读取毫伏值。未连接的引脚会读到有噪声的 60–160 原始值——这是正常现象，不是错误。
• 触摸：使用 touchRead(T2)（T2 = GPIO2 = 引脚 D1）。基线约为 17,500；触摸时数值会升至 40,000 以上（与原始 ESP32 相反）。
• 在使用 WiFi.mode(WIFI_STA) 启动 WiFi 之前，WiFi.macAddress() 会返回 00:00:00:00:00:00——这不是错误。
• core 3.x 中的网络功能：使用 NetworkClient / NetworkServer（旧名称 WiFiClient / WiFiServer 可能不存在）。

引脚映射（XIAO ESP32S3）

标记	GPIO	备注
D0	1	A0，触摸 T1
D1	2	A1，触摸 T2
D2	3	A2，触摸 T3
D3	4	A3，触摸 T4
D4	5	SDA，触摸 T5
D5	6	SCL，触摸 T6
D6	43	UART TX（Serial1）
D7	44	UART RX（Serial1）
D8	7	SPI SCK
D9	8	SPI MISO
D10	9	SPI MOSI
用户 LED	21	反相（LOW = 开）

已知陷阱——开始“调试”前请先阅读

1. 打开 COM 端口会重置开发板（DTR 切换 → rst:0x15 USB_UART_CHIP_RESET）。每次串口读取都会从全新启动开始。这也会清除 RTC_DATA_ATTR 变量，因此无法通过串口监视器观察深度睡眠启动次数。这不是崩溃。
2. 深度睡眠会让 COM 端口消失。 睡眠期间 USB CDC 会断电，因此端口会消失，Windows 每个周期都会播放断开／连接提示音。这是正常现象，也是睡眠正常工作的正确证据。使用 scripts\watch_port.ps1 -Port <PORT> 验证周期（记录端口出现／消失的时间戳），不要打开端口。要重新刷写处于睡眠状态的开发板，请抓住短暂的唤醒窗口，或插入 USB 时按住 BOOT 按钮（进入引导加载程序模式；端口号可能会变化）。
3. arduino-cli monitor 永远不会退出。 在自动化会话中，它会卡住 shell。请始终使用有截止时间的 scripts\read_serial.ps1。
4. PSRAM 默认读取为 0 字节。 默认构建会禁用 PSRAM。如果草图需要 PSRAM（摄像头、大型缓冲区），请在编译和上传命令中都添加 --board-options PSRAM=opi。
5. netsh wlan show networks 使用缓存，可能无法显示开发板刚创建的 SoftAP。请相信开发板的串口输出（“AP IP address: 192.168.4.1”）；改用手机测试 AP。
6. 上传失败／端口忙： 确保没有串口读取程序仍在运行（一次只能有一个进程占用端口）。如果开发板看起来已变砖，请使用引导加载程序模式（陷阱 2）。
7. 首次编译很慢（缓存为空，工具链较大）。至少等待约 3 分钟后再终止；请设置较宽裕的超时时间。
8. 串口会话后开发板可能卡在复位状态（只打印 ROM 横幅 ESP-ROM:esp32s3-...，应用程序始终无法启动，SoftAP／服务停止）。原因：PC 关闭端口时留下了 DTR／RTS 线路状态。使用 arduino-cli upload 恢复（esptool 的复位序列可以修复此问题）。如果无头演示（Web 服务器等）必须持续运行，请完全避免打开串口；改用 mDNS 或路由器的 DHCP 列表查找开发板，而不要通过串口读取其 IP。
9. 替换同名 Edge Impulse 库需要使用 --clean。 将 <project>_inferencing 库替换为重新构建的副本（版本相同）后，arduino-cli 缓存中会残留过期对象——表现为 objs.a ... is not an object 链接错误，或修改看起来没有效果。替换库后的首次编译务必传入 --clean。

不依靠人眼进行验证

• LED／PWM：每个周期也将状态打印到串口，以便通过日志证明其行为。
• WiFi 扫描／BLE 扫描：成功标志＝显示编号的网络／设备列表。
• SoftAP：成功标志＝串口打印 AP IP；完整的 HTTP 测试需要使用手机。
• 深度睡眠：成功标志＝watch_port.ps1 显示稳定的端口消失／出现周期，与设定的睡眠时间相符（唤醒时间约 + 3 秒）。