Skip to content
tomquistPublic

About

No description, website, or topics provided.

Resources

Stars

27 stars

Watchers

8 watching

Forks

Repository files navigation

Marsrelay

Marsrelay runs your Marstek Energy Storage system without the Marstek cloud: a small ESP32-S3 device emulates the cloud locally, so the battery never talks to Marstek while all data and controls flow into your home automation via MQTT.

  • No cloud — all data stays in your home network. Without internet, Marsrelay needs a local time source to keep the batteries' schedules right (details)
  • No device hacking — you only point the battery's WiFi at Marsrelay's access point
  • Home Assistant integration via hm2mqtt

🔋 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 (this repo) Runs your battery completely offline, with no internet or Marstek cloud, while still sending all its data to your smart home
AstraMeter 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

How It Works

Marstek batteries talk to two cloud services: an HTTP API and an MQTT broker. Marsrelay emulates both on one ESP32-S3:

  1. WiFi access point (wifi): the battery connects to it, while Marsrelay stays connected to your home WiFi
  2. DNS capture (capture_dns): every cloud hostname lookup is answered with Marsrelay's own IP
  3. Cloud HTTP emulation (marstack): answers the Marstek cloud requests the battery makes, such as clock sync on port 80 and the TLS telemetry upload a Venus expects on port 443 (see Cloud emulation)
  4. Cloud MQTT emulation (mosquitto_broker): a TLS broker on port 8883 accepts the battery's cloud MQTT connection — battery data (.../device/... topics) is forwarded to your home broker, commands (.../App/.../ctrl) are relayed back
  5. UDP proxy (udp_proxy): bridges power meter broadcasts between both networks for zero feed-in
flowchart LR
    subgraph AP["Marsrelay WiFi AP"]
        Battery[Marstek battery]
    end
    subgraph ESP["Marsrelay (ESP32-S3)"]
        DNS[capture_dns]
        HTTP[marstack]
        Broker[mosquitto_broker]
        UDP[udp_proxy]
    end
    subgraph Home["Home network"]
        HomeBroker[Your MQTT broker]
        HM2MQTT[hm2mqtt]
        HA[Home Assistant]
        Meter[Smart meter / AstraMeter]
    end
    Battery -->|DNS| DNS
    Battery -->|HTTP + HTTPS| HTTP
    Battery <-->|MQTT over TLS| Broker
    Battery <-.->|UDP| UDP
    UDP <-.-> Meter
    Broker <--> HomeBroker
    HomeBroker <--> HM2MQTT
    HM2MQTT <--> HA
Loading

The battery thinks it's online; the Marstek app keeps working via Bluetooth only. You still need hm2mqtt on top — Marsrelay only moves raw MQTT messages, hm2mqtt parses them and creates the Home Assistant entities. Hame Relay is not needed: it bridges the real cloud, which an offline setup doesn't have.

Setup

You need: an ESP32-S3 board (single with "octal" PSRAM, 3-pack, 3-pack mini with "quad" PSRAM), ESPHome (e.g. the Home Assistant add-on), an MQTT broker, and MQTT Explorer.

1. Flash Marsrelay

Download marsrelay_esp32s3.yaml and adjust the substitutions: block at the top:

  • wifi_ssid / wifi_password: your home WiFi
  • ap_ssid / ap_password: the WiFi network your battery will connect to
  • mqtt_broker / mqtt_username / mqtt_password: your home MQTT broker
  • timezone: used to keep the battery clock in sync (timezone list)
  • udp_proxy_port: depends on your power meter / firmware (see the comment in the file)
  • psram: must match your board (details)

Then build and flash it with ESPHome. In the ESPHome Device Builder, create a new device and replace its YAML with this file. That's the only file you need: the config pulls Marsrelay's components straight from this repository (source: github://tomquist/marsrelay@main), and each build picks up the latest version (ESPHome re-checks once a day).

If your config is from an older version and still has type: local / path: ./components under external_components:, replace that source with the GitHub one above rather than copying the components folder around.

2. Connect the battery

In the battery's WiFi settings, connect it to the Marsrelay access point (ap_ssid / ap_password). That's all the battery-side setup — no hacks, no firmware modification.

3. Find your device information

With Marsrelay up and running, power-cycle the battery once: it clears the battery's DNS cache, so the cloud hostnames are looked up again and now resolve to Marsrelay. A battery that joined the access point earlier can otherwise stay quiet for a long time.

Then, in MQTT Explorer (connected to your home broker), wait for a message on marstek_energy/<deviceType>/device/<deviceId>/ctrl — or hame_energy/... on older firmware. Give this at least 30 minutes from the power cycle — the first message usually arrives within 20, but longer is normal. Note down deviceType and deviceId.

  • Ignore .../App/... topics — those are commands sent by hm2mqtt, not by your battery.
  • On a Venus, the Marsrelay log also shows both as soon as the battery's MQTT connection is up: Battery connected on 'marstek_energy/<deviceType>/App/<deviceId>/ctrl'.
  • Nothing appearing? See troubleshooting. You can also read the ID from Hame Relay's startup logs instead of waiting (see finding the encrypted ID).

4. Configure hm2mqtt

On current firmware the deviceId from step 3 is almost always a long encrypted ID, not the battery's MAC address. What goes into hm2mqtt depends on the device family:

  • B2500/Saturn (HMA/HMB/HMF/HMK/HMJ types): use the Bluetooth MAC as deviceId — never the encrypted ID — and add an id_mappings entry in Marsrelay. See Device IDs.
  • Venus, Jupiter and everything else: use the ID from step 3 as deviceId, exactly as it appears in the topic.
  • If the topic shows a plain 12-digit MAC (older firmware, or a B2500 configured for local MQTT): just use that — done.

Documentation

Troubleshooting

The diagnostic entities show which part stopped. See docs/troubleshooting.md for:

License

MIT

About

No description, website, or topics provided.

Resources

Stars

27 stars

Watchers

8 watching

Forks

Releases

Packages

Contributors

Languages