Update README.md

README.md

@@ -1,62 +1,54 @@
+# Home-Assistant Sunrise Alarm  
+_Turn your smart lights into a natural alarm clock_
 
-# Home‑Assistant Sunrise Alarm  
+This project is made up of two blueprints
-**Turn your smart lights into a natural alarm clock**  
+- `sunrise-simulation.yaml`: This script turns any compatible light (or group of lights) into a soft-sunrise / sunset alarm. It gradually ramps the brightness and the colour temperature over a user-defined period.
----
+- `sunrise-alarm.yaml`: Thin wrapper that calls the simulation script when the alarm occurs (or some configured time before/after).
-
-## 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-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. The brightness and color curves can be configured to create more natural-looking sunrises.  |
-| **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. |
+| **sunrise-alarm** (automation) | The “scheduler” that calls the simulation at a chosen time | Triggers the script at *Alarm Time - Offset* (e.g. 30min before the clock). An `input_boolean` lets you switch the alarm on/off. |
 
+> [!NOTE]
 > **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.
+> 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.
+>
+> Scripts can also be stopped while the are executing, allowing you to stop the sunrise arc without turning the scheduler on and off.
 
 ---
 
-## 2. Installation  
+## Installation  
 
-### 2.1 sunrise‑simulation  
+### sunrise-simulation  
 
-1. **Import the blueprint**  
+1. **Import the sunrise script blueprint**  
 
 
    <div>
    <a href="https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https://git.jaroszew.ski/patrick/ha-sunrise-alarm/raw/branch/main/sunrise-simulation.yaml">
-     <img src="https://my.home-assistant.io/badges/blueprint_import.svg" alt="Import sunrise‑simulation">
+     <img src="https://my.home-assistant.io/badges/blueprint_import.svg" alt="Import sunrise-simulation">
    </a>
    </div>
 
 
 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.  
+   * 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).
+   * Click **Create** - Home-Assistant will add a script entity called `script.sunrise-simulation` (or whatever name you gave it).
 
 ---
 
-### 2.2 sunrise‑alarm  
+### sunrise-alarm  
 
 1. **Import the alarm automation blueprint**  
 
    <div>
    <a href="https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https://git.jaroszew.ski/patrick/ha-sunrise-alarm/raw/branch/main/sunrise-alarm.yaml">
-     <img src="https://my.home-assistant.io/badges/blueprint_import.svg" alt="Import sunrise‑alarm">
+     <img src="https://my.home-assistant.io/badges/blueprint_import.svg" alt="Import sunrise-alarm">
    </a>
    </div>
 
@@ -64,18 +56,18 @@
 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 an `offest_duration` for how long before/after to start the sunrise arc relative to the alarm time. You'll usually want this to be the same as `duration` defined in the previous script, this time _negative_, so that the peak (end) of the arc aligns with the alarm time.
-   * Choose the `sunrise‑simulation` script you created in the previous step for the `alarm_script` field.  
+   * 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!
+   * 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`.
+> **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  
+## Configurable variables  
 
-### 3.1 sunrise‑simulation script variables  
+### sunrise-simulation script variables  
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
@@ -90,24 +82,27 @@
 | `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  
+### 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. |
+| `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.  
+1. `Alarm Time - Offset` fires the automation.  
-2. If `Alarm Enabled` is `on`, it calls the sunrise script.  
+2. If `Alarm Enabled` is `on`, it calls the sunrise script.  
-3. If `Alarm Enabled` is `off`, nothing happens.  
+3. If `Alarm Enabled` is `off`, nothing happens.  
+
+> [!WARNING]
+> You may not be able to set negative duration values via the user interface. If so, you'll need to edit the YAML directly.
 
 ---
 
-## 6. License  
+## 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.