From 10ec911f6c4abdf3a4509a0474539da064aa9cb3 Mon Sep 17 00:00:00 2001
From: Jeff Irion <JeffLIrion@users.noreply.github.com>
Date: Tue, 6 Aug 2019 03:07:25 -0700
Subject: [PATCH] Document the 'state_detection_rules' config parameter
 (#10036)

* Document the 'state_detection_rules' config parameter

* Add info about how to determine rules

* Add comments about indentation

This level of indentation for the `wake_lock_size` map is necessary to ensure that the YAML is parsed as intended.

* Update the documentation of the 'state_detection_rules' config parameter
---
 source/_components/androidtv.markdown | 38 ++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/source/_components/androidtv.markdown b/source/_components/androidtv.markdown
index 660860063a5..47e26e2e6a1 100644
--- a/source/_components/androidtv.markdown
+++ b/source/_components/androidtv.markdown
@@ -92,6 +92,11 @@ device_class:
   required: false
   default: auto
   type: string
+state_detection_rules:
+  description: A dictionary whose keys are app IDs and whose values are lists of state detection rules; see the section [Custom State Detection](#custom-state-detection) for more info.
+  required: false
+  default: {}
+  type: map
 turn_on_command:
   description: An ADB shell command that will override the default `turn_on` command.
   required: false
@@ -108,7 +113,8 @@ turn_off_command:
 # Example configuration.yaml entry
 media_player:
   # Use an ADB server to setup an Android TV device, provide
-  # an app name, and override the default turn on/off commands
+  # an app name, override the default turn on/off commands,
+  # and provide custom state detection rules
   - platform: androidtv
     name: Android TV
     device_class: androidtv
@@ -118,6 +124,21 @@ media_player:
       com.amazon.tv.launcher: "Fire TV"
     turn_on_command: "input keyevent 3"
     turn_off_command: "input keyevent 223"
+    state_detection_rules:
+      'com.amazon.tv.launcher':
+        - 'standby'
+      'com.netflix.ninja':
+        - 'media_session_state'
+      'com.ellation.vrv':
+        - 'audio_state'
+      'com.plexapp.android':
+        - 'playing':
+            'media_session_state': 3  # this indentation is important!
+            'wake_lock_size': 3       # this indentation is important!
+        - 'paused':
+            'media_session_state': 3  # this indentation is important!
+            'wake_lock_size': 1       # this indentation is important!
+        - 'standby'
 
   # Use the Python ADB implementation with authentication
   # to setup a Fire TV device and don't get the running apps
@@ -235,3 +256,18 @@ Available key commands include:
 The full list of key commands can be found [here](https://github.com/JeffLIrion/python-androidtv/blob/bf1058a2f746535921b3f5247801469c4567e51a/androidtv/constants.py#L143-L186).
 
 You can also use the command `GET_PROPERTIES` to retrieve the properties used by Home Assistant to update the device's state.  These will be stored in the media player's `'adb_response'` attribute and logged at the INFO level, this information can be used to help improve state detection in the backend [androidtv](https://github.com/JeffLIrion/python-androidtv) package.
+
+## Custom State Detection
+
+The `state_detection_rules` configuration parameter allows you to provide your own rules for state detection.  The keys are app IDs, and the values are lists of rules that are evaluated in order.  Valid rules are:
+
+* `'standby'`, `'playing'`, `'paused'`, `'idle'`, `'stopped'`, or `'off'`
+  * If this is not a map, then this state will always be reported when this app is the current app
+  * If this is a map, then its entries are conditions that will be checked.  If all of the conditions are true, then this state will be reported.  Valid conditions pertain to 3 properties (see the example configuration above):
+    1. ``'media_session_state'``
+    2. ``'audio_state'``
+    3. ``'wake_lock_size'``
+* `'media_session_state'` = try to use the `media_session_state` property to determine the state
+* `'audio_state'` = try to use the `audio_state` property to determine the state
+
+To determine what these rules should be, you can use the `androidtv.adb_command` service with the command `GET_PROPERTIES`, as described in the [androidtv.adb_command](#androidtvadb_command) section.