Add Notification API support (#5465)

* Add Notification API support Signed-off-by: Ivaylo Ivanov <ivivanov.bg@gmail.com>
eclipse-archived · May 18, 2018 · 399d380 · 399d380
1 parent f402f60
commit 399d380
Show file tree

Hide file tree

Showing 14 changed files with 200 additions and 24 deletions.
diff --git a/extensions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/config/config.xml b/extensions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/config/config.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <config-description:config-descriptions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xmlns:config-description="http://eclipse.org/smarthome/schemas/config-description/v1.0.0"
-	xsi:schemaLocation="http://eclipse.org/smarthome/schemas/config-description/v1.0.0 http://eclipse.org/smarthome/schemas/config-description-1.0.0.xsd">
-
+	xsi:schemaLocation="http://eclipse.org/smarthome/schemas/config-description/v1.0.0 http://eclipse.org/smarthome/schemas/config-description-1.0.0.xsd"
+>
 	<config-description uri="thing-type:bosesoundtouch:config">
 		<parameter name="host" type="text" required="true">
 			<label>Host Address</label>
@@ -14,6 +14,44 @@
 			<description>The MAC Address used for communication to this device.
 			</description>
 		</parameter>
+		<parameter name="appKey" type="text" required="false">
+			<label>Authorization Key</label>
+			<description>An authorization key used to identify the client application.
+						Should be requested from the developer portal.
+			</description>
+		</parameter>
+	</config-description>
+
+	<config-description uri="channel-type:bosesoundtouch:notificationSound">
+		<parameter name="notificationVolume" type="integer" min="10" max="70" step="1" unit="%" required="false">
+			<label>Notification Sound Volume</label>
+			<description>This indicates the desired volume level while playing the notification. 
+						The value represents a percentage (0 to 100) of the full audible range of the speaker device. 
+						A value less than 10 or greater than 70 will result in an error and not play the notification. 
+						Upon completion of the notification, the speaker volume will return to its original value. 
+						If not present, the notification will play at the existing volume level.
+			</description>
+		</parameter>
+		<parameter name="notificationService" type="text" required="true">
+			<label>Notification Service</label>
+			<description>This indicates the service providing the notification. 
+						This text will appear on the device display (when available) and the SoundTouch application screen.
+			</description>
+			<default>Notification</default>
+		</parameter>
+		<parameter name="notificationReason" type="text" required="false">
+			<label>Notification Reason</label>
+			<description>This indicates the reason for the notification. 
+						This text will appear on the device display (when available) and the SoundTouch application screen. 
+						If a reason string is not provided, the field with be blank.
+			</description>
+		</parameter>
+		<parameter name="notificationMessage" type="text" required="false">
+			<label>Notification Message</label>
+			<description>This indicates further details about the notification. 
+						This text will appear on the device display (when available) and the SoundTouch application screen. 
+						If a message string is not provided, the field with be blank.
+			</description>
+		</parameter>
 	</config-description>
-
-</config-description:config-descriptions>
+</config-description:config-descriptions>
diff --git a/...sions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/thing/SoundTouch10.xml b/...sions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/thing/SoundTouch10.xml
@@ -3,7 +3,7 @@
 	xmlns:thing="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0"
 	xsi:schemaLocation="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0 http://eclipse.org/smarthome/schemas/thing-description-1.0.0.xsd">
 
-	<thing-type id="10">
+	<thing-type id="10" extensible="notificationsound">
 		<label>Bose SoundTouch 10</label>
 		<description>Bose SoundTouch 10 Speaker</description>
 
@@ -32,6 +32,8 @@
 			<channel id="nowPlayingStationLocation" typeId="nowPlayingStationLocation" />
 			<channel id="nowPlayingStationName" typeId="nowPlayingStationName" />
 			<channel id="nowPlayingTrack" typeId="nowPlayingTrack" />
+			<!-- Notification channels -->
+			<channel id="notificationsound" typeId="notificationsound" />
 		</channels>
 		<config-description-ref uri="thing-type:bosesoundtouch:config" />
 	</thing-type>

diff --git a/...sions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/thing/SoundTouch20.xml b/...sions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/thing/SoundTouch20.xml
@@ -3,7 +3,7 @@
 	xmlns:thing="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0"
 	xsi:schemaLocation="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0 http://eclipse.org/smarthome/schemas/thing-description-1.0.0.xsd">
 
-	<thing-type id="20">
+	<thing-type id="20" extensible="notificationsound" >
 		<label>Bose SoundTouch 20</label>
 		<description>Bose SoundTouch 20 Speaker</description>
 
@@ -32,6 +32,8 @@
 			<channel id="nowPlayingStationLocation" typeId="nowPlayingStationLocation" />
 			<channel id="nowPlayingStationName" typeId="nowPlayingStationName" />
 			<channel id="nowPlayingTrack" typeId="nowPlayingTrack" />
+			<!-- Notification channels -->
+			<channel id="notificationsound" typeId="notificationsound" />
 		</channels>
 		<config-description-ref uri="thing-type:bosesoundtouch:config" />
 	</thing-type>

diff --git a/...sions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/thing/SoundTouch30.xml b/...sions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/thing/SoundTouch30.xml
@@ -3,7 +3,7 @@
 	xmlns:thing="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0"
 	xsi:schemaLocation="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0 http://eclipse.org/smarthome/schemas/thing-description-1.0.0.xsd">
 
-	<thing-type id="30">
+	<thing-type id="30" extensible="notificationsound">
 		<label>Bose SoundTouch 30</label>
 		<description>Bose SoundTouch 30 Speaker</description>
 
@@ -32,6 +32,8 @@
 			<channel id="nowPlayingStationLocation" typeId="nowPlayingStationLocation" />
 			<channel id="nowPlayingStationName" typeId="nowPlayingStationName" />
 			<channel id="nowPlayingTrack" typeId="nowPlayingTrack" />
+			<!-- Notification channels -->
+			<channel id="notificationsound" typeId="notificationsound" />
 		</channels>
 		<config-description-ref uri="thing-type:bosesoundtouch:config" />
 	</thing-type>

diff --git a/extensions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/thing/channels.xml b/extensions/binding/org.eclipse.smarthome.binding.bosesoundtouch/ESH-INF/thing/channels.xml
@@ -281,5 +281,11 @@
 			</options>
 		</state>
 	</channel-type>
-
+	<!-- Notification channels -->
+	<channel-type id="notificationsound" advanced="true">
+		<item-type>String</item-type>
+		<label>Notification Sound</label>
+		<description>Play a notification sound by a given URI</description>
+		<config-description-ref uri="channel-type:bosesoundtouch:notificationSound" />
+	</channel-type>
 </thing:thing-descriptions>
diff --git a/extensions/binding/org.eclipse.smarthome.binding.bosesoundtouch/META-INF/MANIFEST.MF b/extensions/binding/org.eclipse.smarthome.binding.bosesoundtouch/META-INF/MANIFEST.MF
@@ -33,6 +33,7 @@ Import-Package:
  org.eclipse.smarthome.core.thing.type,
  org.eclipse.smarthome.core.types,
  org.eclipse.smarthome.io.net.http,
+ org.osgi.service.component.annotations;resolution:=optional,
  org.slf4j
 Service-Component: OSGI-INF/*.xml
 Export-Package: org.eclipse.smarthome.binding.bosesoundtouch,

diff --git a/extensions/binding/org.eclipse.smarthome.binding.bosesoundtouch/README.md b/extensions/binding/org.eclipse.smarthome.binding.bosesoundtouch/README.md
@@ -29,13 +29,16 @@ The binding has no configuration options, all configuration is done at Thing lev
 
 All thing types have the same configuration parameters:
 
-| Parameter Name | Type   | Required | Description                                                  |
-|----------------|--------|----------|--------------------------------------------------------------|
-| host           | String | Yes      | The host name or IP address of the device                    |
-| macAddress     | String | Yes      | The MAC address of the used interface (format "123456789ABC")|
+| Parameter Name      | Type   | Required | Description                                                  |
+|---------------------|--------|----------|--------------------------------------------------------------|
+| host                | String | Yes      | The host name or IP address of the device                    |
+| macAddress          | String | Yes      | The MAC address of the used interface (format "123456789ABC")|
+| appKey              | String |  No      | An authorization key used to identify the client application |
 
-Both are set when using discovery. For manual configuration, these values can be found in the Bose smartphone app (Settings -> About -> Device Name).
+The required properties are set when using discovery. For manual configuration, these values can be found in the Bose smartphone app (Settings -> About -> Device Name).
 Note that the device might have two MAC addresses, one for ethernet and one for Wifi.
+
+The authorization key is used to identify the client application when using the Notification API. It must be requested from the developer portal.
 
 ## Channels
 
@@ -45,6 +48,7 @@ All devices share the same set of channels, while some of them might not be avai
 |---------------------------|-----------|--------------------------------------------------------------|
 | keyCode                   | String    | Simulates pushing a remote control button                    |
 | mute                      | Switch    | Mutes the sound                                              |
+| notificationsound         | String    | Play a notification sound by a given URI                     |                              
 | nowPlayingAlbum           | String    | Current playing album name                                   |
 | nowPlayingArtist          | String    | Current playing artist name                                  |
 | nowPlayingArtwork         | Image     | Artwork for the current playing song                         |
@@ -54,7 +58,7 @@ All devices share the same set of channels, while some of them might not be avai
 | nowPlayingStationLocation | String    | Location of current playing radio station                    |
 | nowPlayingStationName     | String    | Name of current playing radio station                        |
 | nowPlayingTrack           | String    | Track currently playing                                      |
-| operationMode             | String    |  Current Operation Mode                                      |
+| operationMode             | String    | Current Operation Mode                                       |
 | playerControl             | Player    | Control the Player                                           |
 | power                     | Switch    | SoundTouch power state                                       |
 | preset                    | Number    | 1-6 Preset of Soundtouch, >7 Binding Presets                 |
@@ -65,6 +69,17 @@ All devices share the same set of channels, while some of them might not be avai
 | volume                    | Dimmer    | Set or get the volume                                        |
 | bass                      | Number    | Bass (-9 minimum, 0 maximum)                                 |
 
+
+The *notificationsound* channel has the following optional configuration parameters:
+
+ - notificationVolume - Desired volume level while playing the notification, it must be between 10 and 70 (inclusive). A value outside this range will result in an error and not play the notification.
+ - notificationService - The service providing the notification
+ - notificationReason - The reason for the notification
+ - notificationMessage - Further details about the notification
+
+The texts for the notification service, reason and message appear on the device display (when available) and the SoundTouch application screen.
+Upon completion of the notification, the speaker volume returns to its original value. If not present, the notification will play at the existing volume level.
+
 ## Full Example
 
 Things:

diff --git a/...ain/java/org/eclipse/smarthome/binding/bosesoundtouch/BoseSoundTouchBindingConstants.java b/...ain/java/org/eclipse/smarthome/binding/bosesoundtouch/BoseSoundTouchBindingConstants.java
@@ -46,7 +46,7 @@ public class BoseSoundTouchBindingConstants {
             BST_10_THING_TYPE_UID, BST_20_THING_TYPE_UID, BST_30_THING_TYPE_UID, BST_300_THING_TYPE_UID,
             BST_WLA_THING_TYPE_UID, BST_WSMS_THING_TYPE_UID, BST_SA5A_THING_TYPE_UID);
 
-    public static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = new HashSet<ThingTypeUID>(
+    public static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = new HashSet<>(
             SUPPORTED_KNOWN_THING_TYPES_UIDS);
 
     // List of all Channel IDs
@@ -71,9 +71,7 @@ public class BoseSoundTouchBindingConstants {
     public static final String CHANNEL_NOWPLAYING_STATIONLOCATION = "nowPlayingStationLocation";
     public static final String CHANNEL_NOWPLAYING_STATIONNAME = "nowPlayingStationName";
     public static final String CHANNEL_NOWPLAYING_TRACK = "nowPlayingTrack";
-
-    // Device configuration parameters;
-    public static final String DEVICE_PARAMETER_HOST = "host";
+    public static final String CHANNEL_NOTIFICATION_SOUND = "notificationsound";
 
     // Device information parameters;
     public static final String DEVICE_INFO_NAME = "INFO_NAME";

diff --git a/...c/main/java/org/eclipse/smarthome/binding/bosesoundtouch/BoseSoundTouchConfiguration.java b/...c/main/java/org/eclipse/smarthome/binding/bosesoundtouch/BoseSoundTouchConfiguration.java
@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2014,2018 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * 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.eclipse.smarthome.binding.bosesoundtouch;
+
+import org.eclipse.smarthome.core.thing.Thing;
+
+/**
+ * Configuration class for soundtouch
+ *
+ * @author Ivaylo Ivanov - Initial contribution
+ */
+public class BoseSoundTouchConfiguration {
+
+    // Device configuration parameters;
+    public static final String HOST = "host";
+    public static final String MAC_ADDRESS = Thing.PROPERTY_MAC_ADDRESS;
+    public static final String APP_KEY = "appKey";
+
+    public String host;
+    public String macAddress;
+    public String appKey;
+}
diff --git a/...main/java/org/eclipse/smarthome/binding/bosesoundtouch/handler/BoseSoundTouchHandler.java b/...main/java/org/eclipse/smarthome/binding/bosesoundtouch/handler/BoseSoundTouchHandler.java
@@ -17,6 +17,7 @@
 import java.io.IOException;
 import java.net.URI;
 import java.util.Arrays;
+import java.util.Objects;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
@@ -26,7 +27,9 @@
 import org.eclipse.jetty.websocket.api.WebSocketListener;
 import org.eclipse.jetty.websocket.client.ClientUpgradeRequest;
 import org.eclipse.jetty.websocket.client.WebSocketClient;
+import org.eclipse.smarthome.binding.bosesoundtouch.BoseSoundTouchConfiguration;
 import org.eclipse.smarthome.binding.bosesoundtouch.internal.APIRequest;
+import org.eclipse.smarthome.binding.bosesoundtouch.internal.BoseSoundTouchNotificationChannelConfiguration;
 import org.eclipse.smarthome.binding.bosesoundtouch.internal.CommandExecutor;
 import org.eclipse.smarthome.binding.bosesoundtouch.internal.OperationModeType;
 import org.eclipse.smarthome.binding.bosesoundtouch.internal.PresetContainer;
@@ -38,11 +41,13 @@
 import org.eclipse.smarthome.core.library.types.PercentType;
 import org.eclipse.smarthome.core.library.types.PlayPauseType;
 import org.eclipse.smarthome.core.library.types.StringType;
+import org.eclipse.smarthome.core.thing.Channel;
 import org.eclipse.smarthome.core.thing.ChannelUID;
 import org.eclipse.smarthome.core.thing.Thing;
 import org.eclipse.smarthome.core.thing.ThingStatus;
 import org.eclipse.smarthome.core.thing.ThingStatusDetail;
 import org.eclipse.smarthome.core.thing.binding.BaseThingHandler;
+import org.eclipse.smarthome.core.thing.type.ChannelTypeUID;
 import org.eclipse.smarthome.core.types.Command;
 import org.eclipse.smarthome.core.types.RefreshType;
 import org.eclipse.smarthome.core.types.State;
@@ -223,6 +228,29 @@ public void handleCommand(ChannelUID channelUID, Command command) {
                 }
                 break;
             default:
+                Channel channel = getThing().getChannel(channelUID.getId());
+                if (channel != null) {
+                    ChannelTypeUID chTypeUid = channel.getChannelTypeUID();
+                    if (chTypeUid != null) {
+                        switch (channel.getChannelTypeUID().getId()) {
+                            case CHANNEL_NOTIFICATION_SOUND:
+                                String appKey = Objects.toString(getConfig().get(BoseSoundTouchConfiguration.APP_KEY), null);
+                                if (appKey != null && !appKey.isEmpty()) {
+                                    if (command instanceof StringType) {
+                                        String url = command.toString();
+                                        BoseSoundTouchNotificationChannelConfiguration notificationConfiguration = channel
+                                                .getConfiguration().as(BoseSoundTouchNotificationChannelConfiguration.class);
+                                        if (!url.isEmpty()) {
+                                            commandExecutor.playNotificationSound(appKey, notificationConfiguration, url);
+                                        }
+                                    }
+                                } else {
+                                    logger.warn("Missing app key - cannot use notification api");
+                                }
+                                return;
+                        }
+                    }
+                }
                 logger.warn("{} : Got command '{}' for channel '{}' which is unhandled!", getDeviceName(), command,
                         channelUID.getId());
                 break;
@@ -272,7 +300,7 @@ public String getDeviceType() {
      * @return the MAC Address of this device (in format "123456789ABC")
      */
     public String getMacAddress() {
-        return ((String) getThing().getConfiguration().get(Thing.PROPERTY_MAC_ADDRESS)).replaceAll(":", "");
+        return ((String) getThing().getConfiguration().get(BoseSoundTouchConfiguration.MAC_ADDRESS)).replaceAll(":", "");
     }
 
     /**
@@ -281,7 +309,7 @@ public String getMacAddress() {
      * @return the IP Address of this device
      */
     public String getIPAddress() {
-        return (String) getThing().getConfiguration().getProperties().get(DEVICE_PARAMETER_HOST);
+        return (String) getThing().getConfiguration().getProperties().get(BoseSoundTouchConfiguration.HOST);
     }
 
     /**

diff --git a/...thome/binding/bosesoundtouch/internal/BoseSoundTouchNotificationChannelConfiguration.java b/...thome/binding/bosesoundtouch/internal/BoseSoundTouchNotificationChannelConfiguration.java
@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2014,2018 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * 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.eclipse.smarthome.binding.bosesoundtouch.internal;
+
+/**
+ * Configuration class for soundtouch notification channel
+ *
+ * @author Ivaylo Ivanov - Initial contribution
+ */
+public class BoseSoundTouchNotificationChannelConfiguration {
+
+    public static final String NOTIFICATION_VOLUME = "notificationVolume";
+    public static final String NOTIFICATION_SERVICE = "notificationService";
+    public static final String NOTIFICATION_REASON = "notificationReason";
+    public static final String NOTIFICATION_MESSAGE = "notificationMessage";
+
+    public Integer notificationVolume;
+    public String notificationService;
+    public String notificationReason;
+    public String notificationMessage;
+}