serial

name serial description 嵌入式串口调试工具，用于扫描串口、实时监控、发送数据、记录日志和 Hex 查看。 当用户提到串口、COM 口、UART、AT 命令调试、波特率、Hex 串流、串口抓日志、 串口监控、查看 MCU 输出、二进制协议联调时自动触发，也兼容 /serial 显式调用。 即使用户只是说"看看串口输出"、"发个 AT 命令"或"抓一下日志"，只要上下文涉及 串口通信就应触发此 skill。 argument-hint [scan|monitor|send|hex|log] ... 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 映射