User Guide

voltkeeper is a cross-platform command-line tool for Bluetti power stations. It scans, connects, reads battery data, writes device settings, publishes to MQTT, and runs load tests — all over local BLE, with no cloud account required.

Install

Quick run (no clone required)

uvx --from git+https://github.com/mikemccllstr/voltkeeper voltkeeper --help

This downloads and runs the tool in an isolated environment.

From source

git clone https://github.com/mikemccllstr/voltkeeper
cd voltkeeper
uv run voltkeeper --help

Requirements

• Python 3.13+

• Linux with BlueZ, macOS 11+, or Windows 10 build 19041+ (BLE support)

• Bluetooth adapter with scan capability

On Linux, the BLE adapter may require elevated privileges (CAP_NET_ADMIN or sudo). On macOS, the device’s BLE MAC address may be reported as a UUID rather than a hardware address — use the UUID directly.

The tool reads plain Modbus RTU over BLE from Bluetti power stations. Encrypted devices (AES-CBC over BLE) are supported; the handshake is handled automatically.

Development

Run the full quality gate before committing:

mise run check

This runs lint, typecheck, and tests. See the Developer Guide for contributing and adding new devices.