Deye-2-MQTT

A lightweight unofficial Modbus-to-MQTT bridge for Deye / Sunsynk / Sun-SG04 hybrid inverters.

Designed for RS485 monitoring setups and especially for German §14a EnWG installations where an IVG NetSync (IVG Sync Box) already acts as the Modbus master.

Deye-2-MQTT primarily operates as a passive listener that observes existing Modbus traffic without interfering with the bus, but it can also run as a Modbus polling master when no other master is present.

Unlike many Ethernet-based Deye MQTT bridges, this project focuses on RS485 installations and can passively observe an existing Modbus master such as IVG NetSync. The polling mode mainly exists as an alternative option for standalone setups or testing environments where no other Modbus master is present.

---

§14a EnWG (German regulation) / IVG NetSync Architecture

flowchart LR

GRID["🔌 <br> Power Grid"]

subgraph SMART["Smart Meter"]
    IR["🔍 <br> IR Optical Reader"]
    A14["⚡ <br> §14a Control Output"]
end

subgraph MODBUS["RS485 / Modbus Bus"]
    INV["☀️ <br> Deye Inverter"]
    SYNC["🔀 <br> IVG Sync Box"]
    READER["USB-RS485 Adapter"]
end

subgraph PI["🧠 - Raspberry Pi"]
    D2M["Deye-2-MQTT"]
    S2M["sml2mqtt"]
    MQTT["📡 <br> MQTT Broker"]
end

subgraph HA["🏠 - Home Assistant"]
    HAINT["MQTT Integration"]
end


GRID --> SMART

IR -- Serial --> S2M
S2M -- MQTT Publish --> MQTT

A14 -- Load Control --> SYNC

SYNC -. Modbus RTU (Reader) .- READER
READER -- Serial --> D2M
D2M -- MQTT Publish --> MQTT

SYNC -- Modbus RTU --> INV

PI -- Log Browser --> SYNC

MQTT -. MQTT .- HAINT


classDef lib fill:#d32f2f,stroke:#b71c1c,stroke-width:3px,color:#ffffff;
classDef modbus stroke:#ffc4a6,stroke-width:2px;

class D2M lib
class MODBUS modbus


linkStyle 0 stroke:#2e7d32,stroke-width:3px
linkStyle 1 stroke:#555,stroke-width:3px
linkStyle 2 stroke:#1565c0,stroke-width:3px
linkStyle 3 stroke:#555,stroke-width:3px
linkStyle 4 stroke:#ef6c00,stroke-width:3px
linkStyle 5 stroke:#555,stroke-width:3px
linkStyle 6 stroke:#1565c0,stroke-width:3px
linkStyle 7 stroke:#ef6c00,stroke-width:3px
linkStyle 8 stroke:#555,stroke-width:3px
linkStyle 9 stroke:#1565c0,stroke-width:3px

Loading

Note

🇩🇪 Deutschland -- §14a EnWG

In vielen deutschen Installationen wird ein IVG NetSync eingesetzt, um Anforderungen aus §14a EnWG zu erfüllen.
Dabei kann der Netzbetreiber steuerbare Verbraucher bei Netzengpässen regeln.

Der IVG NetSync fungiert als Modbus‑Master und kommuniziert mit dem Wechselrichter über RS485.

Der Modus ivg_reader wurde speziell für solche Systeme entwickelt:
deye2mqtt arbeitet als passiver Listener, der vorhandenen Modbus‑Traffic mitliest, ohne selbst Anfragen zu senden.

---

🇬🇧 Germany -- §14a EnWG

Many installations in Germany include an IVG NetSync device (often referred to as IVG Sync Box) to comply with §14a EnWG grid control requirements.

In these setups the IVG NetSync acts as the Modbus master communicating with the inverter via RS485.

The ivg_reader mode of deye2mqtt is designed for this scenario:
it operates as a passive listener, observing existing Modbus traffic without sending requests or interfering with the bus.

---

⚡ Features

• Reads Modbus holding and input registers
• Publishes structured values to MQTT
• YAML configuration (~/.config/deye2mqtt/config.yaml)
• Designed for Home Assistant integration
• Supports passive RS485 monitoring
• Runs as systemd service
• Uses isolated Python virtual environments

---

⚠️ Disclaimer

Important

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with any company, brand, product, or service.

This explicitly includes (redundantly listed for clarity):

• Ningbo Deye Inverter Technology Co., Ltd. (Deye)
• IVG Energy Solutions GmbH
• Products and names such as "Deye", "Sunsynk", or "IVG" / "IVG NetSync" / "IVG Sync Box"

Any brand references are used only to identify compatible hardware platforms.

This is an unofficial community project created for personal/home automation use.

Caution

This software is provided "AS IS", without any warranty. You use it at your own risk.

I accept no liability for:

• incorrect inverter configuration
• electrical damage
• wrong measurements
• data loss
• any consequences of using this software

Only use this if you fully understand what you are doing. Working with electrical systems is inherently dangerous.

---

🔀 Operating Modes

Two modes are supported.

---

ivg_reader (listener mode)

deye2mqtt does not generate Modbus requests and passively listens to traffic generated by another Modbus master.

Note

The ivg_reader mode requires an existing Modbus master on the RS485 bus (for example an IVG NetSync).

If no master exists, no inverter data will be received.

Note

The device commonly known as IVG Sync Box is officially named IVG NetSync. Both names refer to the same hardware produced by IVG Energy Solutions.

---

polling (master mode, experimental)

deye2mqtt actively sends Modbus requests on the RS485 bus and performs polling itself. This mode is mainly intended for standalone setups or testing environments where no other Modbus master is present.

Caution

The polling mode has not yet been widely tested.

Warning

Running multiple Modbus masters on the same RS485 bus may cause communication conflicts and unstable inverter behaviour.

If another master already exists, do not use polling mode.

---

🧭 Mode Selection

Scenario	polling	ivg_reader
Standalone inverter monitoring	✅ Required	❌ Will not work
System with IVG NetSync / Sync Box	❌ Bus conflict risk	✅ Recommended
Unknown / shared RS485 environment	⚠️ Test carefully	✅ Safe choice

---

📦 Installation

1. Clone repository

git clone https://github.com/pahibu/deye-2-mqtt.git
cd deye-2-mqtt

2. Create virtual environment

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

3. Configuration

mkdir -p ~/.config/deye2mqtt
cp config/config.example.yaml ~/.config/deye2mqtt/config.yaml
nano ~/.config/deye2mqtt/config.yaml

Configuration templates:

• config/config.example.yaml -- debug configuration
• config/config.production.yaml -- recommended service setup
• config/config.polling.master.example.yaml -- master polling example

---

🚀 Run manually

DEYE2MQTT_CONFIG=~/.config/deye2mqtt/config.yaml venv/bin/python -m deye2mqtt

---

🔧 Systemd Service

Install service template:

sudo cp contrib/systemd/deye2mqtt.service.example /etc/systemd/system/deye2mqtt.service
sudo nano /etc/systemd/system/deye2mqtt.service

Enable service:

sudo systemctl daemon-reload
sudo systemctl enable --now deye2mqtt.service

Logs:

journalctl -u deye2mqtt.service -f

---

🧪 Debugging

For Modbus register validation use the debug configuration:

config/config.example.yaml

Compare values with inverter display or vendor apps.

---

❤️ Contributing

Pull requests are welcome.

Especially for:

• additional inverter register mappings
• bug fixes
• documentation improvements
• MQTT schema enhancements