From 3bc8a71d67c134088b0c2673b9ff454b8fb9794e Mon Sep 17 00:00:00 2001 From: hiperman Date: Fri, 9 Jan 2026 22:08:02 -0500 Subject: [PATCH] update docs --- README.md | 116 +++++++++++++++++++++++++++++++-- sunrise-simulation.yaml | 141 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 252 insertions(+), 5 deletions(-) create mode 100644 sunrise-simulation.yaml diff --git a/README.md b/README.md index 1486583..7431479 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,113 @@ -# ha-sunrise-alarm -A HomeAssistant blueprint that turns your smart lights into a natural alarm clock. +# Home‑Assistant Sunrise Alarm +**Turn your smart lights into a natural alarm clock** +--- - - Open your Home Assistant instance and show the blueprint import dialog - \ No newline at end of file +## Table of Contents +1. [What it is & how it works](#what-it-is-&-how-it-works) +2. [Two‑step installation](#two‑step-installation) + * 2.1 [sunrise‑simulation](#sunrise‑simulation) + * 2.2 [sunrise‑alarm](#sunrise‑alarm) +3. [Configurable variables](#configurable-variables) + * 3.1 `sunrise‑simulation` script variables + * 3.2 `sunrise‑alarm` automation variables +4. [Customising the experience](#customising-the-experience) +5. [Troubleshooting & FAQ](#troubleshooting-&-faq) +6. [License](#license) + +--- + +## 1. What it is & how it works + +| Component | Purpose | What it does | +|-----------|---------|--------------| +| **sunrise‑simulation** (script) | The “engine” that gradually lights up (or down) your bulbs | Uses a `repeat` loop to turn the selected lights on/off and slowly increase/decrease brightness over a configurable time span. | +| **sunrise‑alarm** (automation) | The “scheduler” that calls the simulation at a chosen time | Triggers the script at *Alarm Time – Offset* (e.g. 30 min before the clock). An `input_boolean` lets you switch the alarm on/off. | + +> **Why two separate blueprints?** +> The simulation can be reused in any scenario (e.g. a “morning routine” or a “sunset‑in‑30‑min” routine). The alarm automation is a thin wrapper that turns that simulation into a timed alarm. + +--- + +## 2. Installation + +### 2.1 sunrise‑simulation + +1. **Import the blueprint** + + +
+ + Import sunrise‑simulation + +
+ + +2. **Create a script from the blueprint** + * In the “Create new script” dialog, name it **`sunrise-simulation`** (you can give any name you like). + * You’ll be asked for a handful of variables – see section 3.1 for the defaults and meaning. + * Click **Create** – Home‑Assistant will add a script entity called `script.sunrise-simulation` (or whatever name you gave it). + +--- + +### 2.2 sunrise‑alarm + +1. **Import the alarm automation blueprint** + +
+ + Import sunrise‑alarm + +
+ + +2. **Create the automation** + * Pick an `input_datetime` that represents the clock you want to use as the alarm. + * Pick an `input_boolean` that toggles the alarm on or off. + * Choose a `offset_duration` + * Choose the `sunrise‑simulation` script you created in the previous step for the `alarm_script` field. + * Save – you now have a ready‑to‑run alarm! + +> **Tip** – If you want a *sunset* alarm, simply copy the `sunrise‑simulation` script (or create a new script from the blueprint if you want to define a different arc) and reverse it by setting direction with the `reversed` flag set to `true`. You'll also want to create a new automation that calls it with a negative `offset_duration`. + + +--- + +## 2.3 Configurable variables + +### 3.1 sunrise‑simulation script variables + +| Variable | Type | Default | Description | +|----------|------|---------|-------------| +| `lights` | list of `entity_id`s | `["light.kitchen"]` | All bulbs that should be part of the arc. | +| `total_duration` | integer | `30` | Total time the arc takes on minutes. | +| `steps` | integer | `10` | How many brightness steps the script performs. If your light(s) do not support `transition` you should set this higher for a more gradual change (max value is 100). | +| `start_brightness` | integer | `0` | Brightness percentage at the very beginning of the arc. | +| `end_brightness` | integer | `100` | Brightness percentage at the very end of the arc. | +| `start_temp` | integer | `2000` | Color temperature (kelvin) at the very beginning of the arc. | +| `end_temp` | integer | `5000` | Color temperature (kelvin) at the very end of the arc. | +| `reversed` | boolean | `false` | If `true`, the script will run your arc in reverse (useful for easily defining sunsets). | +| `curve_type` | string | `sigmoid` | `linear`, `parabolic` (quadratic), or `sigmoid` (an S-curve). As we don't perceive light intensity linearly, `sigmoid` or `parabolic` make for a more natural curve. + + +### 3.2 sunrise‑alarm automation variables + +| Variable | Type | Default | Description | +|----------|------|---------|-------------| +| `alarm_time` | `input_datetime` | — | The time you want the alarm to ring (e.g. `07:00 AM`). | +| `offset_duration` | `time` | `"00:30:00"` | How many minutes after `alarm_time` the sunrise arc should start. A negative value would start **before** the alarm. | +| `alarm_enabled` | `input_boolean` | — | A switch that turns the whole alarm on/off. | +| `sunrise_script` | `script` | — | The script instance created by the `sunrise‑simulation` blueprint (`script.sunrise-simulation`). | + +The automation uses the following logic: + +1. `Alarm Time – Offset` fires the automation. +2. If `Alarm Enabled` is `on`, it calls the sunrise script. +3. If `Alarm Enabled` is `off`, nothing happens. + +--- + +## 6. License + +This repository is released under the **MIT License**. +Feel free to fork, modify, or redistribute the blueprints as long as you keep the same license. diff --git a/sunrise-simulation.yaml b/sunrise-simulation.yaml new file mode 100644 index 0000000..5b49fb9 --- /dev/null +++ b/sunrise-simulation.yaml @@ -0,0 +1,141 @@ +blueprint: + name: "Simulated Sunrise Alarm" + description: "Smoothly increase light brightness with configurable steps" + domain: script + + input: + target_lights: + name: Target Light(s) + description: Light(s) to control + selector: + target: + entity: + domain: light + + steps: + name: Number of Steps + description: How many brightness steps in the curve (use more steps if your lights do not support `transition`) + default: 10 + selector: + number: + min: 5 + max: 100 + step: 1 + + total_duration: + name: Total Duration + description: Total time to complete the brightness ramp + default: 30 + selector: + number: + min: 1 + max: 120 + unit_of_measurement: minutes + + start_brightness: + name: Starting Brightness + description: Initial brightness percentage (0-100) + default: 1 + selector: + number: + min: 0 + max: 100 + step: 1 + + end_brightness: + name: Ending Brightness + description: Final brightness percentage (0-100) + default: 100 + selector: + number: + min: 1 + max: 100 + step: 1 + + start_temp: + name: Starting Color Temperature + description: Final color temperature in Kelvin + default: 2000 + selector: + color_temp: + min: 2000 + unit: kelvin + + end_temp: + name: Ending Color Temperature + description: Final color temperature in Kelvin + default: 5000 + selector: + color_temp: + unit: kelvin + + reversed: + name: "Simulate sunset instead of sunrise" + description: If true, reverses the direction (simulates sunset instead of sunrise) + selector: + boolean: + default: false + + curve_type: + name: Curve Type + default: "parabolic" + description: “linear”, "parabolic" (quadratic), or “sigmoid” (an S-curve/logistic curve) + selector: + select: + options: + - "linear" + - "sigmoidal" + - "parabolic" + +variables: + lights: !input target_lights + start_temp: !input start_temp + end_temp: !input end_temp + curve_type: !input curve_type + total_duration: !input total_duration + num_steps: !input steps + step_delay: "{{ (total_duration * 60 / num_steps) | round(0) }}" + start_bright: !input start_brightness + end_bright: !input end_brightness + reversed: !input reversed + +# Loop through each step of the curve +sequence: + - repeat: + count: "{{ num_steps }}" + sequence: + - variables: + # Calculate current step (0 to 1 range) + x: "{{ (repeat.index - 1) / (num_steps - 1) }}" + + # Reflects the curve in the y-axis if reversed is true + - choose: + - conditions: + - condition: template + value_template: "{{ reversed }}" + sequence: + - variables: + x: "{{ 1 - x }}" + + - variables: + curve_func: > + {%- if curve_type == 'linear' -%} + {{ x }} + {%- elif curve_type == 'sigmoidal' -%} + {{ 1 / (1 + (2.71828 ** (-12 * (x - 0.5)))) }} + {%- elif curve_type == 'parabolic' -%} + {{ x ** 2 }} + {%- endif -%} + + # Map result to brightness range and color temperature range respectively + current_brightness: "{{ (start_bright + (end_bright - start_bright) * curve_func | float) | round(0) }}" + current_color_temp: "{{ (start_temp + (end_temp - start_temp) * curve_func | float) | round(0) }}" + + - service: light.turn_on + target: !input target_lights + data: + brightness_pct: "{{ current_brightness }}" + kelvin: "{{ current_color_temp }}" + transition: "{{ step_delay }}" + + - delay: "{{ step_delay }}" \ No newline at end of file