path: root/README.md

# 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

```bash
# 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

```bash
# 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

```bash
./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`):

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

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

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

## Usage

### Command Line Options

```bash
./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

```bash
# 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`:

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


### Configuration Options

| Option | Default | Range | Description |
| :-- | :-- | :-- | :-- |
| `update_interval` | 30 | 5-300 | Battery check interval in seconds |
| `low_battery_threshold` | 20 | 5-50 | Battery percentage for low battery alerts |
| `show_notifications` | true | true/false | Enable desktop notifications |

## 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

```bash
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](LICENSE) file for details.