serial

Original：🇨🇳 Chinese
Translated
6 scripts

Embedded serial port debugging tool for serial port scanning, real-time monitoring, data sending, log recording, and Hex viewing. Automatically triggered when users mention serial port, COM port, UART, AT command debugging, baud rate, Hex streaming, serial port log capturing, serial port monitoring, viewing MCU output, or binary protocol joint debugging. It also supports explicit invocation via /serial. Even if users only say "check serial port output", "send an AT command", or "capture logs", this skill should be triggered as long as the context involves serial port communication.

2installs
Sourcezhinkgit/embeddedskills
Added on

NPX Install

npx skill4agent add zhinkgit/embeddedskills serial

Tags

Translated version includes tags in frontmatter
serial-port-debuggingembedded-toolsserial-monitoringhex-viewingat-command-debugging

SKILL.md Content (Chinese)

View Translation Comparison →

Serial — Embedded Serial Port Debugging Tool

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

Configuration

Environment-level Configuration (
skill/config.json
)

The environment-level configuration for the serial skill is currently an empty object 
{}
since serial port parameters belong to project-level configuration and are managed uniformly in 
.embeddedskills/config.json
of the workspace.

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

The 
.embeddedskills/config.json
under the workspace stores project-level serial port configurations:
json
{
  "serial": {
    "port": "",
    "baudrate": 115200,
    "bytesize": 8,
    "parity": "none",
    "stopbits": 1,
    "encoding": "utf-8",
    "timeout_sec": 1.0,
    "log_dir": ".embeddedskills/logs/serial"
  }
}
FieldDescriptionDefault Value
port
Serial port number, 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 Parsing Priority

  1. CLI parameters (
    --port
    , 
    --baudrate
    , etc.) - Highest priority
  2. Project-level configuration (the 
    serial
    section in 
    .embeddedskills/config.json
    )
  3. State file (historical records in 
    .embeddedskills/state.json
    )
  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, it is automatically used and written to the project configuration
  • If multiple serial ports are found, a candidate list is returned for the user to select (specify via 
    --port
    )
  • If no serial ports are found, an error is prompted

Subcommands

SubcommandPurposeRisk
scan
Scan available serial portsLow
monitor
View text output in real-timeLow
send
Send text or Hex dataMedium
hex
View binary stream in real-timeLow
log
Save serial port logs to filesLow

Execution Flow

  1. Check if 
    pyserial
    is available; prompt 
    pip install pyserial
    if not installed
  2. Parse parameters by priority: CLI > Project-level configuration > State file > Default values
  3. Execute 
    scan
    by default when no subcommand is specified
  4. monitor / send / hex / log
    use the parsed connection parameters
  5. If 
    port
    is not specified, automatically scan system serial ports:
    • Unique candidate: automatically use and write to project configuration
    • Multiple candidates: return list for user selection
  6. After successful execution, write the confirmed parameters back to the project configuration
  7. Run the corresponding script and output structured results
  8. When failed, prioritize feedback on port occupation, driver, baud rate, and encoding issues

Script Invocation

All scripts are located in the 
scripts/
directory of the skill, and can be directly called via 
python
. Scripts read parameters from CLI parameters, project-level configuration, and state files according to priority.
bash
# Scan serial ports
python scripts/serial_scan.py [--filter <keyword>] [--json]

# Real-time monitoring
python scripts/serial_monitor.py [--port <serial port>] [--baudrate <baud rate>] [--timestamp] [--filter <regex>] [--timeout <seconds>] [--json]

# Send data
python scripts/serial_send.py [--port <serial port>] [--baudrate <baud rate>] <data> [--hex] [--crlf] [--repeat <times>] [--wait-response] [--json]

# Hex viewing
python scripts/serial_hex.py [--port <serial port>] [--baudrate <baud rate>] [--width <columns>] [--timeout <seconds>] [--json]

# Log recording
python scripts/serial_log.py [--port <serial port>] [--baudrate <baud rate>] [--output <file>] [--duration <seconds>] [--format text|csv|json] [--json]

Output Format

Single command returns standard JSON:
json
{
  "status": "ok",
  "action": "scan",
  "summary": "Found 2 serial ports",
  "details": { ... }
}
Continuous commands (monitor --json, hex --json) output JSON Lines, and the end summary is written to stderr.
Error output:
json
{
  "status": "error",
  "action": "monitor",
  "error": { "code": "port_busy", "message": "Serial port is occupied by another program" }
}

Core Rules

  • Do not automatically guess ports and baud rates; do not automatically select when multiple candidate serial ports are found
  • Parameter parsing priority: CLI > Project-level configuration > State file > Default values
  • Automatically scan when 
    port
    is not specified; automatically write the unique candidate to configuration, require user selection for multiple candidates
  • After successful execution, automatically write confirmed parameters back to 
    .embeddedskills/config.json
  • Do not actively send any serial port data when the purpose is not clearly stated
  • Continuous streams of 
    --json
    output use JSON Lines, and summaries are written to stderr without polluting the data stream
  • Regular expression filtering failure should not cause monitoring to exit

References

  • references/common_devices.json
    : VID/PID mapping of common USB-to-serial chips