AstraMeter

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 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) — recommended. AstraMeter gives each storage device its own target and shares the load between them.
• 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) or shellypro3em_new (2220).
• Shelly EM gen3
• Shelly Pro EM50

Which device type? Use CT002/CT003. See CT002 / CT003 steering and the Configuration reference.

⚡ Quick start with the config generator

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.

Installation

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. On an ESP32, first add the board in the Marstek app like a real CT, over Bluetooth: see Add the board to the Marstek app.

Supported power meter sources

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, Marstek CT002 / CT003, FRITZ!Smart Energy 250, Fronius Smart Meter, Refoss / Meross energy monitors, Tibber Pulse, Script, and SML.

Configuration

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.ini section for each supported meter.
• CT002 / CT003 steering — the CT emulator, active control, peak shaving, multi-battery balancing, battery power limits, 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.

Testing without hardware

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.

Help & reference

• FAQ & troubleshooting — setup problems, firmware requirements, oscillation/yo-yo fixes, and more.
• B2500 minimum output — the lowest power a B2500 delivers, depending on the inverter selected in the Marstek app.
• CT002/CT003 UDP protocol — the wire protocol used by Marstek storage systems.
• Marstek MQTT & HTTP protocol — the cloud/app protocol.
• CT002/CT003 Bluetooth protocol — how the Marstek app onboards a meter over BLE, and the meter's BLE command set.
• Contributing — development workflow and the Python ↔ ESPHome parity rules.

License

This project uses the General Public License v3.0. See the LICENSE file for details.