SasiRawr/Keychron-Q6-Max-Battery-Widget

# Keychron Q6 Max 电池小组件 一个 Windows 系统托盘小组件，让你能真实了解 Keychron Q6 Max 的电池电量——这是 Keychron 官方的 Launcher 应用和固件 通过 2.4GHz 接收器根本无法提供的功能。 ## 为什么会有这个项目 Keychron 制造了真正出色的键盘。但他们的软件却是另一回事： 通过其 2.4GHz 的“Keychron Link”接收器连接 Q6 Max 时，**任何地方都 没有电量指示**——Launcher 里没有，Windows 里没有，什么都没有。 唯一的反馈是当电量已经严重不足时，空格键下方的红色 LED 闪烁， 而在此之前，你根本无法分辨电量是 80% 还是 15%。 本项目逆向工程了实际可行的功能，并提供了一个实用的解决方案： - **在 2.4G 模式下**（你大概日常都在使用这个模式——延迟低于 Bluetooth）：后台估算的电池百分比，该模型基于键盘处于活动状态 与空闲/休眠状态的时间比例，以及 Keychron 公布的续航数据计算得出。 - **在 Bluetooth 模式下**（暂时切换到此模式）：读取精确的 电量数值，提取自 Windows 自身的 Bluetooth 设备电量显示所使用的 相同电池数据。 完整的调查过程——包括为什么“显而易见”的方法（即为该键盘适配 已公开文档记录的 Keychron 鼠标电池协议）**不**起作用——都在 [`research/`](research/) 中。简短版本：经协议测试、阅读 Keychron Launcher 的源代码，以及即使通过 USB-C 有线连接 Launcher 的 UI 也不显示电量指示器证实，这款键盘当前的固件 无法通过 2.4G 接收器响应电量查询。Bluetooth 的标准 GATT Battery Service 则可以立即工作。 ## 工作原理 - **2.4G 估算**：每 30 秒轮询一次 Windows 的系统级空闲计时器，并 将流逝的时间分为三个耗电等级（活动/开启 RGB、 关闭背光但未休眠、完全休眠），这基于你键盘实际配置的 超时时间以及 Keychron 公布的 4000mAh Q6 Max 续航数据（开启 RGB 约 80 小时 / 关闭 RGB 约 180 小时）。这是一种启发式估算，并非 真实读数——在托盘提示中已明确标记为估算值。 - **Bluetooth 精确读数**：与其直接与 BLE GATT 交互（在 Windows 上 对于已配对的设备很不稳定），不如读取 Windows 标准 PnP 设备属性（`DEVPKEY_Device_BatteryLevel`），一旦你的键盘通过 Bluetooth 配对，Windows 本身就会填充此属性——这与“设置 → Bluetooth 和设备”中 向你显示的数字完全相同。 - **自我重新校准**：每次你进行真实的 Bluetooth 检查时， 启发式估算都会从该真实值重置，因此 2.4G 模型的估算偏差 不会无限累积。 ## 功能 - 托盘图标根据电池电量直观地填充/颜色编码（绿色 → 琥珀色 → 红色），并带有区分估算值和真实读数的标记 - 右键菜单：当前估算值、按需精确 Bluetooth 检查、 “标记为已充满”、Windows 自启动开关 - 跨重启保持状态（`%LOCALAPPDATA%\Keychron_Q6_Max_BatteryWidget`） - 无第三方服务，无遥测，一切均在本地 ## 安装 ### 选项 A — 预构建 exe 从 [Releases](../../releases) 获取最新的 `.exe` 并运行。无需 安装，也不需要 Python。 ### 选项 B — 从源码运行/构建 ``` git clone cd Keychron_Q6_Max_BatteryWidget pip install -r requirements.txt python main.py ``` 构建你自己的独立 exe： ``` pip install pyinstaller pyinstaller --noconsole --onefile --windowed --icon=assets\app.ico main.py -n "Keychron Q6 Max Battery Widget" ``` exe 将位于 `dist/` 目录中。 ## 配置 续航数据和键盘的休眠/背光超时时间位于 `config.py` 中： ``` BATTERY_CAPACITY_MAH = 4000 HOURS_RGB_ON = 80.0 HOURS_RGB_OFF = 180.0 BACKLIGHT_OFF_TIMEOUT_MINUTES = 10 # match your keyboard's actual setting AUTO_SLEEP_TIMEOUT_MINUTES = 30 # match your keyboard's actual setting ``` 这些是为原装 Q6 Max 调整的。如果你在 Launcher 中更改了键盘的休眠 计时器（高级模式，需要有线连接），请更新这些 数值以匹配——估算的准确性取决于这些数字。其他 4000mAh 或类似的 Keychron Max 系列键盘可能足够接近，可以直接 使用；如果你想要更准确的估算，请检查你型号自身公布的 续航数据。 ## 故障排除 **Windows Defender 隔离了 exe / 将其标记为 `Behavior:Win32/Persistence.A!ml`。** 这是误报——Defender 的 机器学习启发式方法会将*任何*写入 Windows 启动注册表 项的未签名 exe 标记出来，因为这也是恶意软件维持自身运行的 结构方式。它具体是由“随 Windows 启动”功能触发的。要解决此问题： 1. Windows 安全中心 → 病毒和威胁防护 → 保护历史记录 → 找到 检测项 → 操作 → 还原。 2. 为运行它的文件夹添加排除项：Windows 安全中心 → 病毒和威胁防护 → 管理设置 → 排除项 → 添加 排除项 → 文件夹。 如果你对这两者中的任何一个感到不适，请改为从源码构建（见 上文）——源码并没有做任何你在 `autostart.py` 中无法亲自阅读 的任何事情（大约只有 30 行代码）。 **“立即检查真实电量”提示未找到键盘 / 未报告电量 数值。** 键盘需要首先通过 Windows 设置 *至少*通过 Bluetooth 配对一次（应用程序不配对设备，只读取 已配对的设备），并且在检查时其物理模式开关需要设置为 BT — 2.4G 和 Bluetooth 在此键盘上是互斥的无线电 模式，通过物理开关选择，软件无法覆盖。 **2.4G 估算似乎不准。** 这是基于空闲时间的启发式方法，而不是 真实读数——请参阅[配置](#configuration)。偶尔进行一次真实的 Bluetooth 检查（切换到 BT，点击“立即检查真实电量”）以重新校准它； 重新校准之间的准确性取决于 `config.py` 的超时时间和每次充电 续航时间与你的实际使用情况和 RGB 设置的匹配程度。 **检查电池时有两个 PowerShell 窗口闪烁。** 应该已经 修复（`ble_reader.py` 使用了 `CREATE_NO_WINDOW`）——如果你仍然看到这种情况， 你可能在运行旧版本；请拉取最新的源码并重新构建。 ## 限制 - **2.4G 模式不公开电池电量。** 这是键盘当前 固件 / Keychron 接收器协议的硬性限制，不是此 应用程序可以通过软件修复的——完整调查请参阅 [`research/`](research/)。 如果 Keychron 未来发布支持通过 2.4G 响应电池 查询的固件，此应用程序可以切换到实时的真实读数；如果你先做到了这一点， 欢迎贡献代码。 - 启发式算法的准确性取决于 `config.py` 是否与你的实际键盘 设置相匹配，以及你的使用情况与 Keychron 公布的 最佳情况下的电池续航数据的吻合程度。 - 仅限 Windows（全程使用了 `winreg`、`ctypes.windll` 和 Windows PnP 设备 属性）。 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。

标签：桌面工具, 漏洞挖掘, 电池监控, 硬件外设, 系统托盘, 蓝牙, 逆向工具