From 093e90432903b85476dec57a3777f9299a7a681b Mon Sep 17 00:00:00 2001 From: Julian Pawlowski Date: Mon, 20 Apr 2026 18:45:20 +0000 Subject: [PATCH] docs: add blueprint import badges and update automation examples automation-examples.md: - Add info callout blocks with "Blueprint available" badges and one-click import links for each appliance section (dishwasher, washing machine, dryer, EV charging, pipeline) - Update YAML examples to reflect current service API (remove relaxation_applied template, fix indentation) sensor-reference.md: - Remove stale data-refs attributes from current_price_trend, next_price_trend_change, and today_volatility anchors examples/: - Add examples/scripts/ directory with placeholder for tibber_notify_residents.yaml script example User-Impact: none --- docs/user/docs/automation-examples.md | 199 +++++++++++++----- docs/user/docs/sensor-reference.md | 6 +- examples/scripts/tibber_notify_residents.yaml | 0 3 files changed, 151 insertions(+), 54 deletions(-) create mode 100644 examples/scripts/tibber_notify_residents.yaml diff --git a/docs/user/docs/automation-examples.md b/docs/user/docs/automation-examples.md index 1b3c65f..9ecab95 100644 --- a/docs/user/docs/automation-examples.md +++ b/docs/user/docs/automation-examples.md @@ -85,16 +85,25 @@ sequenceDiagram The classic use case. Every evening at 20:00, the automation plans when to start the dishwasher overnight. +:::info Blueprint available +These blueprints are **automatically installed** with the integration. Find them under **Settings β†’ Automations β†’ Blueprints**. You can also import them manually: + +| Variant | Import | +|---------|--------| +| **Smart Plug** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fdishwasher.yaml) | +| **Home Connect** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fdishwasher_home_connect.yaml) | +| **Home Connect Alt** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fdishwasher_home_connect_alt.yaml) | +::: + **Prerequisite:** Create an `input_datetime` helper named `input_datetime.dishwasher_start` (type: Date and time).
Show YAML: Dishwasher β€” Plan + Execute (2 automations) ```yaml -# Automation 1: Plan the cheapest time (runs every evening) automation: + # Automation 1: Plan the cheapest time (runs every evening) - alias: "Dishwasher - Plan Cheapest Start Time" - description: "Every evening, find the cheapest 2h window overnight and store the start time" trigger: - platform: time at: "20:00:00" @@ -121,14 +130,6 @@ automation: | as_timestamp | timestamp_custom('%H:%M') }}. Avg price: {{ result.window.price_mean | round(1) }} {{ result.price_unit }}. - {% if result.relaxation_applied | default(false) %} - (Filters were relaxed to find a window.) - {% endif %} - else: - - service: notify.mobile_app - data: - title: "🍽️ Dishwasher" - message: "No cheap window found tonight. Consider running manually." # Automation 2: Execute at the planned time - alias: "Dishwasher - Start at Planned Time" @@ -136,33 +137,6 @@ automation: - platform: time at: input_datetime.dishwasher_start action: - # ════════════════════════════════════════════ - # Option A: Smart appliance (Home Connect) - # Calculate the delay and let the appliance handle timing. - # Prerequisite: "Remote Start" must be enabled on the appliance. - # ════════════════════════════════════════════ - - ## --- Official Home Connect integration --- - # - service: home_connect.start_selected_program - # target: - # device_id: - # data: - # b_s_h_common_option_start_in_relative: 0 - - ## --- Home Connect Alt integration --- - # - service: home_connect_alt.start_program - # target: - # entity_id: switch. - # data: - # program: Dishcare.Dishwasher.Program.Eco50 - # options: - # - key: BSH.Common.Option.StartInRelative - # value: 0 - - # ════════════════════════════════════════════ - # Option B: Simple smart plug - # For appliances without network connectivity. - # ════════════════════════════════════════════ - service: switch.turn_on target: entity_id: switch.dishwasher_smart_plug @@ -175,17 +149,47 @@ automation: 1. At 20:00, calls `find_cheapest_block` to find the cheapest contiguous 2h window between 22:00 and 06:00 2. Stores the start time in an `input_datetime` helper (survives HA restarts) 3. A second automation triggers at the stored time and starts the appliance -4. If relaxation was needed (tight filters), the notification mentions it -:::tip Home Connect: The modern way -If you have a **Bosch/Siemens appliance with Home Connect**, you don't need a smart plug at all. Enable "Remote Start" on the appliance, then use one of the Home Connect integrations to start the selected program directly: - -- **[Official Home Connect](https://www.home-assistant.io/integrations/home_connect/)**: `home_connect.start_selected_program` with `b_s_h_common_option_start_in_relative: 0` (start immediately) -- **[Home Connect Alt](https://github.com/ekutner/home-connect-hass)** (HACS): `home_connect_alt.start_program` with `BSH.Common.Option.StartInRelative: 0` - -You can also calculate a delayed start in seconds: `{{ ((result.window.start | as_datetime - now()).total_seconds()) | int }}` β€” but using `input_datetime` with immediate start at the planned time is simpler and more reliable. +:::tip Home Connect appliances +For **Bosch/Siemens** appliances with Home Connect, use the dedicated **Home Connect blueprints** above instead β€” they handle `StartInRelative` / `FinishInRelative` automatically. You can also import a blueprint and use **"Take Control"** in the automation editor to customize it. ::: +### Washing Machine: Cheapest Window Overnight + +Same pattern as the dishwasher β€” change the `duration` to match your program (ECO 40-60 ~1:30h, Cotton 60Β°C ~2:00h) and swap the entity IDs. + +:::info Blueprint available +These blueprints are **automatically installed** with the integration. Find them under **Settings β†’ Automations β†’ Blueprints**. You can also import them manually: + +| Variant | Import | +|---------|--------| +| **Smart Plug** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fwashing_machine.yaml) | +| **Home Connect** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fwashing_machine_home_connect.yaml) | +| **Home Connect Alt** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fwashing_machine_home_connect_alt.yaml) | +::: + +**Prerequisite:** Create an `input_datetime` helper named `input_datetime.washing_machine_start` (type: Date and time). + +The YAML is identical to the [dishwasher example above](#dishwasher-find-cheapest-2-hour-window-tonight) β€” just adjust `duration`, helper name, and switch entity. Use the blueprints above for a one-click setup, including Home Connect support. + +### Dryer: Cheapest Window Overnight + +Same pattern again β€” dryer programs are typically shorter (45 min–1:15h depending on load and program). + +:::info Blueprint available +These blueprints are **automatically installed** with the integration. Find them under **Settings β†’ Automations β†’ Blueprints**. You can also import them manually: + +| Variant | Import | +|---------|--------| +| **Smart Plug** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fdryer.yaml) | +| **Home Connect** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fdryer_home_connect.yaml) | +| **Home Connect Alt** | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fdryer_home_connect_alt.yaml) | +::: + +**Prerequisite:** Create an `input_datetime` helper named `input_datetime.dryer_start` (type: Date and time). + +The YAML is identical to the [dishwasher example above](#dishwasher-find-cheapest-2-hour-window-tonight) β€” just change `duration` to `"01:00:00"`, helper name, and switch entity. + ### Two Independent Appliances: No Overlap, Each at Its Cheapest When running multiple **independent** appliances overnight (e.g., dishwasher + dryer that don't depend on each other), `find_cheapest_schedule` ensures they don't overlap and each gets its own cheapest slot. @@ -250,7 +254,7 @@ automation: - platform: time at: input_datetime.dishwasher_start action: - # Use Home Connect or smart plug β€” see dishwasher example above + # For Home Connect, use the dedicated blueprints instead - service: switch.turn_on target: entity_id: switch.dishwasher_smart_plug @@ -345,7 +349,7 @@ automation: - platform: time at: input_datetime.washing_machine_start action: - # Home Connect or smart plug (see dishwasher example above) + # For Home Connect, use the dedicated blueprints instead - service: switch.turn_on target: entity_id: switch.washing_machine_smart_plug @@ -355,6 +359,7 @@ automation: - platform: time at: input_datetime.dryer_start action: + # For Home Connect, use the dedicated blueprints instead - service: switch.turn_on target: entity_id: switch.dryer_smart_plug @@ -364,18 +369,94 @@ automation: **How it works:** -1. First `find_cheapest_block` finds the cheapest 1.5h window for the washing machine -2. Second `find_cheapest_block` uses the washer's **end time + 15 min gap** as its search start β€” guaranteeing the dryer runs after the washer +1. With `sequential: true`, the scheduler places the washing machine first at its cheapest window +2. The dryer's search window starts **after the washer ends + 15 min gap** β€” guaranteed order 3. The 15-minute gap gives you time to transfer laundry (adjust or remove as needed) -:::tip Alternative: Home Connect "Finish In Relative" -With Home Connect, you can use `b_s_h_common_option_finish_in_relative` (official) or `BSH.Common.Option.FinishInRelative` (Alt) to set a target finish time. This lets the appliance decide when to start within its own program duration β€” useful for washing machines that support "finish by" scheduling. +### Laundry Day Pipeline: Multiple Loads with Price Optimization + +When you have a full laundry day (2–3 loads that each need washing and drying), managing the timing manually is tedious. The **Laundry Day Pipeline** blueprint automates the entire process: + +```mermaid +sequenceDiagram + participant U as πŸ‘€ You + participant B as πŸ€– Blueprint + participant T as ⚑ Tibber Prices + participant W as πŸ‘• Washer + participant D as πŸŒ€ Dryer + + U->>B: Turn on "Laundry Day" toggle + B->>T: find_cheapest_block (wash 1) + T-->>B: Best window: 08:15–09:45 + B->>W: Start wash 1 + Note over W: Washing... (90 min) + B-->>U: πŸ“± "Wash 1 done! Transfer to dryer" + U->>U: Transfer laundry + B->>T: find_cheapest_block (dry 1) + T-->>B: Best window: 10:15–11:15 + B->>D: Start dryer 1 + Note over D,W: Pipeline: dryer runs while... + B->>T: find_cheapest_block (wash 2) + T-->>B: Best window: 10:15–11:45 + B->>W: Start wash 2 + Note over W: Washing... (90 min) + B-->>U: πŸ“± "Wash 2 done! Transfer" +``` + +**What the blueprint handles:** + +- **Price optimization**: Each cycle is scheduled at the cheapest available window +- **Pipeline mode** (optional): Next wash starts while the dryer runs, cutting total time significantly +- **Transfer reminders**: Notifications when each wash finishes +- **Automatic completion**: Toggle turns off when all loads are done +- **Cancellation**: Turn off the toggle at any time to stop the pipeline + +**What you need:** + +| Helper | Type | Settings | +|--------|------|----------| +| `input_boolean.laundry_day` | Toggle | Starts/stops laundry day | +| `input_number.laundry_loads` | Number | Min: 1, Max: 5, Step: 1 | + +**Choose your variant and import:** + +The blueprint comes in three variants depending on how you control your appliances. Pick the one that matches your setup: + +| Variant | Control Method | Import | +|---------|---------------|--------| +| **Smart Plug** | Smart plug switches (any brand) | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Flaundry_day_pipeline.yaml) | +| **Home Connect** | HA Core Home Connect integration | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Flaundry_day_pipeline_home_connect.yaml) | +| **Home Connect Alt** | [HC Alt HACS integration](https://github.com/ekutner/home-connect-hass) | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Flaundry_day_pipeline_home_connect_alt.yaml) | + +**After importing:** + +1. Create the two helpers (`input_boolean` + `input_number`) +2. Create an automation from the blueprint +3. Configure your appliances, program durations, and deadline +4. On laundry day: set the load count, turn on the toggle, and let the blueprint handle the rest + +:::info Pipeline mode vs. sequential +**Without pipeline** (default): Each wash + dry cycle completes fully before the next one starts. Safe for all setups. + +**With pipeline**: The next wash starts immediately after the dryer begins. This overlaps washer and dryer operation, saving roughly one dryer cycle per load. Only enable this when your **wash duration β‰₯ dryer duration** β€” otherwise the dryer from the previous load might still be running when the next dryer needs to start. + +**Example with 3 loads** (wash 90 min, dry 60 min, 15 min transfer): +- Sequential: ~8h 45min +- Pipeline: ~6h 15min β€” saves 2.5 hours! +::: + +:::caution About program durations +The blueprint uses **estimated durations** (not real-time appliance feedback). Set your durations based on typical program times and add a small buffer (~5 min). If your actual program finishes earlier or later, the timing will drift slightly β€” this is acceptable for price optimization purposes. ::: ### EV Charging: Cheapest 4 Hours Overnight For EV charging, you usually don't need one contiguous block β€” the charger can pause and resume. `find_cheapest_hours` picks the cheapest individual intervals. +:::info Blueprint available +This blueprint is **automatically installed** with the integration. You can also import it manually: [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fev_charging.yaml) +::: + **Prerequisite:** Create `input_datetime.ev_charge_start` helper. For multi-segment charging, see the note below.
@@ -475,6 +556,10 @@ Use sensors for devices that run **continuously** and can **modulate** their pow The simplest real-time approach: adjust the heat pump target temperature based on the current price rating. +:::info Blueprint available +This blueprint is **automatically installed** with the integration. You can also import it manually: [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fheat_pump_price_level.yaml) +::: +
Show YAML: Heat Pump β€” Price-Based Temperature @@ -528,6 +613,10 @@ automation: A more sophisticated approach: combine the best price period with trend sensors to **boost during the full cheap window**, not just the detected period. +:::info Blueprint available +This blueprint is **automatically installed** with the integration. You can also import it manually: [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fheat_pump_smart_boost.yaml) +::: + **Why?** On [V-shaped price days](concepts.md#v-shaped-and-u-shaped-price-days), the Best Price Period may cover only 1–2 hours, but prices remain favorable for 4–6 hours. By checking the price level and trend, you can extend the boost. ```mermaid @@ -623,6 +712,10 @@ A common misconception: **"rising" does NOT mean "too late"**. The Price Outlook Use the best price period for charging and the peak price period for discharging: +:::info Blueprint available +This blueprint is **automatically installed** with the integration. You can also import it manually: [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fhome_battery.yaml) +::: +
Show YAML: Home Battery β€” Charge/Discharge Cycle @@ -683,6 +776,10 @@ automation: Heat your water tank during the cheap window so it's ready when prices rise: +:::info Blueprint available +This blueprint is **automatically installed** with the integration. You can also import it manually: [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fjpawlowski%2Fhass.tibber_prices%2Fblob%2Fmain%2Fcustom_components%2Ftibber_prices%2Fblueprints%2Fautomation%2Ftibber_prices%2Fwater_heater.yaml) +::: +
Show YAML: Water Heater β€” Pre-Heat During Cheap Prices diff --git a/docs/user/docs/sensor-reference.md b/docs/user/docs/sensor-reference.md index 96dd816..100fe92 100644 --- a/docs/user/docs/sensor-reference.md +++ b/docs/user/docs/sensor-reference.md @@ -127,8 +127,8 @@ explanations of each sensor's purpose, attributes, and automation examples. | Entity ID suffix | πŸ‡¬πŸ‡§ English | πŸ‡©πŸ‡ͺ Deutsch | πŸ‡³πŸ‡΄ Norsk | πŸ‡³πŸ‡± Nederlands | πŸ‡ΈπŸ‡ͺ Svenska | Default | |---|---|---|---|---|---|---| -| `current_price_trend` | Current Price Trend | Aktueller Preistrend | NΓ₯vΓ¦rende pristrend | Huidige Prijstrend | Aktuell pristrend | βœ… | -| `next_price_trend_change` | Next Price Trend Change | NΓ€chste TrendΓ€nderung | Neste trendendring | Volgende Prijstrend Wijziging | NΓ€sta pristrendΓ€ndring | βœ… | +| `current_price_trend` | Current Price Trend | Aktueller Preistrend | NΓ₯vΓ¦rende pristrend | Huidige Prijstrend | Aktuell pristrend | βœ… | +| `next_price_trend_change` | Next Price Trend Change | NΓ€chste TrendΓ€nderung | Neste trendendring | Volgende Prijstrend Wijziging | NΓ€sta pristrendΓ€ndring | βœ… | | `next_price_trend_change_in` | Next Price Trend Change In | NΓ€chste TrendΓ€nderung in | Neste trendendring om | Volgende Prijstrend Wijziging over | NΓ€sta pristrendΓ€ndring om | βœ… | | `price_outlook_1h` | Price Outlook (1h) | Preisausblick (1h) | Prisutblikk (1t) | Prijsvooruitzicht (1u) | PrisΓΆversikt (1h) | βœ… | | `price_outlook_2h` | Price Outlook (2h) | Preisausblick (2h) | Prisutblikk (2t) | Prijsvooruitzicht (2u) | PrisΓΆversikt (2h) | βœ… | @@ -151,7 +151,7 @@ explanations of each sensor's purpose, attributes, and automation examples. | Entity ID suffix | πŸ‡¬πŸ‡§ English | πŸ‡©πŸ‡ͺ Deutsch | πŸ‡³πŸ‡΄ Norsk | πŸ‡³πŸ‡± Nederlands | πŸ‡ΈπŸ‡ͺ Svenska | Default | |---|---|---|---|---|---|---| -| `today_volatility` | Today's Price Volatility | VolatilitΓ€t heute | Volatilitet i dag | Vandaag Prijsvolatiliteit | Dagens prisvolatilitet | βœ… | +| `today_volatility` | Today's Price Volatility | VolatilitΓ€t heute | Volatilitet i dag | Vandaag Prijsvolatiliteit | Dagens prisvolatilitet | βœ… | | `tomorrow_volatility` | Tomorrow's Price Volatility | VolatilitΓ€t morgen | Volatilitet i morgen | Morgen Prijsvolatiliteit | Morgondagens prisvolatilitet | ❌ | | `next_24h_volatility` | Next 24h Price Volatility | VolatilitΓ€t der nΓ€chsten 24h | Volatilitet neste 24t | Komende 24u Prijsvolatiliteit | NΓ€sta 24h prisvolatilitet | ❌ | | `today_tomorrow_volatility` | Today+Tomorrow Price Volatility | VolatilitΓ€t heute+morgen | Volatilitet i dag+i morgen | Vandaag+Morgen Prijsvolatiliteit | Idag+Imorgon prisvolatilitet | ❌ | diff --git a/examples/scripts/tibber_notify_residents.yaml b/examples/scripts/tibber_notify_residents.yaml new file mode 100644 index 0000000..e69de29