zorruno-homeassistant/packages/Pool_Controls/pool_light_operation.yaml

#:########################################################################################:#
# Pool Light Operation Package                                                            #
#:########################################################################################:#
#
# TITLE:
#   Pool Light Operation
#
# FILE:
#   packages/Pool_Controls/pool_light_operation.yaml
#
# VERSION:
#   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.
#     - Fixed likely MQTT topic typo in midnight TIMER automation:
#         viewroad-commands/poollights-timer/operation
#       changed to:
#         viewroad-commands/poollight-timer/operation
#
#   V1.0
#     - Initial package.
#     - Provides a Home Assistant UI switch for pool light BOOST / OFF behaviour.
#     - Sends TIMER mode again at midnight when required.
#
# PURPOSE:
#   Provides a Home Assistant UI switch for controlling the pool light timer mode.
#
#   Behaviour:
#     - Turning the UI switch ON sends BOOST if the real pool light output is currently OFF.
#     - Turning the UI switch OFF sends OFF if the real pool light output is currently ON.
#     - If OFF was requested, TIMER mode is sent again at midnight.
#     - The UI switch follows the real ESPHome output state without sending MQTT.
#
# MQTT:
#   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.
#
#:########################################################################################:#

#:########################################################################################:#
# Home Assistant Customisation                                                            #
#:########################################################################################:#

homeassistant:
  customize:
    input_boolean.poollights_mode_switch:
      icon: mdi:light-flood-up

#:########################################################################################:#
# Input Booleans                                                                           #
#:########################################################################################:#

input_boolean:
  poollights_mode_switch:
    name: "Pool Light Operation"
    initial: false

  timer_light_midnight_pending:
    name: "Pool Light - Send TIMER at Midnight"
    initial: false

#:########################################################################################:#
# Automations                                                                              #
#:########################################################################################:#

automation:
  - id: pool_light_send_boost_when_ui_switch_on
    alias: "Pool Light - Send BOOST When UI Switch Turns ON"
    description: "Sends BOOST to the pool light timer when the UI switch is turned on and the real pool light output is off."
    mode: single

    trigger:
      - platform: state
        entity_id: input_boolean.poollights_mode_switch
        to: "on"

    condition:
      - condition: state
        entity_id: switch.esp_poollightpower2_switch
        state: "off"

    action:
      - service: mqtt.publish
        data:
          topic: "viewroad-commands/poollight-timer/operation"
          payload: "BOOST"

  - id: pool_light_send_off_and_schedule_timer_when_ui_switch_off
    alias: "Pool Light - Send OFF And Schedule TIMER When UI Switch Turns OFF"
    description: "Sends OFF to the pool light timer and schedules TIMER mode to be restored at midnight."
    mode: single

    trigger:
      - platform: state
        entity_id: input_boolean.poollights_mode_switch
        to: "off"

    condition:
      - condition: state
        entity_id: switch.esp_poollightpower2_switch
        state: "on"

    action:
      - service: mqtt.publish
        data:
          topic: "viewroad-commands/poollight-timer/operation"
          payload: "OFF"

      - service: input_boolean.turn_on
        target:
          entity_id: input_boolean.timer_light_midnight_pending

  - id: pool_light_send_timer_at_midnight
    alias: "Pool Light - Send TIMER At Midnight"
    description: "Restores TIMER mode at midnight if the pool light was manually turned off earlier."
    mode: single

    trigger:
      - platform: time
        at: "00:00:00"

    condition:
      - condition: state
        entity_id: input_boolean.timer_light_midnight_pending
        state: "on"

    action:
      - service: mqtt.publish
        data:
          topic: "viewroad-commands/poollight-timer/operation"
          payload: "TIMER"

      - service: input_boolean.turn_off
        target:
          entity_id: input_boolean.timer_light_midnight_pending

  - id: pool_light_sync_ui_switch_with_real_output
    alias: "Pool Light - Sync UI Switch With Real Output"
    description: "Keeps the UI switch aligned with the real ESPHome pool light output without sending MQTT commands."
    mode: restart

    trigger:
      - platform: state
        entity_id: switch.esp_poollightpower2_switch

    action:
      - choose:
          - conditions:
              - condition: state
                entity_id: switch.esp_poollightpower2_switch
                state: "on"
            sequence:
              - service: input_boolean.turn_on
                target:
                  entity_id: input_boolean.poollights_mode_switch

              - service: input_boolean.turn_off
                target:
                  entity_id: input_boolean.timer_light_midnight_pending

          - conditions:
              - condition: state
                entity_id: switch.esp_poollightpower2_switch
                state: "off"
            sequence:
              - service: input_boolean.turn_off
                target:
                  entity_id: input_boolean.poollights_mode_switch

              - service: input_boolean.turn_on
                target:
                  entity_id: input_boolean.timer_light_midnight_pending