update docs

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**  
+---
 
-<a href="https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https://git.jaroszew.ski/patrick/ha-sunrise-alarm/src/branch/main/sunrise-alarm.yaml">
-  <img src="https://my.home-assistant.io/badges/blueprint_import.svg" alt="Open your Home Assistant instance and show the blueprint import dialog">
-</a>
+## 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**  
+
+
+   <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">
+   </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.  
+   * 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**  
+
+   <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">
+   </a>
+   </div>
+
+
+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.