2.4G 外设电量

Windows 10/11 的 2.4G 无线外设电量托盘工具。

纯 Python 标准库（ctypes + tkinter），零第三方依赖，不写日志。

甚至只需要网页版驱动就可以拿到电量协议——不少 2.4G 外设的网页版驱动直接用 WebHID 查询电量，翻一眼协议比装 USBPcap 抓包省事得多。

托盘里每台设备一个电量圆环：

下载

两种方式任选：

• 免安装（推荐）：到 Releases 下载 2.4G.exe，双击运行，无需 Python。
• 最小体积：下载 my_devices.py（约 185 KB），安装 Python 3.10+ 后运行：

python my_devices.py

exe 未签名，Windows 可能提示 SmartScreen，选择“更多信息 → 仍要运行”。

功能

• 托盘常驻，左键刷新，右键打开面板
• 启动不自动添加设备；无设备时显示「请插入设备 / 或者拔插一下你想要添加的设备」
• 新设备插入或重新拔插时弹窗确认，显示设备名、VID:PID 和当前电量
• 双击卡片上的设备名即可重命名，名称保存在配置里
• 右键设备卡片可删除该设备，同时清除它的抓包协议和上次电量
• 深色圆角面板、电量卡片、滚动列表、托盘电量图标
• 自动刷新、开机自启（启动项名 2.4G）
• 只读查询，不修改设备设置

协议规则

软件不内置设备协议表，也不会按 VID:PID 自动匹配内置设备。

只有两种来源算“有协议”：

1. 标准 HID 电量能直接读到：自动保存为 {"kind": "standard"}；
2. 抓包成功：保存 {"kind": "captured", "requests": [...], "offset": N}。

设备休眠或未开机时：

• 有协议、也有上次电量：显示上次电量，副标题「上次更新 HH:MM · 设备休眠」；
• 有协议、但没有上次电量：显示「设备休眠」；
• 没有协议：显示「协议未知，无法读取电量」，不会假装休眠。

环境

• Windows 10/11 x64
• Python 3.10+（需包含 tkinter）
• 抓包需要 USBPcap 和管理员权限

运行

python my_devices.py            :: 托盘常驻
python my_devices.py --once     :: 读一次并打印
python my_devices.py --list     :: 列出 HID 接口
python my_devices.py --panel    :: 只开面板，不常驻托盘
python my_devices.py --install  :: 创建开机自启 + 桌面入口

配置文件：%APPDATA%\BatteryTray\config.json

里面保存：

• devices：已添加的设备（VID、PID、名称）
• protocols：标准 HID 或抓包保存的协议
• last：每台设备上次成功读到的电量
• interval：刷新间隔
• usbpcap：USBPcapCMD 路径

未知设备抓包

1. 安装 USBPcap，重启电脑
2. 插拔一次要抓包的设备，在弹窗里点「添加」
3. 关闭厂家驱动，点「开始抓包」并允许管理员权限
4. 打开厂家驱动，让它显示一次电量，记下数值
5. 点「停止」，填入刚才的电量
6. 只有一个字节符合：保存请求帧和电量字节位置
7. 多个字节符合：换一个不同电量再抓一次，对比两次字节差值
8. 保存后立即回读验证：
   • 主动回读失败时，会尝试被动监听输入报告；
   • 仍然失败会删除刚保存的协议，并提示「抓包中不含电量数据，可能是没按要求让厂商软件发电量请求」

提示：

• 没有匹配：注意抓包期间厂家驱动必须显示过电量；
• 匹配不准确：换一个相差 10% 以上的电量再抓；
• 多次没有结果：可能是厂家协议加密，无法通过抓包获取。

抓包分析会排除描述符、EP0 标准控制 setup、字符串描述符和全零报告；HID Feature Report 和厂商自定义报告会保留。

限制

• 电量由设备上报，可能是 5% 步进
• 加密或私有握手协议无法通过抓包读取
• 仅支持 Windows 10/11 x64

文件

• my_devices.py：主程序（抓包助手已内置）
• app.ico：图标
• 启动.bat：启动脚本
• docs/panel.png：界面截图
• docs/tray.png：托盘截图