[enphase] Initial contribution (openhab#9883)

Signed-off-by: Hilbrand Bouwkamp <hilbrand@h72.nl>

CODEOWNERS

@@ -69,6 +69,7 @@
 /bundles/org.openhab.binding.energenie/ @hmerk
 /bundles/org.openhab.binding.enigma2/ @gdolfen
 /bundles/org.openhab.binding.enocean/ @fruggy83
+/bundles/org.openhab.binding.enphase/ @Hilbrand
 /bundles/org.openhab.binding.enturno/ @klocsson
 /bundles/org.openhab.binding.epsonprojector/ @mlobstein
 /bundles/org.openhab.binding.etherrain/ @dfad1469

bom/openhab-addons/pom.xml

@@ -331,6 +331,11 @@
       <artifactId>org.openhab.binding.enocean</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.enphase</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.enturno</artifactId>

bundles/org.openhab.binding.enphase/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.enphase/README.md

@@ -0,0 +1,113 @@
+# Enphase Binding
+
+This is the binding for the [Enphase](https://enphase.com/) Envoy Solar Panel gateway.
+The binding uses the local API of the Envoy gateway.
+Some calls can be made without authentication and some use a user name and password.
+The default user name is `envoy` and the default password is the last 6 numbers of the serial number.
+The Envoy gateway updates the data every 5 minutes.
+Therefore using a refresh rate shorter doesn't provide more information.
+
+## Supported Things
+
+The follow things are supported:
+
+* `envoy` The Envoy gateway thing, which is a bridge thing.
+* `inverter` A Enphase micro inverter connected to a solar panel.
+* `relay`  A Enphase relay.
+
+Not all Envoy gateways support all channels and things.
+Therefore some data on inverters and the relay may not be available.
+The binding auto detects which data is available and will report this in the log on initialization of the gateway bridge.
+
+## Discovery
+
+The binding can discover Envoy gateways, micro inverters and relays.
+
+## Thing Configuration
+
+The Envoy gateway thing `envoy` has the following configuration options:
+
+| parameter    | required | description                                                                                                 |
+|--------------|----------|-------------------------------------------------------------------------------------------------------------|
+| serialNumber | yes      | The serial number of the Envoy gateway which can be found on the gateway                                    |
+| hostname     | no       | The host name/ip address of the Envoy gateway. Leave empty to auto detect                                   |
+| username     | no       | The user name to the Envoy gateway. Leave empty when using the default user name                            |
+| password     | no       | The password to the Envoy gateway. Leave empty when using the default password                              |
+| refresh      | no       | Period between data updates. The default is the same 5 minutes the data is actual refreshed on the Envoy    |
+
+The micro inverter `inverter` and `relay` things have only 1 parameter:
+
+| parameter    | required | description                       |
+|--------------|----------|-----------------------------------|
+| serialNumber | yes      | The serial number of the inverter |
+
+## Channels
+
+The `envoy` thing has can show both production as well as consumption data.
+There are channel groups for `production` and `consumption` data.
+The `consumption` data is only available if the gateway reports this.
+A example of a production channel name is: `production#wattsNow`.
+
+| channel            | type          | description                           |
+|--------------------|---------------|---------------------------------------|
+| wattHoursToday     | Number:Energy | Watt hours produced today             |
+| wattHoursSevenDays | Number:Energy | Watt hours produced the last 7 days   |
+| wattHoursLifetime  | Number:Energy | Watt hours produced over the lifetime |
+| wattsNow           | Number:Power  | Latest watts produced                 |
+
+The `inverter` thing has the following channels:
+
+| channel         | type         | description                          |
+|-----------------|--------------|--------------------------------------|
+| lastReportWatts | Number:Power | Last reported power delivery         |
+| maxReportWatts  | Number:Power | Maximum reported power               |
+| lastReportDate  | DateTime     | Date of last reported power delivery |
+
+The following channels are only available if supported by the Envoy gateway:
+
+The `relay` thing has the following channels:
+
+| channel         | type         | description                                            |
+|-----------------|--------------|--------------------------------------------------------|
+| relay           | Contact      | Status of the relay.                                   |
+| line1Connected  | Contact      | If power line 1 is connected. If closed it's connected |
+| line2Connected  | Contact      | If power line 2 is connected. If closed it's connected |
+| line2Connected  | Contact      | If power line 3 is connected. If closed it's connected |
+
+The `inverter` and `relay` have the following additional advanced channels:
+
+| channel         | type               | description                          |
+|-----------------|--------------------|--------------------------------------|
+| producing       | Switch (Read Only) | If the device is producing           |
+| communicating   | Switch (Read Only) | If the device is communicating       |
+| provisioned     | Switch (Read Only) | If the device is provisioned         |
+| operating       | Switch (Read Only) | If the device is operating           |
+
+## Full Example
+
+Things example:
+
+```
+Bridge enphase:envoy:789012 "Envoy" [ serialNumber="12345789012" ] {
+  Things:
+    inverter 123456 "Enphase Inverter 123456" [ serialNumber="789012123456" ]
+    inverter 223456 "Enphase Inverter 223456" [ serialNumber="789012223456" ]
+}
+```
+
+Items example:
+
+```
+Number:Power  envoyWattsNow          "Watts Now [%d %unit%]"          { channel="enphase:envoy:789012:production#wattsNow" }
+Number:Energy envoyWattHoursToday    "Watt Hours Today [%d %unit%]"   { channel="enphase:envoy:789012:production#wattHoursToday" }
+Number:Energy envoyWattHours7Days    "Watt Hours 7 Days [%.1f kWh]"   { channel="enphase:envoy:789012:production#wattHoursSevenDays" }
+Number:Energy envoyWattHoursLifetime "Watt Hours Lifetime [%.1f kWh]" { channel="enphase:envoy:789012:production#wattHoursLifetime" }
+
+Number:Power i1LastReportWatts "Last Report [%d %unit%]"                          { channel="enphase:inverter:789012:123456:lastReportWatts" }
+Number:Power i1MaxReportWatts  "Max Report [%d %unit%]"                           { channel="enphase:inverter:789012:123456:maxReportWatts" }
+DateTime     i1LastReportDate  "Last Report Date [%1$tY-%1$tm-%1$td %1$tH:%1$tM]" { channel="enphase:inverter:789012:123456:lastReportDate" }
+
+Number:Power i2LastReportWatts "Last Report [%d %unit%]"                          { channel="enphase:inverter:789012:223456:lastReportWatts" }
+Number:Power i21MaxReportWatts "Max Report [%d %unit%]"                           { channel="enphase:inverter:789012:223456:maxReportWatts" }
+DateTime     i2LastReportDate  "Last Report Date [%1$tY-%1$tm-%1$td %1$tH:%1$tM]" { channel="enphase:inverter:789012:223456:lastReportDate" }
+```

bundles/org.openhab.binding.enphase/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.1.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.enphase</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Enphase Binding</name>
+
+</project>

bundles/org.openhab.binding.enphase/src/main/feature/feature.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.enphase-${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-enphase" description="Enphase Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.enphase/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.enphase/src/main/java/org/openhab/binding/enphase/internal/EnphaseBindingConstants.java

@@ -0,0 +1,114 @@
+/**
+ * Copyright (c) 2010-2021 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.enphase.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link EnphaseBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Hilbrand Bouwkamp - Initial contribution
+ */
+@NonNullByDefault
+public class EnphaseBindingConstants {
+
+    private static final String BINDING_ID = "enphase";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_ENPHASE_ENVOY = new ThingTypeUID(BINDING_ID, "envoy");
+    public static final ThingTypeUID THING_TYPE_ENPHASE_INVERTER = new ThingTypeUID(BINDING_ID, "inverter");
+    public static final ThingTypeUID THING_TYPE_ENPHASE_RELAY = new ThingTypeUID(BINDING_ID, "relay");
+
+    // Configuration parameters
+    public static final String CONFIG_SERIAL_NUMBER = "serialNumber";
+    public static final String CONFIG_HOSTNAME = "hostname";
+    public static final String CONFIG_USERNAME = "username";
+    public static final String CONFIG_PASSWORD = "password";
+    public static final String CONFIG_REFRESH = "refresh";
+    public static final String PROPERTY_VERSION = "version";
+
+    // Envoy gateway channels
+    public static final String ENVOY_CHANNELGROUP_CONSUMPTION = "consumption";
+    public static final String ENVOY_WATT_HOURS_TODAY = "wattHoursToday";
+    public static final String ENVOY_WATT_HOURS_SEVEN_DAYS = "wattHoursSevenDays";
+    public static final String ENVOY_WATT_HOURS_LIFETIME = "wattHoursLifetime";
+    public static final String ENVOY_WATTS_NOW = "wattsNow";
+
+    // Device channels
+    public static final String DEVICE_CHANNEL_STATUS = "status";
+    public static final String DEVICE_CHANNEL_PRODUCING = "producing";
+    public static final String DEVICE_CHANNEL_COMMUNICATING = "communicating";
+    public static final String DEVICE_CHANNEL_PROVISIONED = "provisioned";
+    public static final String DEVICE_CHANNEL_OPERATING = "operating";
+
+    // Inverter channels
+    public static final String INVERTER_CHANNEL_LAST_REPORT_WATTS = "lastReportWatts";
+    public static final String INVERTER_CHANNEL_MAX_REPORT_WATTS = "maxReportWatts";
+    public static final String INVERTER_CHANNEL_LAST_REPORT_DATE = "lastReportDate";
+
+    // Relay channels
+    public static final String RELAY_CHANNEL_RELAY = "relay";
+    public static final String RELAY_CHANNEL_LINE_1_CONNECTED = "line1Connected";
+    public static final String RELAY_CHANNEL_LINE_2_CONNECTED = "line2Connected";
+    public static final String RELAY_CHANNEL_LINE_3_CONNECTED = "line3Connected";
+
+    public static final String RELAY_STATUS_CLOSED = "closed";
+
+    // Properties
+    public static final String DEVICE_PROPERTY_PART_NUMBER = "partNumber";
+
+    // Discovery constants
+    public static final String DISCOVERY_SERIAL = "serialnum";
+    public static final String DISCOVERY_VERSION = "protovers";
+
+    // Status messages
+    public static final String DEVICE_STATUS_OK = "envoy.global.ok";
+    public static final String ERROR_NODATA = "error.nodata";
+
+    public enum EnphaseDeviceType {
+        ACB, // AC Battery
+        PSU, // Inverter
+        NSRB; // Network system relay controller
+
+        public static @Nullable EnphaseDeviceType safeValueOf(final String type) {
+            try {
+                return valueOf(type);
+            } catch (final IllegalArgumentException e) {
+                return null;
+            }
+        }
+    }
+
+    /**
+     * Derives the default password from the serial number.
+     *
+     * @param serialNumber serial number to use
+     * @return the default password or empty string if serial number is to short.
+     */
+    public static String defaultPassword(final String serialNumber) {
+        return isValidSerial(serialNumber) ? serialNumber.substring(serialNumber.length() - 6) : "";
+    }
+
+    /**
+     * Checks if the serial number is at least long enough to contain the default password.
+     *
+     * @param serialNumber serial number to check
+     * @return true if not null and at least 6 characters long.
+     */
+    public static boolean isValidSerial(@Nullable final String serialNumber) {
+        return serialNumber != null && serialNumber.length() > 6;
+    }
+}

bundles/org.openhab.binding.enphase/src/main/java/org/openhab/binding/enphase/internal/EnphaseHandlerFactory.java

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2010-2021 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.enphase.internal;
+
+import static org.openhab.binding.enphase.internal.EnphaseBindingConstants.*;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.eclipse.jetty.client.HttpClient;
+import org.openhab.binding.enphase.internal.handler.EnphaseInverterHandler;
+import org.openhab.binding.enphase.internal.handler.EnphaseRelayHandler;
+import org.openhab.binding.enphase.internal.handler.EnvoyBridgeHandler;
+import org.openhab.core.i18n.LocaleProvider;
+import org.openhab.core.i18n.TranslationProvider;
+import org.openhab.core.io.net.http.HttpClientFactory;
+import org.openhab.core.thing.Bridge;
+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.Activate;
+import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Reference;
+
+/**
+ * The {@link EnphaseHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Hilbrand Bouwkamp - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.enphase", service = ThingHandlerFactory.class)
+public class EnphaseHandlerFactory extends BaseThingHandlerFactory {
+
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(THING_TYPE_ENPHASE_ENVOY,
+            THING_TYPE_ENPHASE_INVERTER, THING_TYPE_ENPHASE_RELAY);
+
+    private final MessageTranslator messageTranslator;
+    private final HttpClient commonHttpClient;
+    private final EnvoyHostAddressCache envoyHostAddressCache;
+
+    @Activate
+    public EnphaseHandlerFactory(final @Reference LocaleProvider localeProvider,
+            final @Reference TranslationProvider i18nProvider, final @Reference HttpClientFactory httpClientFactory,
+            @Reference final EnvoyHostAddressCache envoyHostAddressCache) {
+        messageTranslator = new MessageTranslator(localeProvider, i18nProvider);
+        commonHttpClient = httpClientFactory.getCommonHttpClient();
+        this.envoyHostAddressCache = envoyHostAddressCache;
+    }
+
+    @Override
+    public boolean supportsThingType(final ThingTypeUID thingTypeUID) {
+        return SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID);
+    }
+
+    @Override
+    protected @Nullable ThingHandler createHandler(final Thing thing) {
+        final ThingTypeUID thingTypeUID = thing.getThingTypeUID();
+
+        if (THING_TYPE_ENPHASE_ENVOY.equals(thingTypeUID)) {
+            return new EnvoyBridgeHandler((Bridge) thing, commonHttpClient, envoyHostAddressCache);
+        } else if (THING_TYPE_ENPHASE_INVERTER.equals(thingTypeUID)) {
+            return new EnphaseInverterHandler(thing, messageTranslator);
+        } else if (THING_TYPE_ENPHASE_RELAY.equals(thingTypeUID)) {
+            return new EnphaseRelayHandler(thing, messageTranslator);
+        }
+
+        return null;
+    }
+}