About voltkeeper¶
What This Is¶
This repository contains the results of reverse-engineering the official Bluetti
Android app (net.poweroak.bluetticloud, v3.0.8) to understand how Bluetti power
stations communicate over Bluetooth Low Energy.
The practical output is voltkeeper — a cross-platform command-line tool that scans, connects, reads battery data, writes device settings, publishes to MQTT, and runs load tests against Bluetti power stations — all over local BLE, with no cloud account required.
The documentation output — protocol findings, Modbus register maps, encryption details, backend APIs, firmware update flows — lives in the Protocol Reference.
Why It Exists¶
Bluetti does not provide an official local BLE API. The Android app is cloud-dependent for many features, and existing community tools (such as the Home Assistant integration) operate exclusively through Bluetti’s cloud OAuth API. This project exists to enable local-first, offline control of hardware you own — talk directly to your power station over BLE, with no internet connection required.
How It Was Created¶
The official Bluetti Android APK was decompiled using jadx and apktool via automated mise tasks. Static analysis of ~22,900 decompiled classes yielded:
The Bluetooth GATT service UUID and characteristic UUIDs
Two BLE security protocols — a legacy challenge-response handshake and a newer ECDH + ECDSA mutual authentication scheme
Complete Modbus register maps for both V1 and V2 protocol generations
Hardcoded encryption keys and ECDSA keypairs extracted from the decompiled sources
The full 20+ microservice backend architecture, API endpoints, MQTT broker details, and firmware update flows
From these findings, voltkeeper was built as a standalone Python CLI that speaks the same protocol — using only observation and reimplementation. No code was copied from Bluetti’s official libraries.
Nearly all of the code in this repository was generated by AI coding assistants — primarily Claude Code and DeepSeek — working under the direction of a human software engineer. The engineer defined the architecture, made design decisions, reviewed every change, and verified behavior against real hardware.
Key Discoveries¶
BLE communication is plain Modbus RTU over GATT characteristics — plaintext for older ESP32 devices, AES-128-CBC encrypted for newer ones.
Encryption keys and ECDSA keypairs are hardcoded in the APK, identical across all installations.
Three cloud environments (development, test, production) with full URLs, endpoints, and credentials are all embedded in the release APK.
The backend is a 20+ microservice architecture spanning authentication, device management, telemetry, e-commerce, payments, community, and firmware delivery.
The firmware update flow supports BLE local transfer, cloud-triggered MQTT over-the-air, and broadcast upgrades to multiple sub-devices simultaneously.
Repository Tour¶
Path |
Purpose |
|---|---|
|
CLI source (BLE client, device models, MQTT, commands) |
|
Decompiled APK artifacts |
|
Sphinx documentation source |
|
Test suite |
|
APK download and btsnoop parsing automation |
Relationship to Bluetti’s Official Repositories¶
Bluetti publishes several repositories under github.com/bluetti-official,
including a BLE encryption library, a Home Assistant integration, and future
stubs for Modbus TCP and BLE broadcast documentation. We study these for
protocol clues but do not vendor or import any of their source code. Test
vectors — raw byte data from example files — are treated as factual data and
may be used as known-answer test inputs. Source code is never copied.
Contributing¶
A contributor guide for adding support for new device models is in
the Developer Guide. All contributions follow
test-driven development. Run mise run check before committing.
License¶
MIT — not affiliated with or endorsed by Bluetti. The APK decompilation was performed for interoperability research purposes.