various tidyups

packages/Pool_Controls/pool_light_operation.yaml

@@ -6,12 +6,16 @@
 #   Pool Light Operation
 #
 # FILE:
-#   packages/pool_light_boost_switch.yaml
+#   packages/Pool_Controls/pool_light_operation.yaml
 #
 # VERSION:
-#   V1.1 2026-06-29
+#   V1.2 2026-07-20
 #
 # VERSION HISTORY:
+#   V1.2 2026-07-20
+#     - Corrected the documented package filename.
+#     - Documented the relationship with the native ESPHome controls.
+#
 #   V1.1 2026-06-29
 #     - Tidied layout, comments, naming and automation IDs.
 #     - Added structured package header and section comments.
@@ -38,8 +42,15 @@
 #   Operation topic:
 #     viewroad-commands/poollight-timer/operation
 #
+# DEPENDENCIES:
+#   - switch.esp_poollightpower2_switch provides the real output state.
+#   - The ESPHome pool light device subscribes to the MQTT operation topic.
+#   - Native ESPHome mode, boost, and pool-light-mode entities coexist with
+#     this one-tap control.
+#
 # NOTES:
 #   The input_boolean.timer_light_midnight_pending helper is internal to this package.
+#   Dashboard cards currently use input_boolean.poollights_mode_switch.
 #
 #:########################################################################################:#
 

packages/Pool_Controls/pool_pump_operation.yaml

@@ -1,10 +1,68 @@
-# packages/poolpump_operation.yaml
+#:########################################################################################:#
+# Pool Pump Operation Package                                                            #
+#:########################################################################################:#
+#
+# TITLE:
+#   Pool Pump Operation
+#
+# FILE:
+#   packages/Pool_Controls/pool_pump_operation.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured package documentation and section comments.
+#     - Documented the relationship with the native ESPHome controls.
+#
+#   V1.0
+#     - Initial package.
+#     - Provides a Home Assistant UI switch for pool pump BOOST / OFF behaviour.
+#     - Sends TIMER mode again at midnight when required.
+#
+# PURPOSE:
+#   Provides a one-tap Home Assistant UI switch for controlling the pool pump.
+#
+#   Behaviour:
+#     - Turning the UI switch ON sends BOOST if the real pump output is OFF.
+#     - Turning the UI switch OFF sends OFF if the real pump output is ON.
+#     - After OFF is requested, TIMER mode is restored at midnight.
+#     - The UI switch follows the real ESPHome output without publishing MQTT.
+#
+# MQTT:
+#   Operation topic:
+#     viewroad-commands/poolpump-timer/operation
+#
+#   Payloads used by this package:
+#     BOOST
+#     OFF
+#     TIMER
+#
+# DEPENDENCIES:
+#   - switch.esp_poolpumppower_power_output provides the real output state.
+#   - The ESPHome pool pump device subscribes to the MQTT operation topic.
+#   - Native ESPHome mode and boost entities coexist with this one-tap control.
+#
+# NOTES:
+#   - input_boolean.timer_midnight_pending is internal to this package.
+#   - Dashboard cards currently use input_boolean.poolpump_mode_switch.
+#
+#:########################################################################################:#
+
+#:########################################################################################:#
+# Home Assistant Customisation                                                           #
+#:########################################################################################:#
 
 homeassistant:
   customize:
     input_boolean.poolpump_mode_switch:
       icon: mdi:pump
 
+#:########################################################################################:#
+# Input Booleans                                                                         #
+#:########################################################################################:#
+
 input_boolean:
   poolpump_mode_switch:
     name: "Pool Pump Operation"
@@ -14,6 +72,10 @@ input_boolean:
     name: "Send TIMER at Midnight"
     initial: false
 
+#:########################################################################################:#
+# Automations                                                                            #
+#:########################################################################################:#
+
 automation:
   - alias: "Pool Pump → send BOOST when user turns UI switch ON"
     trigger:

packages/Pool_Controls/pool_timers_selections.yaml

@@ -6,12 +6,16 @@
 #   Pool Timer Selection
 #
 # FILE:
-#   pool_timer_selection.yaml
+#   packages/Pool_Controls/pool_timers_selections.yaml
 #
 # VERSION:
-#   V1.0 2026-06-29
+#   V1.1 2026-07-20
 #
 # VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Corrected the documented package filename.
+#     - Documented command selectors versus ESPHome timer feedback.
+#
 #   V1.0 2026-06-29
 #     - Initial package.
 #     - Adds Home Assistant input_select helpers for Pool Pump and Pool Light timer times.
@@ -36,6 +40,16 @@
 #
 #   Payload format is HH:MM.
 #
+# STATUS AND FEEDBACK:
+#   - These input_select helpers send retained MQTT commands to ESPHome.
+#   - They do not synchronize their displayed options from the ESPHome devices.
+#   - The ESPHome Timeclock sensors are authoritative for the currently applied
+#     timer values.
+#   - A selector displaying "Default" does not prove that the device currently
+#     uses its default time.
+#   - Native ESPHome mode controls coexist with this package, while timer
+#     schedule changes continue to use the MQTT topics above.
+#
 # IMPORTANT:
 #   The current ESPHome timer logic only handles same-day timer windows:
 #     current_mins >= on_time AND current_mins < off_time