键鼠盒子串口控制方案
KM Box（键鼠盒子）基于 CH645W：通过 USB 虚拟串口（115200 8N1）接收文本控制指令，在被控电脑上模拟 USB HID 鼠标、键盘；同时支持一套物理鼠键在双机之间透传切换。控制端可用脚本或上位机发送 km.* 命令；被控端将设备识别为普通鼠键，无需安装专用驱动。
资料、硬件与支持
芯片规格见 CH645 / CH645W。设计资料、硬件购买与技术支持请通过 doc.ultrasemi.com 获取。固件命令以设备内 km.help() 输出为准。
1、基于 CH645W：片内通讯 vs 多芯片组合
常见「多芯片」键鼠 / KVM 组合往往需要外挂 USB HUB + MCU + 模拟 USB 开关（或额外桥片）协同工作：协议在芯片之间多次穿越板级走线与接口，延迟与抖动更容易叠加，带来键鼠「飘」、热键反应慢、插拔稳定性差等问题。
本方案以 CH645W 单芯片 集成多路 USB 高速 PHY、组合设备 / HUB 与 KVM 向切换能力：
- 片内通讯路径更短：虚拟串口指令解析、HID 报告生成与双机鼠键切换在片内完成，对比板级多芯片互连更快捷、时序更可预期。
- 更少外设依赖：无需再堆一组 HUB IC + 模拟开关做键鼠矩阵，BOM 与走线更干净。
- 被控端即插即用：对受控电脑呈现标准 USB HID，不依赖专用驱动。
- 控制端协议简单：
115200 8N1文本命令即可完成移动、点击、按键与字符串输入。
芯片级规格、型号对比与框图见 CH645 芯片页。
2、产品与连接
典型连接方式：
| 角色 | 连接 | 说明 |
|---|---|---|
| 控制端 | 运行脚本 / 上位机，向盒子串口发文本命令 | USB 虚拟串口 115200 8N1 |
| 被控端 | USB 接入盒子，系统识别为鼠键设备 | 标准 USB HID，免驱 |
| 物理鼠键（可选） | 插在盒子 USB 口 | 与串口指令作用于同一光标 / 焦点；可切换双机 |
控制端 PC 被控端 PC
│ │
│ USB 虚拟串口 │ USB HID 鼠键
│ 115200 8N1 │
└──────────► 键鼠盒子（CH645W）◄────────┘
▲
│ 可选物理鼠标 / 键盘适用场景包括：双机协同办公、调试与测试、工业控制终端、安全隔离环境下由控制机操作被控机（被控端无需额外网络链路即可接收 HID）。
3、串口参数
| 项目 | 参数 |
|---|---|
| 接口 | USB 虚拟串口（设备管理器中查看 COM 口） |
| 波特率 | 115200 |
| 数据位 | 8 |
| 校验 | 无 |
| 停止位 | 1 |
| 行结束 | 每条命令以换行（Enter）结束 |
使用注意：
- 单条命令建议不超过 64 个字符。
- 发送过快时内置队列满会丢弃新命令，请适当间隔。
- 串口终端请使用 UTF-8，避免帮助信息乱码。
获取命令列表：连接串口后发送 km.help()，终端返回当前支持的全部命令及格式说明。
4、命令书写规则
- 命令以
km.开头，参数写在括号内。 - 多个参数用英文逗号分隔。
- 数值可为负数，例如：
km.move(-50, 20)。 - 键盘可用键名或数字键码；字符串用英文双引号，例如：
km.string("Hello")。 - 命令名称不区分大小写（建议统一小写）。
5、命令总览
| 命令 | 功能 |
|---|---|
km.help() | 显示命令列表 |
km.init() | 清除键盘状态，释放已按下的键 |
km.move(x,y) | 鼠标相对移动 |
km.left(x) | 鼠标左键按下 / 松开 |
km.right(x) | 鼠标右键按下 / 松开 |
km.middle(x) | 鼠标中键按下 / 松开 |
km.side1(x) | 侧键 1（前进）按下 / 松开 |
km.side2(x) | 侧键 2（后退）按下 / 松开 |
km.click(x,y) | 鼠标点击一次 |
km.wheel(x) | 滚轮滚动 |
km.turbo(x,y) | 鼠标连发 |
km.down(x) | 键盘按键按下 |
km.up(x) | 键盘按键松开 |
km.press(x,y) | 键盘单点（自动松开） |
km.string("文本",t) | 输入一段文字 |
6、鼠标命令
6.1 相对移动 km.move(x, y)
| 参数 | 说明 |
|---|---|
x | 水平位移，向右为正，向左为负 |
y | 垂直位移，向下为正，向上为负（可省略，则只水平移动） |
km.move(100)
km.move(100, 50)
km.move(-200, -80)- 大距离会自动分成多步直线移动，无需手动拆分。
- 单次移动有步数上限，超大距离请分多次发送。
- 移动为异步过程，下一条命令前宜预留数十～数百毫秒间隔。
6.2 按住 / 松开
km.left / km.right / km.middle / km.side1 / km.side2：1 按下，0 松开。
km.left(1)
km.left(0)
km.right(1)
km.side1(0)此类命令不会自动松开，需手动发 0，或改用 km.click。
6.3 点击一次 km.click(x, y)
| 参数 | 说明 |
|---|---|
x | 1 左键，2 右键，3 中键，4 侧键 1，5 侧键 2 |
y | 按下持续时间（毫秒），默认 75，可省略 |
km.click(1, 50)
km.click(2, 100)6.4 滚轮 km.wheel(x)
正数向上滚，负数向下滚。示例：km.wheel(3)、km.wheel(-5)。
6.5 连发 km.turbo(x, y)
| 参数 | 说明 |
|---|---|
x | 1～5 见键表；0 关闭全部连发 |
y | 连发间隔（毫秒）；0 关闭该键连发；省略约 100ms |
x | 按键 |
|---|---|
1 | 左键 |
2 | 右键 |
3 | 中键 |
4 | 侧键 1 |
5 | 侧键 2 |
km.turbo(1, 80)
km.turbo(1, 0)
km.turbo(0)7、键盘命令
7.1 键的写法
- 键名（推荐）：
km.down("a")、km.press("enter")、km.press("1") - 数字键码：
km.down(4)（参考 HID 键盘扫描码） - 单个大写字母加引号可自动带 Shift：
km.press("A")
7.2 按下 / 松开 / 单点
km.down("w")
km.up("w")
km.press("a")
km.press("enter", 100)km.press(x, y)：按下后自动松开；y 为按下时长（毫秒），默认 75。
7.3 输入字符串 km.string("文本", t)
按顺序输入 ASCII 文字，自动处理大写与常用符号的 Shift。t 为每字符间隔（毫秒），默认 75。
km.string("Hello")
km.string("Hi", 100)7.4 复位 km.init()
停止文字输入、清空键盘状态、释放串口控制的按键。脚本异常或「卡键」时建议执行。
8、常用键名
| 类别 | 键名示例 |
|---|---|
| 字母 / 数字 | a～z，0～9 |
| 编辑 | enter，esc，backspace，tab，space，capslock |
| 修饰键 | shift / lshift，ctrl / lctrl，alt / lalt，win / lgui |
| 方向与导航 | up down left right，home end，pageup/pgup，pagedown/pgdn |
| 功能 | f1～f12，insert/ins，delete/del，printscreen |
更多键名可通过实测或联系技术支持获取完整列表。
9、使用示例
9.1 移动后左键单击
km.move(300, 200)等待移动完成（建议延时 200～500ms，视距离调整）后：
km.click(1, 75)9.2 组合键 Ctrl+C
km.down("ctrl")
km.press("c", 50)
km.up("ctrl")9.3 输入文字并回车
km.string("notepad")
km.press("enter", 80)9.4 左键连发与停止
km.turbo(1, 50)
km.turbo(0)或：km.turbo(1, 0)。
9.5 异常恢复
km.init()
km.left(0)
km.right(0)10、常见问题
| 现象 | 处理建议 |
|---|---|
| 发命令没反应 | 检查 COM 口、波特率 115200、命令是否以换行结束 |
| 命令偶尔丢失 | 降低发送频率；单条不超过 64 字符 |
| 移动有停顿 | 大距离自动分多步完成，属正常现象 |
| 键盘卡住 | 执行 km.init()，并对相关键发 km.up |
| 鼠标键未松开 | 对对应键发 km.left(0) 等，或重新插拔 USB |
| 不能移到绝对屏幕坐标 | 当前仅支持相对移动；精确定位需控制端自行计算偏移 |
| 控制端与被控端是不同电脑 | 被控端光标位置无法自动回读，需被控端程序配合或仅用相对移动 |
11、技术说明
- 主控芯片：CH645W。
- 固件命令以设备内
km.help()输出为准。 - 本文档对应用户手册 v1.0。