mchose-linux

在 Linux 上配置迈从（MCHOSE）游戏鼠标、键盘和耳机。用户态程序，不写内核驱动，不常驻后台。

官方 M HUB 只有 Windows 版（网页版也只保证 macOS），Linux 下设备能用，但 DPI、回报率、 抬起高度、去抖、休眠、键盘灯效、改键、耳机电量/音效模式这些设置都改不了。这个项目直接 通过 hidraw 和设备的厂商 HID 接口通信，把设置写进设备自己的配置。

已知设备：

设备	USB（接收器）	机体 PID	固件
MCHOSE K7 Ultra（鼠标）	3837:1001	3837:4150	5.28.5.0
MCHOSE K99 V2（键盘，有线）	258a:010c	258a:010c	—
MCHOSE V9 PRO（耳机，2.4G）	291d:385d	291d:385d	耳机 0036，接收器 0012

K7 Ultra、K99 V2 和 V9 PRO 的设置读写均已在本机实测。耳机需要 291d:385d 的 udev 规则，首次使用前请重装规则并运行 mchose --headset info 确认。

其他带 0xFF01 厂商配置接口的迈从鼠标理论上也能读，型号数据会走通用回退； 键盘目前只验证了 K99 V2 有线；耳机使用 C-Media BLK 协议，S9 PRO / G9 PRO / V9 / X9 等同系列耳机理论上也适用。欢迎提 issue 补充实测数据。

功能

鼠标：

• QML GUI（PySide6）：电量、六档 DPI、回报率、去抖、休眠、LOD、板载配置、备份
• info / show / status --json / battery：型号、固件、连接方式、电量、当前设置
• DPI：单档修改、指定档位、一次写六档、切换当前档位
• 回报率：125 / 500 / 1000 / 2000 / 4000 / 8000 Hz
• 按键去抖、休眠时间、抬起高度（0.7 / 1 / 2 mm）、三组板载配置切换
• 配置块备份 / 恢复，原始配置自动备份
• raw：直接收发一帧，方便继续逆向其他字段

键盘（K99 V2 有线）：

• 灯效：模式、亮度、速度、单色、多彩；逐键 RGB（自定义灯效）
• 性能：250 / 500 / 1000 Hz 回报率、休眠、标准 / 速度延迟、Win 键锁、Mac 模式
• 改键：Default / Fn / Fn2 三层，113 个键位，目标可用功能名或原始 4 字节编码
• 键盘配置备份 / 恢复（JSON），原始配置自动备份
• raw：直接发送 519 字节厂商 feature report

耳机（V9 PRO 等 BLK 系列 2.4G）：

• 电量、充电 / 休眠状态
• 音效模式：游戏模式 1 / 2、音乐模式；写入后回读确认
• 耳机和接收器固件版本
• raw：直接收发 0x55 输出报告或 0xAA feature report

暂未实现：鼠标按键重映射、宏、灯光、固件升级；键盘 2.4G 接收器、宏、 音乐律动、GIF、固件升级；耳机的 EQ、空间音效、麦克风降噪等依赖 Windows 音频驱动的设置。键盘只验证了 K99 V2 有线（258a:010c）。

安装

需要 Rust 和 cargo：

git clone https://github.com/aipno/mchose-linux.git
cd mchose-linux
./install.sh

install.sh 会：

1. cargo build --release
2. 把二进制装到 ~/.local/bin/mchose
3. 安装 udev 规则（需要输入一次 sudo 密码）
4. 重新加载 udev

装完后重新插拔接收器/键盘/耳机，让规则生效。确保 ~/.local/bin 在 PATH 里。

手动安装也可以：

cargo build --release
install -Dm755 target/release/mchose ~/.local/bin/mchose
sudo install -Dm644 70-mchose.rules /etc/udev/rules.d/70-mchose.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

没有 udev 规则时 /dev/hidrawN 是 root:root 0600，普通用户会看到 “Permission denied”。规则同时支持鼠标的 0x5253 / 0x3837、键盘的 258a:010c 和耳机的 291d:385d。

Arch 包

Arch / CachyOS 可以直接构建本地包：

./packaging/arch/build.sh
sudo pacman -U mchose-0.1.0-2-x86_64.pkg.tar.zst

包会安装：

• /usr/bin/mchose 和 /usr/bin/mchose-gui
• /usr/lib/udev/rules.d/70-mchose.rules
• /usr/share/icons/hicolor/scalable/apps/mchose.svg
• /usr/share/doc/mchose/、桌面启动项和 GUI 文件
• GUI 使用 uv 创建的独立 venv，并复用系统 pyside6，不会向系统 Python 安装包

安装脚本只重新加载 udev 规则，不修改 /etc、不启用服务、不碰固件。如果之前用 ./install.sh 装过 ~/.local/bin/mchose，且它在 PATH 里优先于 /usr/bin， 可以改用 /usr/bin/mchose，或删除旧的本地二进制避免版本混用。

GUI

GUI 用 PySide6 + QML。协议仍然只由 Rust 实现：GUI 启动一个常驻的 mchose serve， 通过 stdin/stdout 的 JSON Lines 通信，点击按钮不会重新起进程、重新打开设备。 顶部会列出所有已识别的鼠标、键盘和耳机，可以直接切换；连接耳机时显示电量、固件和 音效模式，连接鼠标/键盘时显示对应设置。 需要 Python 3.10+、uv 和 PySide6 6.5+。首次运行 gui/run.sh 会自动在 gui/.venv 创建虚拟环境并安装依赖：

./gui/run.sh

手动运行：

cd gui
uv venv
uv pip install -r requirements.txt
.venv/bin/python main.py

先装好 CLI 和 udev 规则（如果之前装过旧版，重新运行一次 ./install.sh 更新二进制）。 多个设备同时连接时，GUI 顶部可以直接选择鼠标、键盘或耳机；启动时也可以指定：

./gui/run.sh --keyboard
./gui/run.sh --mouse
./gui/run.sh --headset
./gui/run.sh --device /dev/hidraw7

GUI 会优先使用仓库里的 target/release/mchose，其次在 PATH 和 ~/.local/bin/mchose 里找 CLI；也可以用 MCHOSE_BIN=/path/to/mchose 指定。 RPC 方法、请求/响应格式见 docs/RPC.md。

用法

mchose devices                 # 找配置接口，例如 /dev/hidraw2
mchose info                    # 型号、固件、电量、当前设置
mchose show                    # 六档 DPI、回报率、去抖、休眠、LOD
mchose status --json           # 机器可读状态，GUI 和脚本用这个
mchose serve                   # 常驻 stdio JSON-RPC，GUI 使用
mchose battery                 # 只输出电量，适合脚本

mchose dpi 1600                # 改当前档位
mchose dpi 800 --stage 0       # 改第 1 档，不切换
mchose dpi --list 400,800,1600,3200,6400,42000
mchose stage 2                 # 切到第 3 档
mchose rate 8000               # 8K 回报率
mchose debounce 3
mchose sleep 5                 # 5 分钟无操作休眠；0 关闭
mchose lod 1                   # 1 mm
mchose profile 1               # 第 2 组板载配置

mchose backup mouse.bin
mchose restore mouse.bin
mchose raw 11 06               # 原始读命令，打印解码后的回复

键盘（K99 V2 有线）：

mchose --keyboard info
mchose --keyboard show
mchose --keyboard status --json

mchose --keyboard light --mode 2          # 呼吸模式
mchose --keyboard light --brightness 60 --speed 2 --color ff0000
mchose --keyboard rgb ff0000 --all        # 逐键 RGB，全部红色
mchose --keyboard rgb 00ff00 --key A      # A 键绿色

mchose --keyboard performance --rate 1000 --sleep 5 --latency speed
mchose --keyboard performance --winlock on --mac off

mchose --keyboard keys Fn                 # 列出 Fn 层 113 键
mchose --keyboard key Default Caps Left_Ctrl
mchose --keyboard key Fn A mouse.volumeUp

mchose --keyboard backup keyboard.json
mchose --keyboard restore keyboard.json
mchose --keyboard raw 84 00 00 01 00 80 00   # 原始读性能设置

耳机（V9 PRO 等 BLK 系列 2.4G）：

mchose --headset info
mchose --headset show
mchose --headset status --json
mchose --headset battery

mchose --headset mode              # 查看当前音效模式
mchose --headset mode game1        # 游戏模式 1
mchose --headset mode music        # 音乐模式
mchose --headset raw 55 65 01      # 原始电量查询，打印 0x55 输入报告

--device /dev/hidrawN 可以跳过自动探测；多个设备同时连接时用 --keyboard / --mouse / --headset 选择。

安全

• 鼠标第一次写操作前，原始 63 字节配置会保存到 ~/.local/state/mchose/config.original.bin，只保存一次。
• 键盘第一次写操作前，完整配置（灯效、性能、三层按键、逐键 RGB）会保存到 ~/.local/state/mchose/keyboard.original.json，只保存一次。
• 键盘的写命令是整块覆盖：程序总是先读回对应块，只改目标字段，再写回并回读校验； 不会拿空数据覆盖设备配置。
• 耳机没有可备份的配置块；切换音效模式后会回读确认，失败会报错。
• 大部分写命令写完会回读校验；失败会报错，不会静默成功。
• 不碰固件，不会刷砖。
• raw 是裸写接口，写未知命令前请先 backup。
• GUI 打开时会保持一个 mchose serve 进程；不要同时用 CLI 改同一项设置， 两边不会自动同步，最后一次写入为准。

它是怎么工作的

鼠标的第三个 USB 接口是一个厂商 HID 集合（usage page 0xFF01），用两个 feature report：

Report	长度	用途
0x11	20 字节	短命令：设备信息、回报率、DPI 档位、去抖、休眠、LOD、配置切换
0x12	64 字节	长命令：完整 63 字节配置块、按键、宏

负载在总线上逐字节 XOR 0xFF，没有校验和；回复用 report ID 和命令回显匹配。 详细帧格式、实测样本和 K7 Ultra 的差异见 docs/PROTOCOL.md。

键盘是另一套厂商 HID 协议：usage page 0xFF00，feature report 0x06，519 字节负载。 读命令回显 7 字节命令头，数据从回包第 8 字节开始；写命令是 1 字节命令号 + 整块数据。 详细块布局、偏移和写报文见 docs/KEYBOARD.md。

耳机使用 C-Media BLK 协议：0x55 输出/输入报告负责电量和音效模式，0xAA feature 报告读取耳机和接收器固件版本。命令来自 M HUB 前端，详见 docs/HEADSET.md。

GUI 不再每次起进程：它保持一个 mchose serve，通过 stdin/stdout 的 JSON Lines 调用 同一组 Rust 函数。RPC 方法和字段见 docs/RPC.md。

代码按设备分开，新增型号或命令只需改对应模块：

路径	职责
src/mouse/	鼠标发现、CLI 命令、状态和 RPC；protocol.rs 是 0xFF01 帧协议
src/keyboard/	键盘发现、CLI 命令、状态和 RPC；protocol.rs 是 0xFF00 协议
src/headset/	耳机发现、CLI 命令、状态和 RPC；protocol.rs 是 BLK 0x55/0xAA 协议
src/device.rs	鼠标/键盘/耳机选择与统一 RPC 入口
src/rpc.rs	JSON Lines 服务循环
src/main.rs	命令行参数、帮助和顶层分发
src/hidraw.rs	纯 hidraw/sysfs 访问，不含设备业务

几个实现上的坑：

• 鼠标空闲后的第一条请求经常返回全零，必须重发，不能当成“配置被清空”。
• 连续命令太快会让配置通道卡住，帧之间至少间隔 25 ms。
• K7 Ultra 的回报率写在配置块 byte[2] 高半字节，设备主动推送里的回报率字段也跟着它； byte[1] 的高半字节不会同步。
• K7 Ultra 的 LOD 索引可直接从配置块 sensor 低 2 位读回， 0/1/2 分别对应 0.7/1/2 mm。
• 耳机的电量和音效模式走 0x55 输出报告，回复是另一条输入报告，不是 feature ioctl；0xAA feature 报告只用于固件版本。

协议来源与致谢

协议是从官方 M HUB 的 WebHID 前端和真机实验中还原的。以下项目的公开文档/实现 提供了重要交叉验证（均为 MIT）：

• alexfrih/mchose-linux — 帧格式、命令表、配置块字段
• LORQAQ/mchose-tray — K7 Ultra 型号数据、半字节实验
• Brokeos/mchose-lite — 同一套 feature report 协议
• wzk112/MchoseHub — K87/K99 V2 有线键盘命令表、字段布局和灯效对照
• M HUB 网页版 — 键盘 0xFF00 命令表、灯效参数和逐键 RGB 布局

本项目是独立实现，没有复制上述项目的代码；协议常量来自公开文档和本机实测。

MCHOSE、M HUB 等名称属于其权利人。本项目与迈从官方无关。

License

MIT，见 LICENSE。