[vigiecrues] Vigicrues binding : track river level (#7503)

Signed-off-by: clinique <[email protected]>

CODEOWNERS

@@ -208,6 +208,7 @@
 /bundles/org.openhab.binding.vektiva/ @octa22
 /bundles/org.openhab.binding.velbus/ @cedricboon
 /bundles/org.openhab.binding.velux/ @gs4711
+/bundles/org.openhab.binding.vigicrues/ @clinique
 /bundles/org.openhab.binding.vitotronic/ @steand
 /bundles/org.openhab.binding.volvooncall/ @clinique
 /bundles/org.openhab.binding.weathercompany/ @mhilbush

bom/openhab-addons/pom.xml

@@ -1036,6 +1036,11 @@
       <artifactId>org.openhab.binding.velux</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.vigicrues</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.vitotronic</artifactId>

bundles/org.openhab.binding.vigicrues/.classpath

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="src" output="target/classes" path="src/main/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry excluding="**" kind="src" output="target/classes" path="src/main/resources">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" output="target/test-classes" path="src/test/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+			<attribute name="test" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="output" path="target/classes"/>
+</classpath>

bundles/org.openhab.binding.vigicrues/.project

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.openhab.binding.vigicrues</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.m2e.core.maven2Builder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+		<nature>org.eclipse.m2e.core.maven2Nature</nature>
+	</natures>
+</projectDescription>

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

@@ -0,0 +1,81 @@
+# VigiCrues Binding
+
+This binding allows you to get data regarding water flow and water height on major French rivers.
+These data are made public through OpenDataSoft website. 
+
+## Supported Things
+
+There is exactly one supported thing type, which represents a river level measurement station.
+It is identified by the `id`.
+
+To get your station id :
+
+1. open https://www.vigicrues.gouv.fr/
+
+2. Select your region on the France map
+
+3. Select the station nearest to your location
+
+4. In the 'Info Station' tab you'll get the id just near the station name (e.g. X9999999299)
+
+Of course, you can add multiple Things, e.g. for getting measures for different locations.
+
+
+## Discovery
+
+This binding does not handle auto-discovery.
+
+## Binding Configuration
+
+The binding has no configuration options, all configuration is done at Thing level.
+
+## Thing Configuration
+
+The thing has a few configuration parameters:
+
+| Parameter | Description                                                             |
+|-----------|-------------------------------------------------------------------------|
+| id        | Id of the station.                                                      |
+| refresh   | Refresh interval in minutes. Optional, the default value is 30 minutes. |
+
+
+## Channels
+
+The VigiCrues information that retrieved are made available with these channels:
+
+| Channel ID       | Item Type                 | Description                   |
+|------------------|---------------------------|-------------------------------|
+| observation-time | DateTime                  | Date and time of measurement  |
+| flow             | Number:VolumetricFlowRate | Volume of water per time unit |
+| height           | Number:Length             | Water height of the river     |
+
+
+## Full Example
+
+vigicrues.things:
+
+```
+Thing vigicrues:station:poissy "Station Poissy" @ "VigiCrues" [id="H300000201", refresh=30]
+Thing vigicrues:station:vernon "Station Vernon" @ "VigiCrues" [id="H320000104", refresh=30]
+```
+
+vigicrues.items:
+
+```
+Group gVigiCrues "VigiCrues" <flow>
+    Number:Length VC_hauteur "Hauteur Eau Poissy [%.2f %unit%]"  <none> (gVigiCrues) {channel="vigicrues:station:poissy:height"}
+    Number:VolumetricFlowRate VC_debit "Débit Eau Poissy [%.2f %unit%]" <flow> (gVigiCrues) {channel="vigicrues:station:poissy:flow"}
+    DateTime VC_ObservationPTS "Timestamp [%1$tH:%1$tM]" <time> (gVigiCrues) {channel="vigicrues:station:poissy:observation-time" }
+```
+
+vigicrues.sitemap:
+
+```
+sitemap vigicrues label="VigiCrues" {
+    Frame {
+        Default item=VC_hauteur
+        Default item=VC_debit
+        Default item=VC_ObservationPTS
+    }
+}
+```

bundles/org.openhab.binding.vigicrues/pom.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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>2.5.6-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.vigicrues</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: VigiCrues Binding</name>
+
+</project>

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

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

bundles/org.openhab.binding.vigicrues/src/main/java/org/openhab/binding/vigicrues/internal/VigiCruesBindingConstants.java

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2010-2020 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.vigicrues.internal;
+
+import java.util.Collections;
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.smarthome.core.thing.ThingTypeUID;
+
+/**
+ * The {@link VigiCruesBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+public class VigiCruesBindingConstants {
+
+    public static final String BINDING_ID = "vigicrues";
+    public static final String OPENDATASOFT_URL = "https://public.opendatasoft.com/api/records/1.0/search/";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_VIGI_CRUES = new ThingTypeUID(BINDING_ID, "station");
+
+    // List of all Channel id's
+    public static final String OBSERVATION_TIME = "observation-time";
+    public static final String HEIGHT = "height";
+    public static final String FLOW = "flow";
+
+    public static final String COMMENT = "comment";
+
+    public static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Collections.singleton(THING_TYPE_VIGI_CRUES);
+}

bundles/org.openhab.binding.vigicrues/src/main/java/org/openhab/binding/vigicrues/internal/VigiCruesConfiguration.java

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2010-2020 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.vigicrues.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link VigiCruesConfiguration} is the class used to match the
+ * thing configuration.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+public class VigiCruesConfiguration {
+    public String id = "";
+    public int refresh = 30;
+}

bundles/org.openhab.binding.vigicrues/src/main/java/org/openhab/binding/vigicrues/internal/VigiCruesHandlerFactory.java

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) 2010-2020 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.vigicrues.internal;
+
+import static org.openhab.binding.vigicrues.internal.VigiCruesBindingConstants.*;
+
+import java.time.ZonedDateTime;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.eclipse.smarthome.core.i18n.TimeZoneProvider;
+import org.eclipse.smarthome.core.thing.Thing;
+import org.eclipse.smarthome.core.thing.ThingTypeUID;
+import org.eclipse.smarthome.core.thing.binding.BaseThingHandlerFactory;
+import org.eclipse.smarthome.core.thing.binding.ThingHandler;
+import org.eclipse.smarthome.core.thing.binding.ThingHandlerFactory;
+import org.openhab.binding.vigicrues.internal.handler.VigiCruesHandler;
+import org.osgi.service.component.annotations.Activate;
+import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Reference;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonDeserializer;
+
+/**
+ * The {@link VigiCruesHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@Component(service = ThingHandlerFactory.class, configurationPid = "binding.vigicrues")
+@NonNullByDefault
+public class VigiCruesHandlerFactory extends BaseThingHandlerFactory {
+    private final Gson gson;
+    // Needed for converting UTC time to local time
+    private final TimeZoneProvider timeZoneProvider;
+
+    @Activate
+    public VigiCruesHandlerFactory(@Reference TimeZoneProvider timeZoneProvider) {
+        this.timeZoneProvider = timeZoneProvider;
+        this.gson = new GsonBuilder()
+                .registerTypeAdapter(ZonedDateTime.class, (JsonDeserializer<ZonedDateTime>) (json, type,
+                        jsonDeserializationContext) -> ZonedDateTime.parse(json.getAsJsonPrimitive().getAsString()))
+                .create();
+    }
+
+    @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 (thingTypeUID.equals(THING_TYPE_VIGI_CRUES)) {
+            return new VigiCruesHandler(thing, timeZoneProvider, gson);
+        }
+
+        return null;
+    }
+
+}