DOCSEARCHbyAlgolia
Submit Docs

Sunsynk Home Assistant Integration

website·Indexed 30 days ago

https://kellerza.github.io/sunsynk/

Documentation for enabling access to Deye and Sunsynk hybrid inverters within Home Assistant. Includes guides on installation via Docker or Home Assistant Add-Ons, RS485 wiring, mbusd configuration, sensor definitions, and Lovelace dashboard examples for energy management and power flow visualization.

Tokens
16.4K
Snippets
73
Records
108
Agent score
75%

What's inside Sunsynk

  1. Overview of Deye and Sunsynk Inverter Integration

    This project provides a way to access Deye Hybrid Inverters and Deye-branded inverters (such as Sunsynk) using a Python 3 library. It enables reading sensor values and writing settings via the Modbus protocol. The project is primarily delivered as a Python library and a Home Assistant OS Add-On.

  3. Understand the Sunsynk add-on startup process

    The add-on initializes in three distinct stages. If the process fails at any stage, check the logs for specific errors:

    1. Configuration Load: Loads config, sensor definitions, and schedules. Logs will flag unknown/deprecated sensors or custom sensor errors.
    2. Inverter Connection: Attempts to read inverter identity (registers 0–7) and rated power. If this fails, it indicates a cabling, configuration, or hardware issue. If successful, it verifies the serial number and reads all configured sensors.
    3. MQTT Connection: Publishes discovery data for Home Assistant. If this fails, entities will not appear in Home Assistant; check MQTT server settings.

  4. Deploy Sunsynk Multi as a standalone Docker service

    The Sunsynk Multi add-on can be run as a standalone Docker service without Home Assistant Core or Supervisor. It requires an MQTT broker to publish data. A common architecture uses mbusd to convert an RS-485 serial link to Modbus TCP, which the Sunsynk Multi service then consumes.
    services:
  sunsynk-multi:
    restart: unless-stopped
    image: ghcr.io/kellerza/hass-addon-sunsynk-multi:stable
    volumes:
      - ${PWD}/options.yaml:/data/options.yaml
      - /etc/localtime:/etc/localtime:ro
      - ${PWD}/mysensors.py:/share/hass-addon-sunsynk/mysensors.py # optional custom sensors

  mbusd:
    restart: unless-stopped
    image: 3cky/mbusd:0.5.3
    ports:
      - 502:502
    privileged: true
    volumes:
      - /dev/ttyRS485:/dev/ttyUSB0 # Replace /dev/ttyRS485 with your actual host device
      - ${PWD}/mbusd.conf:/etc/mbusd.conf

  5. Wire a dedicated RS485 port on Sunsynk/Deye inverters

    RS485 communication requires a twisted pair, typically using CAT5 network cable with RJ-45 connectors. The pinout depends on whether the connector is crimped using the T568A or T568B standard. If the outermost colors are brown and green, it is likely T568A; if brown and orange, it is likely T568B.
    RJ45 Pin (inverter side)Wire Color (T568A)Wire Color (T568B)RS485 pins
    1Green-WhiteOrange-WhiteB/D-
    2GreenOrangeA/D+
    3Orange-WhiteGreen-WhiteGND

  6. Create custom sensors using mysensors.py

    Custom sensors can be added by creating a file named mysensors.py in the /share/hass-addon-sunsynk/ directory (accessible via the Samba addon in Home Assistant). This file must expose a global SENSORS variable of type SensorDefinitions to which sensor definitions are added.

    Sensor definition parameters generally follow this order:

    1. Register number(s)
    2. Sensor name
    3. Unit (e.g., WATT, VOLT, AMPS)
    4. Scale factor (optional)

    Available sensor types include:

    • Sensor: Basic read-only sensor.
    • MathSensor: Combines multiple registers with mathematical operations.
    • NumberRWSensor: Read/write sensor for configurable numeric values.
    • SelectRWSensor: Read/write sensor with predefined options.
    • SwitchRWSensor: Read/write sensor for boolean values.
    from sunsynk import AMPS, CELSIUS, KWH, VOLT, WATT, Sensor, SensorDefinitions
from sunsynk.rwsensors import NumberRWSensor, SelectRWSensor, TimeRWSensor
from sunsynk.sensors import MathSensor, TempSensor

# Initialize the sensor definitions
SENSORS = SensorDefinitions()

# Add your custom sensors
SENSORS += (
    # Basic sensor example
    Sensor(178, "My Custom Power Sensor", WATT, -1),

    # Math sensor example (combining multiple registers)
    MathSensor((175, 172), "Custom Combined Power", WATT, factors=(1, 1)),

    # Read/Write sensor example
    NumberRWSensor(130, "Custom Control Setting", "%", min=0, max=100),
)

  7. Use the Home Assistant Sunsynk Add-On

    The Sunsynk Add-On for Home Assistant OS collects inverter values via Modbus and pushes them to Home Assistant using MQTT. It supports auto-discovery for sensors and flexible scheduling for reading and reporting data.

    Requirements:

    • Home Assistant OS
    • An RS-485 adapter to connect the hardware to the inverter.

  8. Deploy Sunsynk integration using Standard Home Assistant Add-on

    Use the standard deployment when the Inverter is physically close to the server or Single Board Computer (SBC) running Home Assistant. In this setup, the Sunsynk Add-on runs on Home Assistant OS, reads the Inverter's Modbus registers over RS-485, and publishes the sensor values to the MQTT server.

  10. Deploy Sunsynk integration via Modbus TCP to RTU/Serial Gateway

    When the Inverter is distant from the Home Assistant server, you can extend RS485 over Ethernet using a Modbus gateway. Options include:

    • Software-based gateways: Using a Raspberry Pi running software such as mbusd.
    • Commercial hardware: Using a dedicated Modbus gateway like the USR-W630.

  11. Connect to the DB9/Dongle port using RS-232

    The DB9 connector used for WiFi data loggers runs Modbus RTU at RS-232 levels (single-ended TX/RX), not RS-485. You must use a USB-to-RS-232 adaptor. Pin 9 typically provides +12Vdc power, and pin 5 is the signal ground.
    DB9 PinInverter signalConnect to (USB‑RS‑232)
    2TXAdaptor RX
    3RXAdaptor TX
    5D‑GNDGND
    9VdcTypically 12v

  12. Deploy Sunsynk integration as a standalone Docker container

    The Sunsynk integration can be run independently of Home Assistant by deploying it within a Docker container. This is useful for users who do not want a dependency on the Home Assistant OS environment.