# About voltkeeper

```{toctree}
:hidden:

naming
brand
```

## 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 |
|---|---|
| `src/voltkeeper/` | CLI source (BLE client, device models, MQTT, commands) |
| `bluetti-files/` | Decompiled APK artifacts |
| `docs/source/` | Sphinx documentation source |
| `tests/` | Test suite |
| `scripts/` | 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](../developer/contributing-devices.md). 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.