[novafinedust] Nova Fine Dust binding for SDS011 sensors (openhab#7528)

* Nova Fine Dust binding for SDS011 sensors Closes openhab#7527 Signed-off-by: Stefan Triller <[email protected]>
andrewfg · Aug 31, 2020 · d960f26 · d960f26
1 parent 1fa2646
commit d960f26
Show file tree

Hide file tree

Showing 27 changed files with 1,637 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -137,6 +137,7 @@
 /bundles/org.openhab.binding.nibeuplink/ @alexf2015
 /bundles/org.openhab.binding.nikobus/ @crnjan
 /bundles/org.openhab.binding.nikohomecontrol/ @mherwege
+/bundles/org.openhab.binding.novafinedust/ @t2000
 /bundles/org.openhab.binding.ntp/ @marcelrv
 /bundles/org.openhab.binding.nuki/ @mkatter
 /bundles/org.openhab.binding.oceanic/ @kgoderis

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -676,6 +676,11 @@
       <artifactId>org.openhab.binding.nikohomecontrol</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.novafinedust</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.ntp</artifactId>

diff --git a/bundles/org.openhab.binding.novafinedust/.classpath b/bundles/org.openhab.binding.novafinedust/.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>
diff --git a/bundles/org.openhab.binding.novafinedust/.project b/bundles/org.openhab.binding.novafinedust/.project
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.openhab.binding.novafinedust</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>
diff --git a/bundles/org.openhab.binding.novafinedust/NOTICE b/bundles/org.openhab.binding.novafinedust/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.novafinedust/README.md b/bundles/org.openhab.binding.novafinedust/README.md
@@ -0,0 +1,84 @@
+# NovaFineDust Binding
+
+This binding is for the fine dust sensor (PM Sensor) from Nova Fitness.
+Currently only one model is supported, the SDS011.
+
+It basically implements the protocol specified in [this document](https://cdn.sparkfun.com/assets/parts/1/2/2/7/5/Laser_Dust_Sensor_Control_Protocol_V1.3.pdf).
+One can measure the PM 2.5 and PM 10 values with this device.
+It comes very handy for detecting air pollution like neighbors firing their oven with wet wood etc. so one can deactivate the ventilation system. 
+
+## Supported Things
+
+There is only one Thing type for this binding, which is `SDS011`.
+
+## Discovery
+
+There is no automatic discovery.
+
+## Thing Configuration
+
+There are 2 different working modes for the `SDS011` thing: Reporting and Polling.
+
+### Reporting
+
+This is the preferred mode and thus also configured as a default.
+In this mode the sensor wakes up every `reportingInterval` minutes, performs a measurement for 30 seconds and sleeps for `reportingInterval` minus 30 seconds.
+Remember: According to the [datasheet](https://www-sd-nf.oss-cn-beijing.aliyuncs.com/%E5%AE%98%E7%BD%91%E4%B8%8B%E8%BD%BD/SDS011%20laser%20PM2.5%20sensor%20specification-V1.4.pdf) the sensor has a lifetime of 8000 hours. Using a 0 as `reportingInterval` will make the sensor report its data as fast as possible.
+
+### Polling
+
+If one needs data in different intervals, i.e. not as fast as possible and not in intervals that are a multiple of full minutes, polling can be configured.
+The `pollingInterval` parameter specifies the time in seconds when data will be polled from the sensor.
+
+In addition to the mode one has to provide the port to which the device is connected.
+
+A full overview about the parameters of the `SDS011` thing is given in the following table:
+
+| parameter name    | mandatory | description                                                                           |
+|-------------------|-----------|---------------------------------------------------------------------------------------|
+| port              | yes       | the port the sensor is connected to, i.e. /dev/ttyUSB0.                              |
+| reporting         | no        | whether the reporting mode (value=true) or polling mode should be used.               |
+| reportingInterval | no        | the time in minutes between reportings from the sensor (default=1, min=0, max=30).    |
+| pollingInterval   | no        | the time in seconds between data polls from the device. (default=10, min=3, max=3600) |
+
+## Channels
+
+Since the supported device is a sensor, both channels are read-only channels. 
+
+| channel  | type           | description                   |
+|----------|----------------|-------------------------------|
+| pm25     | Number:Density | This provides the PM2.5 value |
+| pm10     | Number:Density | This provides the PM10 value  |
+
+## Full Example
+
+demo.things:
+
+```
+Thing novafinedust:SDS011:mySDS011Report "My SDS011 Fine Dust Sensor with reporting" [ port="/dev/ttyUSB0", reporting=true, reportingInterval=1 ]
+Thing novafinedust:SDS011:mySDS011Poll "My SDS011 Fine Dust Sensor with polling" [ port="/dev/ttyUSB0", reporting=false, pollingInterval=10 ]
+```
+
+demo.items:
+
+```
+Number:Density PM25 "My PM 2.5 value" { channel="novafinedust:SDS011:mySDS011Report:pm25" }
+Number:Density PM10 "My PM 10 value" { channel="novafinedust:SDS011:mySDS011Report:pm10" }
+```
+
+demo.sitemap:
+
+```
+sitemap demo label="Main Menu"
+{
+    Frame {
+        Text item=PM25 label="My PM 2.5 value"
+        Text item=PM10 label="My PM 10 value"
+    }
+}
+```
+
+## Limitations
+
+In theory one can have multiple sensors connected and distinguish them via their device ID. However, this is currently not implemented and the binding always configures any device and accepts data reportings from any device too.
+However, it is implemented that one can attach one sensor to one serial port, like `/dev/ttyUSB0` and a second sensor on a different serial port, like `/dev/ttyUSB1`.
diff --git a/bundles/org.openhab.binding.novafinedust/pom.xml b/bundles/org.openhab.binding.novafinedust/pom.xml
@@ -0,0 +1,16 @@
+<?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>2.5.6-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.novafinedust</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: NovaFineDust Binding</name>
+
+</project>
diff --git a/bundles/org.openhab.binding.novafinedust/src/main/feature/feature.xml b/bundles/org.openhab.binding.novafinedust/src/main/feature/feature.xml
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.novafinedust-${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-novafinedust" description="NovaFineDust Binding" version="${project.version}">
+        <feature>openhab-runtime-base</feature>
+        <feature>openhab-transport-serial</feature>
+        <bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.novafinedust/${project.version}</bundle>
+    </feature>
+</features>
diff --git a/...src/main/java/org/openhab/binding/novafinedust/internal/NovaFineDustBindingConstants.java b/...src/main/java/org/openhab/binding/novafinedust/internal/NovaFineDustBindingConstants.java
@@ -0,0 +1,35 @@
+/**
+ * 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.novafinedust.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.smarthome.core.thing.ThingTypeUID;
+
+/**
+ * The {@link NovaFineDustBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Stefan Triller - Initial contribution
+ */
+@NonNullByDefault
+public class NovaFineDustBindingConstants {
+
+    private static final String BINDING_ID = "novafinedust";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_SDS011 = new ThingTypeUID(BINDING_ID, "SDS011");
+
+    // List of all Channel ids
+    public static final String CHANNEL_PM25 = "pm25";
+    public static final String CHANNEL_PM10 = "pm10";
+}
diff --git a/...st/src/main/java/org/openhab/binding/novafinedust/internal/NovaFineDustConfiguration.java b/...st/src/main/java/org/openhab/binding/novafinedust/internal/NovaFineDustConfiguration.java
@@ -0,0 +1,32 @@
+/**
+ * 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.novafinedust.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link NovaFineDustConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Stefan Triller - Initial contribution
+ */
+@NonNullByDefault
+public class NovaFineDustConfiguration {
+
+    /**
+     * USB port of the device
+     */
+    public String port = "";
+    public boolean reporting = true;
+    public int reportingInterval = 1;
+    public int pollingInterval = 10;
+}
diff --git a/...t/src/main/java/org/openhab/binding/novafinedust/internal/NovaFineDustHandlerFactory.java b/...t/src/main/java/org/openhab/binding/novafinedust/internal/NovaFineDustHandlerFactory.java
@@ -0,0 +1,66 @@
+/**
+ * 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.novafinedust.internal;
+
+import static org.openhab.binding.novafinedust.internal.NovaFineDustBindingConstants.THING_TYPE_SDS011;
+
+import java.util.Collections;
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+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.eclipse.smarthome.io.transport.serial.SerialPortManager;
+import org.osgi.service.component.annotations.Activate;
+import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Reference;
+
+/**
+ * The {@link NovaFineDustHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Stefan Triller - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.novafinedust", service = ThingHandlerFactory.class)
+public class NovaFineDustHandlerFactory extends BaseThingHandlerFactory {
+
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Collections.singleton(THING_TYPE_SDS011);
+
+    private final SerialPortManager serialPortManager;
+
+    @Activate
+    public NovaFineDustHandlerFactory(@Reference SerialPortManager serialPortManager) {
+        this.serialPortManager = serialPortManager;
+    }
+
+    @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 (THING_TYPE_SDS011.equals(thingTypeUID)) {
+            return new SDS011Handler(thing, serialPortManager);
+        }
+
+        return null;
+    }
+}