Lightning-13/monsgeek-rgb
GitHub: Lightning-13/monsgeek-rgb
通过逆向工程 MonsGeek 键盘的 USB HID 协议，提供独立于官方软件的 Python 灯效控制库与协议文档。
Stars: 0 | Forks: 0
# MonsGeek RGB
一个用于在不使用官方 MonsGeek 软件的情况下控制 **MonsGeek FUN60 Pro** RGB 灯效的 Python 库和协议文档。
本项目是对键盘 USB HID RGB 协议进行全面逆向工程的成果。它使用 `hidapi` 直接与键盘通信，绕过了官方应用程序 `iot_driver.exe` 及其 gRPC 通信层。
## 功能
* ✅ 直接的 USB HID 通信
* ✅ 不依赖官方 MonsGeek 软件
* ✅ 自动检测有线和 2.4 GHz 模式
* ✅ 静态 RGB 灯效
* ✅ 持久化的逐键 RGB 布局（自定义层 / Custom Layer）
* ✅ 亮度控制
* ✅ 逆向工程的协议文档
## 当前状态
| 功能 | 状态 |
| ----------------------- | ---------------- |
| 设备检测 | ✅ |
| 有线模式 | ✅ |
| 2.4 GHz 模式 | ✅ |
| 静态 RGB | ✅ |
| 逐键 RGB | ✅ |
| 亮度 | ✅ |
| 内置效果控制 | ✅ 部分支持 |
| 实时 RGB 流 | ❌ 未识别 |
## 支持的设备
| 设备 | 连接方式 | VID | PID |
| ------------------ | ---------- | ------ | ------ |
| MonsGeek FUN60 Pro | 有线 | 0x3151 | 0x502F |
| MonsGeek FUN60 Pro | 2.4 GHz | 0x3151 | 0x5026 |
如果其他 MonsGeek/Yichip 键盘实现了相同的 HID 协议，则可能也支持它们。
## 安装说明
克隆代码库：
```
git clone https://github.com/Lightning-13/monsgeek-rgb.git
cd monsgeek-rgb
```
安装所需的依赖项：
```
pip install hidapi
```
## 快速示例
```
from fun60_controller import FUN60Controller
with FUN60Controller() as keyboard:
keyboard.set_all(0, 255, 0)
```
这会将持久的绿色布局写入键盘的自定义层（Custom Layer）。
## 工作原理
键盘暴露了一个用于 RGB 控制的厂商特定 USB HID 接口。
本项目不与官方软件通信，而是将 HID Feature Report 直接发送到接口 2。RGB 数据会被写入键盘内部的 framebuffer，并使用与官方应用程序相同的协议提交到板载的自定义层（Custom Layer）。
## 项目结构
```
docs/
protocol.md
reverse_engineering.md
limitations.md
led_map.md
examples/
tests/
fun60_controller.py
```
## 文档
`docs` 目录中提供了详细的技术文档。
* **protocol.md** — 完整的 HID 协议参考。
* **reverse_engineering.md** — 研究过程与发现。
* **limitations.md** — 已知的协议限制和设计决策。
* **led_map.md** — 物理按键到 LED 索引的映射。
## 限制
该协议目前仅支持持久的自定义层（Custom Layer）写入。
在本次研究中，未识别出通用的基于 RAM 的 RGB 流传输协议。官方的 MonsGeek 软件同样是将更改提交到闪存，而不是提供实时的逐键 RGB 预览。
这意味着该库非常适用于：
* 静态布局
* 逐键颜色配置文件
* 配置实用程序
**不**适用于诸如 SignalRGB 或 OpenRGB 通常生成的高帧率动画，除非发现了以前未记录的流传输协议。
## 许可证
本项目基于 MIT 许可证发布。
## 免责声明
本项目是一项独立的逆向工程成果，不隶属于 MonsGeek、Akko、Yichip 或任何相关公司，也未获得其认可。
所有商标均归其各自所有者所有。
标签：Python, RGB灯效, USB HID, 云资产清单, 外设驱动, 无后门, 硬件控制, 逆向工具, 逆向工程