XIAO ESP32S3 通过 arduino-cli（Windows）使用。以下内容均在真实硬件上验证（esp32 core 3.3.10，2026-07）。按此严格执行即可无需排查问题。路径相对本技能文件夹，<PORT> 为板卡 COM 口，<SKETCH_DIR> 为用户工作区中的草图文件夹。
【一次性设置】（已满足的步骤可跳过） arduino-cli version # 确认 arduino-cli 存在 arduino-cli core list # esp32:esp32 3.x 是否已安装？
若未安装（下载约 1 GB，可能耗时数分钟——请使用较长超时）：
arduino-cli core update-index arduino-cli core install esp32:esp32
【查找板卡】 arduino-cli board list XIAO 通常显示为未识别的 "Serial Port (USB)"，该行的端口（如 COM4）即 <PORT>。若未出现任何端口：板卡可能处于深度睡眠（端口仅在唤醒时存在，见陷阱 2），或需要进入 bootloader 模式（插 USB 时按住 BOOT 按钮；端口号可能变化）。
【标准工作流】
草图布局规则：文件夹名与 .ino 名必须一致：my_sketch\my_sketch.ino
编译（会话首次编译需 1-3 分钟；之后走缓存）
arduino-cli compile --fqbn esp32:esp32:XIAO_ESP32S3 <SKETCH_DIR>
上传
arduino-cli upload -p <PORT> --fqbn esp32:esp32:XIAO_ESP32S3 <SKETCH_DIR>
读取串口 10 秒（切勿使用 arduino-cli monitor——它会永久阻塞）
powershell -File scripts\read_serial.ps1 -Port <PORT> -Seconds 10
可选：向板卡发送一行并读取响应
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.macAddress() 在未以 WiFi.mode(WIFI_STA) 启动 WiFi 前返回 00:00:00:00:00:00 —— 这不是错误。 core 3.x 网络：使用 NetworkClient / NetworkServer（旧名 WiFiClient / WiFiServer 可能不存在）。
【引脚映射（XIAO ESP32S3）】 D0 → GPIO1，A0，触摸 T1 D1 → GPIO2，A1，触摸 T2 D2 → GPIO3，A2，触摸 T3 D3 → GPIO4，A3，触摸 T4 D4 → GPIO5，SDA，触摸 T5 D5 → GPIO6，SCL，触摸 T6 D6 → GPIO43，UART TX (Serial1) D7 → GPIO44，UART RX (Serial1) D8 → GPIO7，SPI SCK D9 → GPIO8，SPI MISO D10 → GPIO9，SPI MOSI 用户 LED → GPIO21，反相（LOW = 亮）
【已知陷阱——排查前必读】 打开 COM 口会复位板卡（DTR 翻转 → rst:0x15 USB_UART_CHIP_RESET）。每次串口读取都从全新启动开始。这也会清空 RTC_DATA_ATTR 变量，因此无法通过串口监视器观察深度睡眠启动计数。这不是崩溃。 深度睡眠会使 COM 口消失。睡眠期间 USB CDC 断电，端口消失，Windows 每个周期播放断开/连接音效。这属正常，正是睡眠生效的正确证据。请用 scripts\watch_port.ps1 -Port <PORT>（记录出现/消失时间戳）验证周期，而非打开端口。为给睡眠中的板卡重新烧录，可捕捉短暂唤醒窗口，或插 USB 时按住 BOOT 按钮（bootloader 模式；端口号可能变化）。 arduino-cli monitor 永不退出。在自动化会话中会挂起你的 shell。请始终使用带截止时间的 scripts\read_serial.ps1。 PSRAM 默认读出 0 字节。默认构建禁用 PSRAM。若草图需要 PSRAM（摄像头、大缓冲），请在编译和上传命令中都加上 --board-options PSRAM=opi。 netsh wlan show networks 有缓存，可能不显示板卡刚创建的 SoftAP。请信任板卡串口输出（"AP IP address: 192.168.4.1"）；改用手机测试 AP。 上传失败/端口占用：确认没有串口读取进程仍在运行（同一端口只能被一个进程占用）。若板卡看似变砖，使用 bootloader 模式（陷阱 2）。 首次编译慢（冷缓存、大工具链）。约 3 分钟前不要终止；请使用宽松超时。 串口会话后板卡可能卡在复位状态（只打印 ROM 横幅 ESP-ROM:esp32s3-...，应用永不启动，SoftAP/服务器失效）。原因：PC 关闭端口时留下的 DTR/RTS 线状态。用 arduino-cli upload 恢复（esptool 的复位序列可修复）。若必须让无头演示（如 web 服务器）持续运行，请完全不要打开串口——改用 mDNS 或路由器 DHCP 表查找板卡，而非通过串口读取其 IP。 同名 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 秒唤醒）。