various tidyups

packages/room_fan_control.yaml

@@ -1,9 +1,55 @@
 ##########################################################################################
-# MASTER BEDROOM FAN (Tasmota / Sonoff iFan02)
-# Improvements:
-# - Numeric speed entity (0-3) reflecting actual device state via MQTT
-# - Button to cycle speed 1,2,3,0
-# - Keep input_select in sync with actual FanSpeed (incl after reboots)
+# Room Fan Control
+##########################################################################################
+#
+# TITLE:
+#   Room Fan Control
+#
+# FILE:
+#   packages/room_fan_control.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured documentation for all three bedroom fans.
+#     - Documented the master-bedroom feedback loop and command-only controls.
+#
+#   V1.0
+#     - Initial Tasmota and Sonoff iFan02 fan controls.
+#
+# PURPOSE:
+#   Controls the master-bedroom, Bedroom 2, and Bedroom 3 ceiling-fan speeds
+#   through Tasmota MQTT commands and Home Assistant dropdown helpers.
+#
+# SPEED MAPPING:
+#   - 0 = Off
+#   - 1 = Low
+#   - 2 = Medium
+#   - 3 = High
+#
+# MASTER BEDROOM:
+#   - Queries FanSpeed when Home Assistant starts.
+#   - Listens to Tasmota RESULT and STATE topics for device feedback.
+#   - Synchronizes the numeric and dropdown helpers with actual device state.
+#   - Uses optimistic local updates until MQTT feedback corrects the helpers.
+#   - Provides a button that cycles through speeds 1, 2, 3, and 0.
+#
+# BEDROOMS 2 AND 3:
+#   - Dropdown changes publish FanSpeed commands to each Tasmota device.
+#   - These controls are command-only and do not synchronize from feedback.
+#   - Their displayed dropdown state may not reflect physical or external changes.
+#
+# MQTT COMMAND TOPICS:
+#   - Master bedroom: cmnd/tasmo-ifan02-3793-bedrm1-1/FanSpeed
+#   - Bedroom 2: cmnd/tasmo-ifan02-7042-bedrm2/FanSpeed
+#   - Bedroom 3: cmnd/tasmo-ifan02-3497-bedrm3/FanSpeed
+#
+# DEPENDENCIES:
+#   - The three Tasmota devices must accept FanSpeed values from 0 through 3.
+#   - Master-bedroom feedback uses its RESULT and STATE MQTT topics.
+#
 ##########################################################################################
 
 input_select:
@@ -75,6 +121,7 @@ automation:
   - id: master_bedroom_fan_query_on_ha_start
     initial_state: true
     alias: Master Bedroom Fan - Query FanSpeed on HA Start
+    description: "Requests the current master-bedroom FanSpeed when Home Assistant starts."
     trigger:
       - platform: homeassistant
         event: start
@@ -90,6 +137,7 @@ automation:
   - id: master_bedroom_fan_sync_from_mqtt
     initial_state: true
     alias: Master Bedroom Fan - Sync Helpers From MQTT FanSpeed
+    description: "Synchronizes the master-bedroom fan helpers from Tasmota MQTT feedback."
     trigger:
       - platform: mqtt
         topic: stat/tasmo-ifan02-3793-bedrm1-1/RESULT
@@ -122,6 +170,7 @@ automation:
   - id: set_the_master_bedroom_fan
     initial_state: true
     alias: Set the Master Bedroom Fan
+    description: "Publishes master-bedroom fan speed changes and updates the numeric helper optimistically."
     trigger:
       - platform: state
         entity_id: input_select.master_bedroom_fan_set
@@ -145,11 +194,12 @@ automation:
           value: "{{ desired }}"
 
   ########################################################################################
-  # BEDROOM 2 FAN - Unchanged
+  # BEDROOM 2 FAN - Command Only
   ########################################################################################
   - id: set_bedroom_2_fan
     initial_state: true
     alias: Set Bedroom 2 Fan Speed
+    description: "Publishes Bedroom 2 fan speed dropdown changes to Tasmota."
     trigger:
       entity_id: input_select.bedroom_2_fan_set
       platform: state
@@ -163,11 +213,12 @@ automation:
           '
 
   ########################################################################################
-  # BEDROOM 3 FAN - Unchanged
+  # BEDROOM 3 FAN - Command Only
   ########################################################################################
   - id: set_bedroom_3_fan
     initial_state: true
     alias: Set Bedroom 3 Fan Speed
+    description: "Publishes Bedroom 3 fan speed dropdown changes to Tasmota."
     trigger:
       entity_id: input_select.bedroom_3_fan_set
       platform: state