# Power Overconsumption Monitor Blueprint
# Monitors power sensors for sustained overconsumption above a threshold.
# See README.md for detailed documentation.

blueprint:
  name: "Custom: Power Overconsumption Monitor"
  description: >
    Monitors power sensors for sustained overconsumption above a maximum threshold.
    Filters out normal startup spikes by requiring high power for a sustained duration.
    Optionally turns off the associated switch for safety.
  domain: automation

  input:
    # -------------------------------------------------------------------------
    # Sensor Configuration
    # -------------------------------------------------------------------------
    power_sensors:
      name: Power Sensors
      description: >
        Power sensors to monitor. Switch entities are derived by replacing
        "sensor." with "switch." and removing "_power" suffix.
        Example: sensor.my_plug_power -> switch.my_plug
      selector:
        entity:
          domain: sensor
          device_class: power
          multiple: true

    # -------------------------------------------------------------------------
    # Detection Thresholds
    # -------------------------------------------------------------------------
    max_power_threshold:
      name: Maximum Power Threshold
      description: >
        Alert when power consumption exceeds this value.
        Set this to slightly above the device's normal maximum draw.
        Example: For a 1500W heater, set to 1600W.
      default: 1500
      selector:
        number:
          min: 10
          max: 10000
          step: 10
          unit_of_measurement: W
          mode: box

    sustained_duration:
      name: Sustained Duration
      description: >
        Power must stay above the threshold for this duration before alerting.
        Filters out normal startup spikes and transient fluctuations.
        Set to 0 for immediate alerts (not recommended).
      default: 30
      selector:
        number:
          min: 0
          max: 300
          step: 5
          unit_of_measurement: seconds

    idle_power_threshold:
      name: Idle Power Threshold (optional)
      description: >
        Ignore readings below this value (device considered "off" or idle).
        Helps avoid false alerts from sensor noise when device is off.
        Set to 0 to monitor all readings.
      default: 5
      selector:
        number:
          min: 0
          max: 100
          step: 1
          unit_of_measurement: W

    # -------------------------------------------------------------------------
    # Actions Configuration
    # -------------------------------------------------------------------------
    auto_turn_off:
      name: Auto Turn Off Switch
      description: >
        Automatically turn off the associated switch when overconsumption is detected.
        Recommended for safety-critical monitoring.
      default: false
      selector:
        boolean:

    # -------------------------------------------------------------------------
    # Notification Configuration
    # -------------------------------------------------------------------------
    notify_target:
      name: Notification Target (optional)
      description: >
        Notify entity to send alerts (e.g., notify.mobile_app_phone).
        Leave empty to use the default notify.notify service.
      default:
      selector:
        entity:
          domain: notify

# Single mode - we want to track each overconsumption event separately
mode: single
max_exceeded: silent

# =============================================================================
# Trigger - Power exceeds threshold for sustained duration
# =============================================================================
trigger:
  - platform: numeric_state
    entity_id: !input power_sensors
    above: !input max_power_threshold
    for:
      seconds: !input sustained_duration
    id: "overconsumption_detected"

# =============================================================================
# Variables
# =============================================================================
variables:
  # Input references
  max_power_threshold: !input max_power_threshold
  auto_turn_off: !input auto_turn_off
  notify_target: !input notify_target
  idle_power_threshold: !input idle_power_threshold

  # Trigger context
  entity: "{{ trigger.entity_id }}"
  entity_name: "{{ state_attr(trigger.entity_id, 'friendly_name') | default(trigger.entity_id) }}"
  current_power: "{{ states(trigger.entity_id) | float(0) }}"
  excess_power: "{{ (current_power - max_power_threshold) | round(1) }}"
  excess_percent: "{{ ((current_power / max_power_threshold - 1) * 100) | round(1) if max_power_threshold > 0 else 0 }}"

  # Derive switch entity from sensor naming convention
  # sensor.<name>_power -> switch.<name>
  switch_entity: >
    {{ entity | regex_replace('^sensor\\.', 'switch.') | regex_replace('_power$', '') }}
  switch_name: "{{ state_attr(switch_entity, 'friendly_name') | default(switch_entity) }}"

  # Debug flag - set to true to enable persistent notifications for troubleshooting
  is_debug: false

# =============================================================================
# Condition - Ensure power is above idle threshold (device is actually "on")
# =============================================================================
condition:
  - condition: template
    value_template: "{{ current_power > idle_power_threshold }}"

# =============================================================================
# Actions
# =============================================================================
action:
  # ---------------------------------------------------------------------------
  # Debug Logging (optional)
  # ---------------------------------------------------------------------------
  - choose:
      - conditions:
          - condition: template
            value_template: "{{ is_debug }}"
        sequence:
          - service: persistent_notification.create
            data:
              title: "Power Monitor Debug"
              message: >
                Entity: {{ entity_name }} ({{ entity }})
                Current: {{ current_power }}W
                Threshold: {{ max_power_threshold }}W
                Excess: {{ excess_power }}W (+{{ excess_percent }}%)
                Switch: {{ switch_name }} ({{ switch_entity }})
                Auto turn off: {{ auto_turn_off }}

  # ---------------------------------------------------------------------------
  # Send Overconsumption Alert
  # ---------------------------------------------------------------------------
  - choose:
      # Use configured notify target if provided
      - conditions:
          - condition: template
            value_template: "{{ notify_target is not none }}"
        sequence:
          - service: notify.send_message
            target:
              entity_id: "{{ notify_target }}"
            data:
              title: "Power Overconsumption Alert"
              message: >
                {{ entity_name }} is drawing {{ current_power }}W ({{ excess_power }}W over {{ max_power_threshold }}W limit)
    # Fall back to default notify service
    default:
      - service: notify.notify
        data:
          title: "Power Overconsumption Alert"
          message: >
            {{ entity_name }} is drawing {{ current_power }}W ({{ excess_power }}W over {{ max_power_threshold }}W limit)

  # ---------------------------------------------------------------------------
  # Auto Turn Off Switch (if enabled)
  # ---------------------------------------------------------------------------
  - choose:
      - conditions:
          - condition: template
            value_template: "{{ auto_turn_off }}"
        sequence:
          - service: switch.turn_off
            target:
              entity_id: "{{ switch_entity }}"

          # Notify that the switch was turned off
          - choose:
              - conditions:
                  - condition: template
                    value_template: "{{ notify_target is not none }}"
                sequence:
                  - service: notify.send_message
                    target:
                      entity_id: "{{ notify_target }}"
                    data:
                      message: "{{ switch_name }} has been automatically turned off due to overconsumption."
            default:
              - service: notify.notify
                data:
                  message: "{{ switch_name }} has been automatically turned off due to overconsumption."