GeneralD/cyberboard-cli

# cyberboard-cli

      一个协议知识库 —— 以及计划中的 CLI —— 用于**无需官方 AM Master 应用程序**即可编写 **AngryMiao CyberBoard R4** 的配置。 目标：将你的 keymap 和 LED 显示作为**独立的、可版本控制的 源**进行管理，并直接从命令行将其写入键盘 —— 稳定可靠， 没有 AM Master 那种不稳定的连接。 ## 为什么 官方的设置存在三个问题，本项目正好解决了它们： - **Keymap 和 LED 存放在同一个 JSON 文件中。** 应用社区的 LED 动画 会覆盖你的 keymap。本项目将它们分开，仅在 构建时才将它们重新组合，因此“仅替换 LED”是安全的。 - **AM Master 的连接不稳定** —— 写入是成功还是失败完全是随机的。 现已查明根本原因（参见协议文档），并且可以在 CLI 端进行修复。 - **它不够灵活** —— 没有部分更新，不支持脚本，没有差异对比。 ## 我们已知的内容（主要发现） 所有内容均逆向工程自 AM Master 1.3.7（在本地反编译；反编译的 源代码**并未**在此处重新分发 —— 参见*法律声明*）： - **传输方式是 USB CDC serial (pyserial) @ 9600 波特率。** HID 仅用于检测。 - **配置路径没有加密** —— 应用程序中的 AES 只是 PyInstaller 的字节码混淆。 - **帧固定为 64 字节：** `[0]` 类别，`[1]` 子命令， `[2..62]` 负载，`[63]` **CRC-8** (多项式 `0x07`)。 - **LED 模型：** `frames` = 40×5 = 200 像素的顶部显示屏；`keyframes` = 90 个独立按键背光。槽位 1/2/3 = 页面 5/6/7。*（经验证： 活动页面总是严格打包为精确的 200 像素 / 90 像素 —— 参见 [`_re/verify_encoding.py`](_re/verify_encoding.py)。）* - **发送序列和完整的命令表** 记录在[`.claude/rules/30-write-protocol.md`](.claude/rules/30-write-protocol.md)中。 ## 仓库结构 | 路径 | 内容 | |---|---| | [`.claude/rules/`](.claude/rules/) | 协议和 schema 知识库（日语）—— 从 `00-overview.md` 开始阅读 | | `.claude/rules/30-write-protocol.md` | 权威的写入协议规范（传输、帧、CRC、命令表、发送顺序） | | [`_re/verify_encoding.py`](_re/verify_encoding.py) | 独立的编码器，重新推导字节打包并根据真实的配置 JSON 进行检查（无需设备） | | `_re/zscan.py` | 纯 Python 编写的 zlib 暴力扫描器，用于首次静态分析阶段 | ## 路线图 - **M0 — 协议分析** ✅ 已反编译；已根据真实数据验证编码。 剩余工作：实时 serial 捕获以确认传输字节。 - **M1 — 完整写入**，通过逆向工程得出的序列写入已知的良好配置（合并器的输出）。 - **M2 — 回读 + 差异对比**以进行验证。 - **M3 — 自定义 schema → IR 构建**（保持 keymap / LED 独立）。 - **M4 — 部分写入**（仅 LED 插槽）+ 连接强化。 ## 法律声明 这是一个独立的互操作性项目。此逆向工程是 在本地拥有的 AM Master 副本上进行的，唯一目的是与 作者拥有的硬件进行互操作。**供应商的应用程序、其安装程序、提取的 字节码以及反编译的源代码均被刻意排除在此仓库之外** （参见 `.gitignore`）；仅发布原创的分析和自主开发的工具。 所有商标均属于其各自的所有者。“AngryMiao”和“CyberBoard” 是 AngryMiao 的商标。 ## 鸣谢 - [`angrymiao-cyberboard-config-merger`](https://github.com/GeneralD/angrymiao-cyberboard-config-merger) 和 [`miaomerge`](https://github.com/GeneralD/miaomerge) —— 相关的配套工具， 用于将 LED 动画合并/复合为可写入的 JSON（写入仍然依赖于 AM Master；这正是本项目要填补的空白）。

标签：USB通信, 串口通信, 协议逆向, 文档结构分析, 硬件工具, 蓝牙键盘配置, 逆向工具