Auto Off Timer

blueprint:
  name: Auto-Off After X Time (Restart-Safe)
  description: >
    Turns a device off a set amount of time after it turns on — no matter
    what turned it on (an automation, a schedule, a dashboard tap, or the
    physical button on the device). Unlike a plain "for:" trigger, this
    survives a Home Assistant restart: instead of counting elapsed time in
    memory, it writes the actual clock time the device should turn off into
    an input_datetime helper, and schedules off of that. If HA happens to be
    down through the entire window, a catch-up check at startup turns the
    device off immediately instead of missing it.

    REQUIRED SETUP: before using this blueprint, create an input_datetime
    helper for this device (Settings > Devices & services > Helpers >
    Create helper > Date and/or time). Check BOTH "Date" and "Time" — a
    time-only helper does not reliably hold a future timestamp across a
    restart. Create one helper per device you use this blueprint on.
  domain: automation
  input:
    target_entity:
      name: Device
      description: The single entity to auto-off. Duplicate this automation (with its own helper) for additional devices.
      selector:
        entity:
          domain:
            - light
            - switch
            - fan
            - climate
            - humidifier
            - media_player
            - siren
            - valve
            - water_heater
            - remote
            - input_boolean
            - cover
            - lock

    helper_datetime:
      name: Off-time helper
      description: >
        An input_datetime helper (with both Date and Time enabled) dedicated
        to this device. This blueprint writes the scheduled off-time into
        it. Create one per device — don't share a single helper across
        multiple instances of this blueprint.
      selector:
        entity:
          domain: input_datetime

    auto_off_time:
      name: Turn off after
      description: How long the device should stay "on" before it's turned off.
      default:
        hours: 0
        minutes: 15
        seconds: 0
      selector:
        duration: {}

    send_warning:
      name: Send a warning first?
      description: >
        Optional, best-effort only. This warning is NOT restart-safe (it
        uses a simple timer, same as the old approach) — if HA restarts
        during the warning window, the warning may be skipped. The
        turn-off itself is unaffected and still happens reliably.
      default: false
      selector:
        boolean: {}

    warning_time:
      name: Warning lead time
      description: How long after the device turns on to run the warning action. Must be shorter than "Turn off after".
      default:
        hours: 0
        minutes: 1
        seconds: 0
      selector:
        duration: {}

    warning_action:
      name: Warning action
      description: >
        What to do when the warning fires. Defaults to a persistent
        notification. Replace with a mobile app notify action, a light
        flash, a TTS announcement, etc.
      default:
        - action: persistent_notification.create
          data:
            title: Auto-off warning
            notification_id: "autooff_warning"
            message: >-
              {{ state_attr(target_entity, 'friendly_name') or target_entity }} will turn off soon.
      selector:
        action: {}

    turnoff_condition:
      name: Condition to allow turn-off
      description: >
        Advanced. A template that must evaluate to "true" for the turn-off
        to actually happen. Leave as "true" to always turn off. Example: to
        skip turning off a media player while it's actively playing, use
        "{{ is_state(target_entity, 'playing') == false }}".
      default: "true"
      selector:
        template: {}

    turnoff_action:
      name: Turn-off action
      description: >
        What "off" means for this device. Defaults to the generic
        homeassistant.turn_off service. Override for entities that don't
        support it, e.g. cover.close_cover for a cover, or lock.lock for a
        lock. The device is available as {{ target_entity }}.
      default:
        - action: homeassistant.turn_off
          target:
            entity_id: "{{ target_entity }}"
      selector:
        action: {}

variables:
  target_entity: !input target_entity
  off_helper: !input helper_datetime
  auto_off_duration: !input auto_off_time

mode: parallel
max: 10
max_exceeded: silent

trigger:
  - id: schedule
    trigger: state
    entity_id: !input target_entity
    to: "on"

  - id: warn
    trigger: state
    entity_id: !input target_entity
    to: "on"
    for: !input warning_time
    enabled: !input send_warning

  - id: execute
    trigger: time
    at: !input helper_datetime

  - id: catchup
    trigger: homeassistant
    event: start

condition: []

action:
  - choose:
      # Device just turned on: write the real clock time it should turn off at.
      - conditions:
          - condition: trigger
            id: schedule
        sequence:
          - action: input_datetime.set_datetime
            target:
              entity_id: "{{ off_helper }}"
            data:
              datetime: >-
                {{ (now() + timedelta(
                  hours=auto_off_duration.hours | default(0, true),
                  minutes=auto_off_duration.minutes | default(0, true),
                  seconds=auto_off_duration.seconds | default(0, true)
                )).strftime('%Y-%m-%d %H:%M:%S') }}

      # Best-effort warning before turn-off (not restart-safe).
      - conditions:
          - condition: trigger
            id: warn
        sequence: !input warning_action

      # The scheduled off-time was reached normally.
      - conditions:
          - condition: trigger
            id: execute
        sequence:
          - condition: state
            entity_id: !input target_entity
            state: "on"
          - condition: template
            value_template: !input turnoff_condition
          - sequence: !input turnoff_action

      # HA just started up: catch up if the off-time already passed while it was down.
      - conditions:
          - condition: trigger
            id: catchup
        sequence:
          - condition: state
            entity_id: !input target_entity
            state: "on"
          - condition: template
            value_template: >-
              {{ states(off_helper) not in ['unknown', 'unavailable', 'none']
                 and state_attr(off_helper, 'timestamp') is not none
                 and state_attr(off_helper, 'timestamp') <= now().timestamp() }}
          - condition: template
            value_template: !input turnoff_condition
          - sequence: !input turnoff_action