scholzri/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) [](docs/architecture.md) [](#status)  ## 这是什么？ 一个仓库包含两样东西： 1. **完整、开源的 ZMK 固件移植**，适用于 Rainy 75 Pro —— 支持 USB + 蓝牙 LE、 全部 83 个轴体 RGB LED、深度睡眠以及自定义灯光引擎。它可以**无需打开外壳且无需硬件调试器**即可刷入， 并且如果出现任何问题，都有完整的恢复路径。 2. **完整的逆向工程项目** —— 原厂固件（Evision 专有，非 QMK）和 PCB 均从零开始进行逆向工程：识别了 211/211 个固件函数， 追踪了按键/HID 流水线，解码了 OTA 和 VIA 协议，并映射了 GPIO 矩阵 + RGB + BLE 硬件。正是这些工作使得 ZMK 移植成为可能， 并且相关内容已在 [`docs/`](docs/) 中完整记录。 ## 核心亮点 - **运行 ZMK** —— 现代化的开源键盘固件：在 devicetree 中定义键位映射， 通过 USB 刷入，无需专有工具。 - **有线 + 无线** —— USB-C 和蓝牙 LE（HID-over-GATT，设备绑定）。6 键无冲 （ZMK 默认值；可在 config 中启用 NKRO）。*原厂 2.4 GHz 接收器使用的是 专有协议且**未**被移植 —— 请参阅 [已知限制](#known-limitations)。* - **`rainy_rgb` 灯光引擎** —— 一个自定义的、树外的引擎，驱动全部 83 个轴体 WS2812 LED：11 种动态灯效、响应式涟漪/热力图、与帧率无关的速度，以及 *功能性*指示灯（CapsLock、Fn 层高亮、电池电量） —— 请参阅 [docs/rainy-rgb.md](docs/rainy-rgb.md)。 - **安装无需调试器** —— 通过两段式 OTA → mcumgr DFU 路径，利用原厂固件自身的 更新协议刷入 ZMK。只需一条命令：`./install_zmk.sh`。 - **可逆操作** —— `./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 + 蓝牙 LE, 6 键无冲 (可通过 config 启用 NKRO) | | 硬件无线电 | USB-C · BLE · 2.4 GHz 接收器 (2.4 GHz 模式**未**移植) | | 电池 | 2× 3500 mAh 锂聚合物电池 (7000 mAh) | | 原厂固件 | Evision 专有平台 (**非** QMK), VIA V3 | ## 快速入门 | 我想要… | 如何操作 | |------------|-----| | **安装此 ZMK 固件** | `./install_zmk.sh` — 两段式 OTA → mcumgr，无需调试器。完整指南：[INSTALL.md](INSTALL.md)。 | | **恢复至原厂状态** | `./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)。 | | **自定义键位映射 / 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 升级时依然能够保留： - 围绕 Telink 的 BLE controller blob 封装的 **BLE HCI 驱动**（外设 HID-over-GATT） - **USB 设备驱动**（旧版 `usb_dc` API） — HID + CDC-ACM 控制台 - **WS2812 LED 灯带驱动** — PSPI + DMA，中断驱动，负责驱动 83 个轴体 LED - **电池 ADC**、**硬件看门狗**以及**深度睡眠**电源管理 - 带有 mcumgr DFU (USB-CDC) 的 **MCUboot** bootloader，以及看门狗崩溃恢复安全网 - **`rainy_rgb`** — 替代 ZMK 底光的自定义灯光引擎 完整的构建/刷入/引导详细说明：[docs/zmk-firmware.md](docs/zmk-firmware.md) · 灯光引擎：[docs/rainy-rgb.md](docs/rainy-rgb.md)。 ## 已知限制 - **2.4 GHz 接收器** — 原厂 2.4 GHz USB 接收器使用的是专有的 RF 协议， 在此既未进行逆向工程，也未予以实现。此固件**仅支持 USB + BLE**。 - **电池百分比** — 电池 ADC（引脚 / 分压器 / Vref）未在硬件上进行校验， 因此电量测量仅供参考。 - **ANSI 布局** — 实验性，且未在真实硬件上验证过 （[需要帮助](CONTRIBUTING.md#layout-variants-iso--ansi)）。 ## 逆向工程 原厂固件不提供任何源代码。这里的所有内容都是从 flash 转储和 实时探测中恢复出来的。位于 [`docs/`](docs/) 下的逆向实录： | 文档 | 内容 | |----------|----------| | [拆解](docs/teardown.md) | 图文指南：打开外壳、PCB、电池、子板 | | [架构](docs/architecture.md) | MCU、USB 枚举、HID 接口、RGB、电池、连接模式 | | [GPIO 与矩阵](docs/gpio-matrix.md) | 引脚映射（16 列 + 7 行）、扫描方法、时序、键位映射、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/)** — 以持久、交叉链接的参考资料形式编写的发现成果（而非聊天 记录），无论是人类还是智能体都可以在此基础上进行构建。 如果您通过复刻此项目来移植同类主板或添加新功能，这些上下文环境将随 代码库一同转移 —— 只需让 Claude Code 指向它即可开始工作。

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