Publish Modbus data from Sigenergy to MQTT, with optional Home Assistant Auto-Discovery and PVOutput updating
sigenergy2mqtt is a bridge between the Modbus interface of the Sigenergy energy system and the MQTT lightweight publish/subscribe messaging protocol.
In addition, sigenergy2mqtt has several optional features:
sigenergy2mqtt was inspired the Home Assistant integrations developed by TypQxQ.
sigenergy2mqtt was developed for my own use, and as such has only been tested in my single-phase environment without AC or DC chargers. In addition, there has been only cursory testing of the write functions. If you find a problem, please raise an issue.
You need to add my Home Assistant Add-ons repository first, and then you will be able to add the sigenergy2mqtt add-on.
Follow these steps to get the add-on repository installed on your Home Assistant system:
sigenergy2mqtt add-on in the Home Assistant Add-ons Storesigenergy2mqtt (hardware requirements are minimal: I use a Proxmox LXC with 2 cores and 256MiB RAM to run Mosquitto, ecowitt2mqtt and sigenergy2mqtt)Install sigenergy2mqtt via pip:
pip install sigenergy2mqtt
To run sigenergy2mqtt as a service that starts automatically in the background on system boot,
create the file /etc/systemd/system/sigenergy2mqtt.service with your favourite editor,
with the following contents:
[Unit]
Description=Publish Modbus data from Sigenergy to MQTT
Documentation=https://github.com/seud0nym/sigenergy2mqtt
After=network.target mosquitto.service
[Service]
Type=simple
User=sigenergy
Group=daemon
ExecStart=/usr/local/bin/sigenergy2mqtt
ExecReload=kill -HUP $MAINPID
KillMode=process
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
Notes:
sigenergy2mqtt on the same host/container as Mosquitto, remove mosquitto.service from the After= line.Once that is done, run the following commands:
useradd -m -g 1 sigenergy
systemctl enable sigenergy2mqtt.service
When you are ready to start the service, use this command:
systemctl start sigenergy2mqtt.service
To upgrade to a new release, install using pip with the --upgrade option:
pip install sigenergy2mqtt --upgrade
systemctl restart sigenergy2mqtt.service
sigenergy2mqtt is available via a Docker image from both Docker Hub and ghcr.io. It can be configured by using the environment variables listed below, or by placing your configuration file in the root of the /data volume,
Running the image is straightforward:
docker run -it \
-e SIGENERGY2MQTT_MQTT_BROKER=192.168.0.1 \
-e SIGENERGY2MQTT_MQTT_USERNAME=user \
-e SIGENERGY2MQTT_MQTT_PASSWORD=password \
-v /data:/data \
seud0nym/sigenergy2mqtt:latest
Note that you must provide persistent storage via the -v option to preserve the state of calculated accumulation sensors across executions. You can also place your configuration file in the root of this directory, rather than configuring via environment variables.
docker-compose users can find an example configuration file at docker-compose.yaml.
You can configure sigenergy2mqtt via the command line and/or environment variables, but using a persistent configuration file is a better option, as it provides access to all advanced feature configuration.
The complete list of configuration options with associated comments can be found in sigenergy2mqtt.yaml.
Example:
home-assistant:
enabled: true
mqtt:
broker: 127.0.0.1
username: ""
password: ""
modbus:
- host: sigenergy.local
inverters: [ 1 ]
pvoutput:
enabled: false
api-key: your_api_key
system-id: your_system_id
interval-minutes: 5
consumption: true
Notes:
inverters is the Device ID (slave address) as advised by your installer. It is usually 1. If you have multiple inverters, separate them with commas (e.g. [ 1,2 ])anonymous: true under mqtt.sensors-enabled-by-default to true. This setting only applies the first time that Home Assistant auto-discovers devices and entities; changing this configuration after first discovery will have no effect. Entities can be enabled and disabled through the Home Assistant user interface.sigenergy2mqtt.yaml is in /etc/. However, it will also be found in /data/. You can also use the -c command line option or the SIGENERGY2MQTT_CONFIG environment variable to specify a different location and/or filename.This configuration only works with Enphase Envoy firmware versions prefixed with D7 and D8. Add the Envoy host and login details to your sigenergy2mqtt configuration file:
...
modbus:
- host: your_sigenergy_ip_address
inverters: [ 1 ]
log-level: INFO
smart-port:
enabled: true
module:
name: enphase
host: your_enphase_envoy_ip_address
username: your_enphase_enlighten_username
password: your_enphase_enlighten_password
pv-power: EnphasePVPower
...
Notes:
name must be set to enphase.pv-power configuration must be set to EnphasePVPower to create the Plant Total PV Power sensor to accumulate the Enphase PV production and Sigenergy PV production.This configuration requires adding the MQTT topics to which sigenergy2mqtt will subscribe to get the third-party PV power production updates, and setting up an automation within Home Assistant to publish the third-party PV power production to MQTT whenever it changes.
sigenergy2mqtt Configuration File...
modbus:
- host: your_sigenergy_ip_address
inverters: [ 1 ]
log-level: INFO
smart-port:
enabled: true
mqtt:
- topic: sigenergy2mqtt/smartport/envoy_nnnnnnnnnn_current_power_production/state
gain: 1
...
Notes:
Create a new automation and enter a YAML configuration similar to this, using the entity_id that contains the current PV power production from your third-party inverter (this example uses Enphase again):
alias: Publish Envoy PV Production
description: "Update sigenergy2mqtt with the current PV production reported by Enphase Envoy"
triggers:
- trigger: state
entity_id:
- sensor.envoy_nnnnnnnnnn_current_power_production
conditions: []
actions:
- action: mqtt.publish
data:
topic: sigenergy2mqtt/smartport/envoy_nnnnnnnnnn_current_power_production/state
payload: "{{ trigger.to_state.state }}"
mode: queued
Notes:
sigenergy2mqtt configuration and the Home Assistant automation.Command line options override both environment variables and the configuration file.
-h, --help show this help message and exit
-c [SIGENERGY2MQTT_CONFIG], --config [SIGENERGY2MQTT_CONFIG]
The path to the JSON configuration file (default: /etc/sigenergy2mqtt.yaml)
-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
Set the log level. Valid values are: DEBUG, INFO, WARNING, ERROR or CRITICAL. Default is WARNING
(warnings, errors and critical failures)
-d SIGENERGY2MQTT_DEBUG_SENSOR, --debug-sensor SIGENERGY2MQTT_DEBUG_SENSOR
Specify a sensor to be debugged using either the full entity id, a partial entity id, the full sensor class name,
or a partial sensor class name. For example, specifying 'daily' would match all sensors with daily in their entity
name. If specified, --debug-level is also forced to DEBUG
--hass-enabled Enable auto-discovery in Home Assistant.
--hass-discovery-prefix [SIGENERGY2MQTT_HASS_DISCOVERY_PREFIX]
The Home Assistant MQTT Discovery topic prefix to use (default: homeassistant)
--hass-entity-id-prefix [SIGENERGY2MQTT_HASS_ENTITY_ID_PREFIX]
The prefix to use for Home Assistant entity IDs. Example: A prefix of 'prefix' will prepend 'prefix_' to entity IDs
(default: sigen)
--hass-unique-id-prefix [SIGENERGY2MQTT_HASS_UNIQUE_ID_PREFIX]
The prefix to use for Home Assistant unique IDs. Example: A prefix of 'prefix' will prepend 'prefix_' to unique IDs
(default: sigen). Once you have set this, you should NEVER change it, as it will break existing entities in
Home Assistant.
--hass-device-name-prefix [SIGENERGY2MQTT_HASS_DEVICE_NAME_PREFIX]
The prefix to use for Home Assistant entity names. Example: A prefix of 'prefix' will prepend 'prefix ' to names
(default: '')
--hass-discovery-only
Exit immediately after publishing discovery. Does not read values from the Modbus interface,
except to probe for device configuration.
-b [SIGENERGY2MQTT_MQTT_BROKER], --mqtt-broker [SIGENERGY2MQTT_MQTT_BROKER]
The hostname or IP address of an MQTT broker (default: 127.0.0.1)
--mqtt-port [SIGENERGY2MQTT_MQTT_PORT]
The listening port of the MQTT broker (default: 1883)
--mqtt-anonymous Connect to MQTT anonymously (i.e. without username/password).
-u [SIGENERGY2MQTT_MQTT_USERNAME], --mqtt-username [SIGENERGY2MQTT_MQTT_USERNAME]
A valid username for the MQTT broker
-p [SIGENERGY2MQTT_MQTT_PASSWORD], --mqtt-password [SIGENERGY2MQTT_MQTT_PASSWORD]
A valid password for the MQTT broker username
--mqtt-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
Set the paho.mqtt log level. Valid values are: DEBUG, INFO, WARNING, ERROR or CRITICAL.
Default is WARNING (warnings, errors and critical failures)
-m [SIGENERGY2MQTT_MODBUS_HOST], --modbus-host [SIGENERGY2MQTT_MODBUS_HOST]
The hostname or IP address of the Sigenergy device
--modbus-port [SIGENERGY2MQTT_MODBUS_PORT]
The Sigenergy device Modbus port number (default: 502)
--modbus-slave [SIGENERGY2MQTT_MODBUS_INVERTER_SLAVE]
The Sigenergy Inverter Modbus Device ID (Slave ID). May be specified multiple times.
--modbus-accharger-slave [SIGENERGY2MQTT_MODBUS_ACCHARGER_SLAVE]
The Sigenergy AC Charger Modbus Device ID (Slave ID).
--modbus-dccharger-slave [SIGENERGY2MQTT_MODBUS_DCCHARGER_SLAVE]
The Sigenergy DC Charger Modbus Device ID (Slave ID).
--modbus-readonly Only publish read-only sensors to MQTT. Neither read-write or write-only sensors will be
published if specified.
--modbus-no-remote-ems
Do not publish any read-write sensors for remote Energy Management System (EMS) integration to MQTT.
Ignored if --modbus-read-only is specified.
--modbus-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
Set the pymodbus log level. Valid values are: DEBUG, INFO, WARNING, ERROR or CRITICAL.
Default is WARNING (warnings, errors and critical failures)
--scan-interval-low [SIGENERGY2MQTT_SCAN_INTERVAL_LOW]
The scan interval in seconds for Modbus registers that are to be scanned at a low frequency. Default is 600 (seconds), and the minimum value is 300.
--scan-interval-medium [SIGENERGY2MQTT_SCAN_INTERVAL_MEDIUM]
The scan interval in seconds for Modbus registers that are to be scanned at a medium frequency. Default is 60 (seconds), and the minimum value is 30.
--scan-interval-high [SIGENERGY2MQTT_SCAN_INTERVAL_HIGH]
The scan interval in seconds for Modbus registers that are to be scanned at a high frequency. Default is 10 (seconds), and the minimum value is 5.
--scan-interval-realtime [SIGENERGY2MQTT_SCAN_INTERVAL_REALTIME]
The scan interval in seconds for Modbus registers that are to be scanned in near-real time. Default is 5 (seconds), and the minimum value is 1.
--smartport-enabled Enable interrogation of a third-party device for production data.
--smartport-module-name [SIGENERGY2MQTT_SMARTPORT_MODULE_NAME]
The name of the module which will be used to obtain third-party device production data.
--smartport-host [SIGENERGY2MQTT_SMARTPORT_HOST]
The IP address or hostname of the third-party device.
--smartport-username [SIGENERGY2MQTT_SMARTPORT_USERNAME]
The username to authenticate to the third-party device.
--smartport-password [SIGENERGY2MQTT_SMARTPORT_PASSWORD]
The password to authenticate to the third-party device.
--smartport-pv-power [SIGENERGY2MQTT_SMARTPORT_PV_POWER]
The sensor class to hold the production data obtained from the third-party device.
--smartport-mqtt-topic [SIGENERGY2MQTT_SMARTPORT_MQTT_TOPIC]
The MQTT topic to which to subscribe to obtain the production data for the third-party device.
--smartport-mqtt-gain [SIGENERGY2MQTT_SMARTPORT_MQTT_GAIN]
The gain to be applied to the production data for the third-party device obtained from the MQTT topic.
(e.g. 1000 if the data is in kW) Default is 1 (Watts).
--pvoutput-enabled Enable status updates to PVOutput.
--pvoutput-api-key [SIGENERGY2MQTT_PVOUTPUT_API_KEY]
The API Key for PVOutput
--pvoutput-system-id [SIGENERGY2MQTT_PVOUTPUT_SYSTEM_ID]
The PVOutput System ID
--pvoutput-consumption
Enable sending consumption status to PVOutput.
--pvoutput-interval [SIGENERGY2MQTT_PVOUTPUT_INTERVAL]
The interval in minutes to send data to PVOutput (default: 5). Valid values are 5, 10 or 15 minutes.
--pvoutput-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
Set the PVOutput log level. Valid values are: DEBUG, INFO, WARNING, ERROR or CRITICAL. Default is WARNING
(warnings, errors and critical failures)
--clean Publish empty discovery to delete existing devices, then exits immediately.
-v, --version Shows the version number, then exits immediately.
Environment variables override the configuration file, but not command line options.
SIGENERGY2MQTT_CONFIG :
SIGENERGY2MQTT_LOG_LEVEL :
SIGENERGY2MQTT_DEBUG_SENSOR :
SIGENERGY2MQTT_HASS_ENABLED :
SIGENERGY2MQTT_HASS_DISCOVERY_PREFIX :
SIGENERGY2MQTT_HASS_ENTITY_ID_PREFIX :
SIGENERGY2MQTT_HASS_UNIQUE_ID_PREFIX :
SIGENERGY2MQTT_HASS_DEVICE_NAME_PREFIX :
SIGENERGY2MQTT_HASS_DISCOVERY_ONLY:
SIGENERGY2MQTT_MQTT_BROKER :
SIGENERGY2MQTT_MQTT_PORT :
SIGENERGY2MQTT_MQTT_ANONYMOUS :
SIGENERGY2MQTT_MQTT_USERNAME :
SIGENERGY2MQTT_MQTT_PASSWORD :
SIGENERGY2MQTT_MQTT_LOG_LEVEL :
SIGENERGY2MQTT_MODBUS_HOST :
SIGENERGY2MQTT_MODBUS_PORT :
SIGENERGY2MQTT_MODBUS_INVERTER_SLAVE :
SIGENERGY2MQTT_MODBUS_ACCHARGER_SLAVE :
SIGENERGY2MQTT_MODBUS_DCCHARGER_SLAVE :
SIGENERGY2MQTT_MODBUS_NO_REMOTE_EMS:
SIGENERGY2MQTT_MODBUS_READ_WRITE is false.SIGENERGY2MQTT_MODBUS_READ_ONLY :
SIGENERGY2MQTT_MODBUS_READ_WRITE :
SIGENERGY2MQTT_MODBUS_WRITE_ONLY :
SIGENERGY2MQTT_MODBUS_LOG_LEVEL :
SIGENERGY2MQTT_SMARTPORT_ENABLED :
SIGENERGY2MQTT_SMARTPORT_MODULE_NAME :
SIGENERGY2MQTT_SMARTPORT_HOST :
SIGENERGY2MQTT_SMARTPORT_USERNAME :
SIGENERGY2MQTT_SMARTPORT_PASSWORD :
SIGENERGY2MQTT_SMARTPORT_PV_POWER :
SIGENERGY2MQTT_SMARTPORT_MQTT_TOPIC :
SIGENERGY2MQTT_SMARTPORT_MQTT_GAIN :
SIGENERGY2MQTT_SCAN_INTERVAL_LOW :
SIGENERGY2MQTT_SCAN_INTERVAL_MEDIUM :
SIGENERGY2MQTT_SCAN_INTERVAL_HIGH :
SIGENERGY2MQTT_SCAN_INTERVAL_REALTIME :
SIGENERGY2MQTT_PVOUTPUT_ENABLED :
SIGENERGY2MQTT_PVOUTPUT_API_KEY :
SIGENERGY2MQTT_PVOUTPUT_SYSTEM_ID :
SIGENERGY2MQTT_PVOUTPUT_CONSUMPTION :
SIGENERGY2MQTT_PVOUTPUT_INTERVAL :
SIGENERGY2MQTT_PVOUTPUT_LOG_LEVEL :
If you are using Home Assistant, you can set the current values for the daily and lifetime accumulation sensors from the mySigen app through the MQTT device screen. The screen contains controls for inputting the values. Make sure you enter lifetime values first, because daily sensors use the lifetime numbers as their base.
The topics that are published and subscribed to by sigenergy2mqtt can be found here.
For each host defined in the modbus section of the configuration file, an MQTT device will be created in Home Assistant. The first device will be called Sigenergy Plant (plant is the terminology used in the "Sigenergy Modbus Protocol", and is in the context of a power plant). Each plant will have one or more related devices, such as Sigenergy Plant Grid Sensor and if applicable, Sigenergy Plant Smart-Port. Plants will also have associated inverters, and their names will include the model and serial number (e.g. SigenStor CMUxxxxxxxxxx Energy Controller). Each inverter will have an an Energy Storage System device (e.g. SigenStor CMUxxxxxxxxxx ESS) and as many PV String devices as the inverter supports. Chargers will be named Sigenergy AC Charger and Sigenergy DC Charger.
Example:
Sigenergy Plant
├─ Sigenergy Plant Grid Sensor
├─ SigenStor Plant Smart-Port
├─ SigenStor CMUxxxxxxxxxx Energy Controller (ID 1)
│ ├─ SigenStor CMUxxxxxxxxxx ESS
│ ├─ SigenStor CMUxxxxxxxxxx PV String 1
│ ├─ SigenStor CMUxxxxxxxxxx PV String 2
│ ├─ SigenStor CMUxxxxxxxxxx PV String 3
│ ├─ SigenStor CMUxxxxxxxxxx PV String 4
│ └─ Sigenergy DC Charger
└─ SigenStor CMUyyyyyyyyyy Energy Controller (ID 2)
├─ SigenStor CMUyyyyyyyyyy ESS
├─ SigenStor CMUyyyyyyyyyy PV String 1
├─ SigenStor CMUyyyyyyyyyy PV String 2
└─ Sigenergy DC Charger
For simple Sigenergy systems, with no integrated legacy solar system or requirement to integrate with PVOutput, the Sigenergy Local Modbus HACS integration may be a better alternative for integration with Home Assistant.
| Feature | Sigenergy Local Modbus | sigenergy2mqtt (Linux) | sigenergy2mqtt (HA Add-on) | Comments |
|---|---|---|---|---|
| Pre-requisites | None | Python, MQTT broker | None | |
| Installation | GUI | Manual | GUI | |
| Configuration | GUI | Edit configuration file | GUI and/or config file | |
| Home Assistant | HACS Integration | Optional MQTT Auto-discovery | MQTT Auto-discovery | |
| PVOutput | No | Optional | Optional | |
| Third-Party Solar included in production and consumption | No | Optional | Optional | Since the V100R001C00SPC108 firmware update, production systems connected to the Sigenergy Gateway Smart-Port are no longer included in the PV Power reported by the Modbus interface. However, this may change in future firmware releases. |
FAQs
Publish Modbus data from Sigenergy to MQTT, with optional Home Assistant Auto-Discovery and PVOutput updating
We found that sigenergy2mqtt demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.