zmk-battery-center

A system tray app to monitor the battery level of ZMK-based keyboards, built with Tauri v2.

✨ Features

• Display battery level for:
  • Both central and peripheral sides of split keyboards
  • Multiple keyboards simultaneously
• Supports macOS and Windows
• (Options)
  • Push notifications when
    • Keyboard battery level is low
    • Keyboard is connected/disconnected
  • Auto start at login
  • Switch between light and dark themes

Installation

Download the binary/installer from Releases.

Important

On macOS, the app is blocked from opening as it is not signed. Remove the app from quarantine by running the following command in the terminal:

sudo xattr -d com.apple.quarantine /Applications/zmk-battery-center.app

Typically it's located at /Applications/zmk-battery-center.app, but change it to the actual path if it's different.

If you worry about security, you can build the app yourself from source code. See Development section for more details.

Troubleshooting

Cannot open the app on macOS

• On macOS, the app is blocked from opening as it is not signed. Remove the app from quarantine by running the following command in the terminal:

  sudo xattr -d com.apple.quarantine /Applications/zmk-battery-center.app

  Typically it's located at /Applications/zmk-battery-center.app, but change it to the actual path if it's different.

My keyboard does not show up / Peripheral side battery level is not displayed

• Ensure your keyboard is connected to your computer via Bluetooth.
• Confirm your keyboard firmware includes the following ZMK configuration options:

  CONFIG_BT_BAS=y
  CONFIG_ZMK_BATTERY_REPORTING=y
  
  # For split keyboards:
  CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING=y
  CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY=y
  

  See the ZMK Documentation about Bluetooth and about battery for more details.
• On macOS, make sure Bluetooth permission is granted to the app.

Window position is misaligned

Window position may be misaligned if the OS has problems handling multiple monitors or you are using vertical taskbar on Windows.

You can manually move the window to the correct position to address this issue.

1. Right click the tray icon
2. Click Control > Manual window positioning in the menu
3. Now you can grab the top of the window to move it to any position you like

Development

1. Install Bun
2. Install Rustup
3. Clone this repo

   git clone https://github.com/kot149/zmk-battery-center.git
   cd zmk-battery-center

4. Install frontend dependencies

   bun install

5. Run in development mode

   bun tauri dev

6. Build for production

   bun tauri build

   • If build fails, try cleaning the build cache

     cd src-tauri
     cargo clean
     cd ..

   • Specify the target platform with --target option. If omitted, the app will be built for the current platform.

     # for macOS arm64
     bun tauri build --target aarch64-apple-darwin
     
     # for macOS x86_64
     bun tauri build --target x86_64-apple-darwin

You can also build using GitHub Actions.

References

• ZMK PR #1243, #2045 — Implementation and discussion for split battery reporting over BLE GATT
• zmk-ble: Proof-of-concept system tray app for macOS (not compatible with latest macOS)
• Mighty-Mitts: System tray app for macOS
• zmk-split-battery: System tray app for Windows
• zmkBATx: System tray app for Linux