Improve volume event handling (#17387)

Signed-off-by: Michael Lobstein <michael.lobstein@gmail.com>
Signed-off-by: Ciprian Pascu <contact@ciprianpascu.ro>

bundles/org.openhab.binding.kaleidescape/README.md

@@ -31,13 +31,14 @@ In the Inbox, select Search For Things and then choose the Kaleidescape Binding
 The thing has the following configuration parameters:
 
 | Parameter Label                   | Parameter ID           | Description                                                                                                                             | Accepted values                                      |
-|--------------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
+|-----------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
 | Address                           | host                   | Host name or IP address of the Kaleidescape component                                                                                   | A host name or IP address                            |
 | Port                              | port                   | Communication port of the IP connection                                                                                                 | 10000 (default - should not need to change)          |
 | Serial Port                       | serialPort             | Serial port for connecting directly a component                                                                                         | Serial port name (optional)                          |
 | Update Period                     | updatePeriod           | Tells the component how often time status updates should be sent (see notes below)                                                      | 0 or 1 are the currently accepted values (default 0) |
-| Volume Control Enabled   | volumeEnabled          | Enable the volume and mute controls in the K iPad & phone apps                                                                       | Boolean (default false)                              |
+| Advanced Volume Control Enabled   | volumeEnabled          | Enable the volume and mute controls in the K iPad & phone apps; when enabled the volume and mute channels described below are active    | Boolean (default false)                              |
 | Initial Volume Setting            | initialVolume          | Initial volume level set when the binding starts up                                                                                     | 0 to 75 (default 25)                                 |
+| Basic Volume Control Enabled      | volumeBasicEnabled     | Enables stateless volume up/down and mute controls in the K apps; cannot be used when `volumeEnabled` is true (see rules example below) | Boolean (default false)                              |
 | Load Highlighted Details          | loadHighlightedDetails | When enabled the binding will automatically load the the metadata channels when the selected item in the UI (Movie or Album) changes    | Boolean (default false)                              |
 | Load Album Details                | loadAlbumDetails       | When enabled the binding will automatically load the metadata channels for the currently playing Album                                  | Boolean (default false) N/A for Alto and Strato      |
 
@@ -59,10 +60,10 @@ Some notes:
 The following channels are available:
 
 | Channel ID                 | Item Type   | Description                                                                                                                     |
-|----------------------------|-------------|------------------------------------------------------------------------------------------------------------------|
+|----------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------|
 | ui#power                   | Switch      | Turn the zone On or Off (system standby)                                                                                        |
-| ui#volume                  | Dimmer      | A virtual volume that tracks the volume in K control apps, use as a proxy to adjust a real volume item via rules |
+| ui#volume                  | Dimmer      | A virtual volume that tracks the volume control from the K app, use as a proxy to adjust a real volume item via follow or rules |
-| ui#mute                    | Switch      | A virtual mute switch that tracks the mute status in K control apps, use as a proxy to control a real mute item  |
+| ui#mute                    | Switch      | A virtual mute switch that tracks the mute status from the K app, use as a proxy to control a real mute item                    |
 | ui#control                 | Player      | Control Movie Playback e.g. play/pause/next/previous/ffward/rewind                                                              |
 | ui#title_name              | String      | The title of the movie currently playing                                                                                        |
 | ui#play_mode               | String      | The current playback mode of the movie                                                                                          |
@@ -139,9 +140,9 @@ The following channels are available:
 kaleidescape.things:
 
 ```java
-kaleidescape:player:myzone1 "M500 Living Rm" [ host="192.168.1.10", updatePeriod=0, loadHighlightedDetails=true, loadAlbumDetails=true ]
+kaleidescape:strato:myzone1 "Strato Theater Rm" [ host="192.168.1.10", updatePeriod=0, loadHighlightedDetails=true ]
-kaleidescape:cinemaone:myzone2 "My Cinema One" [ host="192.168.1.11", updatePeriod=0, loadHighlightedDetails=true, loadAlbumDetails=true ]
+kaleidescape:player:myzone2 "M500 Living Rm" [ host="192.168.1.11", updatePeriod=0, loadHighlightedDetails=true, loadAlbumDetails=true ]
-kaleidescape:strato:myzone3 "Strato Theater Rm" [ host="192.168.1.12", updatePeriod=0, loadHighlightedDetails=true ]
+kaleidescape:cinemaone:myzone3 "My Cinema One" [ host="192.168.1.12", updatePeriod=0, loadHighlightedDetails=true, loadAlbumDetails=true ]
 ```
 
 kaleidescape.items:
@@ -346,18 +347,13 @@ kaleidescape.rules:
 
 ```java
 var int lightPercent
-val kactions = getActions("kaleidescape","kaleidescape:player:myzone1")
 
 // send command to go to movie covers when button pressed
 rule "Go to Movie Covers"
 when
     Item z1_GoMovieCovers received command
 then
-    if (null === kactions) {
+    z1_Ui_Sendcmd.sendCommand("GO_MOVIE_COVERS")
-      logInfo("kactions", "Actions not found, check thing ID")
-      return
-    }
-    kactions.sendKCommand("GO_MOVIE_COVERS")
 end
 
 // send command to play a script
@@ -365,14 +361,36 @@ rule "Play Script - Great Vistas"
 when
     Item z1_PlayScript received command
 then
-    if (null === kactions) {
+    z1_Ui_Sendcmd.sendCommand("PLAY_SCRIPT:Great Vistas")
-      logInfo("kactions", "Actions not found, check thing ID")
-      return
-    }
-    kactions.sendKCommand("PLAY_SCRIPT:Great Vistas")
 end
 
-// handle a control system command sent from a script
+// handle volume events from K apps or IR remote
+// the events can be used to send a command to another item that controls volume
+rule "Handle volume events"
+when
+    Item z1_Ui_UserDefinedEvent received update
+then
+    var volEvt = newState.toString()
+
+    // When `volumeBasicEnabled` is true for the thing, VOLUME_UP, VOLUME_DOWN and TOGGLE_MUTE are received from the iPad and phone apps
+    // VOLUME_UP_PRESS/RELEASE, VOLUME_DOWN_PRESS/RELEASE, TOGGLE_MUTE events will always be received from the IR remote
+    // *RELEASE events are not used in this example
+
+    if (volEvt == "VOLUME_UP" || volEvt == "VOLUME_UP_PRESS") {
+        logInfo("k rules", "Volumne Up received")
+    }
+
+    if (volEvt == "VOLUME_DOWN" || volEvt == "VOLUME_DOWN_PRESS") {
+        logInfo("k rules", "Volumne Down received")
+    }
+
+    if (volEvt == "TOGGLE_MUTE") {
+        logInfo("k rules", "Mute Toggle received")
+    }
+end
+
+// handle a control system command sent from a kaleidescape script
+// the command string is specified in a "Send command to control system" script step
 rule "Handle script commands"
 when
     Item z1_Ui_UserDefinedEvent received update
@@ -412,6 +430,28 @@ then
     logInfo("k rules", "intermission over")
 end
 
+rule "Movie Search"
+when
+    Item z1_MovieSearch received update
+then
+    if (newState != NULL && newState.toString.length > 0) {
+        z1_Ui_Sendcmd.sendCommand("GO_MOVIE_LIST")
+        Thread::sleep(1000)
+        z1_Ui_Sendcmd.sendCommand("FILTER_LIST")
+        Thread::sleep(300)
+
+        var i = 0
+        var srch = newState.toString.toUpperCase
+        logInfo("k rules","Searching for: " + srch)
+
+        while (i < (srch.length)) {
+            z1_Ui_Sendcmd.sendCommand("KEYBOARD_CHARACTER:" + srch.charAt(i).toString)
+            Thread::sleep(100)
+            i++
+        }
+    }
+end
+
 // The following are no longer required since the thing configuration will enable automatic loading of metatdata.
 // However the examples are still valid for advanced use cases where retrieving metadata from an arbitrary content handle is desired.
 
@@ -419,43 +459,13 @@ rule "Load selected item Metadata"
 when
     Item z1_Ui_HighlightedSelection changed
 then
-    if (null === kactions) {
+    z1_Ui_Sendcmd.sendCommand("GET_CONTENT_DETAILS:" + z1_Ui_HighlightedSelection.state.toString + ":")
-      logInfo("kactions", "Actions not found, check thing ID")
-      return
-    }
-    kactions.sendKCommand("GET_CONTENT_DETAILS:" + z1_Ui_HighlightedSelection.state.toString + ":")
 end
 
 rule "Load Metadata for currently playing album"
 when
     Item z1_Music_AlbumHandle changed
 then
-    if (null === kactions) {
+    z1_Ui_Sendcmd.sendCommand("GET_CONTENT_DETAILS:" + z1_Music_AlbumHandle.state.toString + ":")
-      logInfo("kactions", "Actions not found, check thing ID")
-      return
-    }
-    kactions.sendKCommand("GET_CONTENT_DETAILS:" + z1_Music_AlbumHandle.state.toString + ":")
-end
-
-rule "Movie Search"
-when
-    Item z1_MovieSearch received update
-then
-    if (newState != NULL && newState.toString.length > 0) {
-        kactions.sendKCommand("GO_MOVIE_LIST")
-        Thread::sleep(1000)
-        kactions.sendKCommand("FILTER_LIST")
-        Thread::sleep(300)
-
-        var i = 0
-        var srch = newState.toString.toUpperCase
-        logInfo("kaleidescape.search","Searching for: " + srch)
-
-        while (i < (srch.length)) {
-            kactions.sendKCommand("KEYBOARD_CHARACTER:" + srch.charAt(i).toString)
-            Thread::sleep(100)
-            i++
-        }
-    }
 end
 ```

bundles/org.openhab.binding.kaleidescape/src/main/java/org/openhab/binding/kaleidescape/internal/KaleidescapeBindingConstants.java

@@ -188,6 +188,7 @@ public class KaleidescapeBindingConstants {
     public static final String MUSIC_RANDOM_OFF = "MUSIC_RANDOM_OFF";
 
     public static final String SEND_TO_SYSLOG = "SEND_TO_SYSLOG:INFORMATION:";
+    public static final String SEND_EVENT_VOLUME_CAPABILITIES_3 = "SEND_EVENT:VOLUME_CAPABILITIES=3";
     public static final String SEND_EVENT_VOLUME_CAPABILITIES_15 = "SEND_EVENT:VOLUME_CAPABILITIES=15";
     public static final String SEND_EVENT_VOLUME_LEVEL_EQ = "SEND_EVENT:VOLUME_LEVEL=";
     public static final String SEND_EVENT_MUTE = "SEND_EVENT:MUTE_";

bundles/org.openhab.binding.kaleidescape/src/main/java/org/openhab/binding/kaleidescape/internal/configuration/KaleidescapeThingConfiguration.java

@@ -28,6 +28,7 @@ public class KaleidescapeThingConfiguration {
     public @Nullable Integer updatePeriod;
     public boolean volumeEnabled;
     public Integer initialVolume = 0;
+    public boolean volumeBasicEnabled;
     public boolean loadHighlightedDetails;
     public boolean loadAlbumDetails;
 }

bundles/org.openhab.binding.kaleidescape/src/main/java/org/openhab/binding/kaleidescape/internal/handler/KaleidescapeHandler.java

@@ -89,6 +89,7 @@ public class KaleidescapeHandler extends BaseThingHandler implements Kaleidescap
     protected int metaRuntimeMultiple = 1;
     protected int volume = 0;
     protected boolean volumeEnabled = false;
+    protected boolean volumeBasicEnabled = false;
     protected boolean isMuted = false;
     protected boolean isLoadHighlightedDetails = false;
     protected boolean isLoadAlbumDetails = false;
@@ -162,6 +163,8 @@ public class KaleidescapeHandler extends BaseThingHandler implements Kaleidescap
             this.volume = config.initialVolume;
             this.updateState(VOLUME, new PercentType(this.volume));
             this.updateState(MUTE, OnOffType.OFF);
+        } else if (config.volumeBasicEnabled) {
+            this.volumeBasicEnabled = true;
         }
 
         if (serialPort != null) {

bundles/org.openhab.binding.kaleidescape/src/main/java/org/openhab/binding/kaleidescape/internal/handler/KaleidescapeMessageHandler.java

@@ -478,6 +478,10 @@ public enum KaleidescapeMessageHandler {
                                 handler.connector.sendCommand(SEND_EVENT_VOLUME_LEVEL_EQ + handler.volume);
                                 handler.connector.sendCommand(SEND_EVENT_MUTE + (handler.isMuted ? MUTE_ON : MUTE_OFF));
                             }
+                        } else if (handler.volumeBasicEnabled) {
+                            synchronized (handler.sequenceLock) {
+                                handler.connector.sendCommand(SEND_EVENT_VOLUME_CAPABILITIES_3);
+                            }
                         }
                         break;
                     case "VOLUME_UP":
@@ -514,10 +518,8 @@ public enum KaleidescapeMessageHandler {
                             }
                         }
                         break;
-                    // the default is to just publish all other USER_DEFINED_EVENTs
-                    default:
-                        handler.updateChannel(KaleidescapeBindingConstants.USER_DEFINED_EVENT, new StringType(message));
                 }
+                handler.updateChannel(KaleidescapeBindingConstants.USER_DEFINED_EVENT, new StringType(message));
             } catch (KaleidescapeException e) {
                 logger.debug("USER_DEFINED_EVENT - exception on message: {}", message);
             }

bundles/org.openhab.binding.kaleidescape/src/main/resources/OH-INF/config/config.xml

@@ -32,8 +32,8 @@
 			<default>0</default>
 		</parameter>
 		<parameter name="volumeEnabled" type="boolean" required="false">
-			<label>Volume Control Enabled</label>
+			<label>Advanced Volume Control Enabled</label>
-			<description>Enable the Volume and Mute controls in the Kaleidescape iPad &amp; Phone apps and track their status in
+			<description>Enable the Volume and Mute controls in the Kaleidescape iPad &amp; phone apps and track their status in
 				the binding. Disabled by default to prevent conflicts with other control systems that may already be controlling
 				volume on this zone.</description>
 			<default>false</default>
@@ -43,6 +43,12 @@
 			<description>When the binding starts up, set the Inital Volume level to this value (Default 25).</description>
 			<default>25</default>
 		</parameter>
+		<parameter name="volumeBasicEnabled" type="boolean" required="false">
+			<label>Basic Volume Control Enabled</label>
+			<description>Enable Basic Volume up-down and Mute toggle controls in the Kaleidescape iPad &amp; phone apps. Cannot
+				be used at the same time as volumeEnabled set to true.</description>
+			<default>false</default>
+		</parameter>
 		<parameter name="loadHighlightedDetails" type="boolean" required="false">
 			<label>Load Highlighted Details</label>
 			<description>When enabled the binding will automatically load the metadata channels when the selected item in the UI

bundles/org.openhab.binding.kaleidescape/src/main/resources/OH-INF/i18n/kaleidescape.properties

@@ -50,8 +50,10 @@ thing-type.config.kaleidescape.kaleidescapedevice.serialPort.label = Serial Port
 thing-type.config.kaleidescape.kaleidescapedevice.serialPort.description = (Optional) Serial Port to use for connecting directly to an individual Kaleidescape component.
 thing-type.config.kaleidescape.kaleidescapedevice.updatePeriod.label = Update Period
 thing-type.config.kaleidescape.kaleidescapedevice.updatePeriod.description = Tells the component how often time status updates should be sent; Values greater than 1 are not yet implmented by the protocol. Setting to 1 may impact openHAB system performance due to constant updates while content playing.
-thing-type.config.kaleidescape.kaleidescapedevice.volumeEnabled.label = Volume Control Enabled
+thing-type.config.kaleidescape.kaleidescapedevice.volumeBasicEnabled.label = Basic Volume Control Enabled
-thing-type.config.kaleidescape.kaleidescapedevice.volumeEnabled.description = Enable the Volume and Mute controls in the Kaleidescape iPad & Phone apps and track their status in the binding. Disabled by default to prevent conflicts with other control systems that may already be controlling volume on this zone.
+thing-type.config.kaleidescape.kaleidescapedevice.volumeBasicEnabled.description = Enable Basic Volume up-down and Mute toggle controls in the Kaleidescape iPad & phone apps. Cannot be used at the same time as volumeEnabled set to true.
+thing-type.config.kaleidescape.kaleidescapedevice.volumeEnabled.label = Advanced Volume Control Enabled
+thing-type.config.kaleidescape.kaleidescapedevice.volumeEnabled.description = Enable the Volume and Mute controls in the Kaleidescape iPad & phone apps and track their status in the binding. Disabled by default to prevent conflicts with other control systems that may already be controlling volume on this zone.
 
 # channel group types