Back to Details

xiao-esp32s3

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

XIAO ESP32S3 via arduino-cli (Windows)

通过arduino-cli操作XIAO ESP32S3（Windows系统）

Everything below was verified on real hardware (esp32 core 3.3.10, 2026-07). Follow it literally and you will not need to troubleshoot.
Paths below are relative to this skill's folder. 
<PORT>
is the board's COM port and 
<SKETCH_DIR>
is a sketch folder in the user's workspace.
以下所有内容均在真实硬件上验证通过（esp32核心库3.3.10版本，2026年7月）。严格按照步骤操作即可无需排查问题。
以下路径均相对于本技能的文件夹。
<PORT>
为开发板的COM端口，
<SKETCH_DIR>
为用户工作区中的sketch文件夹。

One-time setup (skip any step that is already true)

一次性设置（已完成的步骤可跳过）

powershell
arduino-cli version                          # confirm arduino-cli exists
arduino-cli core list                        # is esp32:esp32 3.x installed?
powershell
arduino-cli version                          # 确认arduino-cli已安装
arduino-cli core list                        # 是否已安装esp32:esp32 3.x版本？

if not (this downloads ~1 GB and can take several minutes — use a long timeout):

若未安装（此步骤将下载约1GB数据，可能需要数分钟——请设置较长超时时间）：

arduino-cli core update-index arduino-cli core install esp32:esp32
undefined
arduino-cli core update-index arduino-cli core install esp32:esp32
undefined

Finding the board

查找开发板

powershell
arduino-cli board list
The XIAO usually shows as an unidentified "Serial Port (USB)" — that row's port (e.g. 
COM4
) is 
<PORT>
. If NO port appears: the board may be in deep sleep (port only exists while awake — see pitfall 2), or needs bootloader mode (hold the BOOT button while plugging in USB; port number may change).
powershell
arduino-cli board list
XIAO通常显示为未识别的“Serial Port (USB)”——该行的端口（如
COM4
）即为
<PORT>
。若未显示任何端口：开发板可能处于深度睡眠状态（仅在唤醒时才会显示端口——见陷阱2），或者需要进入引导加载模式（插入USB时按住BOOT按钮；端口号可能会变化）。

Standard workflow

标准工作流程

powershell
undefined
powershell
undefined

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

sketch命名规则：文件夹名称与.ino文件名必须一致：my_sketch\my_sketch.ino

compile (first compile of a session takes 1-3 min; cached after)

编译（会话中的首次编译需要1-3分钟；之后会缓存）

arduino-cli compile --fqbn esp32:esp32:XIAO_ESP32S3 <SKETCH_DIR>
arduino-cli compile --fqbn esp32:esp32:XIAO_ESP32S3 <SKETCH_DIR>

upload

上传

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

read serial for 10 s (NEVER 
arduino-cli monitor
— it blocks forever)

读取串口10秒（绝对不要使用
arduino-cli monitor
——它会永久阻塞）

powershell -File scripts\read_serial.ps1 -Port <PORT> -Seconds 10
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 has no `&&`. Chain with `;` or `if ($?) { ... }`.
powershell -File scripts\read_serial.ps1 -Port <PORT> -Seconds 10 -Send "hello"

PowerShell 5.1不支持`&&`。使用`;`或`if ($?) { ... }`来链式执行命令。

Verified example sketches

经过验证的示例sketch

assets/sketches/
contains 11 sketches that all compiled, uploaded, and ran on real hardware. Copy the closest one into the user's workspace as a starting point instead of writing from scratch. See 
references/examples.md
for what each proves and its expected output.
assets/sketches/
目录下包含11个均已在真实硬件上编译、上传并运行成功的sketch。复制最接近需求的sketch到用户工作区作为起点，而非从头编写。详见
references/examples.md
了解每个示例的验证内容及预期输出。

Sketch rules that prevent bugs

避免bug的Sketch编写规则

  • Serial.begin(115200);
    then 
    delay(3000);
    before the first print — USB CDC needs time to enumerate, otherwise early output is silently lost.
  • The user LED is 
    LED_BUILTIN
    (GPIO21) and is inverted: 
    LOW
    = ON, 
    HIGH
    = OFF. 
    analogWrite(LED_BUILTIN, 0)
    = full brightness.
  • ADC: call 
    analogReadResolution(12)
    ; read raw with 
    analogRead(A0)
    and millivolts with 
    analogReadMilliVolts(A0)
    . A floating pin reads noisy 60–160 raw — that is normal, not a bug.
  • Touch: 
    touchRead(T2)
    (T2 = GPIO2 = pin D1). Baseline ≈ 17,500; the value RISES well above 40,000 when touched (opposite of original ESP32).
  • WiFi.macAddress()
    returns 
    00:00:00:00:00:00
    until WiFi is started with 
    WiFi.mode(WIFI_STA)
    — not an error.
  • Networking in core 3.x: use 
    NetworkClient
    / 
    NetworkServer
    (old 
    WiFiClient
    / 
    WiFiServer
    names may not exist).
  • 先执行
    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的噪声值——这是正常现象，并非bug。
  • 触摸：
    touchRead(T2)
    （T2=GPIO2=引脚D1）。基准值≈17500；触摸时数值会上升至40000以上（与原始ESP32相反）。
  • WiFi.macAddress()
    在调用
    WiFi.mode(WIFI_STA)
    启动WiFi前会返回
    00:00:00:00:00:00
    ——这并非错误。
  • 3.x版本核心库中的网络功能：使用
    NetworkClient
    /
    NetworkServer
    （旧的
    WiFiClient
    /
    WiFiServer
    名称可能已不存在）。

Pin map (XIAO ESP32S3)

XIAO ESP32S3引脚映射

LabelGPIONotes
D01A0, touch T1
D12A1, touch T2
D23A2, touch T3
D34A3, touch T4
D45SDA, touch T5
D56SCL, touch T6
D643UART TX (Serial1)
D744UART RX (Serial1)
D87SPI SCK
D98SPI MISO
D109SPI MOSI
user LED21inverted (LOW = on)
标签GPIO说明
D01A0，触摸T1
D12A1，触摸T2
D23A2，触摸T3
D34A3，触摸T4
D45SDA，触摸T5
D56SCL，触摸T6
D643UART TX（Serial1）
D744UART RX（Serial1）
D87SPI SCK
D98SPI MISO
D109SPI MOSI
用户LED21反向逻辑（LOW=点亮）

Known pitfalls — read before "debugging"

已知陷阱——调试前务必阅读

  1. Opening the COM port resets the board (DTR toggle → 
    rst:0x15 USB_UART_CHIP_RESET
    ). Every serial read starts from a fresh boot. This also wipes 
    RTC_DATA_ATTR
    variables, so you cannot observe deep-sleep boot counts through a serial monitor. It is not a crash.
  2. Deep sleep makes the COM port disappear. USB CDC powers down during sleep, so the port vanishes and Windows plays disconnect/connect sounds every cycle. This is normal and is the correct evidence that sleep works. Verify the cycle with 
    scripts\watch_port.ps1 -Port <PORT>
    (logs appear/disappear timestamps) instead of opening the port. To reflash a sleeping board, catch the short awake window, or hold the BOOT button while plugging USB (bootloader mode; the port number may change).
  3. arduino-cli monitor
    never exits.     In an automated session it hangs your shell. Always use 
    scripts\read_serial.ps1
    , which has a deadline.
  4. PSRAM reads 0 bytes by default. The default build has PSRAM disabled. If a sketch needs PSRAM (camera, big buffers), add 
    --board-options PSRAM=opi
    to BOTH compile and upload commands.
  5. netsh wlan show networks
    is cached     and may not show a SoftAP the board just created. Trust the board's serial output ("AP IP address: 192.168.4.1"); test the AP from a phone instead.
  6. Upload fails / port busy: make sure no serial reader is still running (only one process can hold the port). If the board looks bricked, use bootloader mode (pitfall 2).
  7. First compile is slow (cold cache, big toolchain). Do not kill it before ~3 minutes; use a generous timeout.
  8. Board can get stuck in reset after a serial session (only the ROM banner 
    ESP-ROM:esp32s3-...
    prints, app never boots, SoftAP/servers die). Cause: DTR/RTS line state left by the PC when closing the port. Recover with 
    arduino-cli upload
    (esptool's reset sequence fixes it). If a headless demo (web server etc.) must keep running, avoid opening the serial port at all — use mDNS or the router's DHCP table to find the board instead of reading its IP over serial.
  9. Same-name Edge Impulse library swap needs 
    --clean
    .     Replacing the 
    <project>_inferencing
    library with a rebuilt copy (same version) leaves stale objects in arduino-cli's cache — symptoms: 
    objs.a ... is not an object
    link errors or edits that appear to have no effect. Always pass 
    --clean
    on the first compile after swapping the library.
  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已禁用。若sketch需要PSRAM（如摄像头、大缓冲区），需在编译和上传命令中均添加
    --board-options PSRAM=opi
    。
  5. netsh wlan show networks
    存在缓存    ，可能无法显示开发板刚创建的SoftAP。请信任开发板的串口输出（“AP IP地址：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
    参数。

Verifying without human eyes

无需人工目视的验证方法

  • LED/PWM: also print state to serial each cycle so the log proves behavior.
  • WiFi scan / BLE scan: success = a numbered list of networks/devices.
  • SoftAP: success = serial prints the AP IP; full HTTP test needs a phone.
  • Deep sleep: success = 
    watch_port.ps1
    shows a stable disappear/appear cycle matching the programmed sleep time (+ ~3 s awake).
  • LED/PWM：同时在每个周期将状态打印到串口，以便日志证明行为。
  • WiFi扫描/BLE扫描：成功标志为显示编号的网络/设备列表。
  • SoftAP：成功标志为串口打印AP IP地址；完整HTTP测试需要使用手机。
  • 深度睡眠：成功标志为
    watch_port.ps1
    显示稳定的消失/出现周期，与编程的睡眠时间匹配（+约3秒唤醒时间）。