[kaleidescape] Add configuration option to auto load metadata channel…

…s without rules (openhab#11231)

* Add configuration option to auto load metadata channels

Signed-off-by: Michael Lobstein <michael.lobstein@gmail.com>

* Debug message

Signed-off-by: Michael Lobstein <michael.lobstein@gmail.com>
Signed-off-by: Dave J Schoepel <dave@theschoepels.com>

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

@@ -45,14 +45,16 @@ All settings are through thing configuration parameters.
 
 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)                              |
-| Initial Volume Setting | initialVolume | Initial volume level set when the binding starts up                                | 0 to 75 (default 25)                                 |
+| 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)                              |
+| Initial Volume Setting   | initialVolume          | Initial volume level set when the binding starts up                                                                                  | 0 to 75 (default 25)                                 |
+| 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      |
 
 Some notes:
 
@@ -152,14 +154,16 @@ The following channels are available:
 
 kaleidescape.things:
 
-```java
-kaleidescape:player:myzone1 "M500 Living Rm" [host="192.168.1.10", updatePeriod=0, volumeEnabled=true, initialVolume=20]
-kaleidescape:cinemaone:myzone2 "My Cinema One" [host="192.168.1.11", updatePeriod=0, volumeEnabled=true, initialVolume=20]
+```
+kaleidescape:player:myzone1 "M500 Living Rm" [ host="192.168.1.10", updatePeriod=0, loadHighlightedDetails=true, loadAlbumDetails=true ]
+kaleidescape:cinemaone:myzone2 "My Cinema One" [ 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.items:
 
-```java
+```
 // Virtual switch to send a command, see sitemap and rules below
 Switch z1_GoMovieCovers   "Go to Movie Covers"
 
@@ -239,11 +243,12 @@ String z1_Detail_ColorDescription "Color Description: [%s]" { channel="kaleidesc
 String z1_Detail_Country "Country: [%s]" { channel="kaleidescape:player:myzone1:detail#country" }
 String z1_Detail_AspectRatio "Aspect Ratio: [%s]" { channel="kaleidescape:player:myzone1:detail#aspect_ratio" }
 String z1_Detail_DiscLocation "Disc Location: [%s]" { channel="kaleidescape:player:myzone1:detail#disc_location" }
+
 ```
 
 ksecondsformat.js:
 
-```java
+```
 (function(totalSeconds) {
     if (isNaN(totalSeconds)) {
         return '-';
@@ -265,7 +270,7 @@ ksecondsformat.js:
 
 kaleidescape.sitemap:
 
-```perl
+```
 sitemap kaleidescape label="Kaleidescape" {
     Frame label="Zone 1" {
         Image item=z1_Detail_CoverArt
@@ -351,7 +356,7 @@ sitemap kaleidescape label="Kaleidescape" {
 
 kaleidescape.rules:
 
-```java
+```
 var int lightPercent
 val kactions = getActions("kaleidescape","kaleidescape:player:myzone1")
 
@@ -360,7 +365,7 @@ rule "Go to Movie Covers"
 when
     Item z1_GoMovieCovers received command
 then
-    if(null === kactions) {
+    if (null === kactions) {
       logInfo("kactions", "Actions not found, check thing ID")
       return
     }
@@ -372,7 +377,7 @@ rule "Play Script - Great Vistas"
 when
     Item z1_PlayScript received command
 then
-    if(null === kactions) {
+    if (null === kactions) {
       logInfo("kactions", "Actions not found, check thing ID")
       return
     }
@@ -389,28 +394,6 @@ then
     }
 end
 
-rule "Load selected item Metadata"
-when
-    Item z1_Ui_HighlightedSelection changed
-then
-    if(null === kactions) {
-      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) {
-      logInfo("kactions", "Actions not found, check thing ID")
-      return
-    }
-    kactions.sendKCommand("GET_CONTENT_DETAILS:" + z1_Music_AlbumHandle.state.toString + ":")
-end
-
 rule "Bring up Lights when movie is over"
 when
     Item z1_Ui_MovieLocation changed from "Main content" to "End Credits"
@@ -420,7 +403,7 @@ then
     while (lightPercent < 100) {
         lightPercent = lightPercent + 5
         logInfo("k rules", "lights at " + lightPercent.toString + " percent")
-        //myLightItem.sendCommand(lightPercent)
+        // myLightItem.sendCommand(lightPercent)
         Thread::sleep(5000) 
     }
 end
@@ -429,15 +412,40 @@ rule "Bring up Lights at 20 percent during intermission"
 when
     Item z1_Ui_MovieLocation changed from "Main content" to "Intermission"
 then
-    //myLightItem.sendCommand(20)
+    // myLightItem.sendCommand(20)
     logInfo("k rules", "intermission started")
 end
 
 rule "Turn lights back off when intermission over"
 when
     Item z1_Ui_MovieLocation changed from "Intermission" to "Main content"
 then
-    //myLightItem.sendCommand(OFF)
+    // myLightItem.sendCommand(OFF)
     logInfo("k rules", "intermission over")
 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.
+
+rule "Load selected item Metadata"
+when
+    Item z1_Ui_HighlightedSelection changed
+then
+    if (null === kactions) {
+      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) {
+      logInfo("kactions", "Actions not found, check thing ID")
+      return
+    }
+    kactions.sendKCommand("GET_CONTENT_DETAILS:" + z1_Music_AlbumHandle.state.toString + ":")
+end
 ```

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

@@ -166,6 +166,7 @@ public class KaleidescapeBindingConstants {
     public static final String GET_CONTENT_COLOR = "GET_CONTENT_COLOR";
     public static final String SET_STATUS_CUE_PERIOD_1 = "SET_STATUS_CUE_PERIOD:1";
     public static final String GET_TIME = "GET_TIME";
+    public static final String GET_CONTENT_DETAILS = "GET_CONTENT_DETAILS:";
 
     public static final String LEAVE_STANDBY = "LEAVE_STANDBY";
     public static final String ENTER_STANDBY = "ENTER_STANDBY";

bundles/org.openhab.binding.kaleidescape/src/main/java/org/openhab/binding/kaleidescape/internal/communication/KaleidescapeConnector.java

@@ -185,7 +185,7 @@ public void sendCommand(@Nullable String cmd) throws KaleidescapeException {
      */
     public void sendCommand(@Nullable String cmd, @Nullable String cachedMessage) throws KaleidescapeException {
         // if sent a cachedMessage, just send out an event with the data so KaleidescapeMessageHandler will process it
-        if (cachedMessage != null) {
+        if (cmd != null && cachedMessage != null) {
             logger.debug("Command: '{}' returning cached value: '{}'", cmd, cachedMessage);
             // change GET_SOMETHING into SOMETHING and special case GET_PLAYING_TITLE_NAME into TITLE_NAME
             dispatchKeyValue(cmd.replace("GET_", "").replace("PLAYING_TITLE_NAME", "TITLE_NAME"), cachedMessage, true);

bundles/org.openhab.binding.kaleidescape/src/main/java/org/openhab/binding/kaleidescape/internal/communication/KaleidescapeFormatter.java

@@ -12,6 +12,8 @@
  */
 package org.openhab.binding.kaleidescape.internal.communication;
 
+import static org.openhab.binding.kaleidescape.internal.KaleidescapeBindingConstants.*;
+
 import org.apache.commons.lang3.StringEscapeUtils;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 
@@ -23,7 +25,7 @@
 @NonNullByDefault
 public class KaleidescapeFormatter {
     public static String formatString(String input) {
-        if (!input.equals("")) {
+        if (!EMPTY.equals(input)) {
             // convert || back to :
             input = input.replace("||", ":");
 

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

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

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

@@ -90,6 +90,8 @@ public class KaleidescapeHandler extends BaseThingHandler implements Kaleidescap
     protected int volume = 0;
     protected boolean volumeEnabled = false;
     protected boolean isMuted = false;
+    protected boolean isLoadHighlightedDetails = false;
+    protected boolean isLoadAlbumDetails = false;
     protected String friendlyName = EMPTY;
     protected Object sequenceLock = new Object();
 
@@ -124,6 +126,8 @@ public void initialize() {
         final String host = config.host;
         final Integer port = config.port;
         final Integer updatePeriod = config.updatePeriod;
+        this.isLoadHighlightedDetails = config.loadHighlightedDetails;
+        this.isLoadAlbumDetails = config.loadAlbumDetails;
 
         if ((serialPort == null || serialPort.isEmpty()) && (host == null || host.isEmpty())) {
             configError = "undefined serialPort and host configuration settings; please set one of them";
@@ -166,10 +170,10 @@ public void initialize() {
             return;
         }
 
+        updateStatus(ThingStatus.UNKNOWN);
+
         scheduleReconnectJob();
         schedulePollingJob();
-
-        updateStatus(ThingStatus.UNKNOWN);
     }
 
     @Override

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

@@ -57,9 +57,19 @@ public void handleMessage(String message, KaleidescapeHandler handler) {
         }
     },
     HIGHLIGHTED_SELECTION {
+        private final Logger logger = LoggerFactory.getLogger(KaleidescapeMessageHandler.class);
+
         @Override
         public void handleMessage(String message, KaleidescapeHandler handler) {
             handler.updateChannel(KaleidescapeBindingConstants.HIGHLIGHTED_SELECTION, new StringType(message));
+
+            if (handler.isLoadHighlightedDetails) {
+                try {
+                    handler.connector.sendCommand(GET_CONTENT_DETAILS + message + ":");
+                } catch (KaleidescapeException e) {
+                    logger.debug("GET_CONTENT_DETAILS - exception loading content details for handle: {}", message);
+                }
+            }
         }
     },
     DEVICE_POWER_STATE {
@@ -273,6 +283,15 @@ public void handleMessage(String message, KaleidescapeHandler handler) {
                 handler.updateChannel(MUSIC_ALBUM_HANDLE, new StringType(matcher.group(5)));
 
                 handler.updateChannel(MUSIC_NOWPLAY_HANDLE, new StringType(matcher.group(6)));
+
+                if (handler.isLoadAlbumDetails) {
+                    try {
+                        handler.connector.sendCommand(GET_CONTENT_DETAILS + matcher.group(5) + ":");
+                    } catch (KaleidescapeException e) {
+                        logger.debug("GET_CONTENT_DETAILS - exception loading album details for handle: {}",
+                                matcher.group(5));
+                    }
+                }
             } else {
                 logger.debug("MUSIC_TITLE - no match on message: {}", message);
             }

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

@@ -42,5 +42,17 @@
 			<description>When the binding starts up, set the Inital Volume level to this value (Default 25).</description>
 			<default>25</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
+				(Movie or Album) changes.</description>
+			<default>false</default>
+		</parameter>
+		<parameter name="loadAlbumDetails" type="boolean" required="false">
+			<label>Load Album Details</label>
+			<description>When enabled the binding will automatically load the metadata channels for the currently playing Album.
+				Not applicable for Alto and Strato components.</description>
+			<default>false</default>
+		</parameter>
 	</config-description>
 </config-description:config-descriptions>