Serial Commander
VS Code 串口调试工具：支持串口收发、自定义命令模板（包头 / 载荷 / 长度字段 / 包尾校验和）、多种校验算法、配置导入导出。
中文版
功能特性
- 串口通信：枚举端口、选择波特率/数据位/停止位/校验位，实时 HEX 收发与日志显示
- 自定义命令模板：
- 自定义包头（HEX 字面量），包尾即校验和（按算法自动计算附加）
- 载荷模板支持参数占位符
{参数名}，中间内容可自定义填充
- 长度字段：
{len:N}（大端）/ {lenle:N}（小端），N=1/2/4 字节，自动计算其后载荷长度；{len:1:hi} / {len:1:lo} 只占字节的高/低 4 位，可与固定半字节 {0x?:hi} / {0x?:lo} 合并为同一字节（如 {0x2:hi}{len:1:lo}）；{len:N=V} 为定值长度：长度字段固定填 V（整包总长），发送内容不足时自动补 0
- 校验和 (Checksum)：SUM8、SUM8 取反、XOR、CRC-8、CRC16-Modbus、CRC16-CCITT、CRC16-XMODEM、CRC32；可配置计算范围（起始/结束偏移）与字节序
- 多种命令类型：参数支持
hex、uint8、uint16（大/小端）、uint32（大/小端）、int8、int16（大/小端）、ascii
- 配置导入/导出：命令模板可导出为 JSON 文件，也可从 JSON 导入（同 id 自动覆盖）
- 命令实时预览 HEX 字节，发送前确认
- 快捷命令按钮：在发送栏点击 ＋固定 将当前发送模式与内容固定为快捷按钮，一键发送；按钮悬停可重命名或删除（持久化保存）
- 日志时间戳：可勾选/取消日志行的时间戳显示（持久化保存）
使用
- 命令面板（
Ctrl+Shift+P）执行 Serial Commander: Open Serial Terminal
- 选择串口与参数，点击 连接
- 在 命令发送 区域选择命令，填写参数，点击 预览 查看字节、发送 下发
- 收发日志支持 HEX/ASCII 双模式显示、TX/RX 过滤与时间戳开关
- 使用 新建命令 构建自定义协议命令，导出配置 保存，导入配置 复用
- 常用命令可在发送栏点 ＋固定 生成快捷按钮，点击直接发送
载荷模板语法
模板由 HEX 字面量与占位符组成，例如：
AA 55 01 {addr} {data} {len:2}
| 语法 |
说明 |
AA 55 |
HEX 字面量字节 |
{addr} |
引用参数列表中定义的参数（类型在参数列表中指定） |
{len:2} |
自动长度字段，大端 2 字节，值 = 其后载荷字节数（支持 1/2/4） |
{lenle:2} |
自动长度字段，小端 2 字节 |
{len:1:hiN} / {len:1:loN} |
长度只占一个字节的高/低 N 位（N=1~7，缺省 4；如 {len:1:hi3} 高 3 位最大 7） |
{len:N:cs} |
长度 = 该字段之后的载荷字节数 + 校验和字节数 |
{len:N:frame} |
长度 = 整包总长（包头 + 载荷 + 校验和），与字段位置无关 |
{0x2:hiN} / {0x3:loN} |
固定位域（1~2 位十六进制，N=1~7 缺省 4；如 {0x15:lo5}、{0x9:lo}），可与相邻长度位域合并为同一字节（如 {len:1:hi3}{0x15:lo5} = 高 3 位长度 + 低 5 位固定 0x15） |
{len:1=8} / {len:2=0x10} |
定值长度：字段固定填该值（整包总长），发送内容不足时自动在载荷区补 0 |
参数类型在模板编辑器的参数列表中定义，模板内只需写 {参数名}。
乱码自动断开
串口波特率/校验位不匹配时，接收到的数据常表现为乱码。勾选 乱码自动断开 后，扩展会按窗口（64 字节）统计可打印字符占比，连续 3 个窗口低于阈值（默认 60%，可调 1%~99%）即判定为乱码，自动断开连接并提示检查串口参数。
注意：该检测是启发式判断，默认关闭。调试纯二进制协议时可能误判（二进制数据可打印字符占比低），请按需开启，并可通过阈值微调灵敏度。
| 算法 |
说明 |
none |
不附加校验 |
sum8 |
累加和，取低 8 位 |
sum8-neg |
累加和按位取反 |
xor |
逐字节异或 |
crc8 |
CRC-8 (poly 0x07) |
crc16-modbus |
CRC-16/MODBUS (poly 0xA001, init 0xFFFF) |
crc16-ccitt |
CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF) |
crc16-xmodem |
CRC-16/XMODEM (poly 0x1021, init 0x0000) |
crc32 |
CRC-32 (IEEE 802.3) |
计算范围默认覆盖整条命令（起始偏移 0，结束偏移 -1 表示到末尾），可在模板编辑器中调整。
要求
- VS Code 1.134.0 及以上
- 串口硬件或虚拟串口
- 平台：Windows / macOS / Linux（
serialport 提供预编译二进制）
扩展设置
serialCommander.defaultBaudRate：默认波特率（默认 115200）
开发
npm install # 安装依赖（serialport 含预编译 native 模块）
npm run compile # 类型检查 + lint + 打包
按 F5 启动扩展开发宿主即可调试。
已知问题
- 若系统缺少串口权限（Linux），可能无法枚举/打开端口，请将用户加入
dialout 组或配置 udev 规则。
- 校验和结果在计算范围调整后以字节序配置为准（大端在前 / 小端在前）。
发布说明
0.1.0
- 位域长度字段（高/低位域）、长度计算范围（
cs/frame）、定值长度
- 快捷命令按钮（＋固定 / 重命名 / 删除，持久化）
- 日志时间戳开关、日志搜索（Ctrl+F，区分大小写 / 全字匹配）
- 自定义悬停提示、乱码自动断开
- 界面交互细节优化
0.0.1
- 初始版本：串口收发、命令模板引擎、多校验算法、配置导入导出
English
Serial Commander
A serial port debugging tool for VS Code: serial I/O, custom command templates (header / payload / length field / trailing checksum), multiple checksum algorithms, and config import/export.
Features
- Serial communication: enumerate ports, select baud rate / data bits / stop bits / parity, real-time HEX transmit/receive with logging
- Custom command templates:
- Custom header (HEX literals), trailing checksum (auto-computed and appended per algorithm)
- Payload template with parameter placeholders
{paramName} and customizable filler content
- Length fields:
{len:N} (big-endian) / {lenle:N} (little-endian), N = 1/2/4 bytes, auto-fills the byte count of the payload after it; {len:1:hi} / {len:1:lo} occupy only the high/low 4 bits of a byte and can merge with fixed nibbles {0x?:hi} / {0x?:lo} into one byte (e.g. {0x2:hi}{len:1:lo}); {len:N=V} is a fixed length: the field always fills V (total frame length) and the payload is zero-padded when too short
- Checksum: SUM8, SUM8 (negated), XOR, CRC-8, CRC16-Modbus, CRC16-CCITT, CRC16-XMODEM, CRC32; configurable calculation range (start/end offset) and byte order
- Parameter types:
hex, uint8, uint16 (LE/BE), uint32 (LE/BE), int8, int16 (LE/BE), ascii
- Config import/export: export command templates to JSON, import from JSON (same id auto-overwrites)
- Real-time HEX preview before sending
- Quick command buttons: click ＋Pin in the send bar to pin the current send mode & content as a one-click button; hover to rename or remove (persisted)
- Log timestamps: toggle timestamp display on log rows (persisted)
- Garbage auto-disconnect: detects mismatched baud rate / parity by printable-character ratio; auto-disconnects after 3 consecutive windows below threshold
Usage
- Run Serial Commander: Open Serial Terminal from the Command Palette (
Ctrl+Shift+P)
- Select port & parameters, click Connect
- In the Command Send area, pick a command, fill parameters, click Preview to see bytes, Send to transmit
- TX/RX logs support HEX/ASCII display, TX/RX filter, and timestamp toggle
- Use New Command to build custom protocol commands, Export Config to save, Import Config to reuse
- Pin frequently used commands via ＋Pin for one-click sending
Payload Template Syntax
A template is a sequence of HEX literals and placeholders, e.g.:
AA 55 01 {addr} {data} {len:2}
| Syntax |
Description |
AA 55 |
HEX literal bytes |
{addr} |
Reference to a parameter defined in the parameter list |
{len:2} |
Auto length field, big-endian 2 bytes, value = byte count of the payload after it (1/2/4) |
{lenle:2} |
Auto length field, little-endian 2 bytes |
{len:1:hiN} / {len:1:loN} |
Length occupies only the high/low N bits of one byte (N = 1~7, default 4; e.g. {len:1:hi3} max 7 in high 3 bits) |
{len:N:cs} |
Length = payload bytes after this field + checksum bytes |
{len:N:frame} |
Length = total frame length (header + payload + checksum), independent of field position |
{0x2:hiN} / {0x3:loN} |
Fixed bit field (1~2 hex digits, N = 1~7 default 4; e.g. {0x15:lo5}, {0x9:lo}), merges with an adjacent length field into one byte (e.g. {len:1:hi3}{0x15:lo5} = 3-bit high length + 5-bit low fixed 0x15) |
{len:1=8} / {len:2=0x10} |
Fixed length: the field always fills this value (total frame length); payload zero-padded when too short |
Parameter types are defined in the template editor's parameter list; the template only needs {paramName}.
Garbage Auto-Disconnect
When baud rate / parity is mismatched, received data often appears as garbage. With Garbage Auto-Disconnect enabled, the extension counts the printable-character ratio per window (64 bytes) and disconnects after 3 consecutive windows below the threshold (default 60%, adjustable 1%~99%), then prompts you to check the serial parameters.
Note: this detection is heuristic and off by default. It may misjudge pure binary protocols (binary data has a low printable ratio), so enable it only when needed and tune the threshold.
| Algorithm |
Description |
none |
No checksum appended |
sum8 |
Sum, low 8 bits |
sum8-neg |
Sum, bitwise negated |
xor |
Byte-wise XOR |
crc8 |
CRC-8 (poly 0x07) |
crc16-modbus |
CRC-16/MODBUS (poly 0xA001, init 0xFFFF) |
crc16-ccitt |
CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF) |
crc16-xmodem |
CRC-16/XMODEM (poly 0x1021, init 0x0000) |
crc32 |
CRC-32 (IEEE 802.3) |
The calculation range defaults to the whole command (start offset 0, end offset -1 = to end), adjustable in the template editor.
Requirements
- VS Code 1.134.0 or later
- Serial hardware or virtual serial port
- Platforms: Windows / macOS / Linux (
serialport ships prebuilt binaries)
Extension Settings
serialCommander.defaultBaudRate: default baud rate (default 115200)
Development
npm install # install dependencies (serialport includes prebuilt native modules)
npm run compile # type check + lint + package
Press F5 to launch the Extension Development Host.
Known Issues
- Without serial permissions on Linux, ports may not be enumerated/opened; add the user to the
dialout group or configure udev rules.
- Checksum output respects the configured byte order after range adjustments (BE first / LE first).
Release Notes
0.1.0
- Bit-field length fields (high/low), length scopes (
cs/frame), fixed length values
- Quick command buttons (＋Pin / rename / remove, persisted)
- Log timestamp toggle, log search (Ctrl+F, match case / whole word)
- Custom hover tooltips, garbage auto-disconnect
- UI interaction polish
| |
