goodwe-modbus 0.1.0__tar.gz

goodwe_modbus-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: goodwe-modbus
+Version: 0.1.0
+Summary: Python library to communicate to Goodwe inverter over modbus.
+Author: theneweinstein
+Author-email: theneweinstein <theneweinstein@mail.equust.nl>
+Requires-Dist: modbus-connection>=4.12.3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+

goodwe_modbus-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "goodwe-modbus"
+version = "0.1.0"
+description = "Python library to communicate to Goodwe inverter over modbus."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["modbus-connection>=4.12.3"]
+
+[[project.authors]]
+name = "theneweinstein"
+email = "theneweinstein@mail.equust.nl"
+
+[build-system]
+requires = ["uv_build>=0.12.23,<0.13.0"]
+build-backend = "uv_build"

goodwe_modbus-0.1.0/pyproject.toml.orig

@@ -0,0 +1,16 @@
+[project]
+name = "goodwe-modbus"
+version = "0.1.0"
+description = "Python library to communicate to Goodwe inverter over modbus."
+readme = "README.md"
+authors = [
+    { name = "theneweinstein", email = "theneweinstein@mail.equust.nl" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "modbus-connection>=4.12.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.23,<0.13.0"]
+build-backend = "uv_build"

goodwe_modbus-0.1.0/src/goodwe_modbus/__init__.py

@@ -0,0 +1,15 @@
+from .device import GoodweInverter
+from .pv import PvStrings
+from .inverter import InverterState, Identity, GridOutput
+from .energy import EnergyTotals
+from .settings import ActivePowerControl
+
+__all__ = [
+    "GoodweInverter", 
+    "InverterState", 
+    "Identity", 
+    "GridOutput", 
+    "PvStrings", 
+    "EnergyTotals", 
+    "ActivePowerControl"
+]

goodwe_modbus-0.1.0/src/goodwe_modbus/device.py

@@ -0,0 +1,72 @@
+"""The top-level object for a current-generation Sofar inverter."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from modbus_connection.model import (
+    Device,
+    Raw,
+    UpdateReport,
+)
+
+from .energy import EnergyTotals
+from .inverter import InverterState, Identity, GridOutput
+from .pv import PvStrings
+from .settings import ActivePowerControl
+
+
+if TYPE_CHECKING:
+    from modbus_connection import ModbusUnit
+
+# Attribute names of the sub-systems each update method reads.
+READINGS = ("pv","state","grid","energy")
+SETTINGS = ("powercontrol",)
+ALL = ("identity", *READINGS, *SETTINGS)
+
+class GoodweInverter(Device):
+    """A current-generation Goodwe inverter reached through a ``ModbusUnit``."""
+
+
+    def __init__(
+        self,
+        unit: ModbusUnit,
+    ) -> None:
+        """Set up the sub-systems.
+
+        ``read_pm`` reads parallel-system registers an inverter refuses.
+        """
+        super().__init__(unit)
+
+        self.energy = EnergyTotals(unit)
+        self.grid = GridOutput(unit)
+        self.identity = Identity(unit)
+        self.state = InverterState(unit)
+        self.pv = PvStrings(unit)
+        self.powercontrol = ActivePowerControl(unit)
+
+    async def _async_setup(self) -> None:
+        """Set up the sub-systems."""
+        await self.identity.async_update()
+
+    async def async_update_readings(self) -> UpdateReport:
+        """Update the readings sub-systems."""
+        return await self.async_poll(READINGS)
+
+    async def async_update_settings(self) -> UpdateReport:
+        """Refresh what the controller has been configured to do."""
+        return await self.async_poll(SETTINGS)
+
+    async def async_update(self) -> UpdateReport:
+        """Refresh all components."""
+        report = await self.async_poll(READINGS)
+        return await self.async_poll(SETTINGS, report)
+
+    async def async_read_raw(self, names: Iterable[str] = ALL) -> Raw:
+        """Every register this device reads, undecoded, for diagnostics."""
+        return await super().async_read_raw(names)
+
+
+
+

goodwe_modbus-0.1.0/src/goodwe_modbus/energy.py

@@ -0,0 +1,14 @@
+"""Daily and lifetime energy counters"""
+
+from __future__ import annotations
+
+from modbus_connection.model import Component, uint32, gauge
+
+class EnergyTotals(Component):
+    """Daily and lifetime energy counters"""
+
+    daily_energy = gauge(566, 0.1, signed=False, unit="kWh")
+    """Daily energy in kWh."""
+
+    lifetime_energy = uint32(546, scale = 0.1, unit="kWh")
+    """Lifetime energy in kWh."""

goodwe_modbus-0.1.0/src/goodwe_modbus/enums.py

@@ -0,0 +1,48 @@
+"""Option maps the plugin declares, as enums."""
+
+from __future__ import annotations
+
+from enum import IntEnum, IntFlag
+
+class SystemState(IntEnum):
+    """System state"""
+
+    WAIT = 0
+    NORMAL = 1
+    FAULT = 2
+
+class Fault1(IntFlag):
+    """Fault flags"""
+
+    ID001_GFCI_CHECK = 0x00000001
+    ID002_AC_HCT_CHECK = 0x00000002
+    ID003_REF_V = 0x00000004
+    ID004_DC_SWITCH = 0x00000008
+    ID005_DC_SPD = 0x00000010
+    ID006_SALES1 = 0x00000020
+    ID007_GFCI = 0x00000040
+    ID008_RELAY = 0x00000080
+    ID009_AC_HCT = 0x00000100
+    ID010_UTILITY_LOSS = 0x00000200
+    ID011_GROUND = 0x00000400
+    ID012_DC_BUS = 0x00000800
+    ID013_INTERNAL_FAN = 0x00001000
+    ID014_TEMPERATURE = 0x00002000
+    ID015_SALES2 = 0x00004000
+    ID016_PV_OVER_VOLTAGE = 0x00008000
+    ID017_EXTERNAL_FAN = 0x00010000
+    ID018_VAC = 0x00020000
+    ID019_ISOLATION = 0x00040000
+    ID020_HIGH_DC_COMPONENT = 0x00080000
+    ID021_LCD_COMMUNICATION = 0x00100000
+    ID022_STRING_OVERCURRENT = 0x00200000
+    ID023_PV_REVERSE = 0x00400000
+    ID024_EXPORT_POWER_LIMIT = 0x00800000
+    ID025_NPE = 0x01000000
+    ID026_RELAY_CHECK = 0x02000000
+    ID027_LPE_SHORT_CIRCUIT = 0x04000000
+    ID028_NIGHT_SPS = 0x08000000
+    ID029_AFCI = 0x10000000
+    ID030_GRID_FREQUENCY = 0x20000000
+    ID031_EEPROM = 0x40000000
+    ID032_SPI = 0x80000000

goodwe_modbus-0.1.0/src/goodwe_modbus/faults.py

@@ -0,0 +1,66 @@
+"""Fault definitions, keyed by vendor ID rather than register."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+class FaultCategory(StrEnum):
+    """The subsystem a fault belongs to."""
+
+    AC_OUTPUT = "ac_output"
+    COMMUNICATION = "communication"
+    DC_BUS = "dc_bus"
+    FAN = "fan"
+    GRID = "grid"
+    INSULATION = "insulation"
+    INTERNAL = "internal"
+    PV = "pv"
+    SALES = "sales"
+    THERMAL = "thermal"
+
+@dataclass(frozen=True, slots=True)
+class Fault:
+    """One fault the inverter can report."""
+
+    id: int
+    key: str
+    category: FaultCategory
+
+FAULTS: tuple[Fault, ...] = (
+    Fault(1, "gfci_check_fail", FaultCategory.INTERNAL),
+    Fault(2, "ac_hct_check_fail", FaultCategory.INTERNAL),
+    Fault(3, "ref_v", FaultCategory.INTERNAL),
+    Fault(4, "dc_switch_fault", FaultCategory.DC_BUS),
+    Fault(5, "dc_spd_fault", FaultCategory.DC_BUS),
+    Fault(6, "sales1", FaultCategory.SALES),
+    Fault(7, "gfci_fault", FaultCategory.INTERNAL),
+    Fault(8, "relay_fault", FaultCategory.INTERNAL),
+    Fault(9, "ac_hct", FaultCategory.INTERNAL),
+    Fault(10, "utility_loss", FaultCategory.GRID),
+    Fault(11, "ground_fault", FaultCategory.INSULATION),
+    Fault(12, "dc_bus_high", FaultCategory.DC_BUS),
+    Fault(13, "internal_fan_fault", FaultCategory.FAN),
+    Fault(14, "over_temperature", FaultCategory.THERMAL),
+    Fault(15, "sales2", FaultCategory.SALES),
+    Fault(16, "pv_overvoltage", FaultCategory.PV),
+    Fault(17, "external_fan_fault", FaultCategory.FAN),
+    Fault(18, "vac_fault", FaultCategory.GRID),
+    Fault(19, "isolation_fault", FaultCategory.INSULATION),
+    Fault(20, "high_dc_component", FaultCategory.GRID),
+    Fault(21, "lcd_communication_fault", FaultCategory.COMMUNICATION),
+    Fault(22, "string_over_current", FaultCategory.PV),
+    Fault(23, "pv_reverse_fault", FaultCategory.PV),
+    Fault(24, "export_power_limit_fault", FaultCategory.GRID),
+    Fault(25, "npe", FaultCategory.GRID),
+    Fault(26, "relay_check_fault", FaultCategory.INTERNAL),
+    Fault(27, "lpe", FaultCategory.GRID),
+    Fault(28, "night_sps_fault", FaultCategory.INTERNAL),
+    Fault(29, "afci_fault", FaultCategory.INTERNAL),
+    Fault(30, "grid_frequency_overrun", FaultCategory.GRID),
+    Fault(31, "eeprom", FaultCategory.COMMUNICATION),
+    Fault(32, "spi_fault", FaultCategory.COMMUNICATION)
+)
+
+
+FAULTS_BY_ID: dict[int, Fault] = {fault.id: fault for fault in FAULTS}

goodwe_modbus-0.1.0/src/goodwe_modbus/inverter.py

@@ -0,0 +1,66 @@
+"""Inverter state, identity and on-grid output."""
+
+from __future__ import annotations
+
+from modbus_connection.model import Component, enum, flags, gauge, integer, string, uint32
+
+from .enums import (
+    Fault1,
+    SystemState,
+)
+from .faults import FAULTS_BY_ID, Fault
+
+
+class InverterState(Component):
+    """Inverter state, identity and on-grid output."""
+
+    system_state = enum(564, SystemState, signed = False)
+    fault = flags(544, Fault1, count=2, signed = False)
+    generation_time_total = uint32(548, unit = "h")
+    inverter_temperature = gauge(565, 0.1, signed = False, unit = "°C")
+
+    @property
+    def active_faults(self) -> frozenset[Fault]:
+        """Every fault the inverter currently reports."""
+        return frozenset(
+            fault
+            for member in self.fault
+            if (fault := FAULTS_BY_ID(member.value)) is not None
+        )
+
+class Identity(Component):
+    """Inverter identity."""
+
+    type = string(528, 5)
+    """Inverter type """
+    serial = string(512,8)
+    """Inverter serial number."""
+
+class GridOutput(Component):
+    """Inverter grid output."""
+
+    voltage_l1 = gauge(554, 0.1, unit="V")
+    voltage_l2 = gauge(555, 0.1, unit="V")
+    voltage_l3 = gauge(556, 0.1, unit="V")
+    current_l1 = gauge(557, 0.1, unit="A")
+    current_l2 = gauge(558, 0.1, unit="A")
+    current_l3 = gauge(559, 0.1, unit="A")
+    frequency_l1 = gauge(560, 0.01, unit="Hz")
+    frequency_l2 = gauge(561, 0.01, unit="Hz")
+    frequency_l3 = gauge(562, 0.01, unit="Hz")
+    power = integer(563, unit="W")
+
+    @property
+    def power_l1(self) -> float:
+        """Grid output power on L1 in W."""
+        return self.voltage_l1 * self.current_l1
+
+    @property
+    def power_l2(self) -> float:
+        """Grid output power on L2 in W."""
+        return self.voltage_l2 * self.current_l2   
+
+    @property
+    def power_l3(self) -> float:
+        """Grid output power on L3 in W."""
+        return self.voltage_l3 * self.current_l3

goodwe_modbus-0.1.0/src/goodwe_modbus/pv.py

@@ -0,0 +1,25 @@
+"""PV strings, one component per MPPT tier."""
+
+from __future__ import annotations
+
+from modbus_connection.model import Component, gauge, repeating_group
+
+
+
+class PvString(Component):
+    """A PV string, one component per MPPT tier."""
+
+    pv_voltage = gauge(550,0.1, stride = 1, unit="V")
+    """PV voltage in V."""
+    pv_current = gauge(552,0.1, stride = 1, unit="A")
+    """PV current in A."""
+
+    @property
+    def pv_power(self) -> float:
+        """PV power in W."""
+        return self.pv_voltage * self.pv_current
+
+class PvStrings(Component):
+    """A PV string, one component per MPPT tier."""
+
+    strings = repeating_group(2, PvString, stride = 1)

goodwe_modbus-0.1.0/src/goodwe_modbus/settings.py

@@ -0,0 +1,17 @@
+"""Settings and commands."""
+
+from __future__ import annotations
+
+from modbus_connection.model import Component, integer
+
+class ActivePowerControl(Component):
+    """Active power control settings."""
+
+    active_power_export_limit = integer(256, signed = False, unit = "%")
+    """Active power export limit in W."""
+
+    async def async_set_active_power_export_limit(self, limit: float) -> None:
+        """Set the active power export limit in W."""
+        if not 0 <= limit <= 100:
+            raise ValueError(f"active power limit {limit}% is outside 0-100")
+        await self._unit.write_register(256, round(limit))