search

kbialek / deye-inverter-mqtt

Reads Deye solar inverter metrics and posts them over MQTT
Apache License 2.0
230 stars 50 forks source link
bosswerk deye docker fujisolar inverter modbus mqtt solarman sunsynk

readme

Do you find this project useful? Buy me a coffee ☕ Donate

:sunny: Deye solar inverter MQTT bridge

Reads Deye solar inverter metrics using Modbus over ethernet and publishes them over MQTT.

Supports single inverter installations, as well as fleet of microinverters.

:bulb: Supported inverters and metrics

The meaning of certain inverter registers depends on the inverter type. You should choose metric group(s) that are appropriate to your inverter model. If your inverter is not listed below, it may still work with one of the already existing metric groups. Give it a try and experiment. In the worst case it won't work.

When your inverter is not supported, feel free to open an issue in this github project. Maybe, together we will find a way to add the support.

When your inverter turns out to work well with an already exiting metrics group, then please be so kind, and let me know in this issue. This will help in building the list of supported inverters below. Thanks!

The list below is built basing on the reports from the users. Compatiblity is not guaranteed.

Inverter model Metric groups
Deye SUN-4/5/6/7/8/10/12K-G05-P string, settings
[Deye Microinverters 300/500/600/800/1000/1300/2000]() micro, settings_micro
Deye Microinverters M60/M80/M100 micro, settings
Deye Microinverters M130/M160/M180/M200/M220 micro, settings
Deye SG04LP3 deye_sg04lp3, deye_sg04lp3_battery, deye_sg04lp3_ups, deye_sg04lp3_timeofuse, deye_sg04lp3_generator, settings
Deye SG01LP1 deye_hybrid, deye_hybrid_battery, deye_hybrid_bms, deye_hybrid_timeofuse, settings
Deye SG01HP3 deye_sg01hp3, deye_sg01hp3_battery, deye_sg01hp3_bms, deye_sg01hp3_ups, settings
Meter model Metric groups
IGEN DTSD422-D3 igen_dtsd422
Rebranded models Inverter model Metric groups
Bosswerk MI600 micro
Fuji Solar FU-SUN-4/5/6/7/8/10/12K-G05 string

:hammer_and_wrench: Installation

The communication with the logger can be performed using either Modbus/TCP or Modbus/AT protocol. This project has been started with Modbus/TCP protocol support and it's still the default one. However, logger firmware versions 2.x does not seem to expose Modbus/TCP interface anymore, hence Modbus/AT protocol support has been implemented. Use DEYE_LOGGER_PROTOCOL environment variable to select the communication protocol. Please note, that Modbus/TCP uses tcp/ip, while Modbus/AT uses udp/ip communication.

  1. Copy config.env.example as config.env
  2. Fill in values in config.env, see Configuration for more details

Option 1: Using Docker directly

  1. Run the container

    docker run -d --name deye-mqtt \
    --env-file config.env \
    --restart unless-stopped \
    ghcr.io/kbialek/deye-inverter-mqtt
    • -d will detach the container, so it will run in the background
    • --restart=unless-stopped will make docker to restart the container on host reboot
  2. Stop and remove the container 
    docker stop deye-mqtt
docker rm -v deye-mqtt
  3. Inspect the logs 
    docker logs deye-mqtt

Option 2: Using Docker Compose

  1. Create or modify your own docker-compose.yaml file. Here is a working example

  2. Run the container

    docker compose -f <path-to-docker-compose.yaml> up -d
    • replace <path-to-docker-compose.yaml> with path to your docker-compose.yaml
  3. Stop and remove the container 
    docker compose -f <path-to-docker-compose.yaml> down -v

Connecting to MQTT Broker over TLS

  1. Put certificates and client private key in a folder of your choice. The following files are required.

    1. ca.crt
    2. client.crt
    3. client.key

    Check configuration section if you want to use alternative file names.

  2. Mount certificates folder in a docker container by adding --volume option to the command as follows: 
    --volume <certs_folder>:/opt/deye_inverter_mqtt/certs:ro
    • replace <certs_folder> with the certificates folder location of your choice
  3. Enable TLS in the configuration. 
    MQTT_TLS_ENABLED=true
  4. Start the container

Installation troubleshooting

Docker container fails to start with error message: PermissionError: [Errno 1] Operation not permitted

It can happen on debian buster based linux distributions, including raspbian.

Solution: Install libseccomp2 from the backports

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 04EE7237B7D453EC 648ACFD622F3D138
echo "deb http://deb.debian.org/debian buster-backports main" | sudo tee -a /etc/apt/sources.list.d/buster-backports.list
sudo apt update
sudo apt install -t buster-backports libseccomp2

Network connectivity issues

These problems typically manifest with timeout errors.

The first thing to check is, if given network address is reachable from within the docker container. In order to do this run the following commands:

  1. Login to your docker host
  2. Start the container in shell mode: docker run --rm -ti --entrypoint /bin/sh ghcr.io/kbialek/deye-inverter-mqtt
  3. Install telnet by running apk update && apk add busybox-extras
  4. Check connectivity: telnet <ip> <port>
    1. Substitute <ip> and <port> with appropriate values
  5. You should see either:
    1. Connected to <ip> - connection works fine. The next step is to enable DEBUG logs in config.env and open a github issue
    2. telnet: can't connect to remote host (<ip>): Connection refused - The next step is: fix your network configuration

Random read timeouts

For best performance, multiple Modbus registers are read at once, in so called register ranges. It's been reported here that Deye-SUN-5K-SG03LP1 reading times out when more than 16 registers is requested at once. To mitigate this problem you may try to set DEYE_LOGGER_MAX_REG_RANGE_LENGTH to lower number.

:gear: Configuration

All configuration options are controlled through environment variables.

➕ Additional features

Additional MQTT topics

Availability topic

Reports deye-inverter-mqtt service status (not the inverter/logger status):

The default topic name is status and can be changed in the configuration.

Logger status topic

Reports solar inverter's logger connectivity status

The default topic name is logger_status and can be changed in the configuration.

Monitoring a fleet of microinverters

This feature enables monitoring of N microinverters from a single service instance (docker container), which simplifies the installation and configuration. It is designed to monitor a fleet of microinverters. To activate this feature, set DEYE_LOGGER_COUNT environment variable to the number of loggers you would like to connect to. Next configure each logger by adding a set of environment variables, as follows:

DEYE_LOGGER_{N}_IP_ADDRESS=192.168.XXX.YYY
DEYE_LOGGER_{N}_SERIAL_NUMBER=0123456789
# Optionals
DEYE_LOGGER_{N}_PROTOCOL=at
DEYE_LOGGER_{N}_PORT=48899
DEYE_LOGGER_{N}_MAX_REG_RANGE_LENGTH_PORT=256

Replace {N} with logger index. All loggers in the range of 1 to DEYE_LOGGER_COUNT must be configured.

All other configuration options, in particular the metric groups, are shared by all configured loggers. For example, if you set DEYE_FEATURE_SET_TIME=true, it will activate set-time feature for all configured loggers.

Each logger gets its own MQTT topic prefix {MQTT_TOPIC_PREFIX}/{N}

Additionally, you can enable multi-inverter data aggregation. Set DEYE_FEATURE_MULTI_INVERTER_DATA_AGGREGATOR=true to compute and report Aggregated daily energy and Aggregated AC active power for the entire fleet. See aggregated metrics

Automatically set logger/inverter time

Monitors current logger status and sets the time at the logger/inverter once the connection to it can be established. This is useful in a setup where the inverter has no access to the public internet, or is cut off from the Solarman cloud services. This feature is disabled by default and must be activated by setting DEYE_FEATURE_SET_TIME in the config file.

Reading inverter settings

The service can optionally read inverter settings. This feature may be useful when you dynamically modify active power regulation factor. Enable it by adding settings or settings_micro metric group to DEYE_METRIC_GROUPS env variable.

Writing inverter settings

It is possible to modify selected inverter settings over MQTT.

Setting Topic Unit Value range Feature flag
active power regulation {MQTT_TOPIC_PREFIX}/settings/active_power_regulation/command % 0-120 DEYE_FEATURE_ACTIVE_POWER_REGULATION
time of use {MQTT_TOPIC_PREFIX}/timeofuse/time/(1-6)/command time 0000 - 2359 DEYE_FEATURE_TIME_OF_USE
time of use {MQTT_TOPIC_PREFIX}/timeofuse/power/(1-6)/command W 0 - max power(1) DEYE_FEATURE_TIME_OF_USE
time of use {MQTT_TOPIC_PREFIX}/timeofuse/voltage/(1-6)/command V 0.00 - 63.00 DEYE_FEATURE_TIME_OF_USE
time of use {MQTT_TOPIC_PREFIX}/timeofuse/soc/(1-6)/command % 0 - 100 DEYE_FEATURE_TIME_OF_USE
time of use {MQTT_TOPIC_PREFIX}/timeofuse/enabled/(1-6)/command On/Off 0,1 DEYE_FEATURE_TIME_OF_USE
time of use {MQTT_TOPIC_PREFIX}/timeofuse/control/command string write, reset DEYE_FEATURE_TIME_OF_USE

(1) max inverter power in Watts e.g. 8000, 10000 or 12000

Writing Time Of Use configuration

Prerequisites:

  1. Set DEYE_FEATURE_TIME_OF_USE to true
  2. Enable time-of-use metric group that's appropriate to your inverter model, e.g. deye_sg04lp3_timeofuse

Time Of Use configuration is modified using the following workflow:

  1. The service reads Time Of Use configuration from the inverter and keeps it in the memory. This step happens automatically at each data read from the inverter.
  2. You send modifications over {MQTT_TOPIC_PREFIX}/timeofuse/*/*/command topics as needed. See the table above for more details about used MQTT topics. These changes are not immediately written to the inverter. They are buffered in the service memory instead.
  3. Send write command to topic {MQTT_TOPIC_PREFIX}/timeofuse/control/command. It will build a new Time Of Use configuration by putting your changes on top of the inverter configuration present in the service memory. Next the entire Time Of Use configuration is sent to the inverter. The modifications are cleared, and you can start over sending new modifications.
  4. Alternatively send reset command to purge buffered modifications without writing them to the inverter.

Publish on change feature

The Deye logger usually only updates the measurements only every 5 minutes, so that shorter DEYE_DATA_READ_INTERVAL values would provide duplicate readings of the same measurements. Increasing the read interval to 5 minutes is not a good solution since it is not known when the measurements are actually updated which could add a delay of one 5 min interval.

To get the latest measurements without much delay but still avoid publishing duplicate readings, the DEYE_PUBLISH_ON_CHANGE option can be enabled. With this feature, a new logger reading is only published if any of the new values differs from the previous reading.

For the rare case that none of the measurements may have changed between subsequent measurements, a maximum interval between two published messaged is configured with the variable DEYE_PUBLISH_ON_CHANGE_MAX_INTERVAL (default 360 seconds = 6 minutes).

Home Assistant integration

This project currently has no built-in integration with Home Assistant. You can use the Deye MQTT HA Plugin to integrate all data published via MQTT into Home Assistant.

🔌 Custom plugins

This feature allows advanced users to extend the functionality of this project. At the moment the plugins can be used to provide custom event processors. This means, that you can now process the readings as you like. No need to rely on MQTT at all anymore.

How to implement a plugin

How to start the docker container with custom plugins

Mount your plugins dir into the container filesystem

  --volume ./plugins:/opt/deye_inverter_mqtt/plugins:ro

List of public plugins

Reading and writing raw register values

The tool allows reading and writing raw register values directly in the terminal.

USE AT YOUR OWN RISK! Be sure to know what you are doing. Writing invalid values may damage the inverter. By using this tool you accept this risk, and you take full responsibility for the consequences.

👀 Other related projects and resources

Development

Read CONTRIBUTING.md