Serial Lab
在 VS Code 中查看串口波形、收发数据，调整 STM32 运行中的 RAM 参数。
将多通道波形、文本/HEX 终端和参数面板放在编辑器旁边，支持普通串口调试、Native 协议调参，以及通过 SWD 调试探针直接读写 RAM 变量。
Keil、STM32CubeIDE 用户也能使用，无需学习 CMake。 普通用户不需要下载插件源码、安装 Node.js 或运行 npm 命令。
选择适合你的连接方式
| 想做什么 |
使用方式 |
需要准备 |
| 收发串口数据、查看波形 |
串口连接，支持 CH340 等系统串口设备 |
驱动、正确接线、匹配的波特率和协议 |
| 通过固件协议调整参数 |
Native 串口调参 |
固件接入对应 Native SDK/协议 |
| 不添加上位机通信代码，调整 RAM 参数 |
SWD / DAPLink 调参 |
调试探针、运行中的固件、配套 ELF/AXF |
CH340 USB 转 TTL 用于串口收发，不能替代 SWD 调试探针。串口与 SWD 连接独立，可以按需使用。
第一次使用
- 安装扩展，打开左侧 Serial Lab 侧栏。
- 点击 首次连接向导，选择 Serial / UART 或 SWD。
- 串口模式：选择端口、波特率和数据协议，连接后打开波形面板。
- SWD 模式：准备环境、选择探针、手动选择芯片，再选择匹配的 ELF/AXF 和 RAM 变量。
通过命令面板运行 Serial Lab: Open Workbench 也可以打开工作台。不确定固件发送格式时，可先用 RawData 查看原始数据；显示波形需要匹配的数据协议。
需要 VS Code 1.90 或更新版本。SWD 需要受信任的工作区。安装、接线和完整操作步骤见 使用说明。
不需要更换开发工具
继续使用原来的 IDE 编译和烧录，再将产物交给 Serial Lab：
| 开发工具 |
在插件中选择 |
关键要求 |
| Keil MDK / µVision |
.axf |
启用 Debug Information，产物需包含支持的 ELF/DWARF 信息 |
| STM32CubeIDE |
.elf |
保留调试信息，选择与本次烧录一致的产物 |
| CMake + ARM GCC |
.elf |
使用工程现有预设或脚本，保留 -g / -g3 |
无需转换工程，也不需要专门创建名为 Release-SWD 的配置。HEX/BIN 不能代替变量解析所需的 ELF/AXF。
菜单位置、文件查找和操作步骤见 Keil / CubeIDE / CMake 工程准备指南。
功能
- 多通道波形：连续曲线、缩放、跟随、暂停和通道显隐。
- 串口终端：文本/HEX 收发，可选择发送行尾。
- 协议解析：JustFloat、FireWater、RawData、Native 和自定义协议。
- 运行态调参：选择 RAM 变量，设置写入范围，写入后读回核对。
- 源码操作：连接 SWD 后，在 C/C++ 中右键 Watch、Add to Plot、Edit；成员声明可选择完整实例路径。
- 配置与诊断：查看实际配置和待重连配置，复制诊断报告。
- 数据导出：采样 CSV 和原始收发日志。
串口数据格式
| 协议 |
固件输出格式 |
| JustFloat |
小端 float32 序列，帧尾 00 00 80 7F |
| FireWater |
换行结束的文本数值，数值间用逗号或空格分隔 |
| RawData |
原始字节，仅终端显示，不解析波形 |
| Native |
对应的设备发现、参数及数据协议 |
自定义分隔符、通道和脚本解析见 自定义协议说明。
环境准备与离线使用
默认无需手动安装或激活 Python。首次使用 SWD 时，插件可按提示下载独立环境；后续启动会后台预检已有环境。也可以指定自己的 Python 解释器。
首次在线安装需要下载站点可达。无网络电脑可导入 Windows 同架构离线环境包，其中包含 Python、依赖和导出时已安装的芯片支持包。USB 驱动需单独准备。详见 离线环境说明。
调参前需要了解
- 芯片型号由用户选择，不从 ELF 自动推断。
- ELF/AXF 必须与已烧录固件一致；重新编译并烧录后，应选择对应产物。
- 参数需要有固定可写 RAM 地址，算法应持续读取。推荐使用实际参与运算的
volatile 全局变量或结构体成员。
- 宏、常量、被优化掉的变量、临时局部变量等不属于当前支持范围。
- 启用 D-Cache 的工程需要处理缓存一致性，单加
volatile 不够。
- RAM 修改通常在复位后恢复初始值；插件不自动保存到 Flash，也不负责烧录或使能执行机构。
具体类型、数量限制和缓存说明见 SWD 技术说明。不同电脑、编译器输出和开发板组合仍需实机验证。
遇到问题
查看工作台的 实际连接配置与诊断，需要反馈时点击 复制诊断报告。
| 现象 |
优先检查 |
| 没有串口 |
USB 连接、驱动、刷新端口列表 |
| 串口打不开 |
是否被其他软件占用，查看具体错误 |
| 已连接但 RX 为 0 |
固件发送、接线、端口选择 |
| 收到字节但没有波形 |
波特率、协议和帧格式；RawData 不生成波形 |
| 实际波特率与界面选择不同 |
.seriallab.json 的配置优先，查看来源并重连 |
| SWD 环境或芯片支持缺失 |
使用连接向导，或导入包含该型号的离线环境 |
| 源码变量无法解析 |
先连接 SWD，选择完整表达式或列表中的实例 |
反馈时请说明插件版本、芯片、探针/串口设备和复现步骤。诊断报告包含本机路径及探针 ID，可在分享前删除不必要的信息。
文档
参与开发
以下命令只用于开发插件，普通用户无需执行：
npm install
npm run compile
npm test
在 VS Code 中打开插件源码，按 F5 启动扩展开发宿主。npm run package 生成 VSIX 安装包。
原创代码采用 MPL-2.0，见 许可文件。第三方组件遵循各自许可证；主要组件包括 serialport、uPlot 和 SWD 环境中的 pyOCD。
