Configuration ============= Configuration is done using a json file ``config.json``, which is uploaded to homebattery via web interface, see :doc:`installation <../handbook/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. | 15 | | | | | | | | | If the system is not connected to the network after the timeout, the system | | | | | | | | | | restarts. | | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ | ``ntp_server`` | string, - | Optional. The host address of the ntp server. | time.google.com | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ | ``timezone`` | integer, - | Optional. The UTC offset of your timezone. | 1 for Berlin | | | | | | | | | The UTC offsets can be found here: | | | | | | | | | | https://en.wikipedia.org/wiki/List_of_UTC_offsets . | | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ | ``ntp_timeout`` | integer, s | Optional. The timeout for retriving time from the ntp server. | 10 | | | | | | | | | If no time was retrived from the ntp server after the timeout, the system | | | | | | | | | | continues without time sync. | | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ MQTT ---- Parent key: ``mqtt`` +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ | Key | Datatype | Description | Recommended Value | +========================+================+==================================================================================+===================+ | ``host`` | string | Host address of the MQTT broker. Expected format is ``:``. | n.a. | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ | ``tls``/``ca`` | string | Optional. Turns on TLS and sets the file name of the TLS CA chain certificate. | n.a. | | | | | | | | | The certificate must have DER encoding. | | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ | ``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. | homebattery | | | | | | | | | All MQTT topics the system is using will be sub-topics of this root topic | | | | | | | | | | (except for drivers using MQTT). | | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ Logging ------- Parent key: ``logging`` +------------------------+----------------+----------------------------------------------------------------------------------+-------------------------+ | Key | Datatype | Description | Recommended Value | +========================+================+==================================================================================+=========================+ | ``host`` | string | Optional. If given, logging messages will be send via UDP to this host. | n.a. | | | | | | | | | Expected format is ``:`` | | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------------+ | ``ignore`` | list of | Logging sender which debug messages shall be ignored. | n.a. | | | | | | | | strings | 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. | | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------------+ Inverter -------- Parent key: ``inverter`` +-------------------------------+----------------+------------------------------------------------------------------------------+-------------------+ | Key | Datatype, Unit | Description | Recommended Value | +===============================+================+==============================================================================+===================+ | ``power`` | int, W | Inverter power when in operation mode discharge. | n.a. | | | | | | | | | This value is only used if the netzero algorithm is not used. | | +-------------------------------+----------------+------------------------------------------------------------------------------+-------------------+ | ``reduce_power_during_fault`` | boolean, - | Reduces inverter power to minimum if any inverter switches to status fault. | false | | | | | | | | | This feature might be necessary when connecting multiple inverters to the | | | | | | | | | | batteries. | | +-------------------------------+----------------+------------------------------------------------------------------------------+-------------------+ 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 | n.a. | | | | | | | | | measure power fed into grid (which results in negative values for power | | | | | | | | | | consumption). | | +----------------------------+----------------+------------------------------------------------------------------------------+-------------------+ | ``evaluated_time_span`` | integer, s | Time span that will be evaluated, older data will be ignored. | 30 | | | | | | | | | The maximum value is 120. | | +----------------------------+----------------+------------------------------------------------------------------------------+-------------------+ | ``maturity_time_span`` | integer, s | Time span after an inverter power change during which netzero will not | 15 | | | | | | | | | increase inverter power. | | | | | | | | | | Independently from this value, netzero will not change inverter power with | | | | | | | | | | less than two data points. | | +----------------------------+----------------+------------------------------------------------------------------------------+-------------------+ | ``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``/```` ```` must be unique. +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | Key | Datatype | Description | Recommended Value | +========================+==========+==================================================================================+===================+ | ``driver`` | string | Device driver. Values are given in the sub-sections below. | n.a. | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ Battery ~~~~~~~ .. _confiuration_llt_power_bms: 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. | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ .. _confiuration_daly_8s_24v_60a: 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. | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ .. _confiuration_jk_bms_bd: 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. | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ .. _confiuration_pylontech_us_series: 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`` | n.a. | | | | | | | | | and ``ext2``. | | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | ``serial`` | string | Serial number of the battery. | n.a. | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ .. _confiuration_mqtt_battery: 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. | n.a. | | | | | | | | | Value has the following scheme: ``/bat/dev/``, where ``root`` is | | | | | | | | | | the MQTT root topic of the other homebattery controller and ``name`` is the | | | | | | | | | | device name of the battery. | | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ Solar charger ~~~~~~~~~~~~~ .. _confiuration_generic_solar: 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`` | n.a. | | | | | | | | | and ``ext2``. | | +------------------------+----------------+--------------------------------------------------------------------------------------+-------------------+ | ``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. | +------------------------+----------------+--------------------------------------------------------------------------------------+-------------------+ .. _confiuration_victron_mppt: 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`` | n.a. | | | | | | | | | and ``ext2``. | | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ Grid charger ~~~~~~~~~~~~ .. _confiuration_shelly_charger: Shelly smart switch ''''''''''''''''''' Driver name: ``shellyCharger`` +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | Key | Datatype | Description | Recommended Value | +========================+==========+==================================================================================+===================+ | ``host`` | string | Host address of the device. Expected format is ``:`` | 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, | n.a. | | | | | | | | | ``0`` and ``1`` for dual switch models. | | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ Inverter ~~~~~~~~ .. _confiuration_ahoy_dtu: AhoyDTU ''''''' Driver name: ``ahoyDtu`` +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | Key | Datatype | Description | Recommended Value | +========================+==========+==================================================================================+===================+ | ``host`` | string | Host address of the device. Expected format is ``:``. | n.a. | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | ``id`` | integer | Id of the inverter. Value can be taken from the AhoyDTU web interface start | n.a. | | | | | | | | | page. | | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | ``power_lut`` | string | File name of the inverter power lookup table. | n.a. | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ .. _confiuration_open_dtu: OpenDTU ''''''' Driver name: ``openDtu`` +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | Key | Datatype | Description | Recommended Value | +========================+==========+==================================================================================+===================+ | ``host`` | string | Host address of the device. Expected format is ``:``. | 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. | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ .. _confiuration_growatt: Growatt ''''''' Driver name: ``growattinvertermodbus`` +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | Key | Datatype | Description | Recommended Value | +========================+==========+==================================================================================+===================+ | ``port`` | string | Expansion slot the addon board is connected to. Possible values are ``ext1`` | n.a. | | | | | | | | | and ``ext2``. | | +------------------------+----------+----------------------------------------------------------------------------------+-------------------+ | ``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 ~~~~~~ .. _confiuration_shelly_heater: Shelly smart switch ''''''''''''''''''' Driver name: ``shellyHeater`` See :ref:`confiuration_shelly_charger`. Sensor ~~~~~~ .. _confiuration_http_power: 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. | n.a. | | | | | | | | | If the received data already has unit ``watt``, the value is ``1.0``. | | +------------------------+-----------------+----------------------------------------------------------------------------------+-------------------+ .. _confiuration_mqtt_power: MQTT power '''''''''' Driver name: ``mqttConsumption`` +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+ | Key | Datatype, Unit | Description | Recommended Value | +========================+================+==================================================================================+===================+ | ``topic`` | string | MQTT topic where power data is published. | n.a. | | | | | | | | | The published data at this topic must be a 16 or 32 bit signed integer and | | | | | | | | | | must have the unit watt (W). | | +------------------------+----------------+----------------------------------------------------------------------------------+-------------------+