Back to Details

serial

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Serial — 嵌入式串口调试工具

Serial — Embedded Serial Port Debugging Tool

统一封装端口发现、实时监控、数据发送、日志记录和 Hex 查看能力。
Unified encapsulation of port discovery, real-time monitoring, data sending, log recording, and Hex viewing capabilities.

配置

Configuration

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

Environment-level Configuration (
skill/config.json
)

serial skill 的环境级配置目前为空对象 
{}
，因为串口参数属于工程级配置，统一在工作区的 
.embeddedskills/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.

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

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

工作区下的 
.embeddedskills/config.json
存放工程级串口配置：
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
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 参数 (
    --port
    , 
    --baudrate
    等) - 最高优先级
  2. 工程级配置 (
    .embeddedskills/config.json
    中的 
    serial
    部分)
  3. 状态文件 (
    .embeddedskills/state.json
    中的历史记录)
  4. 默认值 - 最低优先级
  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

当未指定 
port
时，脚本会自动扫描系统串口：
  • 若只找到一个串口，自动使用该端口并写入工程配置
  • 若找到多个串口，返回候选列表让用户选择（通过 
    --port
    指定）
  • 若未找到串口，提示错误
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

子命令用途风险
scan
扫描可用串口低
monitor
实时查看文本输出低
send
发送文本或 Hex 数据中
hex
实时查看二进制流低
log
保存串口日志到文件低
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. 检查 
    pyserial
    是否可用，未安装时提示 
    pip install pyserial
  2. 按优先级解析参数：CLI > 工程级配置 > 状态文件 > 默认值
  3. 无子命令时默认执行 
    scan
  4. monitor / send / hex / log
    使用解析后的连接参数
  5. 若未指定 
    port
    ，自动扫描系统串口：
    • 唯一候选：自动使用并写入工程配置
    • 多候选：返回列表让用户选择
  6. 成功执行后，将确认的参数写回工程配置
  7. 运行对应脚本并输出结构化结果
  8. 失败时优先反馈端口占用、驱动、波特率和编码问题
  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

所有脚本位于 skill 目录的 
scripts/
下，通过 
python
直接调用。 脚本会按优先级从 CLI 参数、工程级配置、状态文件中读取参数。
bash
undefined
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
undefined

扫描串口

Scan serial ports

python scripts/serial_scan.py [--filter <关键词>] [--json]
python scripts/serial_scan.py [--filter <keyword>] [--json]

实时监控

Real-time monitoring

python scripts/serial_monitor.py [--port <串口>] [--baudrate <波特率>] [--timestamp] [--filter <regex>] [--timeout <秒>] [--json]
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 <串口>] [--baudrate <波特率>] <data> [--hex] [--crlf] [--repeat <次>] [--wait-response] [--json]
python scripts/serial_send.py [--port <serial port>] [--baudrate <baud rate>] <data> [--hex] [--crlf] [--repeat <times>] [--wait-response] [--json]

Hex 查看

Hex viewing

python scripts/serial_hex.py [--port <串口>] [--baudrate <波特率>] [--width <列>] [--timeout <秒>] [--json]
python scripts/serial_hex.py [--port <serial port>] [--baudrate <baud rate>] [--width <columns>] [--timeout <seconds>] [--json]

日志记录

Log recording

python scripts/serial_log.py [--port <串口>] [--baudrate <波特率>] [--output <文件>] [--duration <秒>] [--format text|csv|json] [--json]
undefined
python scripts/serial_log.py [--port <serial port>] [--baudrate <baud rate>] [--output <file>] [--duration <seconds>] [--format text|csv|json] [--json]
undefined

输出格式

Output Format

单次命令返回标准 JSON：
json
{
  "status": "ok",
  "action": "scan",
  "summary": "发现 2 个串口",
  "details": { ... }
}
持续命令（monitor --json、hex --json）输出 JSON Lines，结束摘要写入 stderr。
错误输出：
json
{
  "status": "error",
  "action": "monitor",
  "error": { "code": "port_busy", "message": "串口被其他程序占用" }
}
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

  • 不自动猜测端口和波特率，发现多个候选串口时不自动选择
  • 参数解析优先级：CLI > 工程级配置 > 状态文件 > 默认值
  • 未指定 
    port
    时自动扫描，唯一候选自动写入配置，多候选需用户选择
  • 成功执行后，确认的参数自动写回 
    .embeddedskills/config.json
  • 未明确说明用途时不主动发送任何串口数据
  • --json
    输出的持续流使用 JSON Lines，摘要写 stderr 不污染数据流
  • 正则过滤失败不应导致监控退出
  • 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
    ：常见 USB 转串口芯片 VID/PID 映射
  • references/common_devices.json
    : VID/PID mapping of common USB-to-serial chips