homebattery2database

Writes data from homebattery devices to time series databases.

Introduction

This repository is part of the homebattery project. Its primary goal is to store data sent from one or more homebattery controllers into a timeseries database for further processing (visualization, statistics, etc.).

Currently, the following databases are supported:

• InfluxDB 1

Configuration

The configuration is done via yaml file. The example file can be found in config/sample.yaml

Key	Environment variable	Rules	Explanation
log -> level	-	string; DEBUG, INFO, WARN, ERROR or CRITICAL	Selected log level.
log -> path	-	string	Path to log file; if not set, no log file will be created.
log -> days	-	optional, int	If set, log files are deleted after the given number of days.
mqtt -> host	HB2DB_MQTT_HOST	string, <host>:<port>	Host and port of the MQTT server.
mqtt -> ca	-	optional, string	Enables TLS encryption and sets the path to the TLS public certificate chain file.
mqtt -> tls_insecure	-	optional, bool	If set to true, TLS encryption is enabled, but the TLS certificates are not checked (not recommended).
mqtt -> user	HB2DB_MQTT_USER	string	The user name for log in to the MQTT server.
mqtt -> password	HB2DB_MQTT_PASS	string	The password for log in to the MQTT server.
homebattery -> <shown name>	-	string	MQTT root topic of a controller. For multi controller setups, mutiple entries can be given.
influxdb_v1	-	optional	Enables InfluxDB 1 integration.
influxdb_v1 -> host	HB2DB_INFLUXV1_HOST	string, <host>:<port>	Host and port of the database server.
influxdb_v1 -> user	HB2DB_INFLUXV1_USER	string	User name for the database server.
influxdb_v1 -> password	HB2DB_INFLUXV1_PASS	string	Password for the database server.
influxdb_v1 -> database	-	string	Used database at the database server.

Usage without docker

Prerequisites

• Python 3 with pip + venv

This program should run on any OS, but I have no capacity to test this, so feedback is appreciated. My test machines run Ubuntu and Raspbian.

Install

git clone https://github.com/danielringch/homebattery2database.git
python3 -m venv <path to virtual environment>
source <path to virtual environment>/bin/activate
python3 -m pip install -r requirements.txt

Run

source <path to virtual environment>/bin/activate
python3 -B src/homebattery2database.py --config /path/to/your/config/file.yaml

Usage with docker

This software is also available as docker container:

docker pull danielringch/homebattery2database:latest

The container expects the configuration file at /config/homebattery2database.yaml

Example:

docker run --rm -it \
  -v /path/to/config/file:/config \
  -e HB2DB_MQTT_HOST="12.34.56.78:8883" \
  -e HB2DB_MQTT_USER="user" \
  -e HB2DB_MQTT_PASS="password" \
  danielringch/homebattery2database

Data format

Data is written to the database grouped by measurement type. Device and sensor information is added as tags. The timestamp is given in UTC time.

The following measurement types are supported:

type	explanation	unit
capacity	remaining capacity	Ah
current		A
energy	value since the last measurement	Wh
locked	whitespace separated system locks, only used by controller	-
mode	mode of operation, only used by controller	-
power		W
soc	value is given in percent	-
status	only used by connected devices	-
temperature		°C
voltage		V

The device class is added via the tag class_id. The following device classes are supported:

• battery
• charger
• controller
• heater
• inverter
• sensor
• solar

The device name is added via the tag device_id. The device names are configured in the homebattery controller the device is connected to.

For secondary sensors of a device (e.g. cell voltages), the sensor name is added via the tag sensor_id.

Get support

You have trouble getting started? Something does not work as expected? You have some suggestions or thoughts? Please let me know.

Feel free to open an issue here on github or contact me on reddit: 3lr1ng0.