web-serial-debug 功能详细介绍

概述

web-serial-debug 是一款基于浏览器的纯网页串口调试工具，由 itldg 开发维护。使用纯 HTML/CSS/JavaScript 开发，调用浏览器 Web Serial API 实现串口通信，无需安装任何客户端。遵循 Apache-2.0 许可证开源分发。

• 项目地址：https://github.com/itldg/web-serial-debug
• 当前版本：最新版
• 运行平台：Chromium 内核浏览器（已测试 Edge / Chrome，需支持 Web Serial API）
• 部署方式：直接打开 `index.html` 即可运行，或访问在线版
• 在线体验：https://itldg.github.io/web-serial-debug/

核心功能模块

1. 自动重连与设备管理

• 自动重连：设备插拔自动重连，无需手动操作
• 设备列表：自动枚举可用串口设备
• 设备选择：点击选择目标串口设备
• 状态指示：实时显示连接状态（连接/断开）

2. 串口参数配置

• 所有参数可设置：波特率、数据位、停止位、校验位、流控
• 配置自动保存：关闭后配置自动保存，下次打开自动恢复
• 实时修改：运行时可动态修改串口参数

3. 串口日志显示

• HEX 模式：十六进制数据显示，适合二进制协议
• TEXT 模式：文本数据显示，适合文本协议
• 彩色 ANSI：支持 ANSI 颜色代码，彩色显示日志
• 自动滚动：新数据自动滚到底部
• 分包合并：自动合并分包数据，设定超时时间

4. 快捷发送列表

• 自定义分组：支持创建快捷指令分组
• 快捷导入导出：指令集可导入/导出分享
• 常用指令：快速选择常用发送内容
• 分组管理：按项目/设备分类管理指令

5. 配置文件导入导出

• 配置迁移：配置文件可导入/导出
• 方便迁移：换电脑或重装系统后快速恢复配置
• 备份恢复：定期备份配置，防止数据丢失

6. 自定义脚本

• JavaScript 脚本：支持自定义脚本处理发送和接收数据
• 脚本通信：通过 `postMessage` 和 `onmessage` 进行数据通讯
• 发送处理：脚本可修改或增强发送数据
• 接收处理：脚本可解析或过滤接收数据

7. 多语言与在线访问

• 多语言支持：界面支持多种语言
• 在线版：无需本地部署，直接访问在线体验
• 国内镜像：https://www.itldg.com/web_serial_debug/

配置文件说明

依赖与技术栈

适用场景与优势

版本历史摘要

运行方式

方式A：本地运行

1. 解压软件包到任意目录
2. 用浏览器打开 `index.html`
3. 如需 Web Serial 权限，建议通过 `localhost` 或 HTTPS 访问
4. 或使用任意静态服务器承载本目录

方式B：在线访问

1. 访问 https://itldg.github.io/web-serial-debug/
2. 或国内镜像 https://www.itldg.com/web_serial_debug/
3. 直接使用，无需安装

注意：Web Serial API 需要 HTTPS 或 localhost 环境才能正常工作。Chrome/Edge 浏览器需在 `chrome://flags` 中启用 Web Serial API。

web-serial-debug 详细使用教程

目录

1. [快速上手（5分钟入门）](#快速上手5分钟入门)
2. [串口基础收发操作](#串口基础收发操作)
3. [快捷指令配置与使用](#快捷指令配置与使用)
4. [定时循环发送](#定时循环发送)
5. [日志查看与导出](#日志查看与导出)
6. [自定义脚本](#自定义脚本)
7. [配置文件管理](#配置文件管理)
8. [常见问题与故障排查](#常见问题与故障排查)

快速上手（5分钟入门）

1.1 打开网页

1. 在线访问：打开 https://itldg.github.io/web-serial-debug/
2. 本地访问：用浏览器打开 `index.html`
3. 首次使用：浏览器会请求串口权限，点击 `允许`

1.2 选择串口设备

1. 点击顶部 `选择设备` 下拉框
2. 浏览器自动列出可用串口设备
3. 选择目标设备（如 `COM3` 或 `ttyUSB0`）
4. 状态栏显示设备信息

1.3 打开串口

1. 点击 `打开串口` 按钮
2. 浏览器弹出串口参数配置对话框
3. 设置参数：
4. 波特率：`9600`（默认）
5. 数据位：`8`
6. 停止位：`1`
7. 校验位：`None`
8. 点击 `连接` → 状态灯变绿

1.4 测试发送

1. 在发送区输入数据：`Hello Device`
2. 选择发送模式：`TEXT`
3. 点击 `发送` → 接收区显示返回数据
4. 成功标志：接收区显示返回数据，含时间戳

串口基础收发操作

2.1 编码模式切换

2.2 接收区功能

2.3 发送区功能

快捷指令配置与使用

3.1 添加快捷指令

1. 点击右侧面板 `快捷指令`
2. 点击 `新建指令` → 填写：
3. 名称：`读温度`（显示在按钮上）
4. 内容：`01 03 00 01 00 01`（HEX/文本）
5. 模式：`HEX` / `TEXT`
6. 点击 `确定` → 快捷栏出现新按钮

3.2 分组管理

1. 右键快捷按钮 → `移动到分组` → `新建分组`
2. 分组显示为标签页
3. 适合按项目/设备分类管理

3.3 导入导出指令集

• 导出：`快捷指令` → `导出` → 生成 JSON 文件分享给同事
• 导入：`快捷指令` → `导入` → 选择 JSON 文件合并/覆盖

定时循环发送

4.1 单条命令循环

1. 在发送区输入要发送的数据
2. 设置 `发送间隔(ms)`（如 `1000`）
3. 点击 `定时发送` 按钮 → 开始循环
4. 再次点击 → 停止发送

4.2 脚本定时发送

1. 编写自定义脚本设置定时逻辑
2. 通过 `postMessage` 触发定时发送
3. 脚本自动执行，无需人工干预

日志查看与导出

5.1 日志查看

1. 接收区实时显示所有收发数据
2. 支持 HEX/TEXT/ANSI 三种模式切换
3. 支持关键字搜索和过滤
4. 分包数据自动合并显示

5.2 导出日志

1. 右键接收区 → `导出` → 选择格式
2. 支持导出为 `.txt` 文件
3. 包含时间戳、方向、数据内容
4. 可用文本编辑器或 Excel 打开

5.3 配置文件导入导出

1. 导出配置：`文件` → `导出配置` → 保存为 `.json`
2. 导入配置：`文件` → `导入配置` → 选择配置文件
3. 包含串口参数、快捷指令、脚本等全部设置
4. 用途：换电脑后快速恢复配置，备份防丢失

自定义脚本

6.1 编写脚本

脚本使用 JavaScript 编写，通过 `postMessage` 和 `onmessage` 进行数据通讯。

// 示例：自动处理接收到的数据
addEventListener('message', function ({data}) {
    if (data.type == 'uart_receive') {
        // 打印日志
        postMessage({type: 'log', data: '消息长度:' + data.data.length});
        // 原文答复
        postMessage({type: 'uart_send', data: data.data});
    }
});

// 定时发送
setInterval(function() {
    postMessage({type: 'uart_send_txt', data: 'hello world'});
}, 1000);

6.2 脚本数据格式

接收数据格式（`onmessage`）：

{
    "type": "uart_receive",
    "data": [0, 1]
}

发送数据格式（`postMessage`）：

{
    "type": "uart_send",
    "data": [0, 1]
}

6.3 消息类型说明

6.4 脚本管理

1. `工具` → `脚本` → `新建脚本`
2. 编写 JavaScript 代码
3. `保存` → 脚本自动加载
4. 支持导入/导出脚本文件

配置文件管理

7.1 配置文件位置

web-serial-debug/
├─ index.html
├─ config.json          # 用户配置
├─ commands/            # 快捷指令目录
│  ├─ default.json      # 默认指令集
│  └─ custom.json       # 自定义指令集
├─ scripts/             # 自定义脚本目录
│  └─ auto_reply.js     # 自动回复脚本
└─ data/                # 数据缓存目录

7.2 配置迁移

• 导出：`文件` → `导出配置` → 生成 `.json`
• 导入：在新设备上 `文件` → `导入配置`
• 全部设置自动恢复，包括：
• 串口参数
• 快捷指令
• 自定义脚本
• 界面设置

常见问题与故障排查

进阶技巧

9.1 使用静态服务器（Web Serial 要求）

# 使用 Python 静态服务器
cd D:\工业协议\商业产品\开源工具包\web-serial-debug
python -m http.server 8080
# 访问 http://localhost:8080

9.2 多设备监控

1. 复制整个目录 → 重命名
2. 同时打开多个标签页
3. 每个标签页连接不同设备

9.3 团队协作

1. 将配置文件和指令集上传到 Git
2. 团队成员 `导入配置` 即可使用相同设置
3. 共享脚本和常用指令

附录：键盘快捷键

提示：本教程基于 web-serial-debug 最新版编写，界面细节可能随版本微调。遇到未覆盖场景，请参考：GitHub 项目页 或在线文档: https://www.itldg.com/web_serial_debug/