A menu bar app that reads a JBD BMS (Xiaoxiang Electric) over Bluetooth LE and feeds a WidgetKit desktop widget.
Widgets can't hold a BLE connection themselves, so the app writes ~/Library/Application Support/BMSWidget/snapshot.json and the widget reads it.
![]() |
![]() |
![]() |
While charging:
Requires macOS 14+ on Apple Silicon.
Important
The BMS accepts only one Bluetooth connection at a time. Disconnect your phone first: close the Xiaoxiang app or turn off Bluetooth on the phone, otherwise the Mac can't connect.
- Download
BMSWidget-<version>.zipfrom Releases, unzip it and moveBMSWidget.appto/Applications. - The app isn't signed with an Apple certificate, so macOS won't open it until you remove the quarantine flag:
xattr -cr /Applications/BMSWidget.app
- Launch the app, allow Bluetooth and pick your BMS from the menu bar icon.
- Desktop → Edit Widgets → "Battery".
The UI language (UA / EN) is switched at the bottom of the menu; English is the default.
No Xcode needed, the Command Line Tools are enough:
tools/build.sh→build/BMSWidget.app(ad-hoc signed;BUNDLE_PREFIXand the version come fromproject.yml).- Launch
build/BMSWidget.app(or copy it to/Applications) and allow Bluetooth. - Pick your BMS from the list in the menu bar icon (it's remembered).
- Desktop → Edit Widgets → "Battery".
With Xcode: brew install xcodegen && xcodegen && open BMSWidget.xcodeproj, then run the BMSWidget scheme (set DEVELOPMENT_TEAM in project.yml for signing).
- The widget only stays live while the app is running, so add the app to Login Items.
- The widget refreshes at most about once a minute (WidgetKit limits), the menu every 10 s.
- Protocol: service
FF00(FF01notify /FF02write) orFFE0/FFE1. Frames: requestDD A5 03 00 FF FD 77, responseDD 03 00 <len> … <chk> 77. - No App Group: on macOS 15 without a Team ID it asks for access on every launch and the widget doesn't start. Temporary-exception entitlements for a single folder are used instead.
python3 tools/verify_jbd.py is a Python port of App/JBDProtocol.swift with tests.



