HECATE Connect Web

非官方的鼠标网页版驱动，用浏览器 WebHID 直接读写 HECATE G3M PRO，并可向 Rapoo VT9PRO（2.4G 接收器或 USB 有线）发送配置，不依赖桌面客户端。

• 在线使用：https://nesror.github.io/hecate-connect-web/
• 源码仓库：https://github.com/nesror/hecate-connect-web
• 当前界面版本：v1.5

这是一个个人逆向与互操作项目，与 HECATE、漫步者、Rapoo、雷柏均无隶属关系。仓库不包含官方驱动、官方图片或其他专有二进制文件。

支持设备

设备	连接	支持程度
HECATE G3M PRO	USB 数据线或 2.4G 接收器	读写按键、DPI 与性能，写入后回读验证
Rapoo VT9PRO	2.4G 接收器或 USB 数据线（VID 0x24AE）	实验性：只能发送配置，浏览器无法回读

Rapoo 设备没有浏览器可读的配置回读通道，网页只会确认「已发送」，不会声称写入成功或已验证。使用前请先关闭官方 RapooGameDev；如果设置异常，请用官方驱动恢复。

功能

模块	网页端	HECATE G3M PRO	Rapoo VT9PRO
6 键重映射（左键、右键、滚轮、前进、后退、DPI 键）	✅	✅ 读写并回读验证	⚠️ 发送；宏、系统动作会跳过
键盘 114 键、18 个多媒体/浏览器键、3 个系统键、DPI 控制	✅	✅ 通过 WebHID	⚠️ 键盘、多媒体与 DPI 循环；系统与 DPI +/− 未发送
7 档 DPI、XY 独立调节、当前档位、档位颜色	✅	✅ 通过 WebHID	⚠️ 发送 DPI 数值与当前档位；颜色未发送
回报率、直线/波纹修正、LOD、按键去抖	✅	✅ 通过 WebHID	⚠️ 发送，无法回读验证
宏编辑（按键、鼠标动作、延迟、循环、停止方式）	✅ 本地配置	❌ 不写入固件	❌ 不写入固件
多配置文件、JSON 导入/导出	✅	—	—

HECATE 的写入范围包括按键表与 84 字节板载配置块（DPI、档位颜色、当前档位、回报率、LOD、去抖、直线/波纹修正），并会即时应用回报率。写入后自动回读设备，逐项核对按键槽位、配置块变更字节与回报率。

Rapoo 通过输出报告发送配置帧，覆盖 DPI 数值与当前档位、回报率、LOD、去抖、直线/波纹修正和可映射按键。接收器与有线鼠标都不返回配置数据，因此网页无法确认设备是否接受；协议地址尚未在 VT9PRO 上逐项验证。

网页版不提供灯效设置页；HECATE 的 DPI 档位指示灯颜色仍在「DPI 设置」中编辑并随 DPI 写入，Rapoo 不发送颜色。宏仍只随配置文件保存在浏览器，不会写入任何设备；将按键绑定到宏时，该按键会保留设备上的原功能并在结果中明确列出。角度捕捉未在官方固件写入中启用，网页端不提供该开关。

导入支持两种 JSON：

• 网页版导出的完整备份（全部页面设置与宏）。
• 官方 HECATE 驱动导出的配置文件（可转换按键、DPI、性能设置；宏数据不会导入）。

环境要求

• 桌面版 Chrome 或 Edge（Chromium 89+，需要 WebHID）。
• 安全上下文：HTTPS 或 localhost / 127.0.0.1。
• HECATE G3M PRO 处于 2.4G 或有线模式；Rapoo VT9PRO 插入 2.4G 接收器或用 USB 数据线连接，无线模式需保持开机。
• 官方驱动未占用设备。
• 不支持 Firefox、Safari 和移动浏览器。

WebHID 授权按源（origin）保存，每个站点首次连接都需要手动选择设备。

使用步骤

1. 打开在线地址，连接 HECATE 的 2.4G 接收器或 USB 数据线，或用 Rapoo 的 2.4G 接收器 / USB 数据线连接鼠标。
2. 点击右上角「连接设备」，在浏览器弹窗中选择鼠标。Rapoo 设备通常显示为 “Rapoo Gaming Device”。
3. 在「按键设定」「DPI 设置」「性能与校准」中修改配置；页面顶部或设备面板中的写入按钮会写入对应模块。
4. HECATE 写入流程：握手 → 进入配置模式 → 读取设备头、完整按键表与 84 字节配置块 → 只修改目标槽位/字节 → 提交 → 等待 500 ms → 重新读取校验。
5. Rapoo 发送流程：打开 0xBA 输出报告 → 发送探测与解锁帧 → 逐条发送配置帧。设备没有可读回读通道，网页只能确认帧已发送。
6. 设备面板可以一次写入或发送按键、DPI 与性能；HECATE 还可以从设备读取当前按键、DPI、回报率、LOD 与修正设置到浏览器配置。
7. 如果 HECATE 校验失败或提交失败，按提示重新插拔鼠标，再用「重新读取」确认设备状态。Rapoo 设置异常时请退出本页并用官方驱动恢复。

首次使用建议先「导出配置」备份，再执行写入。

数据与隐私

• 所有配置保存在浏览器 localStorage（键名 hecate-connect-web:state:v1），没有后端、账号或遥测。
• 导入/导出都在本地完成，文件不会上传。
• WebHID 设备授权由浏览器管理，可在站点权限中撤销。

本地开发

需要 Node.js 18+。

npm install
npm run dev      # http://127.0.0.1:5173
npm run build    # 类型检查 + 生产构建到 dist/
npm run preview  # 预览生产构建
npm run deploy   # 构建并推送到 gh-pages 分支

vite.config.ts 使用相对 base，因此构建产物可以部署在任意子路径下。GitHub Pages 需要设置为从 gh-pages 分支根目录发布。

协议说明

协议来自对官方驱动的逆向分析与公开协议资料，用于与用户自己的鼠标互操作，仓库不包含官方二进制。网页端实现见 src/hid/HecateHid.ts、src/hid/RapooHid.ts 与对应的协议文件。

HECATE G3M PRO

• 设备：VID 0x320F / PID 0x706B。
• HID：厂商集合 UsagePage 0xFF1C / Usage 0x92，输入输出报告 64 字节，报告 ID 4。
• 帧格式：[0]=0x04、[1..2]=校验和（字节 3..63 的 16 位小端累加）、[3]=命令、[4]=长度、[5..6]=偏移（小端）、[7]=状态、[8..63]=负载。
• 握手 0xAA 返回状态 0xFF 表示就绪；读取命令需要携带对应长度的零填充请求。
• 主要命令：0x01 进入配置、0x02 提交并退出、0x03 读设备头、0x05 读配置块、0x06 写配置块、0x07 读按键表、0x09 写按键表、0x28 DPI 启用、0x29 即时应用回报率。
• 按键表每项 3 字节大端：槽位 0 左键、1 滚轮、2 右键、3 前进、4 后退、5 DPI 键；0xA00000 表示禁用。键盘厂商码为 0x200000 | HID Usage，修饰键使用 0x200000 | 位标志。
• 媒体键、系统键与 DPI 控制使用各自的厂商码；完整的 114 个键盘键、18 个媒体/浏览器键与 3 个系统键均可在网页中选择并写入。
• DPI 键相关厂商码：0x130100 DPI+、0x130200 DPI−、0x130300 DPI 循环。
• 配置块长 84 字节，按 配置文件序号 × 84 寻址；DPI 档位从偏移 14 开始，每档 9 字节（启用、XY 独立、X 编码、Y 值、RGB）；偏移 11 为回报率序号，12 为当前档位，78 为直线修正，79 为去抖（毫秒 × 10），80 为 LOD 序号，82 为波纹修正。

写入前会重新读取设备头（校验 AA 55 标识与按键数量）、完整按键表与目标配置块，只修改目标槽位/字节并保留未知字节。协议已在真机上通过原生 HID 工具验证；WebHID 链路仍需要更多浏览器与固件组合的实机确认。

Rapoo VT9PRO（实验性）

• 设备：VID 0x24AE，厂商集合 UsagePage 0xFF00 / Usage 0x0E。2.4G 接收器为 PID 0x185A，USB 有线为 PID 0x418A，两者都暴露同一组集合。
• HID：报告 0xBA 在描述符中同时声明了 31 字节输入与输出，写入走输出方向。接收器与有线鼠标对探测、读取与写入都不返回推送式输入报告；配置回读只能用 GET_INPUT_REPORT(0xBA) 主动拉取（见下），WebHID 没有该调用，浏览器端因此无法回读。有线鼠标的 0xBB 报告（6 字节）是设备每 3 秒主动推送的电量心跳，官方驱动关闭时也照发。
• 帧格式（WebHID 发送时不含报告 ID）：探测 B0；解锁 A5 A3 00 00 00 00 00 00；写入 A5 A5 <长度> <地址> <Bank> 00 00 <数据…>；读取请求 A5 A4 <长度> <地址> <Bank> 00 00 00。
• 回读应答：发读取请求后用 GET_INPUT_REPORT(0xBA) 拉取，应答格式 01 28 02 00 <数据…>（头部 4 字节，28 02 为固件版本的小端 228；应答数据最多 4 字节，超出部分顺延下一地址）。已在有线 VT9PRO 上逐项验证：档位数量、当前档位、回报率、LOD、去抖（按下/抬起）、休眠、传感器修正、DPI X/Y 表与全部按键槽位均可正确读回；官方驱动启动时正是通过该通道回读全部配置（实验验证：原生写入第 5 档 DPI 6300 后，官方驱动重启显示 6300）。
• Bank：通信 0x00、按键 0x06、系统 0x08。
• 系统地址：回报率 0x80、LOD 0x84、DPI X 表 0x88、档位数量 0x96、当前档位 0x98、去抖 0xC0、休眠分钟 0xC2、传感器修正 0xC3、DPI Y 表 0xC8。
• 按键地址：左键 0x00、滚轮中键 0x04、右键 0x08、DPI+ 0x0C、DPI− 0x10、前进 0x14、后退 0x18、DPI 切换（DIY）键 0x34，每项 4 字节。另有三个未确认槽位：0x1C/0x20（值 07 00 08 00，疑似滚轮前滚/后滚）与 0x38（值 03 00 20 00）。
• 电量心跳 0xBB：bb b0 <电压> 00 <电流 LE16> <百分比>；电压为 BCD 式高低半位（0x41 = 4.1 V），电流单位 mA、非 0 表示充电中，百分比 0–100。网页端已接入该心跳显示电量。
• DPI 表为 u16 小端序列；档位数量写入「数量 − 1」，当前档位写入压缩后索引。回报率为 {125:0x08, 250:0x04, 500:0x02, 1000:0x01}，LOD 为 {1:0x01, 2:0x03, 3:0x04}，去抖按毫秒直接写入，修正字节 bit0 表示关闭直线修正、bit1 表示关闭波纹修正。
• 按键编码：鼠标动作 03 00 <位掩码> 00（bit0 左键、bit1 右键、bit2 中键、bit3 后退、bit4 前进）、禁用 03 00 07 00、键盘 00 00 <usage> 00、修饰键 02 <高位> 00 00、多媒体 04 00 <usage 高低字节>、DPI 动作 08 00 <子码> 00（03 循环、05 DPI+、06 DPI−，已通过回读确认）。
• 写入编码已由回读验证；宏、系统电源动作与滚轮前滚/后滚槽位尚无确认编码，不会写入。

已知限制

• Rapoo 设备（2.4G 接收器或 USB 有线）只能接收配置帧；配置回读通道是 GET_INPUT_REPORT(0xBA) 主动拉取，WebHID 不提供该调用，浏览器无法回读或校验，网页不会显示「写入成功」或「已验证」。设置异常时请退出本页并用官方 RapooGameDev 恢复。
• Rapoo 的写入编码已经原生回读逐项验证；宏、系统电源动作与滚轮前滚/后滚、DPI 颜色不会发送，相关按键会跳过并在结果中列出。
• Rapoo 电量显示来自 0xBB 心跳，仅在有线模式实测过；2.4G 接收器模式下的心跳格式尚未验证。
• 宏不会写入任何设备，也不会在系统层自动执行；绑定宏的按键会保留设备原功能。
• 角度捕捉不受固件写入支持，网页端不提供该开关。
• 组合键动作（复制、粘贴、撤销等）尚未实现；官方驱动通过独立动作结构处理，当前协议只覆盖单键分配。
• 官方驱动运行时可能独占设备，请先退出官方驱动。
• 设备固件差异可能导致协议不兼容；HECATE 此时握手或读取设备头会失败，不会盲目写入；Rapoo 没有浏览器可用的回读通道，无法提前发现不兼容。
• 页面更新后浏览器可能缓存旧资源，遇到行为不一致时用 Ctrl+Shift+R 强制刷新。

项目结构

src/
  App.tsx                    页面状态、配置文件与设备写入流程
  components/                侧边栏、顶栏、鼠标示意图、设备面板等
    DeviceConnectPanel.tsx   通用连接入口与设备能力说明
    HecateDevicePanel.tsx    HECATE 读取、写入与校验面板
    RapooDevicePanel.tsx     Rapoo 发送、跳过项与结果面板
  pages/                     按键、DPI、性能、宏页面
  hid/deviceModels.ts        HECATE / Rapoo 型号元数据
  hid/protocol.ts            HECATE 帧格式、命令、按键表编解码
  hid/profileCodec.ts        HECATE 84 字节配置块（DPI、回报率、LOD、去抖）编解码
  hid/HecateHid.ts           HECATE 握手、读取、写入、提交与校验
  hid/rapooProtocol.ts       Rapoo 帧、Bank/地址、按键与 DPI 编码
  hid/RapooHid.ts            Rapoo 探测、解锁与配置帧发送
  hid/useMouseDevice.ts      WebHID 授权、设备识别与连接状态
  profileIO.ts               导入、导出与官方 JSON 转换
  defaults.ts                默认配置与型号信息
  styles.css                 全局样式

免责声明

本项目为非官方工具，仅供学习、研究与个人设备互操作使用。「HECATE」「漫步者」「Rapoo」「雷柏」及相关商标归其权利人所有。写入或发送鼠标配置存在因固件差异导致设置异常的风险；Rapoo 路径为实验性且无法回读验证，请自行备份并承担使用风险。请勿将本项目用于分发官方驱动或其提取资源。