[roku] binding - initial implementation (openhab#9571)

* Roku binding - initial implementation * update channel names to camelCase * review changes * spelling * update README.md Signed-off-by: Michael Lobstein <[email protected]>
thinkingstone · Nov 7, 2021 · f343b55 · f343b55
1 parent 9e119fc
commit f343b55
Show file tree

Hide file tree

Showing 23 changed files with 2,659 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -218,6 +218,7 @@
 /bundles/org.openhab.binding.rfxcom/ @martinvw @paulianttila
 /bundles/org.openhab.binding.rme/ @kgoderis
 /bundles/org.openhab.binding.robonect/ @reyem
+/bundles/org.openhab.binding.roku/ @mlobstein
 /bundles/org.openhab.binding.rotel/ @lolodomo
 /bundles/org.openhab.binding.russound/ @tmrobert8
 /bundles/org.openhab.binding.sagercaster/ @clinique

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -1076,6 +1076,11 @@
       <artifactId>org.openhab.binding.robonect</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.roku</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.rotel</artifactId>

diff --git a/bundles/org.openhab.binding.roku/NOTICE b/bundles/org.openhab.binding.roku/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.roku/README.md b/bundles/org.openhab.binding.roku/README.md
@@ -0,0 +1,111 @@
+# Roku Binding
+
+This binding connects Roku streaming media players and Roku TVs to openHAB.
+The Roku device must support the Roku ECP protocol REST API.
+
+## Supported Things
+
+There are two supported thing types, which represent either a standalone Roku device or a Roku TV.
+A supported Roku streaming media player or streaming stick uses the `roku_player` id and a supported Roku TV uses the `roku_tv` id.
+The binding functionality is the same for both types, but the Roku TV type adds additional button commands to the button channel dropdown.
+Multiple Things can be added if more than one Roku is to be controlled.
+
+## Discovery
+
+Auto-discovery is supported if the Roku can be located on the local network using SSDP.
+Otherwise the thing must be manually added.
+
+## 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                                                                                                |
+|-----------|------------------------------------------------------------------------------------------------------------|
+| hostName  | The host name or IP address of the Roku device. Mandatory.                                                 |
+| port      | The port on the Roku that listens for http connections. Default 8060                                       |
+| refresh   | Overrides the refresh interval for player status updates. Optional, the default and minimum is 10 seconds. |
+
+## Channels
+
+The following channels are available:
+
+| Channel ID      | Item Type   | Description                                                                                                                                             |
+|-----------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
+| activeApp       | String      | A dropdown containing a list of all apps installed on the Roku. The app currently running is automatically selected. The list updates every 10 minutes. |
+| button          | String      | Sends a remote control command the Roku. See list of available commands below.                                                                          |
+| playMode        | String      | The current playback mode ie: stop, play, pause (ReadOnly).                                                                                             |
+| timeElapsed     | Number:Time | The total number of seconds of playback time elapsed for the current playing title (ReadOnly).                                                          |
+| timeTotal       | Number:Time | The total length of the current playing title in seconds (ReadOnly). This data is not provided by all streaming apps.                                   |
+
+Some Notes:
+
+* The values for `activeApp`, `playMode`, `timeElapsed` & `timeTotal` refresh automatically per the configured `refresh` interval (10 seconds minimum).
+
+**List of available button commands for Roku streaming devices:**  
+Home  
+Rev  
+Fwd  
+Play  
+Select  
+Left  
+Right  
+Up  
+Down  
+Back  
+InstantReplay  
+Info  
+Backspace  
+Search  
+Enter  
+FindRemote  
+
+**List of additional button commands for Roku TVs:**  
+ChannelUp  
+ChannelDown  
+VolumeUp  
+VolumeDown  
+VolumeMute  
+InputTuner  
+InputHDMI1  
+InputHDMI2  
+InputHDMI3  
+InputHDMI4  
+InputAV1  
+PowerOff  
+
+## Full Example
+
+roku.things:
+
+```java
+roku:roku_player:myplayer1 "My Roku" [ hostName="192.168.10.1", refresh=10 ]
+roku:roku_tv:myplayer1 "My Roku TV" [ hostName="192.168.10.1", refresh=10 ]
+```
+
+roku.items:
+
+```java
+String Player_ActiveApp         "Current App: [%s]"         { channel="roku:roku_player:myplayer1:activeApp" }
+String Player_Button            "Send Command to Roku"      { channel="roku:roku_player:myplayer1:button" }
+String Player_PlayMode         "Status: [%s]"              { channel="roku:roku_player:myplayer1:playMode" }
+Number:Time Player_TimeElapsed "Elapsed Time: [%d %unit%]" { channel="roku:roku_player:myplayer1:timeElapsed" }
+Number:Time Player_TimeTotal   "Total Time: [%d %unit%]"   { channel="roku:roku_player:myplayer1:timeTotal" }
+```
+
+roku.sitemap:
+
+```perl
+sitemap roku label="Roku" {
+    Frame label="My Roku" {
+        Selection item=Player_ActiveApp icon="screen"
+        Selection item=Player_Button icon="screen"
+        Text item=Player_PlayMode
+        Text item=Player_TimeElapsed icon="time"
+        Text item=Player_TimeTotal icon="time"
+    }
+}
+```
diff --git a/bundles/org.openhab.binding.roku/pom.xml b/bundles/org.openhab.binding.roku/pom.xml
@@ -0,0 +1,17 @@
+<?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>3.1.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.roku</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Roku Binding</name>
+
+</project>
diff --git a/bundles/org.openhab.binding.roku/src/main/feature/feature.xml b/bundles/org.openhab.binding.roku/src/main/feature/feature.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.roku-${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-roku" description="Roku Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.roku/${project.version}</bundle>
+	</feature>
+</features>
diff --git a/...ab.binding.roku/src/main/java/org/openhab/binding/roku/internal/RokuBindingConstants.java b/...ab.binding.roku/src/main/java/org/openhab/binding/roku/internal/RokuBindingConstants.java
@@ -0,0 +1,66 @@
+/**
+ * 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.roku.internal;
+
+import java.util.Set;
+
+import javax.measure.Unit;
+import javax.measure.quantity.Time;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.library.unit.Units;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link RokuBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Michael Lobstein - Initial contribution
+ */
+@NonNullByDefault
+public class RokuBindingConstants {
+    public static final String BINDING_ID = "roku";
+    public static final String PROPERTY_UUID = "uuid";
+    public static final String PROPERTY_HOST_NAME = "hostName";
+    public static final String PROPERTY_PORT = "port";
+    public static final String PROPERTY_MODEL_NAME = "Model Name";
+    public static final String PROPERTY_MODEL_NUMBER = "Model Number";
+    public static final String PROPERTY_DEVICE_LOCAITON = "Device Location";
+    public static final String PROPERTY_SERIAL_NUMBER = "Serial Number";
+    public static final String PROPERTY_DEVICE_ID = "Device Id";
+    public static final String PROPERTY_SOFTWARE_VERSION = "Software Version";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_ROKU_PLAYER = new ThingTypeUID(BINDING_ID, "roku_player");
+    public static final ThingTypeUID THING_TYPE_ROKU_TV = new ThingTypeUID(BINDING_ID, "roku_tv");
+    public static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(THING_TYPE_ROKU_PLAYER,
+            THING_TYPE_ROKU_TV);
+
+    // List of all Channel id's
+    public static final String ACTIVE_APP = "activeApp";
+    public static final String BUTTON = "button";
+    public static final String PLAY_MODE = "playMode";
+    public static final String TIME_ELAPSED = "timeElapsed";
+    public static final String TIME_TOTAL = "timeTotal";
+
+    // Units of measurement of the data delivered by the API
+    public static final Unit<Time> API_SECONDS_UNIT = Units.SECOND;
+
+    public static final String STOP = "stop";
+    public static final String CLOSE = "close";
+    public static final String EMPTY = "";
+    public static final String ROKU_HOME = "Roku Home";
+    public static final String ROKU_HOME_ID = "-1";
+    public static final String ROKU_HOME_BUTTON = "Home";
+    public static final String NON_DIGIT_PATTERN = "[^\\d]";
+}
diff --git a/...enhab.binding.roku/src/main/java/org/openhab/binding/roku/internal/RokuConfiguration.java b/...enhab.binding.roku/src/main/java/org/openhab/binding/roku/internal/RokuConfiguration.java
@@ -0,0 +1,29 @@
+/**
+ * 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.roku.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+/**
+ * The {@link RokuConfiguration} is the class used to match the
+ * thing configuration.
+ *
+ * @author Michael Lobstein - Initial contribution
+ */
+@NonNullByDefault
+public class RokuConfiguration {
+    public @Nullable String hostName;
+    public Integer port = 8060;
+    public Integer refresh = 10;
+}
diff --git a/...nhab.binding.roku/src/main/java/org/openhab/binding/roku/internal/RokuHandlerFactory.java b/...nhab.binding.roku/src/main/java/org/openhab/binding/roku/internal/RokuHandlerFactory.java
@@ -0,0 +1,67 @@
+/**
+ * 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.roku.internal;
+
+import static org.openhab.binding.roku.internal.RokuBindingConstants.SUPPORTED_THING_TYPES_UIDS;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.eclipse.jetty.client.HttpClient;
+import org.openhab.binding.roku.internal.handler.RokuHandler;
+import org.openhab.core.io.net.http.HttpClientFactory;
+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 RokuHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Michael Lobstein - Initial contribution
+ */
+@NonNullByDefault
+@Component(service = ThingHandlerFactory.class, configurationPid = "binding.roku")
+public class RokuHandlerFactory extends BaseThingHandlerFactory {
+
+    private final HttpClient httpClient;
+    private final RokuStateDescriptionOptionProvider stateDescriptionProvider;
+
+    @Activate
+    public RokuHandlerFactory(final @Reference HttpClientFactory httpClientFactory,
+            final @Reference RokuStateDescriptionOptionProvider provider) {
+        this.httpClient = httpClientFactory.getCommonHttpClient();
+        this.stateDescriptionProvider = provider;
+    }
+
+    @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 (SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID)) {
+            RokuHandler handler = new RokuHandler(thing, httpClient, stateDescriptionProvider);
+            return handler;
+        }
+
+        return null;
+    }
+}
diff --git a/...enhab.binding.roku/src/main/java/org/openhab/binding/roku/internal/RokuHttpException.java b/...enhab.binding.roku/src/main/java/org/openhab/binding/roku/internal/RokuHttpException.java
@@ -0,0 +1,29 @@
+/**
+ * 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.roku.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link RokuHttpException} extends Exception
+ *
+ * @author Michael Lobstein - Initial contribution
+ */
+@NonNullByDefault
+public class RokuHttpException extends Exception {
+    private static final long serialVersionUID = 1L;
+
+    public RokuHttpException(String errorMessage) {
+        super(errorMessage);
+    }
+}