A Cinnamon panel applet for Linux Mint that displays the battery percentage of a Yunzii B87 wireless keyboard connected via its 2.4G USB dongle.
- Reads battery level directly from the keyboard's HID vendor interface — no background daemon required
- Shows a stale-reading indicator (⏳) when the cached reading may be old
- Detects wired USB charging and displays a ⚡ icon
- Updates every 60 seconds
- Linux Mint with the Cinnamon desktop
- Yunzii B87 keyboard with 2.4G USB dongle (USB ID
056d:c077) - Python 3
1. Clone the repo
git clone https://github.com/jordanleeuk/yunzii-applet.git
cd yunzii-applet2. Install udev rules (grants your session user access to the HID device without root)
sudo cp 99-yunzii-b87.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger --subsystem-match=hidrawIf you use the wired charging detection feature, also add yourself to the plugdev group and log out/in:
sudo usermod -aG plugdev $USER3. Install the applet
bash install.shThis symlinks the repo into ~/.local/share/cinnamon/applets/ so edits take effect on the next Cinnamon reload.
4. Add the applet to your panel
Right-click the panel → Add applets to the panel → find Yunzii B87 Battery → Add.
5. Reload Cinnamon
Alt+F2 → type r → Enter.
No reading / ERROR output
Run the reader directly to see what's happening:
python3 battery_reader.pyIf it prints nothing, run discovery mode while pressing Fn+Right Ctrl on the keyboard:
python3 battery_reader.py --discoverReading looks stale
The dongle caches the battery level reported at last keyboard reconnect. To force a fresh reading, power-cycle the keyboard (switch it off and back on) — this triggers a new connection and a fresh report.
Charging not detected
Charge-only USB-C cables cannot be detected. Use a data cable; a second USB device (28e9:30ad) must enumerate for charging detection to work.
See CLAUDE.md for the full HID vendor protocol documentation (report format, byte offsets, command structure, and how charging detection works).
MIT