https://github.com/marcomc/bmgateway
https://github.com/marcomc/bmgateway
Last synced: 13 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/marcomc/bmgateway
- Owner: marcomc
- License: mit
- Created: 2026-04-18T20:15:07.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-04-18T21:21:08.000Z (about 1 month ago)
- Last Synced: 2026-04-18T23:28:21.480Z (about 1 month ago)
- Language: Python
- Size: 614 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# BMGateway
## Quick Index
- [Overview](#overview)
- [Choose Your Path](#choose-your-path)
- [What Is Included](#what-is-included)
- [System Flow](#system-flow)
- [Repository Structure](#repository-structure)
- [Documentation Map](#documentation-map)
- [Development](#development)
- [Release Status](#release-status)
- [Credits And Attribution](#credits-and-attribution)
- [License](#license)
## Overview
`BMGateway` is a Raspberry Pi battery-monitor gateway for BM200/BM6-family and
BM300 Pro/BM7-family devices.
It ships as one Python codebase with two executables:
- `bm-gateway` for runtime collection, configuration, history, and Home
Assistant publishing
- `bm-gateway-web` for the optional local web application
The project is intentionally battery-first:
- live polling from the Raspberry Pi
- retained local history in SQLite
- Home Assistant integration through MQTT discovery
- a mobile-friendly local web UI for Home, History, Devices, and Settings
For the runtime, command-line, web UI, and Home Assistant boundaries, use
[Application surfaces](docs/application-surfaces.md#application-surfaces).
## Choose Your Path
### I Want To Install It On A Raspberry Pi
Start here:
- [rpi-setup/manual-setup.md](rpi-setup/manual-setup.md)
If you want to prepare the SD card from macOS first:
- [rpi-setup/macos-imager-cli.md](rpi-setup/macos-imager-cli.md)
### I Want To Connect It To Home Assistant
Start here:
- [home-assistant/setup.md](home-assistant/setup.md)
Developer reference:
- [home-assistant/contract.md](home-assistant/contract.md)
### I Want To Develop Or Modify The Project
Start here:
- [docs/application-surfaces.md](docs/application-surfaces.md)
- [python/README.md](python/README.md)
- [docs/README.md](docs/README.md)
## What Is Included
- Packaged runtime CLI and web executable
- Live BM200/BM6-family and BM300 Pro/BM7-family polling paths
- SQLite history with raw, daily, monthly, and yearly views
- Optional Home Assistant MQTT discovery integration
- Raspberry Pi bootstrap and `systemd` service installation
- Local web app with:
- Home
- History
- Device Detail
- Devices
- Settings
- Light/dark/system appearance modes
- Modular web localization with a Settings language selector
- Per-device colors, badges, and battery metadata
- Battery, fleet, history, and device charts
- Optional Raspberry Pi self-healing for scheduled reboots and Wi-Fi recovery
For the first release summary, use [CHANGELOG.md](CHANGELOG.md).
## System Flow
This high-level flow shows the normal appliance path from battery monitors to
local state, the web UI, and Home Assistant MQTT discovery.
```mermaid
flowchart LR
accTitle: BMGateway system flow
accDescr: Shows how battery monitor readings move through the runtime, local state, web UI, MQTT broker, and Home Assistant.
Devices["BM200/BM6 and BM300 Pro/BM7 devices"]
Runtime["bm-gateway"]
State["latest_snapshot.json and gateway.db"]
Web["bm-gateway-web"]
Browser["browser on bmgateway.local"]
Broker["MQTT broker"]
HomeAssistant["Home Assistant"]
Devices --> Runtime
Runtime --> State
Runtime --> Broker
Broker --> HomeAssistant
State --> Web
Web --> Browser
```
The full surface map lives in
[docs/application-surfaces.md](docs/application-surfaces.md#application-surfaces).
## Repository Structure
```text
.
├── CHANGELOG.md
├── README.md
├── TODO.md
├── docs/
├── home-assistant/
├── python/
├── rpi-setup/
└── web/
```
- `python/` contains the packaged application and tests
- `home-assistant/` contains the MQTT contract and Home Assistant assets
- `rpi-setup/` contains Raspberry Pi installation and operations docs
- `web/` contains the web product boundary notes
- `docs/` contains architecture, research, and development notes
## Documentation Map
Use one canonical source per topic:
| Topic | Canonical document |
| --- | --- |
| First-release summary | [CHANGELOG.md](CHANGELOG.md) |
| Active backlog | [TODO.md](TODO.md) |
| Runtime, CLI, web UI, and integration surfaces | [docs/application-surfaces.md](docs/application-surfaces.md) |
| Python package and contributor entry point | [python/README.md](python/README.md) |
| Developer notes and architecture index | [docs/README.md](docs/README.md) |
| Documentation maintenance rules | [docs/documentation-maintenance.md](docs/documentation-maintenance.md) |
| Home Assistant setup | [home-assistant/setup.md](home-assistant/setup.md) |
| Home Assistant MQTT contract | [home-assistant/contract.md](home-assistant/contract.md) |
| Raspberry Pi installation | [rpi-setup/manual-setup.md](rpi-setup/manual-setup.md) |
| Web product boundary | [web/README.md](web/README.md) |
## Development
Primary maintainer commands:
```bash
make install-dev
make check
make dev-deploy TARGET=admin@host
```
The default quality gate is `make check`.
## Release Status
The current documented release is:
- `0.3.0`
Use [CHANGELOG.md](CHANGELOG.md) for release content and [TODO.md](TODO.md) for
work that is not shipped yet.
## Credits And Attribution
`BMGateway` is an original project, but it builds on upstream open-source
software and protocol research that should be credited explicitly.
### Open-Source Software Used
- [Bleak](https://github.com/hbldh/bleak) by
[Henrik Blidh](https://github.com/hbldh) and contributors.
`BMGateway` uses `Bleak` as the Python BLE client/scanner foundation for the
Raspberry Pi live polling path. Thanks to the Bleak maintainers and
contributors for the library and surrounding troubleshooting knowledge.
### Protocol / Reverse-Engineering References
- BM6 reverse-engineering reference by
[tarball.ca](https://www.tarball.ca/posts/reverse-engineering-the-bm6-ble-battery-monitor/).
This informed parts of the BM6/BM200 protocol investigation. Thanks for the
published research.
- BM6/Home Assistant community discussion:
[Home Assistant BM6 thread](https://community.home-assistant.io/t/bm6-battery-monitor-esphome/806239).
This helped validate practical behavior seen on live hardware. Thanks to the
community contributors for sharing findings.
- BM300 Pro / BM7 reverse-engineering references:
[slydiman/bm7-battery-monitor](https://github.com/slydiman/bm7-battery-monitor)
and [derekpurdy/BM7](https://github.com/derekpurdy/BM7).
These provided the BM7 AES key, current-state poll command, payload offsets,
and model naming used for the BM300 Pro protocol driver. Thanks to those
project maintainers and contributors for publishing their findings.
- BM2/BM6 community discussion:
[OpenMQTTGateway BM2 thread](https://community.openmqttgateway.com/t/omg-1-8-0-no-longer-gets-bm2-messages/3578).
This provided useful context during compatibility debugging. Thanks to the
contributors there as well.
### Attribution Policy
Whenever code, protocol logic, assets, or meaningful implementation ideas are
adapted from other open-source projects in the future, they must be added to
this section with:
- the project name
- a link to the canonical Git repository when available
- the author or maintainer name when known
- a short note explaining what `BMGateway` reused or was inspired by
## License
[MIT](LICENSE)