DOCSEARCHbyAlgolia
Submit Docs

Sunsynk Library and Home Assistant Add-On

repository·main·Indexed 43 days ago

https://github.com/kellerza/sunsynk

A Python library (v1.2.0) and Home Assistant Add-On for interfacing with Deye and Sunsynk hybrid inverters. It provides programmatic access via Modbus TCP, UDP, and Serial, and includes a Modbus TCP to Modbus RTU Gateway to bridge RS-485 connections to MQTT. Features include multi-inverter support, auto-discovery for Home Assistant, and a component-based architecture for PV sensor readings.

Tokens
33.2K
Snippets
72
Records
134
Agent score
56%

What's inside Sunsynk

  1. Overview of the Sunsynk Inverter Add-on (Multi)

    main

    The Sunsynk Inverter Add-on (Multi) is a Home Assistant add-on designed to read data from Sunsynk inverters and push the sensor data to MQTT.

    Key features include:

    • Multi-Inverter Support: Ability to manage and read from multiple inverters simultaneously.
    • MQTT Integration: Pushes inverter sensor data to an MQTT broker.
    • Home Assistant Auto-discovery: Automatically configures entities in Home Assistant via MQTT discovery.
    • Configurability: Allows users to update and manage specific inverter settings.

  2. Overview of Deye/Sunsynk Home Assistant Addon

    main

    The Deye/Sunsynk Home Assistant Addon allows you to take control of your inverter and integrate it with Home Assistant. Key capabilities include:

    • Energy Management: Enables the Home Assistant Energy Management feature using data from your inverter.
    • Power Flow Visualization: Provides real-time visualization of immediate power flow with reaction times as fast as 1 second.
    • Inverter Settings: Allows remote updates to System Mode Settings. If a specific system mode is not natively supported, you can use Home Assistant automations to achieve control.
    • Broad Compatibility: Supports Sunsynk, Deye, and Turbo-Energy inverters (both single and three-phase). It works with multiple inverters via RS485 or Solarman and supports custom sensors for increased flexibility.

  3. Use the Sunsynk Inverter Add-on (Edge / Development version)

    main
    The Edge/Development version of the Sunsynk Inverter Add-on contains the latest changes committed to the GitHub repository. This version is intended for developers or users who want to test the most recent features and fixes before they are officially released. Use this version if you need functionality that has been committed to the repository but not yet included in a stable release.

  4. Use the Modbus TCP to Modbus RTU Gateway Add-on

    main

    This add-on functions as a Modbus TCP server that acts as an RTU client. It is designed to bridge communication by requesting data from Modbus RTU servers (such as physical hardware connected via RS-485) and exposing that data over a TCP interface.

    Common use cases include:

    • Testing Modbus configurations.
    • Deploying on low-spec hardware (e.g., Raspberry Pi 1b) to convert an RS-485 connection into a TCP-accessible network service.

  5. Choose the correct Sunsynk/Deye Add-on version

    main

    The repository provides several specialized add-ons depending on your requirements:

    • Sunsynk/Deye Inverter Add-on (multi): The recommended version. It supports multiple inverters and custom sensors. Most documentation on this site refers to this version.
    • Sunsynk/Deye Inverter Add-on (edge/dev): The developer version containing the latest changes from the GitHub repository.
    • Modbus TCP to Modbus RTU Gateway Add-on: An mbusd TCP to RTU gateway.
    • EskomSePush Add-on: Allows querying loadshedding schedules via the EskomSePush API.

  6. Single-phase register backfill proposal status

    main

    Status: NOT IMPLEMENTED — plan only.

    The sensors listed in this proposal have not yet been added to the project's definitions. This document serves as a backlog and reference for adding new single-phase sensors by comparing the existing single-phase profile (src/sunsynk/definitions/single_phase.py) with register dumps from the Sunsynk API.

    Key information for developers:

    • The API register numbers align closely with the existing single-phase Modbus map.
    • Core sensors (rated power, run state, energy counters, faults, PV, grid, battery, etc.) are already mapped.
    • This document identifies high-value and lower-priority sensors to be added in future updates.

  7. What is mbusd and how does it function?

    main

    mbusd is an open-source Modbus TCP to Modbus RTU (RS-232/485) gateway. It functions as a TCP server that acts as an RTU client to retrieve data from Modbus RTU servers, presenting a network of RTU servers as a single TCP server.

    In the context of the Sunsynk Home Assistant repository, it is provided as the "Modbus TCP to Modbus RTU Gateway Add-on."

  8. How the Home Assistant add-on handles retries and stale inverters

    main

    The Home Assistant add-on implements several layers of error handling and recovery above the driver level:

    LayerBehaviour
    read_sensors_retry()Up to 3 attempts per scheduled read, 0.2s apart; then retries one sensor at a time if the batch failed
    Stale quietAfter STALE_INVERTER_AFTER_SECONDS without a successful read, skip Modbus for STALE_INVERTER_SKIP_SECONDS, then probe identity
    Timeout counterSunsynk.timeouts increments on timeout; exposed as the RS485 timeout MQTT sensor

    These behaviors apply to Modbus (serial/TCP) and Solarman transports.

  9. Understand Modbus roles for Sunsynk inverters

    main

    When using the Sunsynk Add-On, it is important to understand the Modbus terminology used to describe the connection between the add-on and the inverter:

    • Client: The device that initiates requests. The Sunsynk Add-On is the Client.
    • Server: The device that processes requests and sends replies. The inverter is the Server. The MODBUS_ID corresponds to the inverter's Modbus Serial Number (Modbus SN).

    Key Notes:

    • Multiple servers (inverters) can share a single RS485 bus if each has a unique MODBUS_ID.
    • In three-phase Parallel Mode, every inverter remains a Modbus server, even if the inverter's LCD displays 'Master/Slave' terminology.

  10. How PV sensors work via Components

    main

    The project uses a Component-based architecture for PV (Photovoltaic) readings. Instead of reading individual registers for every sensor, a Component defines a register map family.

    Key Concepts:

    • Component as Layout Map: The Component class (e.g., PVSinglePhase, PVThreePhase) defines the full register layout. It is not configuration-aware.
    • Selective Reads: To optimize Modbus traffic, the system uses Component.restrict_fields() at runtime. This ensures that only the registers required by the user's active configuration are actually polled.
    • Sensor vs. Component: The Component owns the register layout and handles the Modbus read, while Sensor remains the high-level Home Assistant (HA) or mysensors view.
    • PV Power Summation: The pv_power sensor is a SumSensor. It does not read a Modbus register directly; instead, it calculates a sum of the active pvN_power sensors in the InverterState.

    Summation Rules for pv_power:

    • If you enable pv1_power + pv2_power + pv_power, the total is pv1 + pv2.
    • If you enable pv_power alone, the system automatically tracks all pvN_power sensors for that profile as hidden dependencies (they are polled but no individual HA entities are created) to calculate the total.
    • If you only enable pv1_voltage, no power fields are read and pv_power is not calculated.

  11. How schedules work to control sensor reading and reporting

    main

    Schedules allow you to define how often the system reads sensors from the inverter and how often it reports those values to MQTT or Home Assistant. Schedules are applied based on a specific search order, allowing you to target specific sensors by name, by their unit, or by general categories.

    When configuring schedules, the system follows this priority order to find a match for a sensor:

    1. Specific Name: A direct match for the sensor's name.
    2. rw: Sensors designated as Read & Write (configuration sensors).
    3. Unit: A match for the sensor's unit (e.g., W, V, A, kWh).
    4. any_unit: A catch-all for sensors that have a unit assigned.
    5. no_unit: A catch-all for sensors without any unit (typically non-numeric sensors).

    This hierarchy allows you to set broad defaults (like any_unit) while providing specific overrides for critical sensors (like date_time or battery_soc).

  12. Understand the Sunsynk architecture and layers

    main

    The Sunsynk library is structured in layers to separate the application logic from the Modbus transport protocol. This allows the library to support different connection types (TCP, RTU-over-TCP, Serial, or Solarman tunnels) while maintaining a consistent public API.

    Layer Hierarchy

    1. HA Add-on Layer: Handles schedules, MQTT, history averaging, and discovery.
    2. Sunsynk Layer: Provides the public API using Sensor, RWSensor, definitions, InverterState, and group_sensors.
    3. HoldingUnit Layer: Provides the low-level protocol operations: read_holding_registers and write_registers (FC16).
    4. Transport Layer:
      • ModbusConnection.for_unit(server_id): Uses tmodbus for TCP, RTU-over-TCP, or serial.
      • SolarmanUnit: Uses PySolarmanV5Async tunnel.

    Note on server_id: When using for_unit(id), the id refers to the Modbus server id (the device ID), not a register address. In the Home Assistant add-on, this corresponds to MODBUS_ID.