Repository files navigation

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

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

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 thisissue. 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.

Rebranded models

The communication with the logger can be performed using one of three different protocols:

• Proprietary Deye Modbus/TCP protocol - used by inverters produced until 2024 (configuration code istcp)
• Proprietary Deye Modbus/AT protocol - used by inverters produced until 2024 (configuration code isat)
• Standard Modbus/TCP protocol - used by some? inverters produced starting from 2024 onwards. (configuration code ismbtcp)

This project has been started with proprietary Deye 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 proprietary Deye Modbus/AT protocol support has been implemented. UseDEYE_LOGGER_PROTOCOL environment variable to selectthe communication protocol.Please note, that Modbus/TCP uses tcp/ip, while Modbus/AT uses udp/ip communication.

1. Copyconfig.env.example asconfig.env
2. Fill in values inconfig.env, seeConfiguration for more details

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-mqttdocker rm -v deye-mqtt

3. Inspect the logs

   docker logs deye-mqtt

1. Create or modify your owndocker-compose.yaml file. Here isa 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 yourdocker-compose.yaml

3. Stop and remove the container

   docker compose -f <path-to-docker-compose.yaml> down -v

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

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

Solution: Installlibseccomp2 from the backports

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

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. Installtelnet by runningapk 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 inconfig.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

For best performance, multiple Modbus registers are read at once, in so called register ranges. It's been reportedhere 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 setDEYE_LOGGER_MAX_REG_RANGE_LENGTH to lower number.

All configuration options are controlled through environment variables.

• LOG_LEVEL - application log level, can be any ofDEBUG,INFO,WARN,ERROR, defaults toINFO
• LOG_STREAM - log destination stream, can be any ofSTDOUT,STDERR, defaults toSTDOUT
• DEYE_PUBLISH_ON_CHANGE - when set totrue, the event data will only be published if it has changed compared to last readings, defaults tofalse
• DEYE_PUBLISH_ON_CHANGE_MAX_INTERVAL - whenDEYE_PUBLISH_ON_CHANGE istrue, this variable defines the maximum age of a valid event list in seconds, defaults to 360 seconds
• DEYE_DATA_READ_INTERVAL - interval between subsequent data reads, in seconds, defaults to 60
• DEYE_METRIC_GROUPS - a comma delimited set of:
  • string - string inverter
  • micro - micro inverter
  • deye_hybrid - hybrid inverter
  • deye_hybrid_battery - hybrid inverter battery
  • deye_hybrid_timeofuse - hybrid inverter time-of-use settings
  • deye_sg04lp3 - sg04lp3 inverter
  • deye_sg04lp3_battery - sg04lp3 battery
  • deye_sg04lp3_ups - sg04lp3 ups
  • deye_sg04lp3_timeofuse - sg04lp3 time-of-use settings
  • deye_sg01hp3 - sg01hp3 inverter
  • deye_sg01hp3_battery - sg01hp3 battery
  • deye_sg01hp3_bms - sg01hp3 bms
  • deye_sg01hp3_ups - sg01hp3 ups
  • deye_sg01hp3_generator - tracks generation power and energy for each phase (1/2/3) and total (also works with Microinverter mode)
  • deye_sg01hp3_timeofuse - sg01hp3 time-of-use settings
  • igen_dtsd422- dtsd422 smart meter
  • settings - inverter settings, all types except micro
  • settings_micro - inverter settings for micro inverters
• DEYE_LOGGER_COUNT - declares the number of inverters, and therefore loggers to connect, optional, defaults to0, which means, that multi-inverter support is disabled
• DEYE_LOGGER_SERIAL_NUMBER orDEYE_LOGGER_{N}_SERIAL_NUMBER - inverter data logger serial number
• DEYE_LOGGER_IP_ADDRESS orDEYE_LOGGER_{N}_IP_ADDRESS - inverter data logger IP address
• DEYE_LOGGER_PORT orDEYE_LOGGER_{N}_PORT - inverter data logger communication port, optional, defaults to:
  • 8899 for proprietary Deye Modbus/TCP
  • 48899 for proprietary Deye Modbus/AT
  • 502 for standard Modbus/TCP
• DEYE_LOGGER_PROTOCOL orDEYE_LOGGER_{N}_PROTOCOL - inverter communication protocol, optional, defaults totcp, can be set to one of:
  • tcp for proprietary Deye Modbus/TCP
  • at for proprietary Deye Modbus/AT
  • mbtcp for standard Modbus/TCP
• DEYE_LOGGER_MAX_REG_RANGE_LENGTH orDEYE_LOGGER_{N}_MAX_REG_RANGE_LENGTH- controls maximum number of registers to be read in a single Modbus registers read operation, defaults to 256
• DEYE_FEATURE_MQTT_PUBLISHER - controls, if the service will publish metrics over mqtt, defaults totrue
• DEYE_FEATURE_SET_TIME - when set totrue, the service will automatically set the inverter/logger time, defaults tofalse
• DEYE_FEATURE_ACTIVE_POWER_REGULATION - enables active power regulation control over MQTT command topic
• DEYE_FEATURE_TIME_OF_USE - enables Time Of Use feature control over MQTT
• DEYE_FEATURE_MULTI_INVERTER_DATA_AGGREGATOR - enables multi-inverter data aggregation and publishing
• MQTT_HOST - MQTT Broker IP address
• MQTT_PORT - MQTT Broker port, , defaults to1883
• MQTT_USERNAME - MQTT Broker username for authentication, defaults toNone
• MQTT_PASSWORD - MQTT Broker password for authentication, defaults toNone
• MQTT_TOPIC_PREFIX - mqtt topic prefix used for all inverter metrics, defaults todeye
• MQTT_AVAILABILITY_TOPIC - mqtt availability topic, defaults tostatus
• MQTT_LOGGER_STATUS_TOPIC - logger connectivity status topic, defaults tologger_status
• MQTT_TLS_ENABLED - enables TLS encryption for the communication with the broker, defaults tofalse
• MQTT_TLS_INSECURE - Set to true in order to skip server certificate verification, defaults tofalse
• MQTT_TLS_CA_CERT_PATH - CA certificate location to be used instead of the system certification authority, defaults toNone
• MQTT_TLS_CLIENT_CERT_PATH - Client certificate location for TLS based authentication, defaults toNone
• MQTT_TLS_CLIENT_KEY_PATH - Client private key location for TLS based authentication, defaults toNone
• PLUGINS_DIR - Path to a directory containing custom plugins extending the functionality of the service
• PLUGINS_ENABLED - A list of plugin names that will be loaded when successfully discovered inPLUGINS_DIR, defaults to[]

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

• online - when the service is connected to the MQTT broker
• offline - when the service is disconnected from the MQTT broker

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

Reports solar inverter's logger connectivity status

• online - when the service connect to the logger successfully
• offline - when the service can't connect to the logger

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

This feature enables monitoring ofN 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, setDEYE_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.YYYDEYE_LOGGER_{N}_SERIAL_NUMBER=0123456789# OptionalsDEYE_LOGGER_{N}_PROTOCOL=atDEYE_LOGGER_{N}_PORT=48899DEYE_LOGGER_{N}_MAX_REG_RANGE_LENGTH_PORT=256

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

All other configuration options, in particular the metric groups, are shared by all configured loggers. For example, if you setDEYE_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. SetDEYE_FEATURE_MULTI_INVERTER_DATA_AGGREGATOR=true to compute and reportAggregated daily energy andAggregated AC active power for the entire fleet. Seeaggregated metrics

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 settingDEYE_FEATURE_SET_TIME in the config file.

The service can optionally read inverter settings. This feature may be useful when you dynamically modify active power regulation factor. Enable it by addingsettings orsettings_micro metric group toDEYE_METRIC_GROUPS env variable.

It is possible to modify selected inverter settings over MQTT.

⁽¹⁾ encodes the weekdays setting from Monday (bit 7) ... Sunday (bit 1). Additionally controls whether TimeOfUse feature is enabled or not (bit 0)

⁽²⁾ max inverter power in Watts e.g. 8000, 10000 or 12000

⁽³⁾ encodes the charging source, with Grid (bit 0) and Generator (bit 1).

Prerequisites:

1. SetDEYE_FEATURE_TIME_OF_USE totrue
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 arebuffered in the service memory instead.
3. Sendwrite 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 sendreset command to purge buffered modifications without writing them to the inverter.

The Deye logger usually only updates the measurements only every 5 minutes, so that shorterDEYE_DATA_READ_INTERVAL valueswould provide duplicate readings of the same measurements. Increasing the read interval to 5 minutes is not a good solutionsince 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, theDEYE_PUBLISH_ON_CHANGEoption can be enabled. With this feature, a new logger reading is only published if any of the new values differs from theprevious reading.

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

This project currently has no built-in integration withHome Assistant. You can use theDeye MQTT HA Plugin to integrate all data published viaMQTT intoHome Assistant.

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.

• Plugin is a Python file placed inplugins directory. The filename must begin withdeye_plugin_
• The plugin must define aDeyePlugin class. Seeplugins/deye_plugin_sample.py for inspiration.

Mount yourplugins dir into the container filesystem

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

• stdout-publisher by @hoegaarden
• Deye MQTT HA Plugin (mirrored onGitHub) by Carsten Grohmann

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.

• To read register value execute:

  docker run --rm --env-file config.env ghcr.io/kbialek/deye-inverter-mqtt r <reg_address>

  where<reg_address> is register address (decimal)

• To write register value execute:

  docker run --rm --env-file config.env ghcr.io/kbialek/deye-inverter-mqtt w <reg_address> <reg_value>

  where<reg_address> is register address (decimal), and <reg_value> is a value to set (decimal)

• https://github.com/StephanJoubert/home_assistant_solarman
• https://github.com/dasrecht/deye-firmware
• https://github.com/klatremis/esphome-for-deye
• https://github.com/Hypfer/deye-microinverter-cloud-free
• https://github.com/jedie/inverter-connect
• https://github.com/MichaluxPL/Sofar_LSW3
• https://github.com/s10l/deye-logger-at-cmd

ReadCONTRIBUTING.md