Configuration

Configuration is done using a json file config.json, which is uploaded to homebattery via web interface, see installation.

Example

A template configuration file can be found in the repostiory in the config folder or as part of every release.

General

Parent key: general

Key	Datatype, Unit	Description	Recommended Value
default_mode	string, -	Initial mode of operation after statup.	n.a.

Network

Parent key: network

Key	Datatype, Unit	Description	Recommended Value
ssid	string, -	The SSID of your WLAN network.	n.a.
password	string, -	The password of your WLAN network.	n.a.
timeout	integer, s	The timeout for connecting to the network. If the system is not connected to the network after the timeout, the system restarts.	15
ntp_server	string, -	Optional. The host address of the ntp server.	time.google.com
timezone	integer, -	Optional. The UTC offset of your timezone. The UTC offsets can be found here: https://en.wikipedia.org/wiki/List_of_UTC_offsets .	1 for Berlin
ntp_timeout	integer, s	Optional. The timeout for retriving time from the ntp server. If no time was retrived from the ntp server after the timeout, the system continues without time sync.	10

MQTT

Parent key: mqtt

Key	Datatype	Description	Recommended Value
host	string	Host address of the MQTT broker. Expected format is <ip>:<port>.	n.a.
tls/ca	string	Optional. Turns on TLS and sets the file name of the TLS CA chain certificate. The certificate must have DER encoding.	n.a.
tls/insecure	boolean	Optional. Turns on accepting self-signed TLS certificates.	n.a.
user	string	Optional. Username for authentification at the MQTT broker.	n.a.
password	string	Optional. Password for authentification at the MQTT broker.	n.a.
root	string	MQTT root topic. All MQTT topics the system is using will be sub-topics of this root topic (except for drivers using MQTT).	homebattery

Logging

Parent key: logging

Key	Datatype	Description	Recommended Value
host	string	Optional. If given, logging messages will be send via UDP to this host. Expected format is <ip>:<port>	n.a.
ignore	list of strings	Logging sender which debug messages shall be ignored. Some parts of the system have a very verbose logging output for debug purposes. It can make sense to disable them in order to get a more readable log.	n.a.

Inverter

Parent key: inverter

Key	Datatype, Unit	Description	Recommended Value
power	int, W	Inverter power when in operation mode discharge. This value is only used if the netzero algorithm is not used.	n.a.
reduce_power_during_fault	boolean, -	Reduces inverter power to minimum if any inverter switches to status fault. This feature might be necessary when connecting multiple inverters to the batteries.	false

Netzero

If the netzero algorithm shall not be used, this whole sections needs to be removed from the configuration.

Parent key: inverter/netzero

Key	Datatype, Unit	Description	Recommended Value
signed	boolean, -	Set to true, if your power consumption measurement equipment can measure power fed into grid (which results in negative values for power consumption).	n.a.
evaluated_time_span	integer, s	Time span that will be evaluated, older data will be ignored. The maximum value is 120.	30
maturity_time_span	integer, s	Time span after an inverter power change during which netzero will not increase inverter power. Independently from this value, netzero will not change inverter power with less than two data points.	15
target	integer, W	Expected remaining minimum energy consumption.	n.a.
hysteresis	integer, W	Hysteresis of the remaing minimum energy consumption.	n.a.
change_upwards	integer, W	Maximum increase of the inverter power in a single inverter power change.	n.a.
change_downwards	integer, W	Maximum decrease of the inverter power in case of a backfeeding event.	n.a.

Heater

This section can be removed, if no heater is present.

Parent key: heater

Key	Datatype, Unit	Description	Recommended Value
activate/battery	float, °C	Minimum battery cell temperature that activates the heater.	6
deactivate/battery	float, °C	Minimum battery cell temperature that deactivates the heater.	8

Supervisor

Checks can be disabled by removing the corresponding sections from the configuration.

Battery offline check

Parent key: supervisor/battery_offline

Key	Datatype, Unit	Description	Recommended Value
threshold	integer, s	Maximum time span with no successful communication to any battery.	120

Battery cell voltage low check

Parent key: supervisor/cell_low

Key	Datatype, Unit	Description	Recommended Value
threshold	float, V	Minimum voltage of a battery cell.	3.1 for LiFePo4
hysteresis	float, V	Hysteresis of the threshold value.	>= 0.1

Battery cell voltage high check

Parent key: supervisor/cell_high

Key	Datatype, Unit	Description	Recommended Value
threshold	float, V	Maximum voltage of a battery cell.	3.65 for LiFePo4
hysteresis	float, V	Hysteresis of the threshold value.	>= 0.2

Battery cell temperature low while charging check

Parent key: supervisor/temp_low_charge

Key	Datatype, Unit	Description	Recommended Value
threshold	float, °C	Minimum temperature of a battery.	5 for LiFePo4
hysteresis	float, °C	Hysteresis of the threshold value.	2

Battery cell temperature low while discharging check

Parent key: supervisor/temp_low_discharge

Key	Datatype, Unit	Description	Recommended Value
threshold	float, °C	Minimum temperature of a battery.	0 for LiFePo4
hysteresis	float, °C	Hysteresis of the threshold value.	2

Battery cell temperature high while charging check

Parent key: supervisor/temp_high_charge

Key	Datatype, Unit	Description	Recommended Value
threshold	float, °C	Maximum temperature of a battery.	40 for LiFePo4
hysteresis	float, °C	Hysteresis of the threshold value.	2

Battery cell temperature high while discharging check

Parent key: supervisor/temp_high_discharge

Key	Datatype, Unit	Description	Recommended Value
threshold	float, °C	Maximum temperature of a battery.	40 for LiFePo4
hysteresis	float, °C	Hysteresis of the threshold value.	2

Live consumption data lost while charging check

Parent key: supervisor/live_data_lost_charge

Key	Datatype, Unit	Description	Recommended Value
threshold	integer, s	Maximum time span without live consumption data in charge state.	300

Live consumption data lost while discharging check

Parent key: supervisor/live_data_lost_discharge

Key	Datatype, Unit	Description	Recommended Value
threshold	integer, s	Maximum time span without live consumption data in discharge state.	60

MQTT offline check

Parent key: supervisor/mqtt_offline

Key	Datatype, Unit	Description	Recommended Value
threshold	integer, s	Maximum time span without connection to the MQTT broker.	60

Device drivers

Parent key: devices/<device name>

<device name> must be unique.

Key	Datatype	Description	Recommended Value
driver	string	Device driver. Values are given in the sub-sections below.	n.a.

Battery

LLT Power BMS

Driver name: lltPowerBmsV4Ble

Key	Datatype	Description	Recommended Value
mac	string	Bluetooth MAC address of the device. Expected format is aa:bb:cc:dd:ee:ff.	n.a.

Daly H-Series Smart BMS via Bluetooth

Driver name: daly8S24V60A

Key	Datatype	Description	Recommended Value
mac	string	Bluetooth MAC address of the device. Expected format is aa:bb:cc:dd:ee:ff.	n.a.

JK BMS BD-Series

Driver name: jkBmsBd

Key	Datatype	Description	Recommended Value
mac	string	Bluetooth MAC address of the device. Expected format is aa:bb:cc:dd:ee:ff.	n.a.

Pylontech US series

Driver name: pylonLv

Key	Datatype	Description	Recommended Value
port	string	Expansion slot the addon board is connected to. Possible values are ext1 and ext2.	n.a.
serial	string	Serial number of the battery.	n.a.

MQTT battery

Driver name: mqttBattery

Key	Datatype	Description	Recommended Value
root_topic	string	MQTT root topic for the battery data sent from another homebattery controller. Value has the following scheme: <root>/bat/dev/<name>, where root is the MQTT root topic of the other homebattery controller and name is the device name of the battery.	n.a.

Solar charger

Generic Solar

Driver name: genericSolar

Key	Datatype, Unit	Description	Recommended Value
port	string, -	Expansion slot the addon board is connected to. Possible values are ext1 and ext2.	n.a.
address	integer, -	Modbus address of the connected power meter.	n.a.
current_range	int, A	Current range of the shunt. Possible values are 50, 100, 200 or 300.	n.a.
threshold	int, W	Minimum power that must be reached to consider the device as ‘on’.	n.a.

Victron SmartSolar MPPT / Victron BlueSolar MPPT

Driver name: victronMppt

Key	Datatype	Description	Recommended Value
port	string	Expansion slot the addon board is connected to. Possible values are ext1 and ext2.	n.a.

Grid charger

Shelly smart switch

Driver name: shellyCharger

Key	Datatype	Description	Recommended Value
host	string	Host address of the device. Expected format is <ip>:<port>	n.a.
generation	int	Device generation of the switch. Possible values are 1 or 2.	n.a.
relay_id	integer	Relay id of the used output. Value is 0 for single switch models, 0 and 1 for dual switch models.	n.a.

Inverter

AhoyDTU

Driver name: ahoyDtu

Key	Datatype	Description	Recommended Value
host	string	Host address of the device. Expected format is <ip>:<port>.	n.a.
id	integer	Id of the inverter. Value can be taken from the AhoyDTU web interface start page.	n.a.
power_lut	string	File name of the inverter power lookup table.	n.a.

OpenDTU

Driver name: openDtu

Key	Datatype	Description	Recommended Value
host	string	Host address of the device. Expected format is <ip>:<port>.	n.a.
password	string	OpenDTU password for write access.	n.a.
serial	string	Serial number of the inverter.	n.a.
power_lut	string	File name of the inverter power lookup table.	n.a.

Growatt

Driver name: growattinvertermodbus

Key	Datatype	Description	Recommended Value
port	string	Expansion slot the addon board is connected to. Possible values are ext1 and ext2.	n.a.
family	string	Inverter device family. Possible values are xx00-S and TL-X.	n.a.
address	interger	Modbus address of the inverter.	n.a.

Heater

Shelly smart switch

Driver name: shellyHeater

See Shelly smart switch.

Sensor

HTTP power

Driver name: httpConsumption

Key	Datatype, Unit	Description	Recommended Value
host	string	Host address of the sender. Expected format is 1.2.3.4:1883.	n.a.
query	string	HTTP query to retrieve data.	n.a.
path	list of strings	Path through the json data to the field containing the consumption data.	n.a.
interval	integer	Query interval in seconds.	2
factor	float	Factor the received consumption data is multiplied with. If the received data already has unit watt, the value is 1.0.	n.a.

MQTT power

Driver name: mqttConsumption

Key	Datatype, Unit	Description	Recommended Value
topic	string	MQTT topic where power data is published. The published data at this topic must be a 16 or 32 bit signed integer and must have the unit watt (W).	n.a.