# 串口遥控网页调试端 **Repository Path**: gxu-robotz-rc/Serial_control ## Basic Information - **Project Name**: 串口遥控网页调试端 - **Description**: 可自定义页面以及发送数据包，函数等 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-03 - **Last Updated**: 2026-06-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 串口遥控调试台 · Serial Robot Console > 一个**单文件**浏览器端串口调试/遥控工具，专为单片机和机器人开发调试设计。打开网页就能用，无需安装任何软件或驱动。 通过 Chrome / Edge 内置的 Web Serial API 直接读写本机串口，把按键、开关、滑动条、方向键等控件可视化地组合到一个面板上，每个控件按你配置的模板向串口发送数据包；同时实时接收并显示设备返回的数据，可解析为遥测进度条。 适用场景： - 调试新写的串口协议，免去自己写上位机 - 给机器人/小车做一个临时的遥控面板 - 验证传感器数据上报、查看波形/电池电量等遥测 - 现场快速搭建一个可分享的调试界面，发给同事直接用 --- ## 主要特性 - **零依赖单文件**：一个 `.html`，双击即用，离线可跑。 - **真实串口通信**：基于 Web Serial API，支持常见波特率（9600 ~ 921600）。 - **多种控件**：按键、开关、滑动条、进度条（接收方向）、方向键 D-Pad。 - **强大的数据包模板**：支持文本/HEX 两种模式，提供占位符、引用、内联运算表达式，以及全局帧头/帧尾/校验。 - **组件联动**：按键、方向键可绑定滑条/开关的当前值，一次按下携带多个参数。 - **按住连发**：按键和方向键可开启按住时按设定间隔持续发送。 - **自由画布**：拖动卡片任意排版、缩放大小，对齐 8px 网格。 - **自动保存**：所有改动自动写入本地存储，下次打开恢复原状。 - **整页分享**：一键导出"程序 + 配置"二合一 HTML，对方双击即用。 - **响应式适配**：桌面、平板、手机三档自适应；窄屏自动缩放整张面板适应屏宽。 - **接收解析**：可按前缀匹配遥测数据自动驱动进度条。 - **数据终端**：收发实时日志，文本/HEX 双视图，支持手动发送。 --- ## 系统要求 | 项目 | 要求 | | --- | --- | | 浏览器 | Chrome / Edge / Opera **桌面版**（Web Serial 仅在 Chromium 系桌面浏览器支持） | | 打开方式 | 本地双击（`file://`）或 `https://` 网页 | | 操作系统 | Windows / macOS / Linux 均可（驱动按你的 USB-串口芯片要求安装） | | 屏幕 | 任意尺寸，自动适配 | 不支持：Safari、Firefox、移动端浏览器（这些都未实现 Web Serial）；以及在不开放 `serial` 权限的内嵌 iframe 中运行。 --- ## 快速开始 1. 把 `serial-robot-console.html` 下载到本地任意目录。 2. **用 Chrome 或 Edge 双击打开**它。 3. 顶部选择波特率（默认 115200），点 **「连接串口」**，在弹出的对话框里选择你的串口设备。 4. 试试默认面板上的方向键、滑条、按键——它们会按预设模板向串口发送数据；下面终端会显示收发日志。 页面打开后内置了一套机器人示例配置，包含速度滑条、舵机角度、方向控制、前灯开关、巡航指令按键、电池/距离遥测进度条等，直接演示了所有功能的典型用法。 --- ## 界面布局 页面分三块： **顶栏（Header）** 连接状态、波特率选择、连接/断开按钮，以及帧设置、导出、导入、分享、重置等全局操作。 **控制面板（Control Surface）** 你的所有控件卡片所在区域。右上角的 **「+ 添加组件」** 用来新增，**「✥ 编辑布局」** 切到布局编辑模式后可拖动/缩放卡片。 **数据终端（Terminal）** 实时显示发送（▲）和接收（▼）的所有字节，带时间戳，可切换文本/HEX 视图；底部可手动发送任意字符串或十六进制。 --- ## 控件类型 | 类型 | 用途 | 触发时机 | | --- | --- | --- | | **按键 Button** | 一次性指令，如蜂鸣、复位、拍照 | 按下时发一次（可选松开再发） | | **开关 Switch** | 二态控制，如灯/电机/录制开关 | 切换时发 ON 或 OFF 模板 | | **滑动条 Slider** | 数值调节，如速度/亮度/角度 | 拖动时实时发（节流），松手补发最终值 | | **进度条 Progress** | **显示**串口接收的遥测数据 | 按行匹配前缀，自动取值更新 | | **方向键 D-Pad** | 上/下/左/右 + STOP，遥控小车经典布局 | 按下发对应方向；松开发 STOP | 每个组件卡片悬停时右上角出现编辑（✎）和删除（×）按钮。 --- ## 数据包模板语法 这是工具最核心的部分。每个组件都有一个或多个**模板字符串**，描述按下时发送的数据。模板支持两种模式。 ### 文本模式（TEXT） 模板内容直接作为 ASCII 文本发送。支持转义： | 转义 | 含义 | | --- | --- | | `\n` | 换行 0x0A | | `\r` | 回车 0x0D | | `\t` | 制表 0x09 | | `\\` | 反斜杠 | 例：`SPEED={value}\n` → 发送 `SPEED=120\n` ### HEX 模式 模板内容是空格或逗号分隔的十六进制字节，支持 `0x` 前缀。 例：`AA 10 78 55` → 发送 4 字节 `AA 10 78 55` ### 占位符（HEX 与文本通用） | 占位符 | 含义 | | --- | --- | | `{value}` 或 `{v8}` | 当前组件的值（HEX 取 1 字节低 8 位） | | `{v16}` | 当前值的 2 字节大端（高位在前） | | `{v16l}` | 当前值的 2 字节小端（低位在前） | | `{@名称}` | 引用其它组件的当前值；HEX 取低字节，文本填十进制 | | `{= 表达式 }` | 运算结果；详见下节 | | `{=16: 表达式 }` | 运算结果按 2 字节大端输出（HEX 模式） | | `{=16l: 表达式 }` | 运算结果按 2 字节小端输出（HEX 模式） | ### 运算表达式 `{= ... }` 在 `{= }` 中可写任意算术表达式，内部可用： - `x` ——本组件的当前值（绑定了联动滑条/开关则为联动值） - `{@名称}` 或 `@名称` 或 `@[名称]` —— 引用其它组件的值 - 运算符 `+ - * / %`、括号 - 函数 `round floor ceil abs min max sqrt pow sign` 常见用法： | 需求 | 模板 | | --- | --- | | 滑条 0–100 映射到 0–255 | `AA 10 {= round(x*2.55) } 55` | | 值反向（如舵机镜像） | `{= 180-x }` | | 限幅，最大不超过 200 | `{= min(x,200) }` | | 速度 ×2 后当双字节发送 | `{=16: x*2 }` | | 两个组件相乘组合 | `{= {@电机速度} * {@倍率} }` | | 文本协议里换算 | `SPEED={= round(x/2) }\n` | 表达式经安全求值，禁止访问对象属性等危险写法；不合法时回退为 0，**不会**报错或崩溃。 ### 全局数据帧 在顶栏 **「⚙ 帧设置」** 里可配置： | 项 | 说明 | | --- | --- | | 帧头 | 在每个组件内容前追加的字节（HEX，可空） | | 帧尾 | 在每个组件内容后追加的字节（HEX，可空） | | 校验 | 无 / 累加和 SUM8 / 异或 XOR8 | | 校验范围 | 仅组件内容 / 帧头+组件内容 | 最终发送顺序：`[帧头] + 组件内容 + [校验] + [帧尾]` > 提示：如果你的协议较特殊（如校验范围异于上述、CRC16 等），可以把"全局帧设置"留空，把整帧（含校验）直接写进每个组件的模板里。 --- ## 组件联动 **「数值来源」** 下拉：编辑按键、开关、方向键时，可绑定一个滑条或开关作为数值来源。绑定后，本组件模板里的 `{v8}` / `{value}` 会自动取该来源的当前值。 例如默认配置：方向键绑定到「电机速度」滑条，方向键模板为 `AA 01 {v8} 55`——按方向键时，`{v8}` 自动填入当前速度滑条值。 **「插入数据引用」** 芯片：编辑器下方列出所有可用源，点击芯片就会在当前模板光标处插入 `{@名称}`，避免手打。 **开关作为数值源**：开关的"联动输出值 ON/OFF"可自定义（默认 1/0），被引用时按设定值输出。例如把 ON 设为 `255`，OFF 设为 `0`，就能用作数据包里的"标志字节"。 --- ## 按住连发 按键和方向键可开启 **按住连发**： | 字段 | 说明 | | --- | --- | | 按住连发 | 关闭（点一次发一次）/ 开启（按住持续发送） | | 发送间隔 (ms) | 连发周期，最小 10ms（典型 50–200ms） | 启用后，按下立即发一次，之后按住期间每隔设定间隔重复发，松开停止。方向键开启连发，按住方向键持续发该方向指令，松开发 STOP，正好是遥控小车的手感。STOP 键即使开启了连发也只发一次。 未连接串口时，连发会被静默拦截，不会在终端刷屏。 --- ## 自由画布与布局编辑 控件采用绝对像素坐标，可自由排版。 进入编辑：点 **「✥ 编辑布局」**，画布出现对齐网格，卡片可拖动；右下角橙色三角是缩放手柄。完成后再点 **「✓ 完成布局」** 退出。 - 移动和缩放对齐到 8px 网格，便于对齐 - 编辑模式下，卡片不会响应"按下发送"，避免误触 - 编辑模式下保持 1:1 不缩放，便于精确操作 - 退出编辑后，整张面板会按需缩放适应屏宽 --- ## 配置持久化与分享 | 操作 | 说明 | | --- | --- | | **自动保存** | 任何改动都会自动写入浏览器 `localStorage`，下次打开同一文件自动恢复 | | **↓ 导出** | 把所有配置导出为 JSON 文件，体积小，适合个人备份 | | **↑ 导入** | 从 JSON 文件载入配置（合并/覆盖当前） | | **🔗 分享** | 把"程序 + 配置"打包成一个独立 HTML，发给别人直接可用，无需再导入 | | **↺ 重置** | 清除本机自动保存，恢复到默认（或分享文件附带的）布局 | **优先级**：本地自动保存 > 分享文件附带的配置 > 内置默认 也就是说：对方打开你分享的 HTML，第一次用的是你的配置；他在本机改了任何东西，会自动保存到他的浏览器；下次打开仍是他改过的版本，不会被你的初始配置每次覆盖。 --- ## 屏幕适配 | 屏幕 | 行为 | | --- | --- | | 桌面/笔记本 | 左右分栏：控制面板 + 终端 | | 平板/小窗口 | 自动上下堆叠：控制面板在上，终端在下 | | 手机 | 顶栏自动换行，弹窗变单列；控制面板**等比缩放**到屏宽 | 控制面板是自由画布，无法做到"重排"，但会在非编辑状态下整体缩放以适配屏宽，**不出现横向滚动条**。在编辑模式下保持 1:1，可滚动方便精确操作。 > 若主要在手机上当遥控器使用，建议把每个按键做得**大一些**（编辑布局时拖大），缩放后仍然好按。 --- ## 接收解析（进度条） 进度条组件不发送数据，**显示**串口接收到的数据。配置一个匹配前缀，工具会按行解析所有接收到的文本：每当某行以该前缀开头，就取其后的数字更新对应进度条。 举例：设备每秒输出一行 `BAT:78\n` 表示电量 78%，配置一个进度条： - 名称：电池电量 - 前缀：`BAT:` - 最小/最大：0 / 100 - 单位：`%` 工具就会自动显示电量数值和填充比例。 --- ## 协议示例 ### 例 1：简单 4 字节定长帧 帧格式：`AA <命令> <参数> 55` | 命令 | 含义 | | --- | --- | | 0x01 / 0x02 / 0x03 / 0x04 | 上/下/左/右 | | 0x10 | 设置速度（参数 = 0–255） | | 0x00 | 停止 | 配置： - 速度滑条：模板 `AA 10 {v8} 55`，min 0 max 255 - 方向键：联动绑定到速度滑条，上 `AA 01 {v8} 55`、下 `AA 02 {v8} 55`、…、STOP `AA 00 00 55` ### 例 2：带校验和的文本协议 每条指令以 `$` 开头，以 `*校验\n` 结尾，校验为载荷的异或低字节。 可以把帧头设为空、帧尾设为空，直接在组件模板里写完整帧。或者改用工具的全局帧设置：帧头 `24`（即 `$`）、帧尾 `0A`、校验=XOR8、范围=仅组件内容，然后组件模板只写中间载荷。 ### 例 3：带 LED 标志位的巡航命令 按键 "巡航前进"，模板： ``` AA 20 {@电机速度} {@前灯 LED} 55 ``` 按下时，会自动把速度滑条当前值和前灯开关状态各取一字节填进去——一次操作携带多个状态。 --- ## 常见问题（FAQ） **Q：打开网页提示"当前浏览器不支持 Web Serial API"？** 请用 Chrome / Edge / Opera 的**桌面版**。Safari、Firefox、移动端浏览器都不支持。若你确实在 Chromium 桌面版打开仍报错，检查是否运行在受限的 iframe 中。 **Q：连接串口时设备列表是空的？** 检查 USB 线和驱动（CH340/CP210x/FTDI 等）。先在系统设备管理器里能看到串口端口，浏览器才能列出。其它程序（串口助手、IDE 串口监视器等）正占用端口时也会被独占。 **Q：连接后发送数据没反应？** 先确认波特率匹配；试试在终端切到 HEX 视图看实际发出的字节是否正确；用一个回环测试（TX 直接接 RX）确认收发链路。也注意检查"全局帧设置"是否多加了你协议不需要的帧头/帧尾。 **Q：自动保存的位置在哪？换电脑会丢吗？** 保存在浏览器的 `localStorage` 里，绑定到"浏览器 + 文件路径"。换电脑、换浏览器、或挪动 HTML 文件路径，本机存档可能读不到。**重要配置请用「↓ 导出」备份**或用「🔗 分享」生成独立文件。 **Q：分享给别人后，对方打开是空白？** 用最新版本的工具重新生成。如果你用的是旧版（早期版本"分享"功能有一个 bug 会破坏主程序），请下载新版重做分享。新版已修复并经端到端测试。 **Q：表达式 `{= ... }` 报错或得到 0？** 表达式内只允许数字、运算符、括号、空格、`x`、字母数字（用于函数和组件名）。出现禁用字符会被安全拦截返回 0。请用 `round/min/max/abs` 这些函数，避免 `Math.xxx` 写法。 **Q：怎么把数据包做成 CRC16/CRC8 校验？** 当前内置校验只有 SUM8 和 XOR8。CRC 可以通过 `{= 表达式 }` 表达简单的多项式（受表达式语法限制）。如有复杂校验需求，可以扩展，或在模板里手算后固定写入。 **Q：我可以同时打开两个端口/两个设备吗？** 当前一个页面只支持一个串口连接。要管多个设备，开多个标签页（每个标签独立）。 --- ## 数据存储与隐私 - 所有数据（你的配置、收发日志、保存的状态）**仅存在本机浏览器中**，不上传任何服务器。 - 工具不调用任何外部 API，也不收集任何统计信息。 - 唯一的外部资源是 Google Fonts（仅样式美化），离线时会回退到系统字体，功能完全不受影响。 --- ## 局限性 - 仅在 Chromium 桌面浏览器可用（Web Serial 限制）。 - 控制面板为自由画布，不会自动重排——窄屏使用等比缩放策略。 - 进度条解析为**逐行文本匹配**，二进制定长包暂未支持自动解析（可手动观察 HEX 日志）。 - 校验暂只内置 SUM8 和 XOR8（其它校验可借助表达式或手填）。 - 单页面单连接，目前不支持多端口并行。 --- ## 开发与定制 本工具是单文件 HTML，**纯原生 JavaScript + CSS**，无构建步骤、无外部框架。直接用文本编辑器打开 `.html`，所有代码都在文件里： - `