zhinkgit Serial — 嵌入式串口调试工具
统一封装端口发现、实时监控、数据发送、日志记录和 Hex 查看能力。
配置
环境级配置 (skill/config.json)
serial skill 的环境级配置目前为空对象 {}，因为串口参数属于工程级配置，统一在工作区的 .embeddedskills/config.json 中管理。
工程级配置 (.embeddedskills/config.json)
工作区下的 .embeddedskills/config.json 存放工程级串口配置：
{
"serial": {
"port": "",
"baudrate": 115200,
"bytesize": 8,
"parity": "none",
"stopbits": 1,
"encoding": "utf-8",
"timeout_sec": 1.0,
"log_dir": ".embeddedskills/logs/serial"
}
}
| 字段 | 说明 | 默认值 |
|---|---|---|
port |
串口号，如 COM3 |
"" |
baudrate |
波特率 | 115200 |
bytesize |
数据位 | 8 |
parity |
校验位：none/even/odd/mark/space | none |
stopbits |
停止位：1/1.5/2 | 1 |
encoding |
文本编码 | utf-8 |
timeout_sec |
读写超时（秒） | 1.0 |
log_dir |
日志输出目录 | .embeddedskills/logs/serial |
参数解析优先级
- CLI 参数 (
--port,--baudrate等) - 最高优先级 - 工程级配置 (
.embeddedskills/config.json中的serial部分) - 状态文件 (
.embeddedskills/state.json中的历史记录) - 默认值 - 最低优先级
自动扫描行为
当未指定 port 时，脚本会自动扫描系统串口：
- 若只找到一个串口，自动使用该端口并写入工程配置
- 若找到多个串口，返回候选列表让用户选择（通过
--port指定） - 若未找到串口，提示错误
子命令
| 子命令 | 用途 | 风险 |
|---|---|---|
scan |
扫描可用串口 | 低 |
monitor |
实时查看文本输出 | 低 |
send |
发送文本或 Hex 数据 | 中 |
hex |
实时查看二进制流 | 低 |
log |
保存串口日志到文件 | 低 |
执行流程
- 检查
pyserial是否可用，未安装时提示pip install pyserial - 按优先级解析参数：CLI > 工程级配置 > 状态文件 > 默认值
- 无子命令时默认执行
scan monitor / send / hex / log使用解析后的连接参数- 若未指定
port，自动扫描系统串口：- 唯一候选：自动使用并写入工程配置
- 多候选：返回列表让用户选择
- 成功执行后，将确认的参数写回工程配置
- 运行对应脚本并输出结构化结果
- 失败时优先反馈端口占用、驱动、波特率和编码问题
脚本调用
所有脚本位于 skill 目录的 scripts/ 下，通过 python 直接调用。
脚本会按优先级从 CLI 参数、工程级配置、状态文件中读取参数。
# 扫描串口
python scripts/serial_scan.py [--filter <关键词>] [--json]
# 实时监控
python scripts/serial_monitor.py [--port <串口>] [--baudrate <波特率>] [--timestamp] [--filter <regex>] [--timeout <秒>] [--json]
# 发送数据
python scripts/serial_send.py [--port <串口>] [--baudrate <波特率>] <data> [--hex] [--crlf] [--repeat <次>] [--wait-response] [--json]
# Hex 查看
python scripts/serial_hex.py [--port <串口>] [--baudrate <波特率>] [--width <列>] [--timeout <秒>] [--json]
# 日志记录
python scripts/serial_log.py [--port <串口>] [--baudrate <波特率>] [--output <文件>] [--duration <秒>] [--format text|csv|json] [--json]
输出格式
单次命令返回标准 JSON：
{
"status": "ok",
"action": "scan",
"summary": "发现 2 个串口",
"details": { ... }
}
持续命令（monitor --json、hex --json）输出 JSON Lines，结束摘要写入 stderr。
错误输出：
{
"status": "error",
"action": "monitor",
"error": { "code": "port_busy", "message": "串口被其他程序占用" }
}
串口多路复用 (Mux)
当需要同时使用 minicom（或其他串口工具）和 skill 脚本访问同一个串口设备时，可以通过 mux 后台服务实现多路复用。
依赖
- socat —
apt install socat/pacman -S socat
架构
┌──────────────────┐
│ Real Hardware │
│ /dev/ttyUSB0 │
└────────┬─────────┘
│
┌────────▼─────────┐
│ Python mux server │
│ TCP-LISTEN:20001 │ 单串口读者 + 广播
└────────┬─────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌────────▼──────┐ ┌─────▼──────┐ ┌──────▼────────┐
│ socat PTY │ │ skill │ │ skill │
│ /tmp/serial_ │ │ monitor │ │ send/log/hex │
│ mux_vserial │ │ socket:// │ │ socket:// │
└───────┬───────┘ └────────────┘ └───────────────┘
│
┌───────▼───────┐
│ minicom │
│ (用户侧) │
└───────────────┘
- Layer 1: Python mux 进程独占打开真实串口，暴露 TCP server，并把串口 RX 广播给所有客户端
- Layer 2: socat 作为 TCP 客户端创建虚拟 PTY
/tmp/serial_mux_vserial，供 minicom 使用 - Skill 脚本: 自动检测 mux 状态，仅当本次串口配置与 mux 匹配时通过
socket://连接 TCP 端口 - 数据流: 串口 RX → 广播到所有 TCP 客户端；任一客户端 TX → 转发到真实串口
Mux 管理命令
# 启动多路复用
python scripts/serial_mux.py start --port /dev/ttyUSB0 [--baudrate 115200]
# 查询状态
python scripts/serial_mux.py status
# 停止多路复用
python scripts/serial_mux.py stop
启动后，skill 脚本（monitor/hex/log/send）自动通过多路复用连接，无需额外参数。若命令显式指定了不同串口或串口参数，则不会复用当前 mux。
使用流程
python scripts/serial_mux.py start --port /dev/ttyUSB0minicom -D /tmp/serial_mux_vserial（用户侧交互）python scripts/serial_monitor.py（模型侧监控，自动走 mux）- 两个终端同时看到串口数据
python scripts/serial_mux.py stop停止复用（终止 socat 进程并清理/tmp/serial_mux_vserial符号链接）
写入冲突警告
多客户端同时写入会导致串口数据错乱。 监控/hex/log 脚本在通过 mux 连接时输出警告到 stderr。send 脚本输出更强的冲突警告。如需直连真实串口（跳过 mux），使用 --direct 参数。
Mux 状态持久化
mux 进程 PID 保存到 .embeddedskills/state.json 的 serial_mux 段。脚本退出后下次调用 status 会检测进程是否仍存活，自动清理僵尸 PID。start 成功后会把已确认的串口配置写回 .embeddedskills/config.json，方便后续无参命令复用。stop 命令会终止 mux 与 socat PTY 进程，并删除残留的 /tmp/serial_mux_vserial 符号链接。
核心规则
- 不自动猜测波特率；发现多个候选串口时不自动选择端口
- 参数解析优先级：CLI > 工程级配置 > 状态文件 > 默认值
- 未指定
port时自动扫描，唯一候选自动写入配置，多候选需用户选择 - 成功执行后，确认的参数自动写回
.embeddedskills/config.json - 未明确说明用途时不主动发送任何串口数据
--json输出的持续流使用 JSON Lines，摘要写 stderr 不污染数据流- 正则过滤失败不应导致监控退出
- Mux 运行中发送数据前提示用户避免同时写入
参考
references/common_devices.json：常见 USB 转串口芯片 VID/PID 映射