codedgar/gmk87-node

# GMK87 配置器    上传图片到键盘显示屏、配置 RGB 灯效、同步时钟以及在 Zuoya GMK87 键盘上应用预设。 ## 硬件 - **键盘：** Zuoya GMK87 - **厂商 ID：** `0x320f` | **产品 ID：** `0x5055` - **显示屏：** 240x135 像素，RGB565，2 个图片插槽 - **USB 接口：** 3（厂商自定义，`usagePage 0xFF1C`） ## 应用程序 带有图形界面的桌面应用程序。支持 Windows、macOS 和 Linux。 [](https://github.com/codedgar/gmk87-node/releases/latest) [](https://github.com/codedgar/gmk87-node/releases/latest) [](https://github.com/codedgar/gmk87-node/releases/latest) 前往 [Releases](https://github.com/codedgar/gmk87-node/releases/latest)，下载适合你操作系统的文件并安装。 | 操作系统 | 文件 | |---|---| | Windows | `.exe` 安装程序 | | macOS | `.dmg` | | Linux | `.AppImage` 或 `.deb` | ## CLI 终端命令行工具。需要 [Node.js](https://nodejs.org) (v14+)。 ### 安装 ``` git clone https://github.com/codedgar/gmk87-node.git cd gmk87-node npm install ``` ### 命令 | 命令 | 功能 | |---|---| | `npm run sendimage` | 上传图片到显示屏 | | `npm run lights` | 配置 RGB 底光和 LED | | `npm run preset` | 应用预设灯效配置 | | `npm run timesync` | 将系统时间同步到键盘 | ### 上传图片 同时上传到两个插槽（推荐，上传过程会覆盖所有图像内存）： ``` npm run sendimage -- --slot0 image1.png --slot1 image2.jpg ``` 单个插槽（另一个插槽将为空白）： ``` npm run sendimage -- --file image.png --slot 0 ``` 动态 GIF 图： ``` npm run sendimage -- --slot0 animation.gif --slot1 static.png --ms 100 ``` 选项： | 标志 | 描述 | |---|---| | `--slot0` / `--slot1` | 每个显示插槽的路径（静态图片或 GIF） | | `--file` + `--slot` | 单图模式 | | `--ms ` | 动画延迟（毫秒，最小 60，默认 100） | | `--show` | 上传后显示哪个插槽 | 图片会自动调整为 240x135 大小。两个插槽最多支持总计 36 帧。 ### 配置灯光 ``` npm run lights -- --effect breathing --brightness 7 --red 255 --green 0 --blue 0 npm run lights -- --led-color blue --led-mode 3 npm run lights -- --effect rainbow-waterfall --brightness 9 --speed 3 ``` 底光选项： | 标志 | 值 | |---|---| | `--effect` | 名称或 0-18 | | `--brightness` | 0-9 | | `--speed` | 0-9（0 = 快，9 = 慢） | | `--orientation` | 0（从左到右）或 1（从右到左） | | `--rainbow` | true / false | | `--red`、`--green`、`--blue` | 0-255 | LED 选项： | 标志 | 值 | |---|---| | `--led-mode` | 0-4 | | `--led-color` | 名称或 0-8（red、orange、yellow、green、teal、blue、purple、white、off） | | `--led-saturation` | 0-9 | | `--led-rainbow` | true / false | 其他： | 标志 | 值 | |---|---| | `--winlock` | true / false | | `--show-image` | 0（时间）、1（插槽 0）、2（插槽 1） | ### 应用预设 ``` npm run preset -- gaming ``` 可用预设：`gaming`、`relaxed`、`party`、`minimal`、`productivity`、`purple-wave`、`matrix`、`sunset` ### 同步时间 ``` npm run timesync ``` ### 调试日志 ``` DEBUG=1 npm run sendimage -- --slot0 image.png --slot1 image2.jpg ``` ## API 导入 `src/api.js` 以在你自己的代码中控制键盘。 ``` npm install codedgar/gmk87-node ``` ``` import gmk87 from "gmk87-hid-uploader"; ``` 或者使用命名导入： ``` import { uploadImage, setLighting, showSlot, syncTime, readConfig, getKeyboardInfo } from "gmk87-hid-uploader"; ``` ### 函数 #### `uploadImage(imagePath, slot, options)` 将静态图片或 GIF 上传到显示屏。 ``` await gmk87.uploadImage("cat.png", 0, { slot0File: "cat.png", slot1File: "dog.jpg" }); await gmk87.uploadImage("anim.gif", 0, { slot0File: "anim.gif", frameDuration: 100 }); ``` #### `setLighting(changes)` 配置底光和 LED 设置。使用读取-修改-写入方式，未指定的设置将被保留。 ``` await gmk87.setLighting({ underglow: { effect: 5, brightness: 7, hue: { red: 255, green: 0, blue: 128 } }, }); await gmk87.setLighting({ led: { mode: 3, color: 5 }, }); ``` #### `showSlot(slot)` 切换显示屏。`0` = 时间，`1` = 插槽 0，`2` = 插槽 1。 ``` await gmk87.showSlot(2); ``` #### `syncTime()` 将系统时间发送到键盘时钟。 ``` await gmk87.syncTime(); ``` #### `readConfig()` 读取当前的键盘配置。 ``` const config = await gmk87.readConfig(); // config.underglow -> { effect, brightness, speed, orientation, rainbow, hue } // config.led -> { mode, saturation, rainbow, color } // config.showImage -> 0, 1, or 2 ``` #### `getKeyboardInfo()` 获取设备信息（制造商、产品、厂商/产品 ID）。 ``` const info = gmk87.getKeyboardInfo(); ``` 所有 API 函数都会自动处理设备的打开和关闭。 ## 协议 基于官方 Zuoya 应用程序的 USB 抓包。使用 USB 接口 3 上的命令-响应机制。 ### 帧结构 64 字节的 HID 报告： ``` [0] = 0x04 (report ID) [1-2] = checksum (uint16 LE, sum of bytes 3-63) [3] = command byte [4] = data length [5-7] = position (24-bit LE) [8-63] = data payload (56 bytes max) ``` ## 参考 - Jochen Eisinger 提供的 Python 参考实现（包含为 `reference.py`，BSD 许可证） - [@ikkentim](https://github.com/ikkentim) 提供的原始 C# 逆向工程：https://github.com/ikkentim/gmk87-usb-reverse ## 许可证 MIT

标签：API, GNU通用公共许可证, MITM代理, Node.js, RGB565, RGB灯效控制, USB HID通信, 卓耀GMK87, 图片上传, 外设驱动, 客制化键盘, 嵌入式系统, 时间同步, 极客硬件, 桌面应用程序, 桌面端开发, 电竞外设, 硬件交互, 自定义脚本, 键盘配置工具