GaimsDevSoftware/macropad-mac
GitHub: GaimsDevSoftware/macropad-mac
通过逆向工程为仅提供 Windows 软件的 XZKJ 宏键盘实现 macOS 原生配置工具，支持按键绑定、旋钮映射和基于前台应用的动态快捷键切换。
Stars: 0 | Forks: 0
# macropad-mac
适用于 AliExpress 宏键盘 **XZKJ 12 键 / 4 旋钮** (USB `514C:8850`) 的 macOS 配置工具 —
该设备仅附带中文 Windows 软件。
该协议是针对此型号从头进行逆向工程得出的。配置存储在
键盘自带的内存中，因此仅在更改布局时才需要运行该软件。
## 这是你的设备吗？
4×3 布局的十二个按键，四个旋钮 — 两个小的，一个中等的，以及一个位于右上方凸出部分的大旋钮。它以多种名称销售。请检查 USB ID 以确认：
```
hidutil list | grep 514c
```
## 快速开始
```
python3 -m venv .venv
.venv/bin/pip install hidapi pyyaml
.venv/bin/python app.py # åpner http://127.0.0.1:8777
```
点击按键或旋钮，输入绑定，然后按 **写入键盘**（Skriv til tastatur）。
### CLI 替代方案
```
.venv/bin/python macroctl.py flash config.example.yaml
.venv/bin/python macroctl.py validate config.example.yaml
.venv/bin/python macroctl.py list-keys
```
## 绑定语法
| 示例 | 含义 |
|---|---|
| `cmd+c` | Cmd + C |
| `cmd+shift+4` | 多个修饰键 |
| `h,e,i` | 按键序列（包含修饰键最多 18 个） |
| `c@100` | 按键前延迟 100 ms |
| `volumeup` / `volumedown` / `mute` | 音量控制 |
| `mouse:left` | 鼠标点击（`left` / `right` / `middle`） |
修饰键：`cmd` `shift` `alt` `ctrl`，以及用于右侧的 `rshift`、`ralt` 等。
每个旋钮提供三个独立的绑定：**左旋 · 按下 · 右旋**。
## 依赖应用程序的按键
如果你希望同一个旋钮在 Spotify 中执行快进并在 VS Code 中进行缩放 — 或者干脆想要实现播放/暂停功能 — 请运行 daemon。该面板会被刷入 24 个隐形信号，daemon 会根据当前处于前台的 app 对它们进行转换：
```
.venv/bin/python setup_daemon.py # flash signalene — én gang
cp profiles.example.yaml profiles.yaml
.venv/bin/python daemon.py # krever Tilgjengelighet-tilgang
```
```
default:
knob3.press: media:playpause
key5: key:cmd+c
apps:
com.spotify.client:
knob3.left: media:prev
knob3.right: media:next
```
操作：`media:`（传输和音量）、`key:`、`app:`、`url:`、`shell:`。
该文件会在保存时重新加载。参见 [docs/DAEMON.md](docs/DAEMON.md)。
这也解决了播放/暂停/下一个/上一个的问题，因为面板自身无法独立完成这些操作 —
daemon 会通过 macOS 原生的媒体 API 发送这些指令。
## 状态
- ✅ 按键绑定、修饰键、序列、延迟
- ✅ 直接从面板控制音量加/减/静音
- ✅ 鼠标点击
- ✅ 通过 daemon 实现依赖 app 的按键和完整的媒体传输
- ⚠️ 直接从面板*原生*控制播放/暂停/下一个/上一个 — 未找到 consumer 格式
（daemon 实际上已使此功能变得多余）
- ⬜ LED 控制
- ⬜ 第 2 层和第 3 层（协议支持；尚未测试）
有关按键 ID 映射和协议详细信息，请参见 [docs/PROTOCOL.md](docs/PROTOCOL.md)。
## 鸣谢
[kriomant/ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool)，特别是
[@yawor 在 issue #153 中的工作](https://github.com/kriomant/ch57x-keyboard-tool/issues/153)
他破解了相关 16 键/3 旋钮型号的 `03 fd` 帧格式。本项目
绘制了 12 键/4 旋钮型号的映射，并发现此处的媒体键使用的是 keyboard 端点，
而不是 consumer 端点。
## 许可证
MIT
4×3 布局的十二个按键，四个旋钮 — 两个小的，一个中等的，以及一个位于右上方凸出部分的大旋钮。它以多种名称销售。请检查 USB ID 以确认：
```
hidutil list | grep 514c
```
## 快速开始
```
python3 -m venv .venv
.venv/bin/pip install hidapi pyyaml
.venv/bin/python app.py # åpner http://127.0.0.1:8777
```
点击按键或旋钮，输入绑定，然后按 **写入键盘**（Skriv til tastatur）。
### CLI 替代方案
```
.venv/bin/python macroctl.py flash config.example.yaml
.venv/bin/python macroctl.py validate config.example.yaml
.venv/bin/python macroctl.py list-keys
```
## 绑定语法
| 示例 | 含义 |
|---|---|
| `cmd+c` | Cmd + C |
| `cmd+shift+4` | 多个修饰键 |
| `h,e,i` | 按键序列（包含修饰键最多 18 个） |
| `c@100` | 按键前延迟 100 ms |
| `volumeup` / `volumedown` / `mute` | 音量控制 |
| `mouse:left` | 鼠标点击（`left` / `right` / `middle`） |
修饰键：`cmd` `shift` `alt` `ctrl`，以及用于右侧的 `rshift`、`ralt` 等。
每个旋钮提供三个独立的绑定：**左旋 · 按下 · 右旋**。
## 依赖应用程序的按键
如果你希望同一个旋钮在 Spotify 中执行快进并在 VS Code 中进行缩放 — 或者干脆想要实现播放/暂停功能 — 请运行 daemon。该面板会被刷入 24 个隐形信号，daemon 会根据当前处于前台的 app 对它们进行转换：
```
.venv/bin/python setup_daemon.py # flash signalene — én gang
cp profiles.example.yaml profiles.yaml
.venv/bin/python daemon.py # krever Tilgjengelighet-tilgang
```
```
default:
knob3.press: media:playpause
key5: key:cmd+c
apps:
com.spotify.client:
knob3.left: media:prev
knob3.right: media:next
```
操作：`media:`（传输和音量）、`key:`、`app:`、`url:`、`shell:`。
该文件会在保存时重新加载。参见 [docs/DAEMON.md](docs/DAEMON.md)。
这也解决了播放/暂停/下一个/上一个的问题，因为面板自身无法独立完成这些操作 —
daemon 会通过 macOS 原生的媒体 API 发送这些指令。
## 状态
- ✅ 按键绑定、修饰键、序列、延迟
- ✅ 直接从面板控制音量加/减/静音
- ✅ 鼠标点击
- ✅ 通过 daemon 实现依赖 app 的按键和完整的媒体传输
- ⚠️ 直接从面板*原生*控制播放/暂停/下一个/上一个 — 未找到 consumer 格式
（daemon 实际上已使此功能变得多余）
- ⬜ LED 控制
- ⬜ 第 2 层和第 3 层（协议支持；尚未测试）
有关按键 ID 映射和协议详细信息，请参见 [docs/PROTOCOL.md](docs/PROTOCOL.md)。
## 鸣谢
[kriomant/ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool)，特别是
[@yawor 在 issue #153 中的工作](https://github.com/kriomant/ch57x-keyboard-tool/issues/153)
他破解了相关 16 键/3 旋钮型号的 `03 fd` 帧格式。本项目
绘制了 12 键/4 旋钮型号的映射，并发现此处的媒体键使用的是 keyboard 端点，
而不是 consumer 端点。
## 许可证
MIT标签：HID, Python, 云资产清单, 宏键盘, 快捷键, 无后门, 硬件配置工具, 逆向工具, 逆向工程