666mille/MyATxMouseControl

# MyATxMouseControl 一个 Stream Deck 插件，可直接从你的 Elgato Stream Deck 控制 **ATK X1 Ultimate** 无线游戏鼠标（8K dongle）——包括电量、DPI 档位、回报率和传感器固件模式。**无需 ATK HUB。** 此项目的 HID 协议已完全逆向工程（EEPROM 映射、校验和、传感器模式命令）——请参阅下方的[协议](#protocol)。  ## 功能 | 动作 | 作用 | |---|---| | **电量** | 显示电池电量，带有可配置的阈值颜色（满 / 中 / 低 / 充电中）。按下可立即刷新。 | | **DPI 切换** | 循环切换 DPI 档位并显示当前 DPI 值。档位颜色可以实时从鼠标读取（与 DPI LED 匹配）或进行自定义。 | | **传感器固件** | 在 *基础模式*、*ATK Shard 竞技固件* 和 *ATK Shard 竞技固件 MAX* 之间切换。 | | **回报率** | 循环切换可配置的回报率列表（125 Hz - 8 kHz）。 | | **鼠标拨盘**（Stream Deck +） | 按下：切换模式（DPI / 回报率 / 固件）。旋转：更改值。右上角显示电量，底部显示数值条。触摸：刷新。 | 所有动作共享一个中心状态轮询器（所有内容共用一个 HID 会话），因此每个显示都会同步更新。按下任何按钮都会触发所有动作的立即刷新，包括拨盘。 ### 显示状态 - **`?`** - 尚未读取到任何值 - **灰显值 + `Zzz`** - 鼠标处于休眠状态；显示最后已知的值 - **`NO DONGLE`** - USB 接收器已拔出（约 5 秒内检测到，背景颜色可配置） 每个按键都可以在左上角显示可配置的标题文本（默认为 `ATK`）——或者不显示任何内容。 ## 安装 ### 从发布版本安装 从 [Releases](../../releases) 页面下载最新的 `com.holgermilz.myatxmousecontrol.streamDeckPlugin` 并双击它。需要 Windows 10/11 上的 Stream Deck 6.5+ 版本。 ### 从源码安装 ``` npm install npm install -g @elgato/cli streamdeck link com.holgermilz.myatxmousecontrol.sdPlugin npm run build streamdeck restart com.holgermilz.myatxmousecontrol ``` 在开发期间：`npm run watch` 会在文件更改时重新构建并重启插件。 ## 兼容性 使用配对了 ATK **8K 无线 dongle**（`VID 0x373B`、`PID 0x11D9`）的 **ATK X1 Ultimate** 构建并测试。其他 ATK / VXE / VGN 鼠标共享此协议的大部分内容（相同的命令布局和校验和方案），因此只需调整 `src/atk-x1.ts` 中的 VID/PID 可能就足够了——欢迎反馈。 ## 协议 所有操作均通过配置接口（`usagePage 0xFF02`、`usage 0x0002`）上的 17 字节 HID report 运行： ``` Byte 0 Report ID (0x08) Byte 1 Command 0x04 = battery, 0x07 = SetEEPROM, 0x08 = GetEEPROM Byte 2 Status (0 when sending) Byte 3-4 EEPROM address (big endian) Byte 5 Data length Byte 6-15 Data Byte 16 Checksum = (0x55 - sum(bytes 0..15)) & 0xFF ``` EEPROM 映射（通过将快照与 ATK HUB 的更改进行对比以及 USB 抓包验证）： | 地址 | 内容 | |---|---| | `0x00` | 回报率：`1K=1, 500=2, 250=4, 125=8`（分频器）/ `2K=0x10, 4K=0x20, 8K=0x40`（标志位）。存储为 `[value, 0x55-value]`。 | | `0x02` | DPI 档位数量 | | `0x04` | 当前 DPI 档位（从 0 开始），`[value, 0x55-value]` | | `0x0C` + n*4 | 每个档位的 DPI 值：`[dpiX, dpiY, mult, crc]`，其中 `DPI = (dpiX + 1) * 10 * ((mult & 0x0F) + 1)` 且 `crc = 0x55 - sum(values)` | | `0x2C` + n*4 | DPI 档位颜色：`[R, G, B, crc]` | | `0xB5` | 传感器固件模式，6 字节：`[01 54] [12 43] [mode, 0x55-mode]`，其中 `0=Basic, 1=Shard, 2=MAX`（通过 USBPcap 从 ATK HUB 逐字节完全一致地抓取） | 电池命令 `0x04` 在第 6 个字节返回电量，并在第 7 个字节返回有线/充电标志——仅在鼠标处于唤醒状态时由 dongle 应答。 ## 设置概述 - 每个动作的颜色和背景，外加单独的 **无 dongle 背景** - 每个按键/拨盘的**标题**文本（开/关 + 自定义文本） - **DPI 切换：** 使用鼠标自带的档位颜色或自定义颜色 - **回报率：** 要循环切换的回报率列表（例如 `1000,4000,8000`） ## 故障排除 - **到处都是 `Zzz`** - 鼠标处于休眠状态。移动鼠标；显示会在约 5-10 秒内自动恢复。 - **`NO DONGLE`** - 未找到接收器。检查 USB 连接。 - **数值未改变** - 确保 ATK HUB 已关闭。 - 日志：`%appdata%\Elgato\StreamDeck\Plugins\com.holgermilz.myatxmousecontrol.sdPlugin\logs` ## 免责声明 本项目与 ATK 无关。此插件写入的设置会永久保存在鼠标的 EEPROM 中，就像通过 ATK HUB 更改一样——使用风险自负。 ## 许可证 [MIT](LICENSE) (c) 2026 Holger Milz

标签：HID协议, MITM代理, Stream Deck插件, 云资产清单, 游戏外设, 硬件控制, 自动化攻击, 逆向工程, 鼠标管理