dot-agi/ry5088-flasher

# ry5088-flasher 用于 **RongYuan RY5088** 磁轴键盘的开源工具和固件 —— 采用 **Artery AT32F405** 主 MCU 和 **Panchip PAN1080** 无线协处理器，由 MonsGeek、Akko 等厂商出货。该项目包含两个部分： - **`flasher/`** — `ry-flash`，一个单一二进制的**原厂固件刷写工具**，带有终端 UI 和可脚本化的 JSON CLI。它通过 USB 恢复官方固件（无需开壳，无需特殊工具），并且是*变体安全*的： 它会读取已连接键盘的 `dev_id`，并且只刷写与该型号匹配的镜像。 - **`firmware/`** — 可编译的 **AT32F405 自定义固件**：在 `common/` 中包含一个共享代码库 （按键扫描、Hall rapid-trigger、WS2812 RGB、flash-config 持久化、厂商协议、可选的 无线功能），通过位于 `firmware/profiles/.toml` 的一个小型 **profile** 针对不同键盘进行专门配置。 `make PROFILE=` 构建该型号的镜像；添加一个主板只需一个 profile —— 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 支持的型号 **刷写工具**兼容 RY5088 平台上的任何 Hall-effect（**HE**）/ TMR 磁轴键盘：**FUN60 / Pro / Max / Ultra**、**FUN68**、**FUN75**、**M1 / M2 / M3 V5**（HE 和 TMR）、**Akko 5075B / 5087B HE**、 **Shine68** 以及其他 `ry5088_*` 主板 —— 通过 `dev_id` 识别（USB PID 被多种型号共用）。 完整表格：[`docs/models.md`](docs/models.md)。 **自定义固件**提供了 **Fun60 Ultra**（`dev_id 2307`）的 profile 作为参考；其他型号 可以通过贡献 profile 来添加（`make -C firmware models` 会列出现有的型号）—— 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 快速开始 **刷写原厂固件**（通过 USB 插入键盘，关闭厂商应用）： ``` cd flasher cargo build --release # needs libhidapi (brew install hidapi / libhidapi-dev) ./target/release/ry-flash # interactive TUI — detect, confirm, flash # 或 headless / scriptable: ./target/release/ry-flash --auto --arm # detect + flash the matching stock image (auto-downloads if needed) ./target/release/ry-flash --detect --json # machine-readable device info ``` **构建自定义固件**（需要 `arm-none-eabi-gcc` 和 Artery BSP —— 参见 [`firmware/README.md`](firmware/README.md)）： ``` cd firmware make PROFILE=2307 # build the Fun60 Ultra image -> build/2307/ry5088_2307.bin make test # host-side unit tests (no ARM toolchain / BSP needed) make check # validate every board profile ``` ## 添加你的键盘 该平台和厂商协议在所有这些主板上都是共享的，因此支持新型号主要是 *数据*工作：它的 `dev_id`、矩阵几何结构、keymap、LED 映射和轴体参数 —— 一个 `profiles/.toml`。 使用 Claude Code 时，**`/re-tmr`** 技能可以驱动整个流程（检测 → 获取原厂固件 → 分析 → 起草 profile → 构建）。刷写是可恢复的（仅限 app-slot；刷写工具始终会恢复原厂固件），因此 可以安全地进行实验。完整操作手册：[`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 文档 ## 状态与安全性 刷写工具是成熟且经过验证的组件。自定义固件可以构建并通过主机测试，但**尚未** 完成硬件测试 —— 请将其视为实验性内容。刷写是可恢复的：传输失败会将 主板留在其 bootloader 中，而刷写工具始终可以恢复原厂固件。进入 bootloader 会清除 app 配置（可在厂商应用中重新设置）；按键级别的 Hall 校准会被保留。 ## 相关项目 这些磁轴键盘的开源固件**正在**构建中 —— 在此向他们致敬： - **[libhmk](https://github.com/peppapighs/libhmk)** — 一个成熟的开源 **Hall-effect 键盘固件**，已经可以在 **AT32F405** 上运行，并实现了本仓库固件仅做了存根的高级模式：Dynamic Keystroke、Null Bind（SOCD / Snap-Tap）、Tap-Hold、Toggle、Rapid Trigger、8 kHz，外加一个网页配置器。**如果你想要一个功能完备的*替代性*固件，请从这里开始。** - **[QMK PR #25215](https://github.com/qmk/qmk_firmware/pull/25215)** + **[qmk-arterytek](https://github.com/qmk-arterytek)** 组织 —— 将 Artery **AT32F402/F405** MCU 引入 QMK（ChibiOS 移植、UF2 bootloader、KiCad 库）。 - [echtzeit-solutions/monsgeek-akko-linux](https://github.com/echtzeit-solutions/monsgeek-akko-linux) — 用于原厂固件的 Linux **驱动**。 - [RieGan/rongyuan-kb-software](https://github.com/RieGan/rongyuan-kb-software) · [noaione/rongyuan-software](https://github.com/noaione/rongyuan-software) — 逆向工程的 RongYuan 配置**软件**。 **本项目的定位。** 上述项目*替换*了固件（并带来了它们自己的配置器）。本项目是 它们的补充：它可以**通过 USB 刷写和恢复官方原厂固件** —— 无需厂商应用，在 446 个主板上保证变体安全，完全可恢复 —— 外加其背后的 cloud-API / `dev_id` / 主板目录逆向工程。内置的 自定义固件是一个**兼容原厂协议的参考**（仍可从厂商应用中进行配置）；如果要在 同一 MCU 上使用功能完备的开源固件，请使用 **libhmk**。 ## 许可证 MIT —— 参见 [`LICENSE`](LICENSE)。Artery AT32F402_405 固件库（在构建固件时单独获取） 受其自身许可证的约束；参见 `firmware/THIRD-PARTY-NOTICES.md`。

标签：Python安全, Rust, USB, 可视化界面, 固件, 客户端加密, 嵌入式, 硬件工具, 网络流量审计, 键盘