Serial Monitor (WSL & Windows)

在 VS Code 编辑器中打开 COM 串口，实时显示串口日志，支持关键字高亮过滤、日志搜索、数据发送。同时支持 WSL 和 原生 Windows 环境。

✨ 功能特性

功能	说明
🔌 串口连接	自动扫描 COM 口，选择波特率后一键连接
📺 编辑器标签页显示	串口日志在独立 WebView 标签页中实时展示，可与代码并排对照
🔍 关键字过滤	支持多个 Filter，每个可设置独立颜色
🎨 Filter 模式切换	Filter Only（只显示匹配行）/ Highlight All（高亮匹配行，显示全部）
📝 日志搜索	`Ctrl+F` 搜索日志内容，支持高亮匹配 + 上下跳转
⏸ 暂停/恢复	暂停滚动查看历史日志
⬇ 自动滚动	新日志自动滚到底部
📋 复制日志	一键复制全部日志到剪贴板
✏️ 发送数据	支持发送文本或 HEX 数据到串口
⏱ 时间戳	可选为每行添加毫秒级时间戳
🎨 暗色主题	完美融入 VS Code 暗色主题
💻 跨平台	支持 WSL（通过 PowerShell 互操作）和原生 Windows

📸 使用界面

┌──────────────────────────────────────────────────────────────┐
│ [🟢 COM7 @ 115200] [⚡ Connect] [⏸ Pause] [🗑 Clear] [📋 Copy] [⏱] [156] │ Search: [________] [▲][▼] │
├──────────────────────────────────────────────────────────────┤
│ 🔍 [✓] ⊘ [✓ keyword1 🟢][✓ keyword2 🔵] [＋ Add Filter] [156/156] [Clear All] │
├──────────────────────────────────────────────────────────────┤
│ L_PSY sys_work hal psy cb temp =31                          │
│ I>23.034 VOLT sys_work PM:INFO 93722 96 44750 53437 31 4960 │
│ MX_DUMP:8080 0ed2 0000 0ed2 0fd0 0ed2 0fcf 4452 00        │
│ W>23.037 WQ sys_work work too long     14.00 ms 0x48197196 │
│ I>23.154 chargeSe SBEngine [thermostatTempListener] temp:31 │
│ W>30.374 PM_LOCKS sys_work PM_AUDIO lock too long           │
└──────────────────────────────────────────────────────────────┘

🚀 快速开始

安装

方式一：VS Code 扩展商店

打开 VS Code → 扩展面板 (Ctrl+Shift+X)
搜索 WSL Serial Monitor
点击安装

方式二：命令行安装

code --install-extension Roger-Han.wsl-serial-monitor

方式三：从 VSIX 安装

code --install-extension wsl-serial-monitor-0.2.0.vsix

使用

按 Ctrl+Alt+S 或运行命令 WSL Serial: Open Serial Port
从列表中选择 COM 口
选择波特率（默认 115200）
串口日志在编辑器右侧标签页中实时显示

📋 命令

命令	快捷键	说明
`WSL Serial: Open Serial Port`	`Ctrl+Alt+S`	选择 COM 口并打开
`WSL Serial: Close Serial Port`	—	关闭当前串口
`WSL Serial: List Available Ports`	—	列出所有可用 COM 口
`WSL Serial: Send Data to Serial Port`	—	发送数据（文本或 HEX）
`WSL Serial: Clear Log View`	—	清空日志

🔍 Filter 使用

点击 ＋ Add Filter 添加一个过滤器
输入关键字（大小写不敏感）
点击颜色块设置高亮颜色
可添加多个 Filter，每个有独立颜色

两种模式：

模式	说明
Highlight All（默认）	所有日志都显示，匹配行带颜色高亮
Filter Only（勾选 ⊘）	只显示匹配 Filter 的行，其余隐藏

勾选/取消 ⊘ 时，已有行和新到达的行都会立即切换模式。

⚙️ 配置

在 VS Code 设置中搜索 wsl-serial-monitor：

配置项	默认值	说明
`defaultBaudRate`	`115200`	默认波特率
`defaultDataBits`	`8`	数据位（5/6/7/8）
`defaultStopBits`	`One`	停止位（One/OnePointFive/Two）
`defaultParity`	`None`	校验位（None/Odd/Even/Mark/Space）
`showTimestamp`	`true`	是否在每行添加时间戳（WebView 中的 ⏱ 复选框更方便）
`maxLogLines`	`50000`	最大日志行数
`encoding`	`utf-8`	字符编码
`powershellPath`	`powershell.exe`	PowerShell 路径
`lineEnding`	`\r\n`	发送数据的行尾符
`autoReconnect`	`false`	断开后自动重连

🏗 工作原理

┌──────────────────────────────────────────────────────────────┐
│  VS Code (WSL Linux 或 原生 Windows)                         │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  WebView Tab (串口日志)                                 │  │
│  │  Filter │ Search │ Pause │ Copy │ Send │ Timestamp     │  │
│  └────────────────────────────────────────────────────────┘  │
│                         ▲ 数据流                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  Extension Host                                        │  │
│  │  serialPort.ts → TCP 客户端 ←──────┐                   │  │
│  │  serialMonitorView.ts → WebView    │                   │  │
│  └────────────────────────────────────┼───────────────────┘  │
│                                       │ TCP Socket            │
│  ┌────────────────────────────────────┼───────────────────┐  │
│  │  PowerShell (Windows)              │                   │  │
│  │  TCP 监听器 ←──────────────────────┘                   │  │
│  │  System.IO.Ports.SerialPort → COMx                     │  │
│  └────────────────────────────────────────────────────────┘  │
│                                       │                       │
│  ┌────────────────────────────────────▼───────────────────┐  │
│  │  串口设备 (手表/开发板/调试器)                          │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

通信协议

扩展使用 TCP Socket 桥接串口数据（而非 stdin/stdout），完全避免了管道缓冲问题：

PS → Node.js：原始串口字节流 + 控制消息 (CONNECTED|..., DISCONNECTED|..., ERROR|...)
Node.js → PS：HEX:<hexdata>\n（发送数据）, QUIT\n（关闭）

平台适配

环境	PowerShell 路径	TCP 连接目标	脚本路径
WSL	`powershell.exe`（WSL 互操作）	Windows 宿主机 IP（通过 `ip route` 获取）	`wslpath -w` 转换
原生 Windows	`powershell.exe`（直接调用）	`127.0.0.1`	直接使用 `%TEMP%`

扩展自动检测运行环境，无需手动配置。

🔧 环境要求

WSL 环境

VS Code ≥ 1.80
WSL（Windows Subsystem for Linux）
Windows PowerShell (powershell.exe) 可从 WSL 调用
串口设备已连接到 Windows 宿主机

验证 PowerShell 互操作：

which powershell.exe
powershell.exe -Command "Write-Output 'Hello from Windows'"

原生 Windows 环境

VS Code ≥ 1.80
Windows PowerShell 5.1+ 或 PowerShell Core 7+
串口设备已连接到本机

Windows 防火墙

首次使用时 Windows 可能弹出防火墙提示，需允许 PowerShell 监听本地 TCP 端口。如果不小心拒绝了，可以手动添加规则：

# 在 Windows PowerShell (管理员) 中运行
New-NetFirewallRule -DisplayName "WSL Serial Monitor" -Direction Inbound -LocalPort 40000-59999 -Protocol TCP -Action Allow

🐛 故障排查

找不到 COM 口

确认设备已连接（WSL: 连接到 Windows 宿主机；Windows: 连接到本机）
在终端运行 powershell.exe -Command "Get-CimInstance Win32_PnPEntity | Where-Object {$_.Name -match 'COM'}" 验证

连接后没有日志输出

检查 Output 面板（Ctrl+Shift+U → 选 WSL Serial Monitor）是否有 [DATA #N] 日志
如果有但 WebView 不显示，请 Reload Window 后重试
确认波特率与设备端一致

权限错误

确认没有其他串口工具占用了该 COM 口
WSL: 检查 /etc/wsl.conf 中是否启用了互操作

PowerShell 无法调用

WSL: 检查 /etc/wsl.conf 中 interopEnabled=true
可尝试使用完整路径：设置 wsl-serial-monitor.powershellPath 为 C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

🛠 从源码构建

# 克隆仓库
git clone https://github.com/hanzj/wsl-serial-monitor.git
cd wsl-serial-monitor

# 安装依赖
npm install

# 编译
npm run compile

# 打包
npm install -g @vscode/vsce
vsce package

# 安装
code --install-extension wsl-serial-monitor-0.2.0.vsix

开发调试

在 VS Code 中打开项目文件夹，按 F5 启动扩展开发主机进行调试。

许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'Add amazing feature'
推送分支：git push origin feature/amazing-feature
创建 Pull Request