xiao-serial-monitor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Serial monitor: bounded for you, persistent for the user

串口监控：面向调试的有限模式，面向用户的持久模式

Opening a serial port serves two different purposes, and one script covers both.

	You debugging	The user watching
Goal	capture output, act on it	keep a window open all session
Command	`mon.ps1 -Seconds 10`	`mon.ps1`
Ends	on its own	on Ctrl+C

Read the board yourself whenever you need to verify something — that is what bounded mode is for, and it returns a normal exit code.

打开串口有两种不同用途，一个脚本即可覆盖全部场景。

	开发者调试	用户查看
目标	捕获输出并据此操作	全程保持窗口开启
命令	`mon.ps1 -Seconds 10`	`mon.ps1`
结束方式	自动终止	按下Ctrl+C终止

当你需要验证内容时，可自行读取开发板输出——这就是有限模式的用途，它会返回正常的退出码。

The rule that matters most

最重要的规则

Bounded when you run it; hand over the interactive one with a note.

mon.ps1

without

-Seconds

, and

flash.ps1

without

-NoMonitor

, never return. Running those in a tool call hangs the session while the user watches nothing happen — the complaint that motivated this skill was literally "if you start it, it takes forever." So:

Debugging your own change →
```
mon.ps1 -Seconds 10
```
. Bounded, safe, no handoff.
Upload inside a script →
```
flash.ps1 <sketch> -NoMonitor
```
, which exits with a real status code.
The user wants to watch it themselves, now or later → don't launch it. Leave the exact command they can run whenever they want.

That last one is the part worth being deliberate about. After you set the scripts up or finish a change the user will want to observe, close with a short handoff — the command, and how to run it:

The serial monitor is ready whenever you want to check it:
! C:\path\to\scripts\mon.ps1
In Claude Code the
!
prefix runs it right in the session. Ctrl+C exits. If you added the profile shortcuts,
mon
works from any new terminal.

Adapt the wording, but keep the three parts: the literal command, how to launch it, and how to stop it. The user should never have to ask "so how do I see the output?"

你运行时用有限模式；交付给用户时用交互式模式并附上说明。

不带

-Seconds

参数的

mon.ps1

，以及不带

-NoMonitor

参数的

flash.ps1

永远不会返回。在工具调用中运行这些命令会导致会话挂起，而用户看不到任何输出——催生本工具的反馈正是「如果启动它，会一直卡住」。因此：

调试自身变更 → 使用
```
mon.ps1 -Seconds 10
```
。有限模式，安全无需交付。
脚本内上传 → 使用
```
flash.ps1 <sketch> -NoMonitor
```
，它会返回真实的状态码。
用户希望自行查看（无论现在还是之后）→ 不要启动它。留下用户可随时运行的精确命令。

最后一点需要特别注意。在你完成脚本设置或用户需要观察的变更后，用简短的说明收尾——包括命令、启动方式和停止方式：

串口监控已准备就绪，你可随时查看：
! C:\path\to\scripts\mon.ps1
在Claude Code中，
!
前缀可直接在会话中运行该命令。按下Ctrl+C即可退出。如果你已添加配置文件快捷方式，在任何新终端中输入
mon
即可使用。

可调整措辞，但需保留三个核心部分：确切命令、启动方法、停止方法。用户永远无需询问「那我该如何查看输出？」

Setup

安装设置

Copy

scripts/

next to the user's sketches, or leave it in the installed skill folder and reference it by absolute path. Then confirm detection works — this returns immediately:

powershell

. .\scripts\Find-BoardPort.ps1
Find-BoardPort -Explain

A COM port means you are ready. An empty result prints every COM port with its vendor ID so the user can pick one manually with

-Port

Optional but this is usually the actual request — one-word access from any directory.

assets/profile_snippet.ps1

defines

mon

flash

, and

boards

. Append it to

$PROFILE

, edit the

$env:XIAO_TOOLS

path at the top, and note that the profile only loads in newly opened terminals.

powershell

undefined

将

scripts/

文件夹复制到用户的sketch目录旁，或留在已安装的工具文件夹中并通过绝对路径引用。然后确认检测功能正常——该命令会立即返回结果：

powershell

. .\scripts\Find-BoardPort.ps1
Find-BoardPort -Explain

返回COM端口表示已准备就绪。若返回空结果，会打印所有带供应商ID的COM端口，方便用户通过

-Port

参数手动选择。

可选但通常是实际需求——从任意目录通过单字命令访问。

assets/profile_snippet.ps1

定义了

mon

、

flash

和

boards

命令。将其追加到

$PROFILE

中，编辑顶部的

$env:XIAO_TOOLS

路径，并注意配置文件仅在新打开的终端中加载。

powershell

undefined

create the profile if absent, then append

若配置文件不存在则创建，然后追加内容

if (-not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force } Get-Content assets\profile_snippet.ps1 | Add-Content -Path $PROFILE -Encoding utf8

undefined

if (-not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force } Get-Content assets\profile_snippet.ps1 | Add-Content -Path $PROFILE -Encoding utf8

undefined

Usage the user should be told about

需告知用户的使用方法

powershell

mon                      # monitor, port auto-detected
mon COM6 9600            # explicit port and baud
flash blink              # compile + upload + monitor
flash blink -NoMonitor   # upload only
boards                   # what is attached

And for your own verification, which returns:

powershell

.\scripts\mon.ps1 -Seconds 10                  # read 10 s and exit
.\scripts\mon.ps1 -Seconds 10 -Send "ping"     # send a line first

Bounded mode opens the port with DTR asserted, which resets the board, so output starts from a fresh boot banner rather than mid-stream.

powershell

mon                      # 自动检测端口并监控
mon COM6 9600            # 指定端口和波特率
flash blink              # 编译 + 上传 + 监控
flash blink -NoMonitor   # 仅上传
boards                   # 查看已连接设备

而用于你自身验证的命令（会返回结果）：

powershell

.\scripts\mon.ps1 -Seconds 10                  # 读取10秒后退出
.\scripts\mon.ps1 -Seconds 10 -Send "ping"     # 先发送一行数据再读取

有限模式会在打开端口时断言DTR信号，这会重置开发板，因此输出会从全新的启动横幅开始，而非中途的内容。

Pitfalls

常见陷阱

These each cost a real debugging session once.

The first "Serial Port (USB)" row is usually not your board. Dev machines tend to carry a permanently attached USB-UART bridge (CP210x, CH340, FTDI), and it frequently enumerates on a lower COM number, so a naive pick silently monitors the wrong device — a dead-quiet window with no error. Match on USB vendor ID instead:
```
303A
```
Espressif,
```
2341
```
Arduino.
```
Find-BoardPort.ps1
```
does this. Note that
```
arduino-cli board list
```
shows the XIAO as
```
Unknown
```
with an empty FQBN column even when the esp32 core is installed, so FQBN matching alone will not find it.
The COM number changes when the board is replugged. Observed jumping COM5 → COM6 across one unplug. Anything with a hard-coded port breaks the moment someone moves a cable, which is why detection runs on every launch.
arduino-cli monitor
exits whenever the port drops. USB-Serial/JTAG is part of the ESP32-S3 itself rather than a separate bridge, so the port disappears on every reset and every upload. Plain
```
arduino-cli monitor
```
treats that as end-of-session.
```
mon.ps1
```
waits and reattaches, which is the only reason one invocation can cover a whole debugging session.
An open monitor owns the port and uploads fail against it. There is no graceful sharing. Close the monitor with Ctrl+C, upload, reopen — or just use
```
flash.ps1
```
, which sequences it correctly and says so when an upload fails while a monitor is holding the port.
Attaching to an already-running board shows no boot banner. Everything printed from
```
setup()
```
is long gone, so a monitor that opens onto silence looks broken when it is fine. Press the board's Reset button, or upload again, to replay startup. If the sketch only prints during setup, this is the difference between "no output" and "working".
PowerShell 5.1 mangles non-ASCII in BOM-less UTF-8 scripts. It falls back to the ANSI codepage, so Korean, Japanese, and accented characters come out as mojibake — the script still runs, it just becomes unreadable. Save any
```
.ps1
```
containing non-ASCII as UTF-8 with BOM:
powershell
```
$utf8bom = New-Object System.Text.UTF8Encoding($true)
$text = [System.IO.File]::ReadAllText($path, [System.Text.Encoding]::UTF8)
[System.IO.File]::WriteAllText($path, $text, $utf8bom)
```
The scripts here are pure ASCII and unaffected; this applies once someone translates the messages.
Serial.begin(115200); delay(3000);
before the first print. USB CDC needs time to enumerate and early output is dropped without warning. A monitor that "misses the first lines" is usually this, not a monitor bug.
The profile does not apply to already-open terminals. After editing
```
$PROFILE
```
,
```
mon
```
stays undefined in the current window. Open a new terminal or run
```
. $PROFILE
```
. Also note
```
$PROFILE
```
differs between Windows PowerShell 5.1 and PowerShell 7 — editing one leaves the other untouched.

每个陷阱都曾在实际调试会话中造成问题。

第一个「Serial Port (USB)」条目通常不是你的开发板。 开发机器往往会永久连接一个USB-UART桥接器（如CP210x、CH340、FTDI），它通常会枚举到更低的COM编号，因此简单的选择会静默监控错误的设备——窗口无任何输出也无错误提示。应通过USB供应商ID匹配：Espressif为
```
303A
```
，Arduino为
```
2341
```
。
```
Find-BoardPort.ps1
```
就是这么做的。注意即使安装了esp32核心，
```
arduino-cli board list
```
仍会将XIAO显示为
```
Unknown
```
且FQBN列为空，因此仅靠FQBN匹配无法找到它。
重新插拔开发板后COM编号会变化。 曾观察到一次插拔后COM5变为COM6。任何硬编码端口的操作都会在用户移动线缆时失效，这就是每次启动都要运行检测的原因。
arduino-cli monitor
会在端口断开时退出。 USB-Serial/JTAG是ESP32-S3本身的一部分，而非独立桥接器，因此每次重置和上传时端口都会消失。普通的
```
arduino-cli monitor
```
会将此视为会话结束。
```
mon.ps1
```
会等待并重新连接，这也是单次调用就能覆盖整个调试会话的唯一原因。
打开的监控会占用端口，导致上传失败。 串口无法优雅共享。需按下Ctrl+C关闭监控，完成上传后重新打开——或直接使用
```
flash.ps1
```
，它会正确处理顺序，并在监控占用端口导致上传失败时给出提示。
连接到已运行的开发板看不到启动横幅。
```
setup()
```
中打印的所有内容早已消失，因此打开后无输出的监控看似故障，实则正常。按下开发板的Reset按钮，或重新上传，即可重新播放启动过程。如果sketch仅在setup()阶段打印内容，这就是「无输出」和「正常工作」的区别。
PowerShell 5.1会损坏无BOM的UTF-8脚本中的非ASCII字符。 它会回退到ANSI代码页，因此韩语、日语和带重音的字符会变成乱码——脚本仍能运行，但会变得不可读。任何包含非ASCII字符的
```
.ps1
```
文件都应保存为带BOM的UTF-8：
powershell
```
$utf8bom = New-Object System.Text.UTF8Encoding($true)
$text = [System.IO.File]::ReadAllText($path, [System.Text.Encoding]::UTF8)
[System.IO.File]::WriteAllText($path, $text, $utf8bom)
```
本工具中的脚本均为纯ASCII字符，不受影响；此注意事项适用于有人翻译消息之后的情况。
首次打印前需执行
Serial.begin(115200); delay(3000);
。 USB CDC需要时间枚举，若没有延迟，早期输出会被无提示丢弃。「错过前几行」的监控通常是这个原因，而非监控本身的bug。
配置文件不适用于已打开的终端。 编辑
```
$PROFILE
```
后，当前窗口中
```
mon
```
命令仍未定义。需打开新终端或运行
```
. $PROFILE
```
。另外注意
```
$PROFILE
```
在Windows PowerShell 5.1和PowerShell 7中是不同的——编辑其中一个不会影响另一个。

Files

文件说明

Path	Purpose
`scripts/Find-BoardPort.ps1`	vendor-ID port detection, dot-sourced by both scripts
`scripts/mon.ps1`	reconnecting monitor; `-Seconds N` makes it bounded
`scripts/flash.ps1`	compile + upload + monitor; `-NoMonitor` returns
`assets/profile_snippet.ps1`	`mon` / `flash` / `boards` shortcuts for `$PROFILE`

xiao-esp32s3

for the compile/upload workflow and the pin map. Its

read_serial.ps1

is the same bounded reader as

mon.ps1 -Seconds N

; use whichever is already installed.

路径	用途
`scripts/Find-BoardPort.ps1`	基于供应商ID的端口检测脚本，被另外两个脚本引用
`scripts/mon.ps1`	可重新连接的监控脚本； `-Seconds N` 参数启用有限模式
`scripts/flash.ps1`	编译+上传+监控脚本； `-NoMonitor` 参数会返回状态码
`assets/profile_snippet.ps1`	用于 `$PROFILE` 的 `mon` / `flash` / `boards` 快捷命令定义