[plex] add ratingKey channels (#16343)

* [plex] add ratingKey channels

useful for automations related to exactly what's playing, to avoid
having to lookup based on title (which may not be unique)

---------

Signed-off-by: Cody Cutrer <cody@cutrer.us>
Co-authored-by: mlobstein <github@lobstein.org>
Signed-off-by: Ciprian Pascu <contact@ciprianpascu.ro>

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

@@ -95,21 +95,29 @@ Find the `Device` block of the player you want to add and fill in the `clientIde
 
 ## Channels
 
+The PLEX Server supports the following channels:
+
+| Channel              | Type     | Read/Write | Description                                                                                                      |
+|----------------------|----------|------------|------------------------------------------------------------------------------------------------------------------|
+| currentPlayers       | Number   | RO         | The number of players currently configured to watch on PLEX                                                      |
+| currentPlayersActive | Number   | RO         | The number of players currently being used on PLEX                                                               |
+
 The PLEX Player supports the following channels:
 
-| Channel              | Type     | Read/Write | Description                                                           |
+| Channel              | Type     | Read/Write | Description                                                                                                      |
-|----------------------|----------|------------|-----------------------------------------------------------------------|
+|----------------------|----------|------------|------------------------------------------------------------------------------------------------------------------|
-| currentPlayers       | Number   | RO         | The number of players currently configured to watch on PLEX           |
+| state                | String   | RO         | The current state of the Player (BUFFERING, PLAYING, PAUSED, STOPPED)                                            |
-| currentPlayersActive | Number   | RO         | The number of players currently being used on PLEX                    |
+| power                | Switch   | RO         | The power status of the player                                                                                   |
-| state                | String   | RO         | The current state of the Player (BUFFERING, PLAYING, PAUSED, STOPPED) |
+| title                | String   | RO         | The title of media that is playing                                                                               |
-| power                | Switch   | RO         | The power status of the player                                        |
+| type                 | String   | RO         | The current type of playing media                                                                                |
-| title                | String   | RO         | The title of media that is playing                                    |
+| endtime              | DateTime | RO         | Time at which the media that is playing will end                                                                 |
-| type                 | String   | RO         | The current type of playing media                                     |
+| progress             | Dimmer   | RO         | The current progress of playing media                                                                            |
-| endtime              | DateTime | RO         | Time at which the media that is playing will end                      |
+| art                  | String   | RO         | The URL of the background art for currently playing media                                                        |
-| progress             | Dimmer   | RO         | The current progress of playing media                                 |
+| thumb                | String   | RO         | The URL of the cover art for currently playing media                                                             |
-| art                  | String   | RO         | The URL of the background art for currently playing media             |
+| player               | Player   | RW         | The control channel for the player `PLAY/PAUSE/NEXT/PREVIOUS`                                                    |
-| thumb                | String   | RO         | The URL of the cover art for currently playing media                  |
+| ratingKey            | String   | RO         | The unique key in the Plex library identifying the media that is playing                                         |
-| player               | Player   | RW         | The control channel for the player `PLAY/PAUSE/NEXT/PREVIOUS`         |
+| parentRatingKey      | String   | RO         | The unique key in the Plex library identifying the parent (TV show season or album) of the media that is playing |
+| grandparentRatingKey | String   | RO         | The unique key in the Plex library identifying the grandparent (TV show) of the media that is playing            |
 
 ## Full Example
 
@@ -135,7 +143,7 @@ String    PlexTVType01                 "Type [%s]"                 {channel="ple
 String    PlexTVEndTime01              "End time"                  {channel="plex:player:MyViewerName01:endtime"}
 Dimmer    PlexTVProgress01             "Progress [%.1f%%]"         {channel="plex:player:MyViewerName01:progress"}
 String    PlexTVCover1                 "Cover"                     {channel="plex:player:MyViewerName01:thumb"}
-String     ShellArt01                  "Background art"            {channel="plex:player:MyViewerName01:art"}
+String    ShellArt01                   "Background art"            {channel="plex:player:MyViewerName01:art"}
 Switch    PlexTVPower02                "Power"                     {channel="plex:player:MyViewerName02:power"}
 String    PlexTVStatus02               "Status [%s]"               {channel="plex:player:MyViewerName02:state"}
 String    PlexTVTitle02                "Title [%s]"                {channel="plex:player:MyViewerName02:title"}

bundles/org.openhab.binding.plex/src/main/java/org/openhab/binding/plex/internal/PlexBindingConstants.java

@@ -66,6 +66,9 @@ public class PlexBindingConstants {
     // Player
     public static final String CHANNEL_PLAYER_STATE = "state";
     public static final String CHANNEL_PLAYER_TITLE = "title";
+    public static final String CHANNEL_PLAYER_RATING_KEY = "ratingKey";
+    public static final String CHANNEL_PLAYER_PARENT_RATING_KEY = "parentRatingKey";
+    public static final String CHANNEL_PLAYER_GRANDPARENT_RATING_KEY = "grandparentRatingKey";
     public static final String CHANNEL_PLAYER_TYPE = "type";
     public static final String CHANNEL_PLAYER_POWER = "power";
     public static final String CHANNEL_PLAYER_ART = "art";

bundles/org.openhab.binding.plex/src/main/java/org/openhab/binding/plex/internal/dto/MediaContainer.java

@@ -73,6 +73,8 @@ public class MediaContainer {
         @XStreamAsAttribute
         private String title;
         @XStreamAsAttribute
+        private String ratingKey;
+        @XStreamAsAttribute
         private String thumb;
         @XStreamAsAttribute
         private String art;
@@ -81,10 +83,14 @@ public class MediaContainer {
         @XStreamAsAttribute
         private String grandparentTitle;
         @XStreamAsAttribute
+        private String grandparentRatingKey;
+        @XStreamAsAttribute
         private String parentThumb;
         @XStreamAsAttribute
         private String parentTitle;
         @XStreamAsAttribute
+        private String parentRatingKey;
+        @XStreamAsAttribute
         private long viewOffset;
         @XStreamAsAttribute
         private String type;
@@ -113,6 +119,14 @@ public class MediaContainer {
             this.grandparentTitle = grandparentTitle;
         }
 
+        public String getGrandparentRatingKey() {
+            return grandparentRatingKey;
+        }
+
+        public void setGrandparentRatingKey(String ratingKey) {
+            this.grandparentRatingKey = ratingKey;
+        }
+
         public String getParentThumb() {
             return this.parentThumb;
         }
@@ -129,6 +143,14 @@ public class MediaContainer {
             this.parentTitle = parentTitle;
         }
 
+        public String getParentRatingKey() {
+            return parentRatingKey;
+        }
+
+        public void setParentRatingKey(String ratingKey) {
+            this.parentRatingKey = ratingKey;
+        }
+
         public Media getMedia() {
             return this.media;
         }
@@ -145,6 +167,14 @@ public class MediaContainer {
             this.title = title;
         }
 
+        public String getRatingKey() {
+            return ratingKey;
+        }
+
+        public void setRatingKey(String ratingKey) {
+            this.ratingKey = ratingKey;
+        }
+
         public long getViewOffset() {
             return this.viewOffset;
         }

bundles/org.openhab.binding.plex/src/main/java/org/openhab/binding/plex/internal/dto/PlexSession.java

@@ -42,6 +42,9 @@ public class PlexSession {
     private String sessionKey = "";
     private Integer userId;
     private String userTitle = "";
+    private String ratingKey;
+    private String parentRatingKey;
+    private String grandparentRatingKey;
 
     private final Logger logger = LoggerFactory.getLogger(PlexSession.class);
 
@@ -57,6 +60,18 @@ public class PlexSession {
         return title;
     }
 
+    public String getRatingKey() {
+        return ratingKey;
+    }
+
+    public String getParentRatingKey() {
+        return parentRatingKey;
+    }
+
+    public String getGrandparentRatingKey() {
+        return grandparentRatingKey;
+    }
+
     public Date getEndTime() {
         return endTime;
     }
@@ -69,6 +84,18 @@ public class PlexSession {
         this.title = title;
     }
 
+    public void setRatingKey(String ratingKey) {
+        this.ratingKey = ratingKey;
+    }
+
+    public void setParentRatingKey(String ratingKey) {
+        this.parentRatingKey = ratingKey;
+    }
+
+    public void setGrandparentRatingKey(String ratingKey) {
+        this.grandparentRatingKey = ratingKey;
+    }
+
     public String getThumb() {
         return thumb;
     }

bundles/org.openhab.binding.plex/src/main/java/org/openhab/binding/plex/internal/handler/PlexPlayerHandler.java

@@ -139,6 +139,9 @@ public class PlexPlayerHandler extends BaseThingHandler {
         currentSessionData.setSessionKey(sessionData.getSessionKey());
         currentSessionData.setUserId(sessionData.getUser().getId());
         currentSessionData.setUserTitle(sessionData.getUser().getTitle());
+        currentSessionData.setRatingKey(sessionData.getRatingKey());
+        currentSessionData.setParentRatingKey(sessionData.getParentRatingKey());
+        currentSessionData.setGrandparentRatingKey(sessionData.getGrandparentRatingKey());
 
         foundInSession = true;
         updateStatus(ThingStatus.ONLINE);
@@ -179,6 +182,14 @@ public class PlexPlayerHandler extends BaseThingHandler {
                 new StringType(String.valueOf(foundInSession ? currentSessionData.getEndTime() : "")));
         updateState(new ChannelUID(getThing().getUID(), CHANNEL_PLAYER_USER),
                 new StringType(String.valueOf(foundInSession ? currentSessionData.getUserTitle() : "")));
+        final String parentRatingKey = currentSessionData.getParentRatingKey();
+        final String grandparentRatingKey = currentSessionData.getGrandparentRatingKey();
+        updateState(new ChannelUID(getThing().getUID(), CHANNEL_PLAYER_RATING_KEY),
+                new StringType(String.valueOf(foundInSession ? currentSessionData.getRatingKey() : "")));
+        updateState(new ChannelUID(getThing().getUID(), CHANNEL_PLAYER_PARENT_RATING_KEY),
+                new StringType(String.valueOf(foundInSession && parentRatingKey != null ? parentRatingKey : "")));
+        updateState(new ChannelUID(getThing().getUID(), CHANNEL_PLAYER_GRANDPARENT_RATING_KEY), new StringType(
+                String.valueOf(foundInSession && grandparentRatingKey != null ? grandparentRatingKey : "")));
 
         // Make sure player control is in sync with the play state
         if (currentSessionData.getState() == PlexPlayerState.PLAYING) {

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

@@ -39,12 +39,18 @@ channel-type.plex.currentPlayersActive.label = Current Players Active
 channel-type.plex.currentPlayersActive.description = The number of players currently being used on PLEX
 channel-type.plex.endtime.label = End Time
 channel-type.plex.endtime.description = Time at which the media that is playing will end
+channel-type.plex.grandparentRatingKey.label = Grandparent Rating Key
+channel-type.plex.grandparentRatingKey.description = The unique key in the Plex library identifying the grandparent (TV show) of the media that is playing
+channel-type.plex.parentRatingKey.label = Parent Rating Key
+channel-type.plex.parentRatingKey.description = The unique key in the Plex library identifying the parent (TV show season or album) of the media that is playing
 channel-type.plex.player.label = Player Control
 channel-type.plex.player.description = The control channel for the player `PLAY/PAUSE/NEXT/PREVIOUS`
 channel-type.plex.power.label = Player Power State
 channel-type.plex.power.description = The power status of the player
 channel-type.plex.progress.label = Media Progress
 channel-type.plex.progress.description = The current progress of playing media
+channel-type.plex.ratingKey.label = Rating Key
+channel-type.plex.ratingKey.description = The unique key in the Plex library identifying the media that is playing
 channel-type.plex.state.label = Player State
 channel-type.plex.state.description = The current state of the Player
 channel-type.plex.thumb.label = Cover Art

bundles/org.openhab.binding.plex/src/main/resources/OH-INF/thing/thing-types.xml

@@ -31,7 +31,13 @@
 			<channel id="thumb" typeId="thumb"/>
 			<channel id="player" typeId="player"/>
 			<channel id="user" typeId="user"/>
+			<channel id="ratingKey" typeId="ratingKey"/>
+			<channel id="parentRatingKey" typeId="parentRatingKey"/>
+			<channel id="grandparentRatingKey" typeId="grandparentRatingKey"/>
 		</channels>
+		<properties>
+			<property name="thingTypeVersion">1</property>
+		</properties>
 		<config-description-ref uri="thing-type:plex:player"/>
 	</thing-type>
 
@@ -65,6 +71,25 @@
 		<description>The title of media that is playing</description>
 		<state readOnly="true"/>
 	</channel-type>
+	<channel-type id="ratingKey" advanced="true">
+		<item-type>String</item-type>
+		<label>Rating Key</label>
+		<description>The unique key in the Plex library identifying the media that is playing</description>
+		<state readOnly="true"/>
+	</channel-type>
+	<channel-type id="parentRatingKey" advanced="true">
+		<item-type>String</item-type>
+		<label>Parent Rating Key</label>
+		<description>The unique key in the Plex library identifying the parent (TV show season or album) of the media that is
+			playing</description>
+		<state readOnly="true"/>
+	</channel-type>
+	<channel-type id="grandparentRatingKey" advanced="true">
+		<item-type>String</item-type>
+		<label>Grandparent Rating Key</label>
+		<description>The unique key in the Plex library identifying the grandparent (TV show) of the media that is playing</description>
+		<state readOnly="true"/>
+	</channel-type>
 	<channel-type id="type">
 		<item-type>String</item-type>
 		<label>Media Type</label>

bundles/org.openhab.binding.plex/src/main/resources/OH-INF/update/instructions.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
+<update:update-descriptions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xmlns:update="https://openhab.org/schemas/update-description/v1.0.0"
+	xsi:schemaLocation="https://openhab.org/schemas/update-description/v1.0.0 https://openhab.org/schemas/update-description-1.0.0.xsd">
+
+	<thing-type uid="plex:player">
+		<instruction-set targetVersion="1">
+			<add-channel id="ratingKey">
+				<type>plex:ratingKey</type>
+			</add-channel>
+			<add-channel id="parentRatingKey">
+				<type>plex:parentRatingKey</type>
+			</add-channel>
+			<add-channel id="grandparentRatingKey">
+				<type>plex:grandparentRatingKey</type>
+			</add-channel>
+		</instruction-set>
+	</thing-type>
+
+</update:update-descriptions>