[sungrow] Initial contribution

CODEOWNERS

@@ -216,6 +216,7 @@
 /bundles/org.openhab.binding.modbus.sbc/ @fwolter
 /bundles/org.openhab.binding.modbus.stiebeleltron/ @pail23
 /bundles/org.openhab.binding.modbus.studer/ @giovannimirulla
+/bundles/org.openhab.binding.modbus.sungrow/ @soenkekueper
 /bundles/org.openhab.binding.modbus.sunspec/ @mrbig
 /bundles/org.openhab.binding.monopriceaudio/ @mlobstein
 /bundles/org.openhab.binding.mpd/ @stefanroellin

bom/openhab-addons/pom.xml

@@ -1071,6 +1071,11 @@
       <artifactId>org.openhab.binding.modbus.studer</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.modbus.sungrow</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.modbus.sunspec</artifactId>

bundles/org.openhab.binding.modbus.sungrow/NOTICE

@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons

bundles/org.openhab.binding.modbus.sungrow/README.md

@@ -0,0 +1,174 @@
+# Modbus Sungrow Binding
+
+This binding integrates the sungrow inverters into openHAB.
+It is based on the Sungrow specification "Communication Protocol of Residential Hybrid Inverter V1.0.23", which can be found here: https://github.com/bohdan-s/SunGather/issues/36.
+
+## Supported Inverters
+
+As defined within the spec mentioned above the following inverters are supported, but not all are tested yet:
+
+- SH3K6
+- SH4K6
+- SH5K-20
+- SH5K-V13
+- SH3K6-30
+- SH4K6-30
+- SH5K-30
+- SH3.0RS
+- SH3.6RS
+- SH4.0RS
+- SH5.0RS
+- SH6.0RS
+- SH5.0RT
+- SH6.0RT
+- SH8.0RT
+- SH10RT
+
+## Supported Things
+
+The binding supports only one thing:
+
+- `sungrow-inverter`: The sungrow inverter
+
+## Preparation
+
+The data from the inverter is read via Modbus. So you need to configure a Modbus Serial Slave `serial` or Modbus TCP Slave `tcp` as bridge first.
+If you are using a Modbus TCP Slave and the WiNet-S Communication Module please ensure:
+
+- that you have the correct IP-Address of your WiNet-S Device
+- that Modbus is enabled within the Communication Module
+- that you've the correct port number
+- that the white list is disabled or your openHAB instance IP is listed
+
+Enabling modbus and whitelist setting can be done in WiNet-S Web-UI as shown below:
+<img src="./doc/WiNet-S_Modbus.PNG" alt="WiNet-S Modbus configuration"/>
+
+## Thing Configuration
+
+Once you've configured the Modbus TCP Slave or Modbus Serial Slave as Bridge you can configure the Sungrow inverter thing.
+You just have to select the configured bridge and optional configure the polling interval.
+
+### Sungrow Inverter (`sungrow-inverter`)
+
+| Name         | Type    | Description                          | Default | Required | Advanced |
+|--------------|---------|--------------------------------------|---------|----------|----------|
+| pollInterval | integer | Interval the device is polled in ms. | 5000    | yes      | no       |
+
+## Channels
+
+The `sungrow-inverter` thing has channels that serve the current state of the sungrow inverter, as you are used to from the iSolareCloud Website and App.
+
+| Channel Type ID                    | Item Type                | Description                           | Advanced  | Channel Group       |
+|------------------------------------|--------------------------|---------------------------------------|-----------|---------------------|
+| sg-internal-temperature            | Number:Temperature       | Internal Temperature                  | yes       | Overview            |
+| sg-total-dc-power                  | Number:Power             | Total DC Power                        | no        | Overview            |
+| sg-phase-a-voltage                 | Number:ElectricPotential | Phase A Voltage                       | yes       | Overview            |
+| sg-phase-b-voltage                 | Number:ElectricPotential | Phase B Voltage                       | yes       | Overview            |
+| sg-phase-c-voltage                 | Number:ElectricPotential | Phase C Voltage                       | yes       | Overview            |
+| sg-daily-pv-generation             | Number:Energy            | Daily PV Generation                   | no        | Overview            |
+| sg-total-pv-generation             | Number:Energy            | Total PV Generation                   | no        | Overview            |
+| sg-reactive-power                  | Number:Power             | Reactive Power                        | yes       | Overview            |
+| sg-power-factor                    | Number:Dimensionless     | Power Factor                          | yes       | Overview            |
+| sg-phase-a-current                 | Number:ElectricCurrent   | Phase A Current                       | yes       | Overview            |
+| sg-phase-b-current                 | Number:ElectricCurrent   | Phase B Current                       | yes       | Overview            |
+| sg-phase-c-current                 | Number:ElectricCurrent   | Phase C Current                       | yes       | Overview            |
+| sg-total-active-power              | Number:Power             | Total Active Power                    | no        | Overview            |
+| sg-grid-frequency                  | Number:Frequency         | Grid Frequency                        | yes       | Overview            |
+| sg-mppt1-voltage                   | Number:ElectricPotential | MPPT1 Voltage                         | yes       | MPPT Information    |
+| sg-mppt1-current                   | Number:ElectricCurrent   | MPPT1 Current                         | yes       | MPPT Information    |
+| sg-mppt2-voltage                   | Number:ElectricPotential | MPPT2 Voltage                         | yes       | MPPT Information    |
+| sg-mppt2-current                   | Number:ElectricCurrent   | MPPT2 Current                         | yes       | MPPT Information    |
+| sg-daily-battery-charge            | Number:Energy            | Daily Battery Charge                  | no        | Battery Information |
+| sg-total-battery-charge            | Number:Energy            | Total Battery Charge                  | no        | Battery Information |
+| sg-battery-voltage                 | Number:ElectricPotential | Battery Voltage                       | yes       | Battery Information |
+| sg-battery-current                 | Number:ElectricCurrent   | Battery Current                       | yes       | Battery Information |
+| sg-battery-power                   | Number:Power             | Battery Power                         | no        | Battery Information |
+| sg-battery-level                   | Number:Dimensionless     | Battery Level                         | no        | Battery Information |
+| sg-battery-healthy                 | Number:Dimensionless     | Battery Healthy                       | no        | Battery Information |
+| sg-battery-temperature             | Number:Temperature       | Battery Temperature                   | no        | Battery Information |
+| sg-daily-battery-discharge-energy  | Number:Energy            | Daily Battery Discharge Energy        | no        | Battery Information |
+| sg-total-battery-discharge-energy  | Number:Energy            | Total Battery Discharge Energy        | no        | Battery Information |
+| sg-battery-capacity                | Number:Energy            | Battery Capacity                      | no        | Battery Information |
+| sg-daily-charge-energy             | Number:Energy            | Daily Charge Energy                   | no        | Battery Information |
+| sg-total-charge-energy             | Number:Energy            | Total Charge Energy                   | no        | Battery Information |
+| sg-daily-import-energy             | Number:Energy            | Daily Import Energy                   | no        | Grid Information    |
+| sg-total-import-energy             | Number:Energy            | Total Import Energy                   | no        | Grid Information    |
+| sg-daily-export-energy             | Number:Energy            | Daily Export Energy                   | no        | Grid Information    |
+| sg-total-export-energy             | Number:Energy            | Total Export Energy                   | no        | Grid Information    |
+| sg-daily-export-power-from-pv      | Number:Power             | Daily Export Power from PV            | no        | Grid Information    |
+| sg-total-export-energy-from-pv     | Number:Energy            | Total Export Energy from PV           | no        | Grid Information    |
+| sg-export-power                    | Number:Power             | Export Power                          | no        | Grid Information    |
+| sg-load-power                      | Number:Power             | Load Power                            | no        | Load Information    |
+| sg-daily-direct-energy-consumption | Number:Energy            | Daily Direct Energy Consumption       | no        | Load Information    |
+| sg-total-direct-energy-consumption | Number:Energy            | Total Direct Energy Consumption       | no        | Load Information    |
+| sg-self-consumption-today          | Number:Dimensionless     | Self Consumption Today                | no        | Load Information    |
+
+## Full Example
+
+This example shows how to configure a sungrow inverter connected via modbus and uses the most common channels.
+
+_sungrow.things_
+
+```java
+Bridge modbus:tcp:sungrowBridge [ host="10.0.0.2", port=502, id=1, enableDiscovery=false ] {
+    Thing sungrow-inverter sungrowInverter "Sungrow Inverter" [ pollInterval=5000 ]
+}
+```
+
+_sungrow.items_
+
+```java
+// Groups
+Group sungrowInverter "Sungrow Inverter" ["Inverter"]
+Group overview "Overview" (sungrowInverter)
+Group batteryInformation "Battery information" (sungrowInverter)
+Group gridInformation "Grid information" (sungrowInverter)
+Group loadInformation "Load information" (sungrowInverter)
+
+// Overview
+Number:Power total_active_power "Total Active Power" (overview) ["Measurement", "Power"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-overview#sg-total-active-power"}
+Number:Power total_dc_power "Total DC Power" (overview) ["Measurement", "Power"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-overview#sg-total-dc-power"}
+Number:Energy daily_pv_generation "Daily PV Generation" (overview) ["Measurement", "Energy"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-overview#sg-daily-pv-generation"}
+Number:Energy total_pv_generation "Total PV Generation" (overview) ["Measurement", "Energy"]  {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-overview#sg-total-pv-generation"}
+
+// Battery information
+Number:Power battery_power "Battery Power" (batteryInformation) ["Measurement", "Power"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-battery-information#sg-battery-power"}
+Number:Dimensionless battery_level "Battery Level" (batteryInformation) ["Measurement", "Energy"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-battery-information#sg-battery-level"}
+Number:Energy daily_charge_energy "Daily Battery Charge Energy" (batteryInformation) ["Measurement", "Energy"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-battery-information#sg-daily-charge-energy"}
+Number:Energy daily_discharge_energy "Daily Battery Discharge Energy" (batteryInformation) ["Measurement", "Energy"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-battery-information#sg-daily-battery-discharge-energy"}
+
+// Grid information
+Number:Power export_power "Export Power" (gridInformation) ["Measurement", "Power"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-grid-information#sg-export-power"}
+Number:Energy daily_export_energy "Daily Export Energy" (gridInformation) ["Measurement", "Energy"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-grid-information#sg-daily-export-energy"}
+Number:Energy daily_import_energy "Daily Import Energy" (gridInformation) ["Measurement", "Energy"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-grid-information#sg-daily-import-energy"}
+
+// Load information
+Number:Power load_power "Load Power" (loadInformation) ["Measurement", "Power"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-load-information#sg-load-power"}
+Number:Energy daily_direct_energy_consumption "Daily Direct Energy Consumption" (loadInformation) ["Measurement", "Energy"] {channel="modbus:sungrow-inverter:sungrowBridge:sungrowInverter:sg-load-information#sg-daily-direct-energy-consumption"}
+```
+
+_sungrow.sitemap_
+
+```perl
+sitemap sungrow label="Sungrow Binding"
+{
+    Frame {
+        Text item=total_active_power
+        Text item=total_dc_power
+        Text item=daily_pv_generation
+        Text item=total_pv_generation
+
+        Text item=battery_power
+        Text item=battery_level
+        Text item=daily_charge_energy
+        Text item=daily_discharge_energy
+
+        Text item=export_power
+        Text item=daily_export_energy
+        Text item=daily_import_energy
+
+        Text item=load_power
+        Text item=daily_direct_energy_consumption
+    }
+}
+```

bundles/org.openhab.binding.modbus.sungrow/pom.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>4.2.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.modbus.sungrow</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Modbus Sungrow Binding</name>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.modbus</artifactId>
+      <version>${project.version}</version>
+      <scope>provided</scope>
+    </dependency>
+  </dependencies>
+
+
+</project>

bundles/org.openhab.binding.modbus.sungrow/src/main/java/org/openhab/binding/modbus/sungrow/internal/ConversionConstants.java

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2010-2024 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.modbus.sungrow.internal;
+
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.util.function.Function;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * Constants for converting values.
+ *
+ * @author Sönke Küper - Initial contribution
+ */
+@NonNullByDefault
+final class ConversionConstants {
+
+    private ConversionConstants() {
+    }
+
+    /**
+     * Multiplicand for 0.1.
+     */
+    static final BigDecimal DIV_BY_TEN = new BigDecimal(BigInteger.ONE, 1);
+
+    /**
+     * Value conversion from Celsius to Kelvin.
+     */
+    static final Function<BigDecimal, BigDecimal> CELSIUS_TO_KELVIN = (BigDecimal celsius) -> celsius
+            .add(new BigDecimal(273.15f));
+}

bundles/org.openhab.binding.modbus.sungrow/src/main/java/org/openhab/binding/modbus/sungrow/internal/ModbusSungrowBindingConstants.java

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2010-2024 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.modbus.sungrow.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.binding.modbus.ModbusBindingConstants;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link ModbusSungrowBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Sönke Küper - Initial contribution
+ */
+@NonNullByDefault
+public class ModbusSungrowBindingConstants {
+
+    /**
+     * ThingType-ID for Inverter.
+     */
+    public static final ThingTypeUID THING_TYPE_INVERTER = new ThingTypeUID(ModbusBindingConstants.BINDING_ID,
+            "sungrow-inverter");
+}

bundles/org.openhab.binding.modbus.sungrow/src/main/java/org/openhab/binding/modbus/sungrow/internal/ModbusSungrowHandlerFactory.java

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2010-2024 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.modbus.sungrow.internal;
+
+import static org.openhab.binding.modbus.sungrow.internal.ModbusSungrowBindingConstants.*;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.core.thing.Thing;
+import org.openhab.core.thing.ThingTypeUID;
+import org.openhab.core.thing.binding.BaseThingHandlerFactory;
+import org.openhab.core.thing.binding.ThingHandler;
+import org.openhab.core.thing.binding.ThingHandlerFactory;
+import org.osgi.service.component.annotations.Component;
+
+/**
+ * The {@link ModbusSungrowHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Sönke Küper - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.sungrow", service = ThingHandlerFactory.class)
+public class ModbusSungrowHandlerFactory extends BaseThingHandlerFactory {
+
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(THING_TYPE_INVERTER);
+
+    @Override
+    public boolean supportsThingType(ThingTypeUID thingTypeUID) {
+        return SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID);
+    }
+
+    @Override
+    protected @Nullable ThingHandler createHandler(Thing thing) {
+        ThingTypeUID thingTypeUID = thing.getThingTypeUID();
+
+        if (THING_TYPE_INVERTER.equals(thingTypeUID)) {
+            return new SungrowInverterHandler(thing);
+        }
+
+        return null;
+    }
+}

bundles/org.openhab.binding.modbus.sungrow/src/main/java/org/openhab/binding/modbus/sungrow/internal/SungrowInverterConfiguration.java

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2010-2024 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.modbus.sungrow.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link SungrowInverterConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Sönke Küper - Initial contribution
+ */
+@NonNullByDefault
+public class SungrowInverterConfiguration {
+
+    public int pollInterval;
+}