SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsserial

serial

Coding & development

View repository

Updated 10-15 15:28

About this skill

Serial — Embedded Serial Debugging Tool

Unified encapsulation of port discovery, real-time monitoring, data sending, logging, and Hex viewing capabilities.

Configuration

Environment-level configuration (skill/config.json)

The environment-level configuration of the serial skill is currently an empty object {}, because serial port parameters are project-level configuration and are uniformly managed in the workspace's .embeddedskills/config.json .

Project-level configuration (.embeddedskills/config.json)

Under the workspace, .embeddedskills/config.json stores project-level serial configuration:

{
  "serial": {
    "port": "",
    "baudrate": 115200,
    "bytesize": 8,
    "parity": "none",
    "stopbits": 1,
    "encoding": "utf-8",
    "timeout_sec": 1.0,
    "log_dir": ".embeddedskills/logs/serial"
  }
}
Field Description Default Value
port Serial port name, e.g. COM3 ""
baudrate Baud rate 115200
bytesize Data bits 8
parity Parity: none/even/odd/mark/space none
stopbits Stop bits: 1/1.5/2 1
encoding Text encoding utf-8
timeout_sec Read/write timeout (seconds) 1.0
log_dir Log output directory .embeddedskills/logs/serial

Parameter Resolution Priority

  1. CLI parameters (--port, --baudrate , etc.) - highest priority
  2. Project-level configuration (.embeddedskills/config.json in serial section)
  3. State file (.embeddedskills/state.json history)
  4. Default values - lowest priority

Automatic Scanning Behavior

When port is not specified, the script automatically scans system serial ports:

  • If only one serial port is found, automatically use that port and write it to the project configuration
  • If multiple serial ports are found, return a candidate list for the user to choose (specified via --port )
  • If no serial port is found, prompt an error

Subcommands

Subcommand Purpose Risk
scan Scan available serial ports Low
monitor View text output in real time Low
send Send text or Hex data Medium
hex View binary stream in real time Low
log Save serial logs to a file Low

Execution Flow

  1. Check whether pyserial is available; if not installed, prompt pip install pyserial
  2. Resolve parameters by priority: CLI > project-level configuration > state file > default values
  3. When there is no subcommand, execute by default scan
  4. monitor / send / hex / log Use the resolved connection parameters
  5. If portis not specified, automatically scan system serial ports:
    • Single candidate: automatically use and write to the project configuration
    • Multiple candidates: return a list for the user to choose
  6. After successful execution, write the confirmed parameters back to the project configuration
  7. Run the corresponding script and output structured results
  8. On failure, prioritize reporting port occupation, driver, baud rate, and encoding issues

Script Invocation

All scripts are located under the skill directory's scripts/ , via python Call directly. The script reads parameters by priority from CLI arguments, project-level configuration, and state file.

# 扫描串口
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]

Output Format

Single commands return standard JSON:

{
  "status": "ok",
  "action": "scan",
  "summary": "发现 2 个串口",
  "details": { ... }
}

Continuous commands (monitor --json, hex --json) output JSON Lines, with the end summary written to stderr.

Error output:

{
  "status": "error",
  "action": "monitor",
  "error": { "code": "port_busy", "message": "串口被其他程序占用" }
}

Serial Port Multiplexing (Mux)

When minicom (or another serial tool) and the skill script need to access the same serial device at the same time, multiplexing can be achieved through the mux background service.

Dependencies

  • socat — apt install socat / pacman -S socat

Architecture

                   ┌──────────────────┐
                   │   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: The Python mux process exclusively opens the real serial port, exposes a TCP server, and broadcasts serial RX to all clients
  • Layer 2: socat acts as a TCP client to create a virtual PTY /tmp/serial_mux_vserial, for minicom to use
  • Skill Script: Automatically detects mux status, and connects to the TCP port via socket:// only when the current serial configuration matches the mux
  • Data Flow: Serial RX → broadcast to all TCP clients; any client TX → forwarded to the real serial port

Mux Management Commands

# 启动多路复用
python scripts/serial_mux.py start --port /dev/ttyUSB0 [--baudrate 115200]

# 查询状态
python scripts/serial_mux.py status

# 停止多路复用
python scripts/serial_mux.py stop

After startup, skill scripts (monitor/hex/log/send) automatically connect through multiplexing without additional parameters. If the command explicitly specifies a different serial port or serial parameters, the current mux will not be reused.

Usage Workflow

  1. python scripts/serial_mux.py start --port /dev/ttyUSB0
  2. minicom -D /tmp/serial_mux_vserial(user-side interaction)
  3. python scripts/serial_monitor.py(model-side monitoring, automatically goes through mux)
  4. Both terminals see serial data at the same time
  5. python scripts/serial_mux.py stop Stop multiplexing (terminate the socat process and clean up the /tmp/serial_mux_vserial symlink)

Write Conflict Warning

Multiple clients writing at the same time will cause serial data corruption. The monitor/hex/log scripts output a warning to stderr when connecting through mux. The send script outputs a stronger conflict warning. To connect directly to the real serial port (bypassing mux), use the --direct parameter.

Mux State Persistence

The mux process PID is saved to the .embeddedskills/state.json section of serial_mux . After the script exits, the next call to status will check whether the process is still alive and automatically clean up zombie PIDs.start After success, the confirmed serial configuration is written back to .embeddedskills/config.json, making it easy for subsequent parameterless commands to reuse.stop The command terminates the mux and socat PTY processes and deletes the residual /tmp/serial_mux_vserial symlink.

Core Rules

  • Do not automatically guess the baud rate; when multiple candidate serial ports are found, do not automatically select a port
  • Parameter resolution priority: CLI > project-level configuration > state file > default values
  • When port is not specified, automatically scan; a unique candidate is automatically written to the configuration, while multiple candidates require user selection
  • After successful execution, the confirmed parameters are automatically written back to .embeddedskills/config.json
  • Do not proactively send any serial data unless the purpose is explicitly stated
  • --json The continuous stream output uses JSON Lines, and the summary is written to stderr without polluting the data stream
  • Regex filtering failure should not cause monitoring to exit
  • While mux is running, prompt the user before sending data to avoid simultaneous writes

References

  • references/common_devices.json: Common USB-to-serial chip VID/PID mappings