adventsundaysliminess908/rainy75-zmk

# Wobkey Rainy 75 Pro — 开源 ZMK 固件与逆向工程 适用于 Wobkey Rainy 75 Pro (ISO DE) 的开源 **[ZMK](https://zmk.dev) 固件**， 外加一份关于其原厂固件和硬件的完整**逆向工程报告** — 即被多款客制化键盘共享的 Telink TLSR9511 (B91, RISC-V) 平台。 [](LICENSE) [](https://zmk.dev) [-orange)](docs/architecture.md) [](#status)  ## 这是什么？ 一个存储库包含两样东西： 1. **一个完整、开源的 ZMK 固件移植**，适用于 Rainy 75 Pro — 支持 USB + Bluetooth LE， 全部 83 个轴体 RGB LED，深度睡眠，以及自定义灯效引擎。它可以**无需打开外壳且无需硬件调试器**进行刷写，并且如果出现任何问题，有完整的恢复路径。 2. **一个完整的逆向工程项目** — 从零开始对原厂固件（Evision 专有，非 QMK）和 PCB 进行逆向工程：识别了 211/211 个固件函数，追踪了按键/HID 流水线，解码了 OTA 和 VIA 协议，并映射了 GPIO 矩阵 + RGB + BLE 硬件。正是这项工作使得 ZMK 移植成为可能，且全部记录在 [`docs/`](docs/) 下。 ## 适用人群 首先说明实际情况 — 这是一个**面向爱好者、自己动手构建**的项目，而不是一键刷写工具： - **从源码构建。** 没有预编译的下载：该固件链接了一个无法重新分发的 Telink 专有 BLE blob，因此每个人都在本地构建（构建过程会自动为你获取该 blob）。需要配置真正的 Zephyr 工具链 — Zephyr SDK 0.17.0 + west；详见 [INSTALL.md](INSTALL.md#4-build-from-source)。 - **仅限 Linux。** 安装/恢复辅助脚本是 bash + [`mcumgr`](https://github.com/apache/mynewt-mcumgr-cli) (`/dev/ttyACM*`, udev 规则)。目前暂不支持 macOS/Windows。 - **熟悉终端操作。** 你需要构建、安装 `mcumgr`、添加 udev 规则并运行刷写脚本 — 没有 GUI。 - **它会取代原厂体验。** 不支持 VIA — 使用 **ZMK Studio** 进行重映射（通过蓝牙，在 Chrome/Edge 中）。没有 **2.4 GHz dongle**（仅限 USB + BLE）。默认支持 6 键无冲。 - **存在真实风险。** 错误的刷写可能会导致键盘需要**硬件**恢复（需要在 SWS 焊盘上连接 Telink 烧录板）。请保留好你的原厂镜像。风险自负。 不感兴趣？[逆向工程报告](#reverse-engineering) 本身也非常值得一读。 ## 亮点 - **运行 ZMK** — 现代化的开源键盘固件：在 devicetree 中定义你的 keymap，通过 USB 刷写，无需专有工具。 - **有线 + 无线** — USB-C 和 Bluetooth LE（HID-over-GATT，绑定）。6 键无冲 （ZMK 默认值；可在 config 中启用 NKRO）。*原厂 2.4 GHz dongle 使用的是专有协议，**未**进行移植 — 详见 [已知限制](#known-limitations)。* - **`rainy_rgb` 灯效引擎** — 一个自定义的树外引擎，驱动全部 83 个轴体 WS2812 LED：11 种动画效果、响应式涟漪/热力图、独立于 FPS 的速度，以及*功能性*指示灯（CapsLock、Fn 层高亮、电池电量计） — 详见 [docs/rainy-rgb.md](docs/rainy-rgb.md)。 - **安装无需调试器** — 构建镜像后，两阶段的 OTA → mcumgr DFU 路径会利用原厂固件自身的更新协议通过 `./install_zmk.sh` 刷入 ZMK（无需打开外壳，无需硬件编程器）。 - **可逆操作** — `./restore_stock.sh` 可还原原始固件。 - **深度睡眠** — 约 µA 级别保持电流，支持按键唤醒，实现真实的无线电池续航。 - **完全逆向工程** — 命名了 211/211 个原厂固件函数；记录了硬件、协议和平台，方便其他人为兄弟型号进行移植。 ## 图库 | | | |---|---| | 
*主板 — TLSR9511 (B91)* | 
*SWS / GND / VCC 恢复焊盘* | | 
*Telink EVK 恢复接线* | 
*`rainy_rgb` 轴体灯效* | ## 基本规格 | 属性 | 参数 | |----------|-------| | MCU | **Telink TLSR9511** (B91 系列), QFN56, RISC-V | | CPU 核心 | Andes D25F — RV32IMACF + Andes V5 扩展 | | Flash / SRAM | 1 MB / 256 KB | | USB VID:PID | `320F:5055` (原厂) | | 布局 | 75% ISO, 83 键 | | 矩阵 | 8×16 (16 列 + 7 行), 列到行扫描 | | RGB | **83** 个轴体 WS2812 — PB7 (PSPI MOSI), DMA ch4, ~6 MHz | | 连接方式 (本固件) | USB-C + Bluetooth LE, 6 键无冲 (可通过 config 启用 NKRO) | | 硬件无线电 | USB-C · BLE · 2.4 GHz dongle (2.4 GHz 模式**未**移植) | | 电池 | 2× 3500 mAh 锂聚合物电池 (7000 mAh) | | 原厂固件 | Evision 专有平台 (**非** QMK), VIA V3 | ## 快速入门 | 我想… | 如何操作 | |------------|-----| | **安装此 ZMK 固件** | `./install_zmk.sh` — 两阶段 OTA → mcumgr，无需调试器。完整指南：[INSTALL.md](INSTALL.md)。 | | **使用它 — 控制、蓝牙、Studio** | [docs/usage.md](docs/usage.md) — Fn 层、BT 配置文件 + 重置、通过 ZMK Studio 实时编辑 keymap。 | | **恢复至原厂** | `./restore_stock.sh` — 详见 [INSTALL.md](INSTALL.md#3-go-back-to-stock)。 | | **从源码构建** | `./build.sh -a` (Zephyr SDK 0.17.0 + west)。详见 [INSTALL.md](INSTALL.md#4-build-from-source)。 | | **恢复变砖的键盘** | 通过 SWS 焊盘连接 Telink 烧录板 — [docs/recovery.md](docs/recovery.md)。 | | **打开外壳 / 维护电池** | 图文拆解指南 — [docs/teardown.md](docs/teardown.md)。 | | **自定义 keymap / RGB** | 编辑 `zmk/boards/rainy75/rainy75.keymap`；RGB 控制详见 [docs/rainy-rgb.md](docs/rainy-rgb.md)。 | | **使用 ANSI 布局** | 使用 `-DCONFIG_RAINY75_ANSI=y` 构建 — 实验/未测试，详见 [INSTALL.md](INSTALL.md#ansi-layout-experimental-untested)。 | | **贡献代码** | [CONTRIBUTING.md](CONTRIBUTING.md)。 | ## ZMK 固件 [`zmk/`](zmk/) 下的 Zephyr 模块提供了 Rainy 75 所需但尚未合入上游的所有内容 — 以树外驱动程序编写，因此即使 ZMK 升级也能继续使用： - **BLE HCI 驱动** 围绕 Telink 的 BLE 控制器 blob（外设 HID-over-GATT） - **USB 设备驱动**（旧版 `usb_dc` API）— HID + CDC-ACM 控制台 - **WS2812 LED 灯带驱动** — PSPI + DMA，中断驱动，驱动 83 个轴体 LED - **电池 ADC**，**硬件看门狗**，以及**深度睡眠**电源管理 - **MCUboot** bootloader，支持 mcumgr DFU (USB-CDC) 并带有看门狗崩溃恢复安全网 - **`rainy_rgb`** — 取代 ZMK underglow 的自定义灯效引擎 完整的构建/刷写/调试详情：[docs/zmk-firmware.md](docs/zmk-firmware.md) · 灯效引擎：[docs/rainy-rgb.md](docs/rainy-rgb.md)。 ## 已知限制 - **2.4 GHz dongle** — 原厂的 2.4 GHz USB dongle 使用专有 RF 协议，此处并未对其进行逆向工程或实现。此固件**仅支持 USB + BLE**。 - **电池百分比** — 电池 ADC（引脚 / 分压 / Vref）未经过硬件验证，因此电量计仅为近似值。 - **ANSI 布局** — 实验性且未在真实硬件上验证 （[寻求帮助](CONTRIBUTING.md#layout-variants-iso--ansi)）。 ## 逆向工程 原厂固件不提供源码。这里的所有内容都是从 flash dump 和实时探测中恢复的。[`docs/`](docs/) 下的报告： | 文档 | 内容 | |----------|----------| | [拆解](docs/teardown.md) | 图文指南：打开外壳、PCB、电池、子板 | | [架构](docs/architecture.md) | MCU、USB 枚举、HID 接口、RGB、电池、连接模式 | | [GPIO 与矩阵](docs/gpio-matrix.md) | 引脚映射（16 列 + 7 行）、扫描方法、时序、keymap、Fn 组合键 | | [GPIO 引脚分配](docs/gpio-pinout.md) | 完整的引脚分配表 | | [固件分析](docs/firmware-analysis.md) | Ghidra 结果，211 个函数，按键流水线，SRAM 布局 | | [协议](docs/protocols.md) | USB-HID OTA 协议，VIA 协议，HID 探测结果 | | [硬件探测](docs/hardware-probing.md) | 测试焊盘，SWS 调试，逻辑分析仪，Telink 烧录 EVK | | [Evision 平台](docs/evision-platform.md) | 固件生态系统，7+ 款兄弟键盘，GearHub 协议 | | [WOB 驱动](docs/wob-driver-analysis.md) | wobwxe.com JS 分析，HID 协议，flash 映射 | | [资源](docs/resources.md) | SDK 链接，数据手册，参考项目 | ## 存储库布局 ``` zmk/ # Our Zephyr module: board def, out-of-tree drivers, rainy_rgb engine boards/rainy75/ # Board definition (DTS, keymap, defconfig) drivers/ # BLE / USB / LED-strip / battery / watchdog drivers src/rainy_rgb/ # Custom RGB lighting engine lib/ # Telink BLE blob — fetched by fetch_ble_blob.sh, not committed conf/ # Build configuration overlays (app / mcuboot / ota-bridge) patches/ # Small Zephyr patches (applied by west) docs/ # Reverse-engineering writeups + firmware docs reverse/tools/ # USB/HID tools: OTA flasher, VIA probes, stock-firmware extractor, SWS helper fetch_ble_blob.sh # Downloads the (non-redistributable) Telink BLE blob at build time install_zmk.sh # Stock → ZMK (OTA bridge + mcumgr) restore_stock.sh # ZMK → stock build.sh # Build MCUboot + app (+ combined / bridge) ``` ## 使用 Claude Code 构建 此固件和逆向工程工作是使用 [Claude Code](https://claude.com/claude-code)（Anthropic 的智能体编程工具）开发的 — 从 Ghidra 分析和驱动调试到文档和发布本身。该存储库经过精心组织，以便能够高效地继续进行协作： - **[CLAUDE.md](CLAUDE.md)** — Claude Code 会自动加载的项目背景、关键事实和状态，因此它可以随时接续之前的工作继续进行。 - **[docs/](docs/)** — 以持久、交叉链接的参考资料（而非聊天记录）形式编写的发现，人类和智能体都可以在此基础上进行构建。 如果你 fork 此项目以移植兄弟键盘或添加功能，这些上下文也会随存储库一同保留下来 — 只需将 Claude Code 指向它并开始工作即可。 ## 致谢与许可 - 固件基于 [ZMK](https://github.com/zmkfirmware/zmk) (MIT) 和 [Zephyr](https://github.com/zephyrproject-rtos/zephyr) (Apache-2.0) 构建。 - Bluetooth 控制器 blob 是在构建时从 [telink-semi](https://github.com/telink-semi) 获取的 — 它是专有的，在此**未进行重新分发** （详见 [NOTICE](NOTICE)）。 - 本项目自身的代码和文档采用 **Apache-2.0** 许可 （[LICENSE](LICENSE)）。 独立的非官方项目 — 与 Wobkey、Telink 或 Evision 没有任何隶属。 所有商标均归其各自所有者所有。

标签：RISC-V, ZMK固件, 云资产清单, 固件开发, 客制化键盘, 客户端加密, 嵌入式系统, 蓝牙, 逆向工程