MrSchrodingers/fizz-rgb

# d "fizz" mean? It might be a verb or noun. If it's a tool, it might not be translated.

[](https://github.com/MrSchrodingers/fizz-rgb/actions/workflows/ci.yml) [](https://github.com/MrSchrodingers/fizz-rgb/releases/latest) [](LICENSE) [](package.json) [](tsconfig.base.json) [](packages) [](https://www.redragonzone.com/products/redragon-fizz-pro) 这是针对 **Redragon Fizz K617**（60% 有线机械键盘，USB `258a:0049`，使用 Sinowealth SH68F90A MCU）的 Linux RGB 控制器。填补了仅 Windows 平台 Redragon 软件留下的空白。

## 亮点 - **守护进程 + CLI + Electron 图形界面**，内含键盘的 3D 模型。 - **8 种固件原生效果**，通过 USB 抓包逆向工程获得（彩虹、贪吃蛇、瀑布、正弦波、星光闪烁、彩虹花开、滚轮、静态）。 - **通过 Sinodragon 协议进行逐键直接控制**（382 字节 HID 功能报告）。 - **30+ 种主机端流式动画与效果**，以 30 fps 运行——矩阵雨、烟花、DVD 弹球、心率心电图、均衡器、Rule 30、CPU 温度热图、《我的世界》昼夜与永恒云循环、水族馆——加上对你的打字做出反应的响应效果（**涟漪**、**火花**）、一个**二进制 BCD 时钟**，以及经典的 **Doom PSX 火焰**——外加标准的 `blink`、`chase`、`wave`、`typewriter`、`marquee`、`flag-wave` 模式。 - **20+ 款可在物理键盘上玩的游戏**——fizzd 通过一个 udev 规则并行读取 `/dev/input/event*`，因此按键驱动游戏，同时正常的打字依然有效。街机游戏：**Pong** (1P/2P)、**贪吃蛇**、**打砖块**、**吃豆人**、**太空侵略者**、**超级马里奥**、**打地鼠**、**弹幕地狱**、**直线加速赛**、**青蛙过河**、**Flappy Bird** (空格键跳跃)、**Genius/Simon**。更深入的游戏：一个**实体版 Wordle**（字母键亮绿色/黄色/灰色）、一个 **Doom 光线投射 FPS 游戏**、回合制 roguelite 游戏 **Keyboard Crawl**、一个**被诅咒键盘**的传染病生存游戏、一个**闲置花园**，以及一个**简化版《杀戮尖塔》的卡牌构筑游戏**——其中几个带有难度菜单（1-5 级）和磁盘持久化的 meta 进度。 - **60+ 个内置预设**，涵盖 `theme`、`brasil`、`productivity`、`pattern`、`gradient`、`shape`、`word`、`game`，外加用户保存的预设。 - **全局色调选择器**——原始/鲜艳/霓虹/粉彩/单色 风格芯片 + 0.4×–2.0× 饱和度滑块，同样影响有状态动画（守护进程遵守 `pattern.vibrancy` 设置）。 - **动态缩略图**，实时模拟每个预设的实际画面。 - **撤销/重做 (Ctrl+Z)**、拖拽绘制、带有 15 种精选调色板的颜色历史、状态栏、在 1400px 宽度以下会折叠的侧边栏。 - **持久化**：配置文件存于 `~/.config/fizz/profiles.json`，逐键模式存储在浏览器 `localStorage` 中，支持通过 `.fizzpattern.json` 文件进行可移植的导出/导入。 - **系统托盘**、开机自动恢复、键盘重连后自动恢复、作为发布资源的 AppImage。 - **140/140 项 vitest 测试**，覆盖守护进程、CLI、核心和图形界面。 ## 架构 ``` ┌─────────────┐ JSON-RPC 2.0 ┌────────────┐ HID feature reports ┌──────────┐ │ fizz CLI │ ───────────▶ │ fizzd │ ────────────────────▶│ K617 │ └─────────────┘ Unix socket │ (daemon) │ 58a:0049 │ keyboard │ ┌─────────────┐ │ │ └──────────┘ │ fizz-gui │ ───────────▶ │ EffectEng. │ │ (Electron) │ │ ProfileMgr │ └─────────────┘ └────────────┘ ``` - `@fizz/core` — 共享类型、协议编码器、预设、动画。 - `fizzd` — 唯一持有 HID 句柄的进程；运行游戏引擎。 - `fizz` — 通过 IPC 套接字连接的轻量级 CLI 客户端。 - `fizz-gui` — Electron + React 19 + Three.js (R3F + drei) + Tailwind 4 + Zustand。 完整设计请参阅 [`docs/design/specs/2026-05-18-fizz-rgb-controller-design.md`](docs/design/specs/2026-05-18-fizz-rgb-controller-design.md)，线路协议详情请参阅 [`docs/reverse-engineering/protocol.md`](docs/reverse-engineering/protocol.md)。 ## 要求 - Linux（已在 **Fedora 43** 上测试；其他发行版可能也可用）。 - Node.js **22+** 和 npm 10+。 - 一个 **Redragon Fizz K617** (USB `258a:0049`)。 - `hidraw` 内核模块（任何主流发行版默认已启用）。 ## 安装 ### 一键“简易模式”（CLI + 守护进程 + GUI + 自启动） ``` git clone https://github.com/MrSchrodingers/fizz-rgb.git /var/www/fizz-rgb cd /var/www/fizz-rgb ./tools/install.sh --easy # everything: builds AppImage, installs autostart for daemon + GUI tray fizz status # sanity check ``` 使用 `--easy`，安装程序将： 1. 运行 `npm install && npm run build`。 2. 将 `fizz` 和 `fizzd` 符号链接到 `~/.local/bin`。 3. 安装 systemd 用户单元并**启用它** (`systemctl --user enable --now fizzd`)。 4. 安装 udev 规则（需要 `sudo`）。 5. 构建 Electron GUI 的 **AppImage** 并将其复制到 `~/.local/bin/fizz-rgb.AppImage`。 6. 在应用程序菜单中安装应用图标和 `Fizz RGB` 条目。 7. 放置一个 `~/.config/autostart/fizz-rgb.desktop` 文件，以便 GUI 在每次登录时**隐藏在托盘中启动**。 安装后请拔插一次键盘。 ### 最小化安装（仅 CLI + 守护进程，无 GUI） ``` ./tools/install.sh # CLI + daemon, auto-enables systemd unit fizz status fizz effect run fw-rainbow ``` ### 可用标志 | 标志 | 效果 | | ------------------- | -------------------------------------------------------------------------------------------- | | _(无)_ | 构建 + 链接二进制文件，安装 systemd 单元 + udev 规则，自动启用守护进程。 | | `--easy` | 隐含 `--with-gui` 和 `--autostart-gui`。推荐给终端用户的路径。 | | `--with-gui` | 同时构建 AppImage，安装应用菜单启动器，并刷新图标缓存。 | | `--autostart-gui` | 放置自启动 `.desktop` 条目。需要 `--with-gui`（或已有的 AppImage）。 | | `--no-enable` | 跳过自动的 `systemctl --user enable --now fizzd`。如果你想手动控制则使用此标志。 | ### GUI（开发 / 打包） ``` npm run dev -w fizz-gui # development with hot reload npm run build:appimage -w fizz-gui # produce a portable AppImage manually ~/.local/bin/fizz-rgb.AppImage --hidden # launch minimized to tray (used by autostart) ``` ## CLI 速查表 ``` fizz status # device + active effect + daemon fizz set # solid color (#RRGGBB or named) fizz effect list fizz effect run [--speed N] [--brightness N] [--color C] [--direction left|right] fizz effect stop fizz profile list fizz profile save --effect [opts] fizz profile activate fizz profile delete fizz daemon {start|stop|restart|enable|disable|status|logs} ``` ## 固件原生效果 | 效果 | 选项 | | --------------------- | ------------------------------------------------ | | `fw-static` | `--color`（受限调色板） | | `fw-rainbow` | `--speed`, `--brightness`, `--direction` | | `fw-snake` | `--color`, `--speed` | | `fw-sine-wave` | `--speed`, `--brightness` | | `fw-star-twinkle` | `--color`, `--density`, `--speed` | | `fw-rainbow-blossom` | `--speed` | | `fw-waterfall` | `--color`, `--speed` | | `fw-wheel` | `--speed`, `--direction` | 固件效果在断开连接后仍保持（K617 有 8 个出厂烧录的槽位）。 ## 逐键 & 游戏（主机端流式） 逐键自定义模式和 12 种游戏动画在主机上计算，并以 30 fps 流式传输到键盘。它们需要 `fizzd` 运行。它们**不会**持久化到键盘的 NVRAM——当守护进程停止时，键盘将恢复到其上一个固件效果。 使用图形界面来绘制模式、保存用户预设、录制时间轴，或从预设库中选择。 ## 故障排除 | 症状 | 尝试方法 | | ------------------------------------------- | ------------------------------------------------------------------------------------------ | | `fizz status` 显示守护进程离线 | `fizz daemon start`（或 `systemctl --user start fizzd`）。查看日志：`fizz daemon logs --tail 50`。 | | 对 `/dev/hidraw*` 没有权限 | 重新运行 `./tools/install-udev.sh`，然后拔插键盘。 | | 守护进程找不到设备 | `lsusb \| grep 258a` 应显示你的 K617。如果其他进程占用了它：`lsof /dev/hidrawN`。 | | GUI 显示“已断开连接”横幅 | 守护进程未运行，或套接字路径不同。检查 `$XDG_RUNTIME_DIR/fizz.sock`。 | | Three.js `PCFSoftShadowMap` 警告 | 纯属外观问题，drei v10 内部问题——在上游修复前可安全忽略。 | ## 硬件兼容性 | 型号 | USB ID | 状态 | 备注 | | ------------------- | ----------- | ----------------- | ----------------------------------------------------------- | | Redragon Fizz K617 | `258a:0049` | ✅ 完全支持 | 61 键，所有 8 种固件效果 + 逐键 + 游戏已验证。 | | 其他 Redragon 60% | — | ❓ 未知 | 相同 MCU 家族可能有效；欢迎 PR。 | ## 路线图 - 更多预设（城市天际线、交通灯、番茄钟、打字热力图、Tux、运动队）。 - 更多游戏（青蛙过河、打地鼠、Simon Says、小行星、弹球、吃豆人）。 - 图形优化（运动模糊、点击时的粒子效果、更好的按键字体）。 - 可选：PipeWire 音频响应、按应用配置文件自动切换、全局热键循环切换配置文件。 - 远期目标：自定义逐键的 NVRAM 持久化（需要固件转储 + Ghidra）。 ## 文档 - [`docs/design/specs/`](docs/design/) — 架构与设计决策。 - [`docs/design/plans/`](docs/design/) — 实施计划（第一阶段、动画）。 - [`docs/reverse-engineering/protocol.md`](docs/reverse-engineering/protocol.md) — USB 线路协议说明。 ## 安全 要报告安全漏洞，请参阅 [SECURITY.md](SECURITY.md)。**请勿针对安全漏洞提交公开 Issue。** ## 致谢 - [OpenRGB issue #2172](https://gitlab.com/CalcProgrammer1/OpenRGB/-/issues/2172) — 固件效果的初始 USB 抓包。 - [EvanSunde/Sinodragon](https://github.com/EvanSunde/Sinodragon) — SH68F90A MCU 家族的逐键协议参考。 - [carlossless/sinowealth-kb-tool](https://github.com/carlossless/sinowealth-kb-tool) — 固件工具。 ## 许可证 [MIT](LICENSE) © Matheus Munhoz 及 fizz-rgb 贡献者。

标签：3D建模, DNS解析, Electron, GNU通用公共许可证, Linux兼容, Linux应用程序, Minecraft模式, MITM代理, Node.js, Pong游戏, Redragon键盘, RGB灯效, TypeScript, USB协议, 交互式应用, 动画效果, 图形用户界面, 外设软件, 守护进程, 安全插件, 嵌入式控制, 开源项目, 微控制器, 游戏集成, 灯光定制, 灯效预设, 硬件控制, 自动化攻击, 键盘控制器, 键盘驱动