gusleig/ajazz-ak820-pro-mac

# ak820 — AJAZZ AK820 Pro 的 macOS 配置工具 一款用于在 **macOS** 上配置 **AJAZZ AK820 Pro** 键盘的命令行工具 — 可以设置屏幕时钟、RGB 灯光和休眠定时器，完全无需依赖仅限 Windows 的 官方软件。 ## 环境要求 - macOS (Apple Silicon 或 Intel) - Python **3.11+** (示例使用 `python3.13`) - 键盘通过 **USB-C *数据线*** 连接 (仅支持充电的线缆无法使用) ## 安装 ``` # 从项目文件夹 python3.13 -m venv .venv source .venv/bin/activate pip install -e . ``` 如果在构建 `hidapi` 时安装失败，请先安装该库，然后重试： ``` brew install hidapi pip install -e . ``` 下文的所有命令均假设您已激活虚拟环境 (`source .venv/bin/activate`)。 ## 快速开始 ``` ak820 identify # confirm the keyboard is connected ak820 sync-clock # set the keyboard's clock to your Mac's current time ak820 set-rgb --mode static --color 00AAFF # solid cyan lighting ``` ## 命令 ### `ak820 identify` 检查工具是否能识别到键盘 (只读操作 — 不会更改任何设置)。 ``` $ ak820 identify Manufacturer: SONiX Product: AK820 Serial: ``` 如果显示 `No AK820 device found`，请参阅[故障排除](#troubleshooting)。 ### `ak820 sync-clock` — 设置屏幕时钟 ``` # 将键盘时钟设置为 Mac 的当前本地时间（最常见用法） ak820 sync-clock # 设置特定日期/时间（格式："YYYY-MM-DD HH:MM:SS"，24小时制） ak820 sync-clock --time "2026-06-30 09:15:00" ``` 键盘的小屏幕必须处于其**时钟界面**才能看到效果。此后时钟会自行运转；如果时间出现偏差，随时可以重新运行 `sync-clock`。 ### `ak820 set-rgb` — RGB 灯光 ``` # 纯色（使用 "static" 模式） ak820 set-rgb --mode static --color FF0000 # solid red ak820 set-rgb --mode static --color 00FF00 --brightness 3 # dimmer green # 固定颜色的动画效果 ak820 set-rgb --mode breath --color 8000FF --speed 2 # purple breathing # Rainbow / 多色效果（忽略 --color，使用 --rainbow） ak820 set-rgb --mode spectrum --rainbow --brightness 5 --speed 3 ak820 set-rgb --mode rolling --rainbow --direction right # 关闭灯光 ak820 set-rgb --mode off ``` **选项** | 选项 | 取值 | 默认值 | 说明 | |---|---|---|---| | `--mode` | 参见下文列表 | `static` | 灯光效果 | | `--color` | `RRGGBB` 十六进制 | `FFFFFF` | 固定颜色 (设置了 `--rainbow` 时将忽略此项) | | `--rainbow` | 标志 | off | 循环切换颜色，而不是使用固定颜色 | | `--brightness` | `0`–`5` | `5` | `0` 表示关闭 | | `--speed` | `0`–`5` | `3` | 动画速度 (适用时) | | `--direction` | `left` `right` `up` `down` | `left` | 用于具有方向性的效果 | **模式：** `off`, `static`, `single-on`, `single-off`, `glittering`, `falling`, `colourful`, `breath`, `spectrum`, `outward`, `scrolling`, `rolling`, `rotating`, `explode`, `launch`, `ripples`, `flowing`, `pulsating`, `tilt`, `shuttle`。 ### 灯光预设 (单词命名风格) 为了快速设置命名的灯光风格，这里提供了一个小脚本 — `presets/ak820-preset`： ``` presets/ak820-preset list # show all presets presets/ak820-preset focus # dim steady blue (low distraction) presets/ak820-preset party # bright, fast rainbow presets/ak820-preset chill # slow rainbow drift presets/ak820-preset demo # cycle through several (~15s) ``` 可用预设：`focus`, `work`, `calm`, `chill`, `gaming`, `party`, `night`, `off`, `demo`。 该脚本会自动查找 `ak820` CLI (它使用代码库的 `.venv`)，因此您甚至无需 激活虚拟环境。**制作您自己的预设**只需编辑 `presets/ak820-preset` — 每个 预设都是一行 `set-rgb` 选项；只需复制一行，重命名，然后调整 `--mode` / `--color` / `--brightness` / `--speed` 即可。 ### `ak820 set-sleep` — 背光休眠定时器 设置键盘空闲多久后灯光熄灭。 ``` ak820 set-sleep 5 # sleep after 5 minutes ak820 set-sleep 30 # sleep after 30 minutes ak820 set-sleep 0 # never sleep ``` 允许的值：`0` (从不)，`1`, `5`, `30` 分钟。 ### `ak820 recover` — 解除屏幕卡死 如果屏幕时钟冻结或显示卡住 (最常见于命令被中断之后)，此命令会清除键盘的挂起状态并重新同步时钟： ``` ak820 recover # clear stuck state + re-sync clock to now ak820 recover --no-resync # just clear the stuck state, leave the clock as-is ``` 通常情况下您不需要用到它 — 但它提供了一行命令的替代方案，免去了拔插键盘的麻烦。 ## 故障排除 | 症状 | 原因与修复方法 | |---|---| | `No AK820 device found` | 键盘无法通过 USB 访问。**请使用 USB-C *数据线*连接** (不要使用 2.4 GHz 接收器、蓝牙或仅支持充电的线缆)。然后重新运行 `ak820 identify`。 | | 命令执行了但**没有任何变化** | 您可能是通过**接收器或蓝牙**连接的 — 这些方式不提供控制通道。请切换为 **USB-C 线缆**。 | | 屏幕**时钟冻结 / 卡住** | 运行 **`ak820 recover`**。如果仍然卡住，拔下线缆约 5 秒后重新插入 (不会写入任何永久内存，因此会正常重启)。 | | `OSError: open failed` | 另一个程序正在占用键盘接口。退出其他键盘应用程序，或拔插线缆，然后重试。 | | `pip install` 构建 `hidapi` 失败 | 运行 `brew install hidapi`，然后再次运行 `pip install -e .`。 | | `command not found: ak820` | 先激活虚拟环境：`source .venv/bin/activate`。 | | 安装时出现 Python 版本错误 | 请使用 Python 3.11+。使用 `python3.13 -m venv .venv` 创建虚拟环境。 | | RGB 的 `--color` 似乎被忽略 | 某些模式是多色的；若要使用单一稳定颜色，请使用 `--mode static`。如果设置了 `--rainbow`，颜色将被刻意忽略。 | | `sync-clock` 后时钟显示错误时间 | 请将键盘屏幕切换至其**时钟界面** (不要显示图片/GIF)，然后再次运行 `ak820 sync-clock`。 | ### 此工具在 macOS 上**无法做到**的事 - **macOS 不支持上传 LCD 图片 / GIF。** 屏幕的图像数据使用的是 macOS 不允许用户程序访问的批量 USB 接口 (这在 Linux 和 Windows 软件中有效)。时钟、灯光和休眠功能不受影响。 - **按键重映射 / 宏**尚未实现。 ## 工作原理 (简述) 该键盘是一款基于 SONiX 的设备 (USB VID `0x0C45`)。此工具通过有线 USB 连接，使用 64 字节的 HID 特征报告事务 (`START → preamble → data → FINISH`)，与其供应商 HID **控制接口** (`0xFF13`) 进行通信。设置会被保存到键盘的板载内存中。 更多文档： - [`docs/protocol.md`](docs/protocol.md) — 字节级 HID 协议 - [`docs/DISCOVERY-LOG.md`](docs/DISCOVERY-LOG.md) — 逆向工程过程 (路径、阻碍和经验教训) - [`docs/REMAP-RESEARCH.md`](docs/REMAP-RESEARCH.md) — 按键重映射的开放性问题 - [`docs/USB-CAPTURE-GUIDE.md`](docs/USB-CAPTURE-GUIDE.md) — 捕获 → `ak820 replay` 工作流 ## 开发 安装开发工具并运行测试套件： ``` pip install -e ".[dev]" pytest ``` 大多数测试是纯软件测试，可在任何地方运行。键盘映射测试需要键盘的布局文件，该文件是从专有的 Windows 安装程序中提取的，并且**不会**在此处分发 — 因此 在全新克隆的代码库上，它们会**自动跳过**。要运行它们，请在本地将安装程序解压到 `extracted/app/` (参见 [`docs/protocol.md`](docs/protocol.md))。 ## 鸣谢 协议细节是在以下社区项目的帮助下完成逆向工程的： - [gohv/EPOMAKER-Ajazz-AK820-Pro](https://github.com/gohv/EPOMAKER-Ajazz-AK820-Pro) - [TaxMachine/ajazz-keyboard-software-linux](https://github.com/TaxMachine/ajazz-keyboard-software-linux) - [Aiacos/ajazz-control-center](https://github.com/Aiacos/ajazz-control-center) - [wsclx/ak820pro-modder](https://github.com/wsclx/ak820pro-modder) ## 许可证 [MIT](LICENSE) © gusleig

标签：HID, Python, 外设配置, 客制化键盘, 文档结构分析, 无后门, 逆向工具