Igor-Shpetnyi/womier-sk80-screen

# Womier SK80 — 自定义内置屏幕内容 [](LICENSE)    对机械键盘 **Womier SK80** 内置 TFT 屏幕的 HID 协议进行逆向工程 （并且可能适用于使用相同 SONiX 芯片 `VID_05AC&PID_024F` 的其他键盘）—— 以及一个小巧的 GUI 应用程序，它绕过了原厂 Windows 驱动程序，直接在该屏幕上实时显示动态内容。 而官方驱动只能推送静态 GIF。  *GUI 运行的真实截图 —— “Claude 额度”预设，包含实时数据和事件日志。* | | | |--------------------------------------------|----------------------------------------------------| |  |  | | “时钟”预设 | “Claude 额度”预设（带动画吉祥物） | *（设备上的真实渲染效果 —— 160×90，此处放大了 6 倍以便展示）* ## 为什么开发此项目 官方驱动只能通过其 UI 推送静态 GIF。通过分析 USB 流量 （Wireshark + USBPcap）并解析帧格式和命令握手过程，现在可以在屏幕上绘制 **任何内容** —— 实时时钟、来自任意 API 的数据等 —— 完全不需要驱动程序。 完整的研究过程和所有发现都在 [docs/PROTOCOL.md](docs/PROTOCOL.md) 中。 ## 功能 - **时钟** —— 与每分钟开始同步（测量精度：比 `:00` 晚 +0.03…+0.05 秒）， 可选择颜色（5 种预设选项 + 自定义颜色）。 - **Claude 额度** —— Claude.ai/Code 的 5 小时和每周使用额度，带有奔跑的动画矢量吉祥物（10 帧循环）。数据读取自本地的 Claude Code OAuth token —— 这 **不是** Anthropic API 的额度。智能更新：每 5 分钟进行一次后台检查，仅在数值确实发生变化时才发送到屏幕（以避免对屏幕造成不必要的干扰，并防止无谓地关闭背光）+ 还提供手动检查按钮。 - 打开应用程序时立即自动启动上次活动的预设，并在显示前强制刷新数据。 - 预设 = 一个 `render(epoch_time, scale) -> PIL.Image` 函数；添加新预设用不了 10 行代码（参见 [presets.py](presets.py)）。 - 关闭窗口 (×) 会将应用程序最小化到系统托盘，而不是退出 —— 活动的预设会继续更新屏幕。完全退出（向屏幕发送待机画面）需通过系统托盘右键菜单中的“退出”选项。 关于每项决策的详细说明，请参见 [docs/DECISIONS.md](docs/DECISIONS.md)。 ## 安装 要求： - Windows（协议和 `driver_process_running()` 检查是 Windows 特有的）。 - Python 3.10+。 - 通过 USB 连接的 Womier SK80 键盘 (`VID_05AC&PID_024F`)。 - 官方的 **“Womier-SK80 Driver” 必须完全关闭** —— 包括窗口和系统托盘（否则 HID 设备将被占用，并且 `hid.open_path()` 会抛出错误）。 - **Consolas** 字体（Windows 标准） —— 用于渲染文本。 ``` pip install -r requirements.txt python womier_gui.py ``` 无 GUI 的最简示例 —— [examples/minimal_clock.py](examples/minimal_clock.py)。 ### 构建 standalone .exe (PyInstaller) ``` pip install pyinstaller pyinstaller --onefile --windowed --name WomierSK80 ^ --icon "assets/app_icon.ico" ^ --add-data "assets;assets" ^ --collect-data customtkinter ^ womier_gui.py ``` `--collect-data customtkinter` 是必需的 —— 没有它，构建将无法包含 customtkinter 的内部主题/字体，应用程序在启动时会崩溃。生成的 `.exe` 将出现在 `dist/` 中。 状态文件 `gui_state.json`（上次活动的预设）保存在 `%APPDATA%\WomierSK80\` 中，而不是 `.exe` 旁边，也不在 onefile 构建的临时解压目录中（该目录在退出后会被删除）。辅助调用（`powershell`/`claude` CLI）在运行时没有控制台窗口（`CREATE_NO_WINDOW`），因此在运行 `.exe` 时不会出现任何闪烁。 ## 项目结构 ``` protocol.py низькорівневий HID-протокол (RGB565, кадри, chunking, безпечні шаблони) presets.py реєстр пресетів + рендер кожного (годинник, ліміти Claude, маскот, заставка) claude_limits.py читання лімітів Claude.ai/Code з локального OAuth-токена womier_gui.py GUI-застосунок (customtkinter): вибір пресету, прев'ю, старт/стоп, журнал examples/ мінімальні приклади використання protocol.py без GUI docs/ деталі протоколу та журнал архітектурних рішень ``` ## 安全性与已知限制 - **仅支持 3 帧和 10 帧模板。** 在手动构造的数据包中，即使字节看起来正确，1 帧模式也曾三次导致键盘出现莫名的死机 —— 原因尚未完全查明，因此 `protocol.py` 故意不允许其他帧数 (`ValueError`)。详情见：[docs/PROTOCOL.md](docs/PROTOCOL.md#небезпечні-знахідки-та-чому-вимкнено-1-кадровий-режим)。 - 如果按键卡死 —— 只需重新拔插 USB 线即可恢复工作；在整个研究过程中，这没有造成任何硬件或固件损坏。 - 每次更新屏幕期间，键盘的 RGB 背光会关闭约 3.5 秒（这是固件限制，未找到绕过的方法）。 - 该协议没有官方文档，并且可能因固件版本或使用相同芯片的其他型号而异。使用风险自负。 ## 免责声明 本项目与 Womier 无关，也不附属于 Womier。额度预设中的吉祥物 "Clawd" 是基于广为人知的 Claude Code 吉祥物原型，从零开始绘制的原创矢量同人作品（并非任何 Anthropic 文件的副本）。Claude Code / Claude.ai 是 Anthropic 的商标，此处提及仅用于表示额度预设功能的兼容性。读取额度的方法基于非官方、未公开的 endpoint（参见 [docs/DECISIONS.md, 第 8 条](docs/DECISIONS.md#8-джерело-лімітів-claude--локальний-oauth-токен-не-публічний-api)） 并且可能随时失效，恕不另行通知。 ## 许可证 MIT —— 参见 [LICENSE](LICENSE)。

标签：GUI应用, HID协议, Python, 云资产清单, 外设驱动, 嵌入式屏幕, 无后门, 漏洞挖掘, 逆向工具, 逆向工程