Skip to content

Latest commit

 

History

History
233 lines (189 loc) · 15 KB

README.md

File metadata and controls

233 lines (189 loc) · 15 KB
Raw

Deye solar inverter MQTT bridge

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

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!

Inverter model Metric groups
Deye SUN-4/5/6/7/8/10/12K-G05-P string, settings
Deye SUN300/500G3-US-220/EU-230 micro, settings
Deye SUN600/800/1000G3-US-220/EU-230 micro, settings
Deye SUN-M60/80/100G3-EU-Q0 micro, settings
Deye SUN1300-2000G3-US-220/EU-230 micro, settings
Deye SUN-5/6/8/10/12K-SG04LP3 deye_sg04lp3, deye_sg04lp3_battery, deye_sg04lp3_ups, settings
Deye SUN-5/6K-SG01LP1-US/EU deye_hybrid, deye_hybrid_battery, settings
Deye SUN-7.6/8K-SG01LP1-US/EU deye_hybrid, deye_hybrid_battery, 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

Additional MQTT topics

Availability topic

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 is status and can be changed in the configuration.

Logger status topic

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 is logger_status and can be changed in the configuration.

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 metric group to DEYE_METRIC_GROUPS env variable.

Writing inverter settings

It is possible to modify selected inverter settings over MQTT. At the moment only active power regulation factor is supported. This feature is disabled by default.

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

Additional features

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.

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

  • Plugin is a Python file placed in plugins directory. The filename must begin with deye_plugin_
  • The plugin must define a DeyePlugin class. See plugins/deye_plugin_sample.py for inspiration.

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

Installation

  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

Configuration

All configuration options are controlled through environment variables.

  • LOG_LEVEL - application log level, can be any of DEBUG, INFO, WARN, ERROR, defaults to INFO
  • LOG_STREAM - log destination stream, can be any of STDOUT, STDERR, defaults to STDOUT
  • 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_sg04lp3 - sg04lp3 inverter
    • deye_sg04lp3_battery - sg04lp3 battery
    • deye_sg04lp3_ups - sg04lp3 ups
    • igen_dtsd422- dtsd422 smart meter
    • settings - inverter settings
  • DEYE_LOGGER_SERIAL_NUMBER - inverter data logger serial number
  • DEYE_LOGGER_IP_ADDRESS - inverter data logger IP address
  • DEYE_LOGGER_PORT - inverter data logger communication port, typically 8899
  • DEYE_FEATURE_MQTT_PUBLISHER - controls, if the service will publish metrics over mqtt, defaults to true
  • DEYE_FEATURE_SET_TIME - when set to true, the service will automatically set the inverter/logger time, defaults to false
  • DEYE_FEATURE_ACTIVE_POWER_REGULATION - enables active power regulation control over MQTT command topic
  • MQTT_HOST - MQTT Broker IP address
  • MQTT_PORT - MQTT Broker port, , defaults to 1883
  • MQTT_USERNAME - MQTT Broker username for authentication, defaults to None
  • MQTT_PASSWORD - MQTT Broker password for authentication, defaults to None
  • MQTT_TOPIC_PREFIX - mqtt topic prefix used for all inverter metrics, defaults to deye
  • MQTT_AVAILABILITY_TOPIC - mqtt availability topic, defaults to status
  • MQTT_LOGGER_STATUS_TOPIC - logger connectivity status topic, defaults to logger_status
  • MQTT_TLS_ENABLED - enables TLS encryption for the communication with the broker, defaults to false
  • MQTT_TLS_INSECURE - Set to true in order to skip server certificate verification, defaults to false
  • MQTT_TLS_CA_CERT_PATH - CA certificate location to be used instead of the system certification authority, defaults to None
  • MQTT_TLS_CLIENT_CERT_PATH - Client certificate location for TLS based authentication, defaults to None
  • MQTT_TLS_CLIENT_KEY_PATH - Client private key location for TLS based authentication, defaults to None
  • PLUGINS_DIR - Path to a directory containing custom plugins extending the functionality of the service

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.

  • 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)

Other related projects and resources

Development

Read CONTRIBUTING.md