# ==============================================================================
# Outdoor Lights — Sunset Fade-in / Overnight Fade-out
# Home Assistant Blueprint for automations
# ------------------------------------------------------------------------------
# Drives a light (or light group) through a gentle daily cycle:
#
#   1. Sunset           — fade gradually from 1% to the target brightness
#   2. Late-evening     — fade gradually back down to 1% over the fade-out window
#   3. Late-evening end — hard-off
#
# The colour stays at a single configurable RGB value the whole time. Default is
# warm amber (255, 147, 41) — close to a candle / old-school sodium streetlight,
# easy on the eyes after dark and good for outdoor accent lighting.
#
# The blueprint handles a quirk in HA: a `transition:` on a light that's
# currently off doesn't actually animate — it snaps to the target brightness
# instantly. The workaround is a two-step turn-on:
#   - First call: brightness_pct=1, no transition (establishes the on state)
#   - 5-second settle
#   - Second call: brightness_pct=target, with the full transition (the actual
#     animated fade-in)
# The fade-out side doesn't need the trick — the light is already on, so a
# single transition call from any non-off state works.
#
# Features:
#   - Configurable RGB color (defaults to warm amber)
#   - Configurable target brightness (defaults to 50%)
#   - Configurable fade-in duration (defaults to 30 minutes)
#   - Configurable sunset trigger offset (e.g., -00:20:00 = 20 min before sunset)
#   - Configurable fade-out start time (defaults to 23:30)
#   - Configurable fade-out duration (defaults to 30 minutes)
#   - Configurable turn-off time (defaults to 00:00)
#   - Optional "skip when the sky is still bright" gate using sun elevation
#     (useful for high-summer evenings when astronomical sunset fires but
#     it's still bright outside)
#
# Companion guide with the longer write-up (step-fade variant, color reference,
# troubleshooting table):
#   https://magikh0e.pl/pubHomeAutomation/outdoor-lights-sunset-fade.html
#
# Install — option A (one-time via the HA UI):
#   1. Home Assistant → Settings → Automations & Scenes → Blueprints
#   2. Click "Import Blueprint" and paste this file's URL:
#      https://magikh0e.pl/pubHomeAutomation/blueprints/outdoorLightsSunsetFade.yaml.txt
#   3. Preview, then Import.
#
# Install — option B (drop the file in place):
#   1. Save this file as:
#      config/blueprints/automation/magikh0e/outdoorLightsSunsetFade.yaml
#      (note: .yaml NOT .yaml.txt when saving locally)
#   2. Restart Home Assistant (or reload blueprints from the UI).
#
# Use:
#   1. Settings → Automations & Scenes → "+ Create Automation"
#   2. "Create from Blueprint" → "Outdoor Lights — Sunset Fade-in / Fade-out"
#   3. Pick the light entity. If you have multiple bulbs to control together,
#      create a `light: - platform: group` first and point this at the group.
#   4. Adjust color, brightness, durations, and times to taste. Save.
# ==============================================================================


blueprint:
  name: Outdoor Lights — Sunset Fade-in / Overnight Fade-out
  description: >
    Drives a light or light group through a daily sunset-to-midnight cycle:
    fade in at sunset, fade out at a configurable late-evening time, hard-off
    at a configurable post-fade time. Configurable color, brightness, durations,
    sunset offset, and an optional sun-elevation gate so high-summer evenings
    don't kick the lights on while it's still bright outside.
  domain: automation
  source_url: https://magikh0e.pl/pubHomeAutomation/blueprints/outdoorLightsSunsetFade.yaml.txt
  input:

    # ---------- Light ----------
    light_section:
      name: Light
      icon: mdi:lightbulb-on-outline
      input:
        light_entity:
          name: Light or light group
          description: >
            Single light entity, or a `light: - platform: group` that combines
            multiple bulbs into one logical entity. The blueprint sends one
            light.turn_on / light.turn_off pair per cycle stage, so a group
            is the right approach for synchronised multi-bulb setups.
          selector:
            entity:
              filter:
                - domain: light

        rgb_color:
          name: Color (RGB)
          description: >
            Color used throughout the entire cycle. Default 255,147,41 = warm
            amber (~2200K, candle / sodium-streetlight feel). Other useful
            values: 255,180,107 (cooler white), 255,140,30 (pure amber),
            255,100,80 (coral / sunset), 200,220,255 (cool security white),
            50,200,50 (soft green that blends with garden plants).
          default: [255, 147, 41]
          selector:
            color_rgb:

        target_brightness_pct:
          name: Target brightness (%)
          description: >
            Brightness the light reaches at the end of the fade-in. 50% works
            well for outdoor accent lighting; bump to 80–100 for security-
            style brightness, drop to 20–30 for ambient mood lighting.
          default: 50
          selector:
            number:
              min: 1
              max: 100
              step: 1
              unit_of_measurement: "%"
              mode: slider

    # ---------- Fade-in (sunset) ----------
    fade_in_section:
      name: Sunset fade-in
      icon: mdi:weather-sunset-down
      input:
        sunset_offset:
          name: Sunset trigger offset
          description: >
            Start the fade-in earlier or later than astronomical sunset.
            Negative = earlier, positive = later. Format HH:MM:SS.
            e.g. -00:20:00 = 20 min before sunset, 00:30:00 = 30 min after.
          default: "00:00:00"
          selector:
            text:

        fade_in_seconds:
          name: Fade-in duration (seconds)
          description: >
            How long the bulb takes to ramp from 1% to the target brightness.
            Default 1800 = 30 minutes. Values 300 (5 min) through 3600 (1 hr)
            are all reasonable. Note: very short fades (<60s) may look
            instantaneous on some bulbs that don't honor fine-grained
            transition timing.
          default: 1800
          selector:
            number:
              min: 1
              max: 3600
              step: 1
              unit_of_measurement: "s"
              mode: box

        require_dark:
          name: Skip when the sky is still bright
          description: >
            Optional gate: only run the sunset fade-in if the sun's elevation
            is below the threshold below. Useful in high-summer when
            astronomical sunset fires but it's still bright outside. When
            off, the fade-in always runs at the sunset trigger.
          default: false
          selector:
            boolean:

        dark_elevation:
          name: Dark-sky elevation threshold (degrees)
          description: >
            If "Skip when the sky is still bright" is on, the sunset fade-in
            only runs when sun.sun's elevation is below this. Ignored when
            the gate is off. Default 3° — typical "civil twilight is well
            under way" point. Lower values (-3° to 0°) wait until proper
            astronomical darkness.
          default: 3
          selector:
            number:
              min: -20
              max: 20
              step: 0.5
              unit_of_measurement: "°"
              mode: slider

    # ---------- Fade-out / off (late evening) ----------
    fade_out_section:
      name: Late-evening fade-out
      icon: mdi:weather-night
      input:
        fade_out_time:
          name: Fade-out start time
          description: >
            When the lights start dimming back down. Default 23:30.
            Skips the fade-out gracefully if the light is already off
            (e.g. someone turned it off manually earlier).
          default: "23:30:00"
          selector:
            time:

        fade_out_seconds:
          name: Fade-out duration (seconds)
          description: >
            How long the bulb takes to ramp from its current brightness back
            down to 1%. Default 1800 = 30 minutes.
          default: 1800
          selector:
            number:
              min: 1
              max: 3600
              step: 1
              unit_of_measurement: "s"
              mode: box

        turn_off_time:
          name: Hard-off time
          description: >
            After the fade-out completes, this issues a hard light.turn_off
            so the bulb is fully off (not just at 1%). Default 00:00.
            Should be set to fade-out time + fade-out duration, or slightly
            later, to give the transition time to finish.
          default: "00:00:00"
          selector:
            time:


# One automation can be running at a time. The three triggers fire on widely
# separated schedules (sunset, late evening, just past late evening) so single
# is the right mode — and queued doesn't add value when there's no overlap.
mode: single
max_exceeded: silent

# Each trigger carries an `id:` so the action block can dispatch via `choose`.
trigger:
  - platform: sun
    event: sunset
    offset: !input sunset_offset
    id: sunset_fade_in
  - platform: time
    at: !input fade_out_time
    id: fade_out_start
  - platform: time
    at: !input turn_off_time
    id: turn_off

variables:
  # Surface the blueprint inputs as template-visible variables so the
  # template-condition below (the optional sun-elevation gate) can reference
  # them. !input directly in templates doesn't always resolve cleanly; the
  # `variables:` block is the documented bridge.
  require_dark: !input require_dark
  dark_elevation: !input dark_elevation

action:
  - choose:

      # =========================================================
      # Branch 1: SUNSET FADE-IN
      # =========================================================
      - conditions:
          - condition: trigger
            id: sunset_fade_in
          # Optional sun-elevation gate. When require_dark=false this always
          # passes. When true, we only proceed when the sun is below horizon
          # OR its reported elevation is below the configured threshold.
          # The `| float(99)` fallback prevents a missing-attribute edge case
          # (sun.sun returns no elevation during a state-change blip) from
          # silently swallowing the trigger.
          - condition: template
            value_template: >-
              {{ not require_dark
                 or is_state('sun.sun', 'below_horizon')
                 or (state_attr('sun.sun', 'elevation') | float(99) < dark_elevation) }}
        sequence:
          # Step 1 — establish the bulb's starting state at 1% with the
          # target colour. No `transition:` here on purpose; HA can't
          # transition from the off state, so this is the "wake the bulb"
          # call.
          - action: light.turn_on
            target:
              entity_id: !input light_entity
            data:
              brightness_pct: 1
              rgb_color: !input rgb_color
          # Brief settle so the bulb is reliably on before we ask it to
          # transition. 5 seconds is empirically generous; 2-3 also work
          # for most bulbs. Increase to 10 if your bulb is slow to ack
          # the first turn_on.
          - delay:
              seconds: 5
          # Step 2 — now that the bulb is on, request the real fade.
          - action: light.turn_on
            target:
              entity_id: !input light_entity
            data:
              brightness_pct: !input target_brightness_pct
              rgb_color: !input rgb_color
              transition: !input fade_in_seconds

      # =========================================================
      # Branch 2: LATE-EVENING FADE-OUT
      # =========================================================
      - conditions:
          - condition: trigger
            id: fade_out_start
          # Don't try to fade out a light that's already off — that would
          # call light.turn_on with brightness_pct: 1, which would actually
          # bring the bulb back on at 1%, which is the opposite of what
          # we want. Skip the branch if the light is currently off.
          - condition: state
            entity_id: !input light_entity
            state: "on"
        sequence:
          - action: light.turn_on
            target:
              entity_id: !input light_entity
            data:
              brightness_pct: 1
              transition: !input fade_out_seconds

      # =========================================================
      # Branch 3: HARD-OFF AFTER FADE-OUT
      # =========================================================
      - conditions:
          - condition: trigger
            id: turn_off
        sequence:
          - action: light.turn_off
            target:
              entity_id: !input light_entity