[solarmax] Initial contribution (openhab#10414)

* SolarMax Binding Initial implementation Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * openhab#10413 camelCaserizeTheChannelNames Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * openhab#10413 Delete commented code and Refactor Brute Force Command Discovery into something commitable Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * 10413 Delete commented code and Refactor Brute Force Command Discovery into something commitable Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * openhab#10413 Codestyle Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * 10413 Codestyle Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * openhab#10413 corrected sat-plugin errors Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * openhab#10413 updates from code reviews in PR openhab#10414 Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * 10413 mvn spotless:apply Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * 10413 Updated to 3.2.0-SNAPSHOT Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * Fixed conflicts introduced by foreign commit. Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * Updated copyright years Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * Ran mvn spotless:apply to resolve formatting issues Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * Updates from review Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * Switch to using Units & move softwareVersion & buildNumber to properties Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * A couple of review related updates Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * A couple more review related changes. Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * Added Full Example to README.md Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * Update parent pom.xml version Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> * Update bundles/org.openhab.binding.solarmax/src/main/java/org/openhab/binding/solarmax/internal/SolarMaxHandlerFactory.java Signed-off-by: Fabian Wolter <github@fabian-wolter.de> * Update bundles/org.openhab.binding.solarmax/src/main/java/org/openhab/binding/solarmax/internal/SolarMaxHandlerFactory.java Signed-off-by: Fabian Wolter <github@fabian-wolter.de> Signed-off-by: Jamie Townsend <jamie_townsend@hotmail.com> Signed-off-by: Fabian Wolter <github@fabian-wolter.de> Co-authored-by: Fabian Wolter <github@fabian-wolter.de>
seime · Oct 16, 2022 · 7c1d652 · 7c1d652
1 parent 0bd310e
commit 7c1d652
Show file tree

Hide file tree

Showing 22 changed files with 1,972 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -302,6 +302,7 @@
 /bundles/org.openhab.binding.snmp/ @openhab/add-ons-maintainers
 /bundles/org.openhab.binding.solaredge/ @alexf2015
 /bundles/org.openhab.binding.solarlog/ @johannrichard
+/bundles/org.openhab.binding.solarmax/ @jamietownsend
 /bundles/org.openhab.binding.solarwatt/ @sven-carstens
 /bundles/org.openhab.binding.somfymylink/ @loungeflyz
 /bundles/org.openhab.binding.somfytahoma/ @octa22

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -1516,6 +1516,11 @@
       <artifactId>org.openhab.binding.solarlog</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.solarmax</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.solarwatt</artifactId>

diff --git a/bundles/org.openhab.binding.solarmax/NOTICE b/bundles/org.openhab.binding.solarmax/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
diff --git a/bundles/org.openhab.binding.solarmax/README.md b/bundles/org.openhab.binding.solarmax/README.md
@@ -0,0 +1,132 @@
+# SolarMax Binding
+
+This binding supports SolarMax PV inverters.
+
+## Supported Things
+
+This binding only has a single `inverter` thing that can be added manually.
+The SolarMax MT Series is supported (tested with 8MT2 devices).
+
+## Discovery
+
+Auto-discovery is currently not available.
+
+## Thing Configuration
+
+Each inverter requires the following configuration parameters:
+
+| parameter       | required | default | description                                                          |
+| --------------- | -------- | ------- | -------------------------------------------------------------------- |
+| host            | yes      |         | hostname or IP address of the inverter                               |
+| port            | no       | 12345   | Port number to connect to. This should be `12345` for most inverters |
+| refreshInterval | no       | 15      | Interval (in seconds) to refresh the channel values.                 |
+
+
+## Properties
+
+| property        | description                                            |
+| --------------- | ------------------------------------------------------ |
+| softwareVersion | Software Version installed on the SolarMax device      |
+| buildNumber     | Firmware Build Number installed on the SolarMax device |
+
+
+## Channels
+
+| channel                  | type                     | description                                  |
+| ------------------------ | ------------------------ | -------------------------------------------- |
+| lastUpdated              | DateTime                 | Time when data was last read from the device |
+| startups                 | Number                   | Number of times the device has started       |
+| acPhase1Current          | Number:ElectricCurrent   | Ac Phase 1 Current in Amps                   |
+| acPhase2Current          | Number:ElectricCurrent   | Ac Phase 2 Current in Amps                   |
+| acPhase3Current          | Number:ElectricCurrent   | Ac Phase 3 Current in Amps                   |
+| energyGeneratedToday     | Number:Energy            | Energy Generated Today in Wh                 |
+| energyGeneratedTotal     | Number:Energy            | Energy Generated since recording began in Wh |
+| operatingHours           | Number                   | Operating Hours since recording began in h   |
+| energyGeneratedYesterday | Number:Energy            | Energy Generated Yesterday in Wh             |
+| energyGeneratedLastMonth | Number:Energy            | Energy Generated Last Month in Wh            |
+| energyGeneratedLastYear  | Number:Energy            | Energy Generated Last Year in Wh             |
+| energyGeneratedThisMonth | Number:Energy            | Energy Generated This Month in Wh            |
+| energyGeneratedThisYear  | Number:Energy            | Energy Generated This Year in Wh             |
+| currentPowerGenerated    | Number:Power             | Power currently being generated in W         |
+| acFrequency              | Number:Frequency         | AcFrequency in Hz                            |
+| acPhase1Voltage          | Number:ElectricPotential | Ac Phase1 Voltage in V                       |
+| acPhase2Voltage          | Number:ElectricPotential | Ac Phase2 Voltage in V                       |
+| acPhase3Voltage          | Number:ElectricPotential | Ac Phase3 Voltage in V                       |
+| heatSinkTemperature      | Number:Temperature       | Heat Sink Temperature in degrees celcius     |
+
+### Full Example
+
+Below you can find some example textual configuration for a solarmax with some basic functionallity. This can be extended/adjusted according to your needs and depending on the required channels (see list above).
+
+_inverter.things:_
+
+```
+Thing solarmax:inverter:solarmax "SolarMax Inverter" [
+    host="192.168.1.151",
+    port="12345",
+    refresh="15"
+]
+```
+
+_inverter.items:_
+
+```
+Group    gInverter   "SolarMax Inverter"
+
+DateTime lastUpdated "Last Updated" <clock> (gInverter) {channel="solarmax:inverter:solarmax:lastUpdated"}
+
+Number startups "Startups" (gInverter) { channel="solarmax:inverter:solarmax:startups" }
+
+Number:ElectricCurrent acPhase1Current "Ac Phase 1 Current in Amps" <energy> (gInverter) { channel="solarmax:inverter:solarmax:acPhase1Current" }
+Number:ElectricCurrent acPhase2Current "Ac Phase 2 Current in Amps" <energy> (gInverter) { channel="solarmax:inverter:solarmax:acPhase2Current" }
+Number:ElectricCurrent acPhase3Current "Ac Phase 3 Current in Amps" <energy> (gInverter) { channel="solarmax:inverter:solarmax:acPhase3Current" }
+
+Number:Energy energyGeneratedToday "Energy Generated Today in Wh" <energy> (gInverter) { channel="solarmax:inverter:solarmax:energyGeneratedToday" }
+Number:Energy energyGeneratedTotal "Energy Generated since recording began in Wh" <energy> (gInverter) { channel="solarmax:inverter:solarmax:energyGeneratedTotal" }
+
+Number operatingHours "Operating Hours since recording began in h" <time> (gInverter) { channel="solarmax:inverter:solarmax:operatingHours" }
+
+Number:Energy energyGeneratedYesterday "Energy Generated Yesterday in Wh" <energy> (gInverter) { channel="solarmax:inverter:solarmax:operatingHours" }
+Number:Energy energyGeneratedLastMonth "Energy Generated Last Month in Wh" <energy> (gInverter) { channel="solarmax:inverter:solarmax:energyGeneratedLastMonth" }
+Number:Energy energyGeneratedLastYear "Energy Generated Last Year in Wh" <energy> (gInverter) { channel="solarmax:inverter:solarmax:energyGeneratedLastYear" }
+Number:Energy energyGeneratedThisMonth "Energy Generated This Month in Wh" <energy> (gInverter) { channel="solarmax:inverter:solarmax:energyGeneratedThisMonth" }
+Number:Energy energyGeneratedThisYear "Energy Generated This Year in Wh" <energy> (gInverter) { channel="solarmax:inverter:solarmax:energyGeneratedThisYear" }
+
+Number:Power currentPowerGenerated "Power currently being generated in W" (gInverter) { channel="solarmax:inverter:solarmax:currentPowerGenerated" }
+Number:Frequency acFrequency "AcFrequency in Hz" (gInverter) { channel="solarmax:inverter:solarmax:acFrequency" }
+
+Number:ElectricPotential acPhase1Voltage "Ac Phase1 Voltage in V" <energy> (gInverter) { channel="solarmax:inverter:solarmax:acPhase1Voltage" }
+Number:ElectricPotential acPhase2Voltage "Ac Phase2 Voltage in V" <energy> (gInverter) { channel="solarmax:inverter:solarmax:acPhase2Voltage" }
+Number:ElectricPotential acPhase3Voltage "Ac Phase3 Voltage in V" <energy> (gInverter) { channel="solarmax:inverter:solarmax:acPhase3Voltage" }
+
+Number:Temperature heatSinkTemperature "Heat Sink Temperature in degrees celcius" <temperature> (gInverter) { channel="solarmax:inverter:solarmax:heatSinkTemperature" }
+
+```
+
+_heatpump.sitemap:_
+
+```
+sitemap heatpump label="Heatpump" {
+    Frame label="Heatpump" {
+        Text item=HeatPump_State_Ext
+        Text item=HeatPump_Temperature_1
+        Text item=HeatPump_Outside_Avg
+        Text item=HeatPump_Hours_Heatpump
+        Text item=HeatPump_Hours_Heating
+        Text item=HeatPump_Hours_Warmwater
+        Switch item=HeatPump_heating_operation_mode  mappings=[0="Auto", 1="Auxiliary heater", 2="Party", 3="Holiday", 4="Off"]
+        Setpoint item=HeatPump_heating_temperature minValue=-10 maxValue=10 step=0.5
+        Switch item=HeatPump_warmwater_operation_mode  mappings=[0="Auto", 1="Auxiliary heater", 2="Party", 3="Holiday", 4="Off"]
+        Setpoint item=HeatPump_warmwater_temperature minValue=10 maxValue=65 step=1
+    }
+}
+```
+
+### SolarMax Commands
+
+During the implementation the SolarMax device was sent all possible 3 character commands and a number of 4 character commands, to see what it responded to.
+The most interesting, identifiable and useful commands were implemented as channels above.
+
+Here is a list of other commands, which are known to return some kind of value: ADR (DeviceAddress / Device Number - only used if the devices are linked serially), AMM, CID, CPG, CPL, CP1, CP2, CP3, CP4, CP5, CYC, DIN, DMO, ETH, FH2, FQR, FWV, IAA, IED, IEE, IEM, ILM, IP4, ISL, ITS, KFS, KHS, KTS, LAN (Language), MAC (MAC Address), PAE, PAM, PDA, PDC, PFA, PIN (Power Installed), PLR, PPC, PRL (AC Power Percent, PSF, PSR, PSS, QAC, QMO, QUC, RA1, RA2, RB1, RB2, REL, RH1, RH2, RPR, RSD, SAC, SAL, SAM, SCH, SNM (IP Broadcast Address??), SPS, SRD, SRS, SYS (Operating State), TCP (probably port number - 12345), TI1, TL1, TL3, TND, TNH, TNL, TP1, TP2, TP3, TV0, TV1, TYP (Type?), UA2, UB2, UGD, UI1, UI2, UI3, ULH, ULL, UMX, UM1, UM2, UM3, UPD, UZK, VCM
+
+Valid commands which returned a null/empty value during testing: FFK, FRT, GCP, ITN, PLD, PLE, PLF, PLS, PPO, TV2, VLE, VLI, VLO
diff --git a/bundles/org.openhab.binding.solarmax/pom.xml b/bundles/org.openhab.binding.solarmax/pom.xml
@@ -0,0 +1,17 @@
+<?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 http://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>3.4.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.solarmax</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: SolarMax Binding</name>
+
+</project>
diff --git a/bundles/org.openhab.binding.solarmax/src/main/feature/feature.xml b/bundles/org.openhab.binding.solarmax/src/main/feature/feature.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.solarmax-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-solarmax" description="SolarMax Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.solarmax/${project.version}</bundle>
+	</feature>
+</features>
diff --git a/...olarmax/src/main/java/org/openhab/binding/solarmax/internal/SolarMaxBindingConstants.java b/...olarmax/src/main/java/org/openhab/binding/solarmax/internal/SolarMaxBindingConstants.java
@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2010-2022 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.solarmax.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link SolarMaxBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Jamie Townsend - Initial contribution
+ */
+@NonNullByDefault
+public class SolarMaxBindingConstants {
+
+    private static final String BINDING_ID = "solarmax";
+    private static final String THING_TYPE_ID = "inverter";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_SOLARMAX = new ThingTypeUID(BINDING_ID, THING_TYPE_ID);
+}
diff --git a/...binding.solarmax/src/main/java/org/openhab/binding/solarmax/internal/SolarMaxChannel.java b/...binding.solarmax/src/main/java/org/openhab/binding/solarmax/internal/SolarMaxChannel.java
@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2010-2022 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.solarmax.internal;
+
+import javax.measure.Unit;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.solarmax.internal.connector.SolarMaxCommandKey;
+import org.openhab.core.library.unit.SIUnits;
+import org.openhab.core.library.unit.Units;
+
+/**
+ * The {@link SolarMaxChannel} Enum defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Jamie Townsend - Initial contribution
+ */
+@NonNullByDefault
+public enum SolarMaxChannel {
+
+    CHANNEL_LAST_UPDATED("lastUpdated", null), //
+    CHANNEL_STARTUPS(SolarMaxCommandKey.startups.name(), null),
+    CHANNEL_AC_PHASE1_CURRENT(SolarMaxCommandKey.acPhase1Current.name(), Units.AMPERE),
+    CHANNEL_AC_PHASE2_CURRENT(SolarMaxCommandKey.acPhase2Current.name(), Units.AMPERE),
+    CHANNEL_AC_PHASE3_CURRENT(SolarMaxCommandKey.acPhase3Current.name(), Units.AMPERE),
+    CHANNEL_ENERGY_GENERATED_TODAY(SolarMaxCommandKey.energyGeneratedToday.name(), Units.WATT_HOUR),
+    CHANNEL_ENERGY_GENERATED_TOTAL(SolarMaxCommandKey.energyGeneratedTotal.name(), Units.WATT_HOUR),
+    CHANNEL_OPERATING_HOURS(SolarMaxCommandKey.operatingHours.name(), Units.HOUR),
+    CHANNEL_ENERGY_GENERATED_YESTERDAY(SolarMaxCommandKey.energyGeneratedYesterday.name(), Units.WATT_HOUR),
+    CHANNEL_ENERGY_GENERATED_LAST_MONTH(SolarMaxCommandKey.energyGeneratedLastMonth.name(), Units.WATT_HOUR),
+    CHANNEL_ENERGY_GENERATED_LAST_YEAR(SolarMaxCommandKey.energyGeneratedLastYear.name(), Units.WATT_HOUR),
+    CHANNEL_ENERGY_GENERATED_THIS_MONTH(SolarMaxCommandKey.energyGeneratedThisMonth.name(), Units.WATT_HOUR),
+    CHANNEL_ENERGY_GENERATED_THIS_YEAR(SolarMaxCommandKey.energyGeneratedThisYear.name(), Units.WATT_HOUR),
+    CHANNEL_CURRENT_POWER_GENERATED(SolarMaxCommandKey.currentPowerGenerated.name(), Units.WATT_HOUR),
+    CHANNEL_AC_FREQUENCY(SolarMaxCommandKey.acFrequency.name(), Units.HERTZ),
+    CHANNEL_AC_PHASE1_VOLTAGE(SolarMaxCommandKey.acPhase1Voltage.name(), Units.VOLT),
+    CHANNEL_AC_PHASE2_VOLTAGE(SolarMaxCommandKey.acPhase2Voltage.name(), Units.VOLT),
+    CHANNEL_AC_PHASE3_VOLTAGE(SolarMaxCommandKey.acPhase3Voltage.name(), Units.VOLT),
+    CHANNEL_HEAT_SINK_TEMPERATUR(SolarMaxCommandKey.heatSinkTemperature.name(), SIUnits.CELSIUS);
+
+    private final String channelId;
+
+    @Nullable
+    private Unit<?> unit;
+
+    private SolarMaxChannel(String channelId, @Nullable Unit<?> unit) {
+        this.channelId = channelId;
+        this.unit = unit;
+    }
+
+    public String getChannelId() {
+        return channelId;
+    }
+
+    @Nullable
+    public Unit<?> getUnit() {
+        return this.unit;
+    }
+}
diff --git a/...g.solarmax/src/main/java/org/openhab/binding/solarmax/internal/SolarMaxConfiguration.java b/...g.solarmax/src/main/java/org/openhab/binding/solarmax/internal/SolarMaxConfiguration.java
@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2010-2022 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.solarmax.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link SolarMaxConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Jamie Townsend - Initial contribution
+ */
+@NonNullByDefault
+public class SolarMaxConfiguration {
+    public String host = ""; // this will always need to be overridden
+    public int portNumber = 12345; // default value is 12345
+
+    public int refreshInterval = 15; // default value is 15
+}