[nzwateralerts] New Zealand Water Alerts Binding initial contribution (…

…openhab#7899)

Signed-off-by: Stewart Cossey <stewart.cossey@gmail.com>

CODEOWNERS

@@ -154,6 +154,7 @@
 /bundles/org.openhab.binding.ntp/ @marcelrv
 /bundles/org.openhab.binding.nuki/ @mkatter
 /bundles/org.openhab.binding.nuvo/ @mlobstein
+/bundles/org.openhab.binding.nzwateralerts/ @cossey
 /bundles/org.openhab.binding.oceanic/ @kgoderis
 /bundles/org.openhab.binding.ojelectronics/ @EvilPingu
 /bundles/org.openhab.binding.omnikinverter/ @hansbogert

bom/openhab-addons/pom.xml

@@ -756,6 +756,11 @@
  <artifactId>org.openhab.binding.nuvo</artifactId>
  <version>${project.version}</version>
  </dependency>
+ <dependency>
+ <groupId>org.openhab.addons.bundles</groupId>
+ <artifactId>org.openhab.binding.nzwateralerts</artifactId>
+ <version>${project.version}</version>
+ </dependency>
  <dependency>
  <groupId>org.openhab.addons.bundles</groupId>
  <artifactId>org.openhab.binding.oceanic</artifactId>

bundles/org.openhab.binding.nzwateralerts/.classpath

@@ -0,0 +1,49 @@
+<?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="src" path="target/generated-sources/annotations">
+ <attributes>
+ <attribute name="optional" value="true"/>
+ <attribute name="maven.pomderived" value="true"/>
+ <attribute name="ignore_optional_problems" value="true"/>
+ <attribute name="m2e-apt" value="true"/>
+ </attributes>
+ </classpathentry>
+ <classpathentry kind="src" output="target/test-classes" path="target/generated-test-sources/test-annotations">
+ <attributes>
+ <attribute name="optional" value="true"/>
+ <attribute name="maven.pomderived" value="true"/>
+ <attribute name="ignore_optional_problems" value="true"/>
+ <attribute name="m2e-apt" value="true"/>
+ <attribute name="test" value="true"/>
+ </attributes>
+ </classpathentry>
+ <classpathentry kind="output" path="target/classes"/>
+</classpath>

bundles/org.openhab.binding.nzwateralerts/.project

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>org.openhab.binding.nzwateralerts</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.nzwateralerts/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.nzwateralerts/README.md

@@ -0,0 +1,73 @@
+# NZ Water Alerts Binding
+
+Get Water Alert Levels for cities in New Zealand.
+Getting this alert level can help you script and automate smarter tasks for water and avoid getting penalized from your distract or local council. 
+
+> Example: Disable automated spinklers based on a level 3 or 4 water alert level
+
+This Binding scrapes multiple websites for Water Levels:
+
+* Northland's [BeWaterWise Website](https://bewaterwise.org.nz/)
+* Waikato's [Smart Water Website](https://www.smartwater.org.nz/)
+* Napier's [Council Website](https://www.napier.govt.nz)
+
+## Thing Configuration
+
+The binding and thing ID is `nzwateralerts:wateralert`.
+
+### Configuration Values
+
+| Value | Type | Description |
+| --------------- | ------------ | -------------------------------------- |
+| location | string | The location to get water data from. Refer to the list below for values. |
+| refreshInterval | number | The time interval (in hours) to refresh the data.
+
+### Supported city/area list
+
+| City | Config Value |
+| ------------------------ | ------------------------------------------ |
+| Bream Bay | bewaterwise:whangarei:breambay |
+| Dargaville & Baylys | bewaterwise:kaipara:dargavilleampbaylys |
+| Glinks Gully | bewaterwise:kaipara:glinksgully |
+| Hamilton City | smartwater:hamilton:hamilton |
+| Kaikohe / Ngawha | bewaterwise:farnorth:kaikohengawha |
+| Kaitaia | bewaterwise:farnorth:kaitaia |
+| Kerikeri / Waipapa | bewaterwise:farnorth:kerikeriwaipapa |
+| Mangapai | bewaterwise:whangarei:mangapai |
+| Mangawhai | bewaterwise:kaipara:mangawhai |
+| Maungakaramea | bewaterwise:whangarei:maungakaramea |
+| Maungaturoto | bewaterwise:kaipara:maungaturoto |
+| Moerewa / Kawakawa | bewaterwise:farnorth:moerewakawakawa |
+| Napier | napiercitycouncil:napier:napier |
+| Okaihau | bewaterwise:farnorth:okaihau |
+| Opononi / Omapere | bewaterwise:farnorth:opononiomapere |
+| Rawene | bewaterwise:farnorth:rawene |
+| Ruawai | bewaterwise:kaipara:ruawai |
+| Russell | bewaterwise:farnorth:russell |
+| Waipa District | smartwater:waipa:waipa |
+| Waikato District | smartwater:waikato:waikato |
+| Waitangi / Paihia / Opua | bewaterwise:farnorth:waitangipaihiaopua |
+| Whangarei | bewaterwise:whangarei:whangarei |
+
+### Example
+
+```
+Thing nzwateralerts:wateralert "HCC" [ location="smartwater:hamilton:hamilton", refreshInterval="4" ]
+```
+
+The above gets the Water Alert level for Hamilton and refreshes this data every 4 hours.
+
+## Channels
+
+There is only one channel with this binding labelled `alertlevel` which contains a Number 0-4 to represent the alert level.
+
+Depending on your region, either Alert Level 0 or 1 can represent _No Water Restrictions_.
+Check with your regional council for further details.
+
+## Other Cities
+
+At present the supported cities were implemented by scraping the web page on the respective website which contains the restriction information. 
+
+**No councils have this data in a programmatic format easily accessible to software.**
+Most won't have pages which contain the current alert level and only offer alerts via twitter or text.
+If you can convince your council to always have a page displaying the current alert level (even if none is in effect) then I can attempt to parse the page for inclusion in this Binding.

bundles/org.openhab.binding.nzwateralerts/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/maven-v4_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.9-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>org.openhab.binding.nzwateralerts</artifactId>
+
+ <name>openHAB Add-ons :: Bundles :: NZ Water Alerts Binding</name>
+
+</project>

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

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

bundles/org.openhab.binding.nzwateralerts/src/main/java/org/openhab/binding/nzwateralerts/internal/NZWaterAlertsBindingConstants.java

@@ -0,0 +1,45 @@
+/**
+ * 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.nzwateralerts.internal;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.smarthome.core.thing.ThingTypeUID;
+import org.openhab.binding.nzwateralerts.internal.api.BeWaterWise;
+import org.openhab.binding.nzwateralerts.internal.api.NapierCityCouncil;
+import org.openhab.binding.nzwateralerts.internal.api.SmartWater;
+import org.openhab.binding.nzwateralerts.internal.api.WaterWebService;
+
+/**
+ * The {@link NZWaterAlertsBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Stewart Cossey - Initial contribution
+ */
+@NonNullByDefault
+public class NZWaterAlertsBindingConstants {
+
+ private static final String BINDING_ID = "nzwateralerts";
+
+ // List of all Thing Type UIDs
+ public static final ThingTypeUID THING_TYPE_WATERALERT = new ThingTypeUID(BINDING_ID, "wateralert");
+
+ // List of all Channel ids
+ public static final String CHANNEL_ALERTLEVEL = "alertlevel";
+
+ // List of all supported services
+ public static final List<WaterWebService> WATER_WEB_SERVICES = Arrays
+ .asList(new WaterWebService[] { new SmartWater(), new BeWaterWise(), new NapierCityCouncil() });
+}

bundles/org.openhab.binding.nzwateralerts/src/main/java/org/openhab/binding/nzwateralerts/internal/NZWaterAlertsConfiguration.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.nzwateralerts.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+/**
+ * The {@link NZWaterAlertsConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Stewart Cossey - Initial contribution
+ */
+@NonNullByDefault
+public class NZWaterAlertsConfiguration {
+ public @Nullable String location;
+ public int refreshInterval;
+}

bundles/org.openhab.binding.nzwateralerts/src/main/java/org/openhab/binding/nzwateralerts/internal/api/BeWaterWise.java

@@ -0,0 +1,77 @@
+/**
+ * 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.nzwateralerts.internal.api;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * The {@link BeWaterWise} class contains the logic to get data the
+ * bewaterwise.org.nz website.
+ * 
+ * Northland Regional Council
+ *
+ * @author Stewart Cossey - Initial contribution
+ */
+@NonNullByDefault
+public class BeWaterWise implements WaterWebService {
+ private final Logger logger = LoggerFactory.getLogger(BeWaterWise.class);
+
+ private static final String HOSTNAME = "https://bewaterwise.org.nz";
+ private static final String REGION_FARNORTH = "/current-water-levels_far-north/";
+ private static final String REGION_WHANGAREI = "/current-water-levels_whangarei/";
+ private static final String REGION_KAIPARA = "/current-water-levels_kaipara/";
+
+ private static final String PATTERN = "vc_text_separator.*?<span>(.*?)<\\/span>.*?water-level-([0-4]).*?";
+ private static final Pattern REGEX = Pattern.compile(PATTERN,
+ Pattern.CASE_INSENSITIVE | Pattern.MULTILINE | Pattern.DOTALL);
+
+ @Override
+ public String service() {
+ return "bewaterwise";
+ }
+
+ @Override
+ public String endpoint(final String region) {
+ switch (region.toLowerCase()) {
+ case "farnorth":
+ return HOSTNAME + REGION_FARNORTH;
+
+ case "whangarei":
+ return HOSTNAME + REGION_WHANGAREI;
+
+ case "kaipara":
+ return HOSTNAME + REGION_KAIPARA;
+ }
+ return "";
+ }
+
+ @Override
+ public int findWaterLevel(final String data, final String area) {
+ final Matcher matches = REGEX.matcher(data);
+
+ while (matches.find()) {
+ final String dataArea = matches.group(1).replaceAll("\\W", "");
+ final String level = matches.group(2);
+ logger.debug("Data Area {} Level {}", dataArea, level);
+ if (dataArea.equalsIgnoreCase(area)) {
+ return Integer.valueOf(level);
+ }
+ }
+ return -1;
+ }
+}