zorruno-homeassistant/packages/Pool_Controls/pool_pump_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"
    initial: false

  timer_midnight_pending:
    name: "Send TIMER at Midnight"
    initial: false

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

automation:
  - alias: "Pool Pump → send BOOST when user turns UI switch ON"
    trigger:
      platform: state
      entity_id: input_boolean.poolpump_mode_switch
      to: "on"
    condition:
      condition: state
      entity_id: switch.esp_poolpumppower_power_output
      state: "off"
    action:
      - service: mqtt.publish
        data:
          topic: "viewroad-commands/poolpump-timer/operation"
          payload: "BOOST"

  - alias: "Pool Pump → send OFF & schedule TIMER when user turns UI switch OFF"
    trigger:
      platform: state
      entity_id: input_boolean.poolpump_mode_switch
      to: "off"
    condition:
      condition: state
      entity_id: switch.esp_poolpumppower_power_output
      state: "on"
    action:
      - service: mqtt.publish
        data:
          topic: "viewroad-commands/poolpump-timer/operation"
          payload: "OFF"
      - service: input_boolean.turn_on
        data:
          entity_id: input_boolean.timer_midnight_pending

  - alias: "Pool Pump → send TIMER at midnight"
    trigger:
      platform: time
      at: "00:00:00"
    condition:
      condition: state
      entity_id: input_boolean.timer_midnight_pending
      state: "on"
    action:
      - service: mqtt.publish
        data:
          topic: "viewroad-commands/poolpump-timer/operation"
          payload: "TIMER"
      - service: input_boolean.turn_off
        data:
          entity_id: input_boolean.timer_midnight_pending

  - alias: "Pool Pump → sync UI switch with real output (no MQTT)"
    trigger:
      platform: state
      entity_id: switch.esp_poolpumppower_power_output
    action:
      - choose:
          - conditions:
              - condition: state
                entity_id: switch.esp_poolpumppower_power_output
                state: "on"
            sequence:
              - service: input_boolean.turn_on
                data:
                  entity_id: input_boolean.poolpump_mode_switch
              - service: input_boolean.turn_off
                data:
                  entity_id: input_boolean.timer_midnight_pending
          - conditions:
              - condition: state
                entity_id: switch.esp_poolpumppower_power_output
                state: "off"
            sequence:
              - service: input_boolean.turn_off
                data:
                  entity_id: input_boolean.poolpump_mode_switch
              - service: input_boolean.turn_on
                data:
                  entity_id: input_boolean.timer_midnight_pending