Formerly known as b2500-meter. We renamed the project because it supports the full range of Marstek storage systems (B2500, Jupiter, Venus, …), not just the B2500.
AstraMeter emulates Smart Meter devices for Marstek storage systems such as the B2500, Jupiter, and Venus. You can feed it from almost any real smart meter. Your storage system sees a meter it understands, while AstraMeter reads your actual grid power from a source you choose and steers the batteries toward net-zero grid exchange.
The built-in live status dashboard — three batteries sharing one house.
🔋 The Marstek ecosystem. This repo is part of a family of open-source tools for Marstek batteries (B2500, Venus, Jupiter, …):
| Project | What it does |
|---|---|
| hm2mqtt | Brings your battery into your smart home, turning its raw data into readable sensors and controls (e.g. in Home Assistant) |
| hame-relay | Connects the official Marstek cloud/app and your local smart home so both work together, forwarding data whichever way your battery is set up |
| marsrelay | Runs your battery completely offline, with no internet or Marstek cloud, while still sending all its data to your smart home |
| AstraMeter (this repo) | Tells your battery your live grid usage (read from your existing meter) so it charges and discharges to avoid buying or selling power |
| hmjs | Sets up and configures B2500 batteries over Bluetooth, right from your web browser, with no app or account needed |
| esphome-b2500 | Continuously monitors and controls a B2500 over Bluetooth using a small ESP32 board |
It does this by emulating one or more of these devices:
- CT002 / CT003 (Marstek's native CT protocol) — use this for multiple storage devices. It coordinates one shared target across the whole fleet.
- Shelly Pro 3EM — uses port 1010 (B2500 firmware up to v224) and port 2220
(B2500 firmware v226+). To pick one port, use
shellypro3em_old(1010) orshellypro3em_new(2220). - Shelly EM gen3
- Shelly Pro EM50
Which device type? Use CT002/CT003 when you steer multiple storage devices. Otherwise use a Shelly type (
shellypro3em,shellyemg3,shellyproem50, …). See CT002 / CT003 steering and the Configuration reference.
The easiest way to start is the
config generator. This
beginner-friendly tool asks a few questions about your power meter and writes a
ready-to-use config.ini (Home Assistant add-on / Docker / direct install) or
ESPHome YAML, explaining each option as you go. It runs entirely in your
browser — nothing is uploaded — and you can save, share, and reload your
answers.
You can install and run AstraMeter in several ways:
| Method | Best for | Guide |
|---|---|---|
| Home Assistant add-on | Home Assistant users (easiest) | docs/installation/home-assistant.md |
| Docker | Standalone server deployment | docs/installation/docker.md |
| Direct (Python) | Development or custom setups | docs/installation/direct.md |
| ESPHome on an ESP32 | A dedicated board, no server | docs/installation/esphome.md |
Once AstraMeter is running, switch your Marstek battery to "Self-Adaptation" mode to turn on the powermeter functionality.
AstraMeter reads your real grid power from many kinds of source. For the
config.ini settings of each one, see
docs/powermeters.md. For the ESPHome external
component, see docs/esphome-powermeters.md.
Supported sources include: Shelly, Tasmota, Shrdzm, Emlog, ioBroker, Home Assistant, VZLogger, ESPHome (Http-Polling or native API), AMIS Reader, Modbus (TCP/UDP), MQTT, JSON HTTP, TQ Energy Manager, HomeWizard, Enphase Envoy, SMA Energy Meter, FRITZ!Smart Energy 250, Fronius Smart Meter, Refoss / Meross energy monitors, Tibber Pulse, Script, and SML.
You configure AstraMeter in a config.ini file, or in ESPHome YAML on an ESP32.
Start with the config generator,
then read the reference docs as needed:
- Configuration reference — general options, value transformation, the PID controller, and running multiple powermeters.
- Powermeter sources — the
config.inisection for each supported meter. - CT002 / CT003 steering — the CT emulator, active control, multi-battery balancing, efficiency optimization, and Marstek cloud registration.
- Live status dashboard — the built-in web UI. It shows live grid and per-battery state, and lets you edit your configuration in the browser. It is on by default in the Home Assistant add-on and in Docker or standalone runs, and an ESP32 can serve it too.
- MQTT Insights & Home Assistant entities — publishing internal state to MQTT, HA Device Discovery, and per-battery controls.
- ESPHome powermeter sources — the equivalent
grid-power
sensor:configuration on an ESP32.
The bundled simulator (astra-sim) mimics N batteries
speaking the CT002 UDP protocol and serves a powermeter endpoint. You can run
the full emulator and balancer end-to-end without any real devices.
- FAQ & troubleshooting — setup problems, firmware requirements, oscillation/yo-yo fixes, and more.
- CT002/CT003 UDP protocol — the wire protocol used by Marstek storage systems.
- Marstek MQTT & HTTP protocol — the cloud/app protocol.
- Contributing — development workflow and the Python ↔ ESPHome parity rules.
This project uses the General Public License v3.0. See the LICENSE file for details.