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 on2026-04-18

NPX Install

npx skill4agent add zhinkgit/embeddedskills serial

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"
  }
}

Field	Description	Default 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

CLI parameters (
```
--port
```
,
```
--baudrate
```
, etc.) - Highest priority
Project-level configuration (the
```
serial
```
section in
```
.embeddedskills/config.json
```
)
State file (historical records in
```
.embeddedskills/state.json
```
)
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

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 port logs to files	Low

Execution Flow

Check if
```
pyserial
```
is available; prompt
```
pip install pyserial
```
if not installed
Parse parameters by priority: CLI > Project-level configuration > State file > Default values
Execute
```
scan
```
by default when no subcommand is specified
```
monitor / send / hex / log
```
use the parsed connection parameters
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
After successful execution, write the confirmed parameters back to the project configuration
Run the corresponding script and output structured results
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

serial

NPX Install

Tags

SKILL.md Content (Chinese)

Serial — Embedded Serial Port Debugging Tool

Configuration

Environment-level Configuration (
`skill/config.json`
)

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

Parameter Parsing Priority

Automatic Scanning Behavior

Subcommands

Execution Flow

Script Invocation

Output Format

Core Rules

References

serial

NPX Install

Tags

SKILL.md Content (Chinese)

Serial — Embedded Serial Port Debugging Tool

Configuration

Environment-level Configuration (skill/config.json)

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

Parameter Parsing Priority

Automatic Scanning Behavior

Subcommands

Execution Flow

Script Invocation

Output Format

Core Rules

References

Environment-level Configuration (
`skill/config.json`
)

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