[solarforecast] Initial contribution (openhab#13308)

Signed-off-by: Bernd Weymann <[email protected]>

bom/openhab-addons/pom.xml

@@ -1646,6 +1646,11 @@
       <artifactId>org.openhab.binding.solaredge</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.solarforecast</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.solarlog</artifactId>

bundles/org.openhab.binding.solarforecast/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.solarforecast/pom.xml

@@ -0,0 +1,26 @@
+<?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.solarforecast</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: SolarForecast Binding</name>
+  <dependencies>
+    <!-- version needs to match with other projects like org.openhab.io.openhabcloud.pom.xml -->
+    <dependency>
+      <groupId>org.json</groupId>
+      <artifactId>json</artifactId>
+      <version>20231013</version>
+      <scope>compile</scope>
+    </dependency>
+  </dependencies>
+
+</project>

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

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

bundles/org.openhab.binding.solarforecast/src/main/java/org/openhab/binding/solarforecast/internal/SolarForecastBindingConstants.java

@@ -0,0 +1,59 @@
+/**
+ * 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.solarforecast.internal;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link SolarForecastBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Bernd Weymann - Initial contribution
+ */
+@NonNullByDefault
+public class SolarForecastBindingConstants {
+
+    private static final String BINDING_ID = "solarforecast";
+
+    // Things
+    public static final ThingTypeUID FORECAST_SOLAR_SITE = new ThingTypeUID(BINDING_ID, "fs-site");
+    public static final ThingTypeUID FORECAST_SOLAR_PLANE = new ThingTypeUID(BINDING_ID, "fs-plane");
+    public static final ThingTypeUID SOLCAST_SITE = new ThingTypeUID(BINDING_ID, "sc-site");
+    public static final ThingTypeUID SOLCAST_PLANE = new ThingTypeUID(BINDING_ID, "sc-plane");
+    public static final Set<ThingTypeUID> SUPPORTED_THING_SET = Set.of(FORECAST_SOLAR_SITE, FORECAST_SOLAR_PLANE,
+            SOLCAST_SITE, SOLCAST_PLANE);
+
+    // Channel groups
+    public static final String GROUP_AVERAGE = "average";
+    public static final String GROUP_OPTIMISTIC = "optimistic";
+    public static final String GROUP_PESSIMISTIC = "pessimistic";
+    public static final String GROUP_RAW = "raw";
+
+    // Channels
+    public static final String CHANNEL_POWER_ESTIMATE = "power-estimate";
+    public static final String CHANNEL_ENERGY_ESTIMATE = "energy-estimate";
+    public static final String CHANNEL_POWER_ACTUAL = "power-actual";
+    public static final String CHANNEL_ENERGY_ACTUAL = "energy-actual";
+    public static final String CHANNEL_ENERGY_REMAIN = "energy-remain";
+    public static final String CHANNEL_ENERGY_TODAY = "energy-today";
+    public static final String CHANNEL_JSON = "json";
+
+    // Other
+    public static final int REFRESH_ACTUAL_INTERVAL = 1;
+    public static final String SLASH = "/";
+    public static final String EMPTY = "";
+    public static final String PATTERN_FORMAT = "yyyy-MM-dd HH:mm:ss";
+}

bundles/org.openhab.binding.solarforecast/src/main/java/org/openhab/binding/solarforecast/internal/SolarForecastException.java

@@ -0,0 +1,30 @@
+/**
+ * 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.solarforecast.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.binding.solarforecast.internal.actions.SolarForecast;
+
+/**
+ * The {@link SolarForecastException} is thrown if forecast data is invalid
+ *
+ * @author Bernd Weymann - Initial contribution
+ */
+@NonNullByDefault
+@SuppressWarnings("serial")
+public class SolarForecastException extends RuntimeException {
+
+    public SolarForecastException(SolarForecast ref, String message) {
+        super(ref.getIdentifier() + " # " + message);
+    }
+}

bundles/org.openhab.binding.solarforecast/src/main/java/org/openhab/binding/solarforecast/internal/SolarForecastHandlerFactory.java

@@ -0,0 +1,83 @@
+/**
+ * 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.solarforecast.internal;
+
+import static org.openhab.binding.solarforecast.internal.SolarForecastBindingConstants.*;
+
+import java.util.Optional;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.eclipse.jetty.client.HttpClient;
+import org.openhab.binding.solarforecast.internal.forecastsolar.handler.ForecastSolarBridgeHandler;
+import org.openhab.binding.solarforecast.internal.forecastsolar.handler.ForecastSolarPlaneHandler;
+import org.openhab.binding.solarforecast.internal.solcast.handler.SolcastBridgeHandler;
+import org.openhab.binding.solarforecast.internal.solcast.handler.SolcastPlaneHandler;
+import org.openhab.core.i18n.LocationProvider;
+import org.openhab.core.i18n.TimeZoneProvider;
+import org.openhab.core.io.net.http.HttpClientFactory;
+import org.openhab.core.library.types.PointType;
+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 SolarForecastHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Bernd Weymann - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.solarforecast", service = ThingHandlerFactory.class)
+public class SolarForecastHandlerFactory extends BaseThingHandlerFactory {
+    private final TimeZoneProvider timeZoneProvider;
+    private final HttpClient httpClient;
+    private Optional<PointType> location = Optional.empty();
+
+    @Activate
+    public SolarForecastHandlerFactory(final @Reference HttpClientFactory hcf, final @Reference LocationProvider lp,
+            final @Reference TimeZoneProvider tzp) {
+        timeZoneProvider = tzp;
+        httpClient = hcf.getCommonHttpClient();
+        PointType pt = lp.getLocation();
+        if (pt != null) {
+            location = Optional.of(pt);
+        }
+    }
+
+    @Override
+    public boolean supportsThingType(ThingTypeUID thingTypeUID) {
+        return SolarForecastBindingConstants.SUPPORTED_THING_SET.contains(thingTypeUID);
+    }
+
+    @Override
+    protected @Nullable ThingHandler createHandler(Thing thing) {
+        ThingTypeUID thingTypeUID = thing.getThingTypeUID();
+        if (FORECAST_SOLAR_SITE.equals(thingTypeUID)) {
+            return new ForecastSolarBridgeHandler((Bridge) thing, location);
+        } else if (FORECAST_SOLAR_PLANE.equals(thingTypeUID)) {
+            return new ForecastSolarPlaneHandler(thing, httpClient);
+        } else if (SOLCAST_SITE.equals(thingTypeUID)) {
+            return new SolcastBridgeHandler((Bridge) thing, timeZoneProvider);
+        } else if (SOLCAST_PLANE.equals(thingTypeUID)) {
+            return new SolcastPlaneHandler(thing, httpClient);
+        }
+        return null;
+    }
+}

bundles/org.openhab.binding.solarforecast/src/main/java/org/openhab/binding/solarforecast/internal/actions/SolarForecast.java

@@ -0,0 +1,110 @@
+/**
+ * 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.solarforecast.internal.actions;
+
+import java.time.Instant;
+import java.time.LocalDate;
+
+import javax.measure.quantity.Energy;
+import javax.measure.quantity.Power;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.binding.solarforecast.internal.solcast.SolcastObject.QueryMode;
+import org.openhab.core.library.types.QuantityType;
+import org.openhab.core.types.TimeSeries;
+
+/**
+ * The {@link SolarForecast} Interface needed for Actions
+ *
+ * @author Bernd Weymann - Initial contribution
+ */
+@NonNullByDefault
+public interface SolarForecast {
+    /**
+     * Argument can be used to query an average forecast scenario
+     */
+    public static final String AVERAGE = "average";
+    /**
+     * Argument can be used to query an optimistic forecast scenario
+     */
+    public static final String OPTIMISTIC = "optimistic";
+    /**
+     * Argument can be used to query a pessimistic forecast scenario
+     */
+    public static final String PESSIMISTIC = "pessimistic";
+
+    /**
+     * Returns electric energy production for one day
+     *
+     * @param date
+     * @param args possible arguments from this interface
+     * @return QuantityType<Energy> in kW/h
+     */
+    QuantityType<Energy> getDay(LocalDate date, String... args);
+
+    /**
+     * Returns electric energy between two timestamps
+     *
+     * @param start
+     * @param end
+     * @param args possible arguments from this interface
+     * @return QuantityType<Energy> in kW/h
+     */
+    QuantityType<Energy> getEnergy(Instant start, Instant end, String... args);
+
+    /**
+     * Returns electric power at one specific point of time
+     *
+     * @param timestamp
+     * @param args possible arguments from this interface
+     * @return QuantityType<Power> in kW
+     */
+    QuantityType<Power> getPower(Instant timestamp, String... args);
+
+    /**
+     * Get the first date and time of forecast data
+     *
+     * @return date time
+     */
+    Instant getForecastBegin();
+
+    /**
+     * Get the last date and time of forecast data
+     *
+     * @return date time
+     */
+    Instant getForecastEnd();
+
+    /**
+     * Get TimeSeries for Power forecast
+     *
+     * @param mode QueryMode for optimistic, pessimistic or average estimation
+     * @return TimeSeries containing QuantityType<Power>
+     */
+    TimeSeries getPowerTimeSeries(QueryMode mode);
+
+    /**
+     * Get TimeSeries for Energy forecast
+     *
+     * @param mode QueryMode for optimistic, pessimistic or average estimation
+     * @return TimeSeries containing QuantityType<Energy>
+     */
+    TimeSeries getEnergyTimeSeries(QueryMode mode);
+
+    /**
+     * SolarForecast identifier
+     *
+     * @return unique String to identify solar plane
+     */
+    String getIdentifier();
+}