serial

Q: What does the serial skill do?

嵌入式串口调试工具，用于扫描串口、实时监控、发送数据、记录日志和 Hex 查看。 当用户提到串口、COM 口、UART、AT 命令调试、波特率、Hex 串流、串口抓日志、 串口监控、查看 MCU 输出、二进制协议联调时自动触发，也兼容 /serial 显式调用。 即使用户只是说"看看串口输出"、"发个 AT 命令"或"抓一下日志"，只要上下文涉及 串口通信就应触发此 skill。

Q: How do I install serial?

Run npx skills add https://github.com/zhinkgit/embeddedskills --skill serial in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/serial/ (personal) or .claude/skills/serial/ (project).

by zhinkgit

嵌入式串口调试工具，用于扫描串口、实时监控、发送数据、记录日志和 Hex 查看。当用户提到串口、COM 口、UART、AT 命令调试、波特率、Hex 串流、串口抓日志、串口监控、查看 MCU 输出、二进制协议联调时自动触发，也兼容 /serial 显式调用。即使用户只是说"看看串口输出"、"发个 AT 命令"或"抓一下日志"，只要上下文涉及串口通信就应触发此 skill。

Installs: 814
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/zhinkgit/embeddedskills --skill serial

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads serial automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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/ttyUSB0
minicom -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 映射

FAQ

What does the serial skill do?

How do I install serial?

Run npx skills add https://github.com/zhinkgit/embeddedskills --skill serial in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/serial/ (personal) or .claude/skills/serial/ (project).

Which AI agents can use serial?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is serial safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains serial?

It is published by zhinkgit in zhinkgit/embeddedskills. It has 814 recorded installs.

More from zhinkgit/embeddedskills

View all →

keil

zhinkgit/embeddedskills

Keil MDK 工程构建工具，用于扫描 .uvprojx/.uvproj/.uvmpw 工程、枚举 Target、执行 build/rebuild/clean 并解析构建日志，返回可供 jlink/openocd 复用的产物路径。 flash 子命令仅作为兼容入口保留。当用户提到 Keil、MDK、uVision、UV4、 Target 枚举、编译、重建、清理、烧录、下载固件、flash 时自动触发，也兼容 /keil 显式调用。即使用户只是说"编译一下"或"烧录到板子上"，只要上下文涉及嵌入式 Keil 工程就应触发此 skill。

870 installs

can

zhinkgit/embeddedskills

嵌入式 CAN / CAN-FD 调试工具，用于扫描接口、监控报文、发送测试帧、记录日志、数据库文件解码和总线统计。当用户提到 CAN、CAN-FD、DBC 解码、总线抓包、USB-CAN 联调、报文发送、总线统计、 PCAN、Vector、slcan、CAN 接口扫描、CAN ID 过滤、ASC 日志、BLF 文件时自动触发，也兼容 /can 显式调用。即使用户只是说"看看 CAN 报文"、"发一帧试试"或"解码一下 DBC"，只要上下文明确提到 CAN 总线通信的操作或问题就应触发此 skill。

720 installs

jlink

zhinkgit/embeddedskills

J-Link 下载与在线调试工具，用于探测设备、烧录固件、读写内存、查看寄存器、复位目标、读取 RTT/SWO 日志，以及在线调试（暂停/恢复/单步/断点运行/调用栈/变量查看）。当用户提到 J-Link、JLink、RTT、烧录固件、写内存、读内存、寄存器查看、目标复位、探针连通性检查、在线调试、单步、断点、调用栈时自动触发，也兼容 /jlink 显式调用。即使用户只是说"烧录一下"、"看看 RTT 输出"或"调试一下"，只要上下文涉及 J-Link 探针就应触发此 skill。

683 installs

openocd

zhinkgit/embeddedskills

OpenOCD 下载与调试工具，用于探针探测、固件烧录、Flash 擦除、GDB Server 启动、目标复位控制、 Telnet 在线调试（halt/resume/step/寄存器/内存/断点）、GDB 源码级调试，以及 Semihosting/ITM 输出捕获和底层查询。当用户提到 OpenOCD、ST-Link、CMSIS-DAP、DAPLink、FTDI、烧录固件、擦除 Flash、GDB Server、 reset、interface/target/board 配置、openocd.cfg、在线调试、单步、断点、寄存器查看、内存读写、semihosting 时自动触发，也兼容 /openocd 显式调用。即使用户只是说"烧录一下"、"启动 GDB Server"、"擦除芯片"、"看看寄存器"、"单步调试" 或"抓一下 semihosting"，只要上下文涉及 OpenOCD 支持的开源调试器就应触发此 skill。

Backend & APIs673 installs

gcc

zhinkgit/embeddedskills

GCC 嵌入式工程构建工具（CMake + arm-none-eabi-gcc），用于扫描 CMake 型嵌入式工程、列出预设、配置、编译、重建、清理和分析 ELF 大小。当用户提到 GCC、arm-none-eabi、 CMake 嵌入式编译、Ninja 构建、ELF 大小分析、arm-gcc、交叉编译、cmake --build、 cmake --preset 时自动触发，也兼容 /gcc 显式调用。即使用户只是说"编译一下"或 "看看固件多大"，只要上下文涉及 CMake 嵌入式 GCC 工程就应触发此 skill。

667 installs

workflow

zhinkgit/embeddedskills

embeddedskills 的薄编排层，用于在当前 workspace 中发现工程、选择 build/flash/debug/observe 后端、串联 .embeddedskills/state.json，并聚合底层 skill 的结果。当用户明确输入以下命令之一："一键构建烧录"、"自动诊断"、"串起 build - flash - debug - observe" 或显式调用 /workflow 时触发。

Productivity & Automation659 installs

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs

serial

Install

Install

Describe the task

Review the result

SKILL.md

Serial — 嵌入式串口调试工具

配置

环境级配置 (skill/config.json)

工程级配置 (.embeddedskills/config.json)

参数解析优先级

自动扫描行为

子命令

执行流程

脚本调用

输出格式

串口多路复用 (Mux)

依赖

架构

Mux 管理命令

使用流程

写入冲突警告

Mux 状态持久化

核心规则

参考

FAQ

More from zhinkgit/embeddedskills

Popular other skills

环境级配置 (`skill/config.json`)

工程级配置 (`.embeddedskills/config.json`)