MemoryHazy313/madlions-configurator

# MADLIONS 60 配置器   一款桌面应用程序，用于配置 **MADLIONS 60% Hall Effect** 键盘的 **灯光和霍尔效应性能** —— 每个按键的 RGB 灯光、动画（内置和自定义）、激活/快速触发/ SOCD 调校，以及配置文件 —— 作为官方网页配置器的替代方案。按键重映射、Fn 层和宏故意留给了官方软件（见 [它不做什么，以及为什么](#what-it-doesnt-do-and-why)）。 它通过 USB HID 直接与键盘通信，并读取板子的当前状态，以便界面反映设备上实际存储的内容。  ## 为什么存在这个 我购买了一块 MADLIONS 60% Hall Effect 板，非常喜欢硬件，但库存的灯光选项感觉有限——只有几个预设效果，没有真正的方法来设计自己的或调整霍尔效应行为，以满足我的需求。所以我逆向工程了键盘的 HID 协议（通过观察官方网页应用程序发送的流量），并构建了一个配置器，它实际上是我想要的：真正的按键控制、合适的动画编辑器、完整的霍尔效应调校，以及从板子读取的设置。它在这里共享，以防其他拥有相同键盘的人也想得到同样的东西。 ## 功能 - **灯光** —— 每个按键的颜色，带有实时选择器、色卡、亮度和一个引导的 **白平衡** 校准器，该校准器将板子填充为白色并实时调整 R/G/B。 - **效果** —— 15 个内置动画加上您创建的任何自定义动画。 - **编辑器** —— 在时间轴上绘制自己的关键帧动画：拖动绘制、点击切换、每帧保持/缓动，以及准确的内置预览、多帧选择以进行批量编辑、撤销/重做和连续自动保存，以便未保存的工作在崩溃后仍然存在。 - **性能（霍尔效应）** —— 每个按键的激活深度、快速触发、性能切换（交换 WASD / Win 锁定 / Mac / NKRO / 假触控）和 **SOCD / 快速点击**（例如 A+D 用于侧滑）。所有这些在页面打开时都从板子读取。 - **配置文件** —— 快照和恢复完整的外观（灯光、白平衡等）。 - **按键映射向导** —— 固件的槽位顺序不是视觉顺序；每个板子映射一次。 - **最小化到托盘** —— 关闭窗口会继续播放动画（应用程序在系统托盘中继续运行，就像 Discord 或 Steam 一样）；从托盘菜单完全退出。 自定义动画和配置文件存储在每个用户的 `~/.madlions/` 下，永远不会离开您的机器——它们不是应用程序或此存储库的一部分。 ## 它不做什么，以及为什么 **按键重映射、Fn 层和宏在此未实现。** 此项目始于一个目标——添加库存软件缺乏的自定义灯光和动画——并扩展到涵盖霍尔效应设置。重映射是另一回事：重新发明它将是一大堆脆弱的工作，而好处却很小，因为官方网页应用程序已经做得很好。 更重要的是，您使用两者不会失去任何东西。这些绑定位于键盘的 **板载闪存** 中，此应用程序 **永远不会写入该区域**——因此，在官方软件中设置的任何重映射、Fn 层或宏都保持不变，并与您在此设置的灯光和性能共存。在此应用程序中设置您的颜色和霍尔效应感觉；在官方网页应用程序中设置您的按键绑定；它们不会冲突。 **不要同时运行此应用程序和官方网页应用程序。** 一次只能有一个程序通过 USB 持有键盘。在打开另一个之前关闭一个。每个程序在连接时都会读取板子的当前状态，因此您在一个中做出的更改在切换后会在另一个中显示。 ## 支持的硬件 开发和验证针对： - **MADLIONS MAD60** — 60% 霍尔效应键盘，USB **VID `0x373B`，PID `0x1054`**，61 个按键（底部行：Ctrl，Win，Alt，空格，Alt，菜单，Ctrl，Fn）。 所有测量都在一个物理单元上进行。同一型号的不同固件版本很可能也能工作，但每个按键索引映射是在真实硬件上测量的。**其他 MADLIONS 型号可能使用不同的 USB ID 或协议，并且不能保证**——见下文 [报告问题](#reporting-issues--other-models)。 在 Windows 中检查您拥有的内容：设备管理器 → 您的键盘 → 属性 → 详细信息 → "硬件 Ids"。如果显示 `VID_373B&PID_1054`，则是支持的板子。 ## 安装和运行 **最简单（Windows，无需 Python）：** 从 [发布](../../releases) 页面下载 `MADLIONS60.exe` 并运行它。需要 Edge WebView2 运行时；它在 Windows 10/11 上预先安装。 **从源代码：** ``` pip install -r requirements.txt python main.py ``` 或双击 `MADLIONS.bat`（使用 `MADLIONS-debug.bat` 以查看用于故障排除的控制台）。 如果 `hidapi` 在 Windows 上无法打开设备，请使用 [Zadig](https://zadig.akeo.ie/) 将 WinUSB 驱动程序分配给键盘的 RGB/配置接口。 ## 首次设置 1. **按键映射**（设置 > "运行映射向导"）——教应用程序您的板子槽位顺序，以便按键控制正确。保存到 `~/.madlions/`。 2. **白平衡**（设置 > "校准白平衡"）——如果白色看起来像青色或粉色，调整 R/G/B 直到它读取中性。平衡的白比全功率要暗；这是 LED 的属性，而不是错误。 用户数据（校准、按键映射、配置文件、自定义动画、编辑器自动保存）位于 `~/.madlions/`。 ## 它是如何工作的 - `device/` 是唯一构建原始 HID 报告字节的层；其他所有内容都通过它传递。 - 动画在主机上渲染，并逐帧流到板子上，因此它们与编辑器允许的（并且当应用程序关闭时停止——因此最小化到托盘）一样丰富。 - 应用程序使用相同命令的读取变体从板子读取设置，因此用户界面显示键盘的真实状态，包括在供应商软件中做出的更改。 - 它只发送文档化的配置报告——永远不会写入固件、引导加载程序或闪存区域。按键重映射/ Fn 层/宏留给官方软件（见 [它不做什么，以及为什么](#what-it-doesnt-do-and-why)）。 ## 报告问题/其他型号 欢迎提交错误报告和 "请让它在我的 MADLIONS 上工作" 的请求——打开 [问题](../../issues)。由于协议是针对每个型号逆向工程的，因此使不同型号工作通常需要从该硬件捕获。以下是需要包含的有用信息： - 您确切的键盘型号及其 USB `VID:PID`（见 [支持的硬件](#supported-hardware)）。 - 您尝试了什么以及发生了什么（以及您期望什么）。 - 是否在相同的机器上运行了官方软件。 - 对于新型号：`tools/` 中的捕获工具（一个 WebHID 记录器加一个本地信标）可以记录官方网页应用程序发送的协议；请参阅这些文件的注释。 ## 构建独立的 .exe 包含 PyInstaller 规范： ``` pip install pyinstaller pyinstaller madlions.spec ``` 将单文件可执行文件写入 `dist/MADLIONS60.exe`。它捆绑了网页前端、`hidapi` 本地库、pywebview WebView2 加载器以及托盘图标；目标机器仍然需要 Edge WebView2 运行时（在 Windows 10/11 上预先安装）。 ## 项目布局 ``` device/ HID protocol + connect/read/write (the only layer that builds report bytes) engine/ models, animation runtime, profile/animation storage, layout ui/ web frontend (HTML/CSS/JS) served in a pywebview window tools/ reverse-engineering capture helpers (not needed to run the app) bridge.py pywebview js_api: the methods the frontend calls into Python main.py wires it together, single-instance + tray ``` ## 技术栈 Python 3.11+，`hidapi` 用于 USB HID，`pywebview`（Edge WebView2）用于窗口，`pystray` + `Pillow` 用于托盘图标，PyInstaller 用于打包。 ## 致谢 在 Claude 的帮助下开发，Anthropic 的 AI 编码助手。 ## 许可证 根据 **PolyForm Noncommercial License 1.0.0** 许可——见 [`LICENSE`](LICENSE）。您可以使用、修改和共享它，用于任何 **非商业** 目的（个人使用、爱好项目、研究、教育和类似用途）。商业用途——包括出售或收费——是不允许的。在任何副本中保留版权声明。 ## 免责声明 与 MADLIONS 无关、未经授权或获得支持。提供 "按原样"，不提供任何类型的保证；作者不对使用它而产生的任何损害或损失负责。 此应用程序仅向键盘发送 **文档化的配置报告**（灯光和霍尔效应设置）。它永远不会写入固件、引导加载程序或闪存区域，因此它不能像不良固件闪存那样损坏设备——最坏的情况是错误的设置，您可以在此处或供应商软件中更改它们。即使如此，使用它仍存在风险。

标签：Hall Effect, MADLIONS 60%, PolyForm Noncommercial 1.0.0, RGB灯光, USB HID, Windows平台, 开源许可, 桌面应用程序, 用户界面, 硬件逆向工程, 自定义动画, 逆向工具, 键盘协议, 键盘宏, 键盘性能调优, 键盘映射, 键盘灯光编辑, 键盘配置