various tidyups

packages/office_media_buttons.yaml

@@ -1,3 +1,49 @@
+#:########################################################################################:#
+# Office Media Buttons Package                                                           #
+#:########################################################################################:#
+#
+# TITLE:
+#   Office Media Buttons
+#
+# FILE:
+#   packages/office_media_buttons.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured documentation and automation descriptions.
+#     - Identified the active ZHA implementation and disabled alternatives.
+#
+#   V1.0
+#     - Initial office media-button automations.
+#
+# PURPOSE:
+#   Controls office TV playback from a Zigbee media button using direct ZHA
+#   click events.
+#
+# ACTIVE BUTTON MAPPING:
+#   - Single press pauses playback.
+#   - Double press starts or resumes playback.
+#   - Triple press seeks backward by 30 seconds.
+#
+# DEPENDENCIES:
+#   - ZHA event source: device IEEE 00:15:8d:00:06:79:46:c8.
+#   - media_player.office_tv provides the current playback position.
+#   - The media actions target the office TV device registered in Home Assistant.
+#
+# NOTES:
+#   - seek_amount is not normally provided by the event and defaults to -30.
+#   - Commented MQTT and entity-state implementations below are disabled
+#     historical alternatives retained for reference.
+#
+#:########################################################################################:#
+
+#:########################################################################################:#
+# Historical Disabled MQTT Sensor                                                       #
+#:########################################################################################:#
+
 #mqtt:
 #  sensor:
 #    - unique_id: office_media_button_1
@@ -6,10 +52,14 @@
 #      unit_of_measurement: "Press"
 #      value_template: "{{ value_json.ZbReceived.Office_Media_Button.Power }}"
 
+#:########################################################################################:#
+# Active ZHA Automations                                                                 #
+#:########################################################################################:#
+
 automation:
   - id: pause_office_tv_on_media_button
     alias: Pause Office TV on Media Button
-    description: ""
+    description: "Pauses the office TV when the media button is pressed once."
     trigger:
       - platform: event
         event_type: zha_event
@@ -26,7 +76,7 @@ automation:
     mode: single
   - id: play_office_tv_on_media_button
     alias: Play Office TV on Media Button
-    description: ""
+    description: "Starts or resumes office TV playback when the media button is pressed twice."
     trigger:
       - platform: event
         event_type: zha_event
@@ -43,7 +93,7 @@ automation:
     mode: single
   - id: seek_office_tv_on_media_button
     alias: Seek Office TV on Media Button
-    description: ""
+    description: "Seeks office TV playback backward 30 seconds when the media button is pressed three times."
     trigger:
       - platform: event
         event_type: zha_event
@@ -62,6 +112,8 @@ automation:
         target:
           device_id: abb6b5a6b4e4925dcb3a77ea2c293eaa
     mode: single
+
+  # Historical disabled MQTT and entity-state alternatives.
 #  - id: "1629271273958"
 #    alias: Pause office TV on MQTT
 #    description: ""
@@ -90,6 +142,7 @@ automation:
 #          seek_position: 30
 #    mode: single
 
+# Historical disabled entity-state automation block.
 #automation:
 #  - id: "1629271273952"
 #    unique_id: pause_office_tv_on_media_button