内容
# PadKit
**为廉价的6键+旋转旋钮的CH552宏键盘定制固件和工具 — 让每个键和旋钮都能做任何事情，并通过浏览器设置。**
### 这是你的设备吗？
任何 **CH552 / CH552G 宏键盘，带有 6 个键 + 1 个旋转旋钮**，并以 USB `1189:8890` 枚举。它被以许多名称出售 — 参考设备是在亚马逊上购买的 *"SinLoon Mini Macro Programmable Keyboard, 6 Keys 1 Knob"*；同样的板子在 AliExpress/eBay 上作为通用 "6-key knob macro keypad" 出现。内部接线在克隆之间有所不同 — 包含的 [扫描器](firmware/scanner/) 会在默认值不匹配时映射您的设备。
*以下三个层级都在真实的垫子上经过了硬件验证。*
## 你可以做的事情
| | 功能 | 安装 |
|---|---|---|
| **绑定键** | 固件发送标准 **F13–F23** — 在任何操作系统、AutoHotkey、Karabiner、Home Assistant 等中绑定它们。 | 闪存一次 |
| **在浏览器中配置** | [**打开配置工具**](https://denniswjpg.github.io/padkit/config.html) → 设置每键颜色、亮度和每个键发送的快捷方式 → 保存到垫子上。 | 无（Chrome/Edge） |
| **自动化和集成** | [`padkitd`](daemon/) 守护进程将键/旋钮转换为 shell 命令、HTTP webhooks 或事件驱动的 LED — 并公开一个 **MCP 服务器**，以便 AI 代理驱动垫子。 | 一个二进制文件 |
[](https://denniswjpg.github.io/padkit/config.html)
*↑ 浏览器配置工具 — [尝试无需硬件](https://denniswjpg.github.io/padkit/config.html?demo=1)。*
## 多快
**浏览器，约 2 分钟，无需安装**（macOS/Linux）：
1. 将垫子进入引导加载程序模式 — [打开外壳，在插入 USB 时桥接 **SW2**](docs/flashing.md)（指南中有照片）。
2. [**在浏览器中刷新 →**](https://denniswjpg.github.io/padkit/flash.html)（连接 → 完成）。
3. 重新插入，[**打开配置工具 →**](https://denniswjpg.github.io/padkit/config.html)，并设置您的颜色/键。
**更喜欢终端？** `cd flasher && make` 然后 `./flasher/isp55e0 -f firmware/padkit.bin`。从 [最新版本](https://github.com/denniswjpg/padkit/releases/latest) 获取预建的 `padkit.bin` 和 `padkitd` 二进制文件。
## 需要知道
- **它是不可损坏的。** CH552 引导加载程序存放在掩模 ROM 中 — 不良的闪存始终可以通过重新进入引导加载程序模式来恢复。
- **引导加载程序窗口很短 — 请快速操作。** 在 SW2 短路后，垫子仅在几秒钟内保持在引导加载程序中，因此请迅速点击 **连接和闪存**，并在 Chrome 的弹出窗口中选择设备。更容易：使用闪存工具的 **"等待引导加载程序"** 按钮 — 它会在垫子出现时自动闪存，无需匆忙。
- **Windows** 需要一次性 Zadig → WinUSB 驱动程序交换用于引导加载程序（CH552 ROM 特殊性，与 CLI 和浏览器相同）。macOS/Linux 无需任何操作（Linux：一个 udev 规则）。
- **配置保留在垫子上**（DataFlash）— 颜色和键映射在拔出时保存；守护进程是可选的。
## 输入映射
| 控制 | 发送 |
|---|---|
| 键 1-6 | F13 · F14 · F15 · F16 · F17 · F18 （真实按下/释放 → 点击或按住） |
| 旋钮转动 | 逆时针 → F19 · 顺时针 → F21 |
| 旋钮点击 | F20 |
| 按下 + 转动 | 逆时针 → F22 · 顺时针 → F23 |
完整规格 — 按操作系统划分的绑定配方、LED/键映射 HID 协议，以及 AI 代理的工作示例 — 在 [`AGENTS.md`](AGENTS.md) 中（[`llms.txt`](llms.txt) 指向它）。
## 使它成为你的
六个键和一个旋钮，可以发送任意快捷方式、运行任意命令、触发 webhook 或与 AI 代理通信。一些起点：
- **通话** — 键上静音/取消静音和摄像头切换，旋钮上音量。
- **媒体** — 键上播放/暂停和跳过，旋钮上搜索或音量。
- **编码** — 键上运行测试、格式化、暂存+提交；旋钮上撤销/重做或编辑器缩放。
- **Home Assistant** — 一个键用于每个场景，旋钮用于调暗灯光（通过 webhook）。
- **AI 编程代理** — 从键上批准或中断代理，通过旋钮滚动其输出，并在它需要您时让它点亮一个键（通过守护进程的 MCP 服务器）。 *这是 PadKit 最初构建的内容 — 用于 AI 助手的物理遥控器。*
### 交给你的 AI 代理
您不需要手动连接任何东西 — PadKit 提供了一个完整的机器可读规范，以便代理可以为您完成。 将以下内容粘贴到 Claude（或任何编码代理）并填写空白：
> 我有一个 **PadKit** 宏键盘 — 6 个键 + 一个旋转旋钮，开源 CH552 固件。其完整规格（输入映射、LED/键映射 HID 协议和带有 shell / webhook / MCP 操作的 `padkitd` 伴侣）位于 https://github.com/denniswjpg/padkit/blob/main/AGENTS.md — 请先阅读。然后帮助我设置我的垫子以 **‹您希望它执行的操作›**。我在 ‹macOS / Windows / Linux› 上，我更喜欢 ‹纯 OS 键绑定 / padkitd 守护进程 / MCP 服务器›。给我确切的配置或步骤。
代理可以从规范中生成您的 OS 键绑定、`padkitd` 配置文件或 MCP 集成 — 无需反向工程协议。
## 布局和许可
```
firmware/ CH552 固件 + 扫描器/ — CC-BY-SA （基于 wagiminator 的 CH552 堆栈）
flasher/ 补丁 isp55e0 CLI 闪存工具 — GPLv3 （来自 frank-zago/isp55e0）
web/ WebHID 配置 + WebUSB 闪存工具（→ GitHub Pages）— MIT
daemon/ Go 伴侣 + MCP 服务器 — MIT
docs/ · examples/ · AGENTS.md — MIT
```
每个目录都有自己的许可证；请参见根目录 [`LICENSE`](LICENSE)。感谢 **wagiminator** （CH552 堆栈）、**frank-zago/isp55e0** （闪存工具）和 **QMK/VIA** （供应商-HID/WebHID 方法）。
