MQTT interface

Homebattery can be controlled and monitored over MQTT. Only MQTT v5 is supported.

For configuration of MQTT, see the configuration page.

General messages

<root> is the MQTT topic root set in the configuration.

Topic	Datatype	Direction	Description
<root>/mode/set	utf-8	W	Requested operation mode. Possible values are charge, discharge, idle and protect.
<root>/mode/actual	utf-8	R	Current operation mode. Possible values are charge, discharge, idle and protect.
<root>/locked	utf-8	R	Reason for system lock. Payload is JSON and contains a list of all locks. An empty list means that there is no lock.
<root>/reset	utf-8	W	Writing the value reset to this topic will lead to a system reset.

Device class data

For all device classes, two types of messages are sent:

• sum messages, containing aggregated measurement data of a whole device class

• dev messages, containing measurement data of a specific device

The device class sensor does not send sum messages.

All messages use a JSON payload:

{
    "capacity": "<float value, unit Ah>",
    "current": "<float value, unit A>",
    "energy": "<integer value, unit Wh>",
    "power": "<integer value, unit W>",
    "status": "<on / syncing / off / fault / offline>",
    "voltage": "<float value, unit V>"
}

The content of a message may vary, not all measurands are present in every message.

energy contains the energy since the last message containing an energy value, which means to get the energy of a longer period, the values of the energy messages need to be accumulated. All other measurands contain the average value since the last message with the same measurand.

A measurand is sent with a minimum interval of ~ 6s when a value changed. In addition to that, it is sent every ~ 300s, even if no value changed. The device class battery sends messages every time the battery data is read, no matter whether a value changed or not.

Battery dev messages

battery dev messages use a different payload format:

{
    "v": "<battery voltage, float value, unit V>",
    "i": "<battery current, float value, unit A>",
    "soc": "<battery soc, float value, no unit>",
    "c": "<remaining capacity, float value, unit Ah>",
    "c_full": "<full battery capacity, float value, unit Ah>",
    "n": "<battery cycles, integer value, no unit>",
    "temps": "<battery cell temperatures, list of float values, unit °C>",
    "cells": "<battery cell voltage, list of float values, unit V>"
}

Measurands are not sent if they are not supported by the battery.

Device class messages

<root> is the MQTT topic root set in the configuration.

<name> is the device name set in the configuration.

Topic	Datatype	Direction	Description
<root>/cha/sum	utf-8	R	sum message of the charger device class.
<root>/cha/dev/<name>	utf-8	R	dev message of a charger device.
<root>/hea/sum	utf-8	R	sum message of the heater device class.
<root>/hea/dev/<name>	utf-8	R	dev message of a heater device.
<root>/inv/sum	utf-8	R	sum message of the inverter device class.
<root>/inv/dev/<name>	utf-8	R	dev message of a inverter device.
<root>/sol/sum	utf-8	R	sum message of the solar device class.
<root>/sol/dev/<name>	utf-8	R	dev message of a solar device.
<root>/bat/sum	utf-8	R	sum message of the battery device class.
<root>/bat/dev/<name>	utf-8	R	dev message of a battery device.
<root>/sen/dev/<name>	utf-8	R	dev message of a sensor device.