ZMK BattMan

A lightweight system tray application for monitoring battery levels of ZMK split keyboards on Linux. Displays both left (central) and right (peripheral) battery percentages with configurable low battery notifications.

Features

• Dual Battery Monitoring - Shows battery levels for both keyboard halves
• System Tray Integration - Clean, minimal tray icon with battery percentages
• Desktop Notifications - Configurable low battery alerts
• CLI Configuration - Easy setup and management via command line

ZMK Configuration Required

Your ZMK config must have these configuration options enabled:

CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY=y
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING=y

Installation

Place the zmk-battman binary in anywhere in your PATH.

Build from Source

# Clone the repository
git clone https://git.tablaster.dev/blaster4385/zmk-battman
cd zmk-battery-monitor

# Build the app
make battman

Quick Start

1. Initial Setup

# Run the interactive setup
./zmk-battman --setup

This will guide you through:

• Selecting your ZMK keyboard from available Bluetooth devices
• Setting the update interval (default: 30 seconds)
• Configuring notifications (default: enabled)
• Setting low battery threshold (default: 20%)

2. Start Monitoring

./zmk-battman

The application will start in the system tray and begin monitoring your keyboard's battery levels.

3. Autostart (Optional)

Add to your window manager configuration:

Hyprland (~/.config/hypr/hyprland.conf):

exec-once = /path/to/zmk-battman

i3/sway (~/.config/i3/config):

exec --no-startup-id /path/to/zmk-battman

Usage

Command Line Options

./zmk-battman [OPTIONS]

Options:
  --setup                    Run interactive setup wizard
  --config                   Display current configuration
  --device ADDRESS           Set keyboard device by Bluetooth address
  --interval SECONDS         Set update interval (5-300 seconds)
  --threshold PERCENT        Set low battery threshold (5-50%)
  --notify true/false        Enable/disable desktop notifications

Examples

# Initial configuration
./zmk-battman --setup

# Quick device configuration
./zmk-battman --device "AA:BB:CC:DD:EE:FF"

# Set low battery threshold to 15%
./zmk-battman --threshold 15

# Enable notifications with 10% threshold
./zmk-battman --notify true --threshold 10

# View current settings
./zmk-battman --config

# Start the app
./zmk-battman

Configuration

Configuration is stored at ~/.config/zmk-battman/config.json:

{
  "name": "My ZMK Keyboard",
  "address": "AA:BB:CC:DD:EE:FF",
  "update_interval": 30,
  "low_battery_threshold": 20,
  "show_notifications": true
}

Configuration Options

System Tray Display

The system tray icon shows:

• Title: Battery percentages (e.g., "85%/72%" for left/right)
• Tooltip: Detailed status including device name, connection status, and last update time
• Menu:
  • Connection status
  • Individual battery levels for left/right halves
  • Manual refresh
  • Quit

Notifications

Desktop notifications are sent for:

• Low Battery Warning: When either keyboard half drops to/below the threshold
• Connection Changes: When keyboard connects or disconnects
• Critical Battery Level: Extra urgent notification for battery levels ≤10%

Notifications are rate-limited to prevent spam (10-minute delay between identical alerts).

Technical Details

ZMK Battery Service Detection

The monitor detects ZMK split keyboard batteries by:

1. Multiple Battery Services: Looks for multiple instances of the standard Bluetooth Battery Service (UUID: 0000180f-0000-1000-8000-00805f9b34fb)
2. Service Ordering: First service = left (central), second service = right (peripheral)
3. Fallback Support: Falls back to legacy org.bluez.Battery1 interface for single-service keyboards

Architecture

zmk-battery-monitor/
├── main.go              # CLI interface and application lifecycle
├── internal/
│   ├── types.go         # Data structures
│   ├── bluetooth.go     # Bluetooth device scanning and communication
│   ├── monitor.go       # Battery level monitoring logic
│   ├── config.go        # Configuration management
│   ├── notifications.go # Desktop notification system
│   └── tray.go          # System tray interface
└── assets/
    ├── keyboard-icon.png # icon (embedded at build time)
    └── icon.go          # Embed icon into binary

Troubleshooting

Keyboard Not Found

• Ensure your ZMK keyboard is paired and connected via Bluetooth
• Check that the keyboard appears in bluetoothctl list or similar

No Battery Information

• Your ZMK config must have these configuration options enabled:

CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY=y
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING=y

• Some keyboards may need some time after connection before battery data is available
• Check system logs for D-Bus connection errors

System Tray Not Appearing

• Ensure that your desktop environment supports system tray (most modern DEs do)
• Check that the application is running: ps aux | grep zmk-battman
• Try running in foreground (not autostart) to see error messages

Notifications Not Working

• Verify your system supports freedesktop notifications
• Test with: notify-send "Test" "This is a test notification"
• Check if notifications are enabled: ./zmk-battman --config

Development

Building

go build -o zmk-battman

Dependencies

• github.com/getlantern/systray - System tray functionality
• github.com/godbus/dbus/v5 - D-Bus communication for Bluetooth and notifications

Contributing

Contributions are welcome but idk how. Try contacting me on my email if you want to contribute something here. Or just feel free to fork this to your github or whatever and do whatever you want. Just ensure to provide proper credits and adhere to the license.

License

This project is licensed under the GPLv2 License - see the LICENSE file for details.