diff --git a/docs/user/docs/automation-examples.md b/docs/user/docs/automation-examples.md index 7f47587..c0a6822 100644 --- a/docs/user/docs/automation-examples.md +++ b/docs/user/docs/automation-examples.md @@ -58,6 +58,9 @@ gantt This automation starts a flexible load when the best price period begins, but keeps it running as long as prices remain favorable — even after the period ends. +
+Show YAML: Heat pump — extended cheap period + ```yaml automation: - alias: "Heat Pump - Extended Cheap Period" @@ -103,6 +106,8 @@ automation: temperature: 22 ``` +
+ **How it works:** 1. Starts when the best price period triggers @@ -114,6 +119,9 @@ automation: Use the trend to start slightly before the cheapest period — useful for appliances with warm-up time: +
+Show YAML: Water heater — pre-heat before cheapest window + ```yaml automation: - alias: "Water Heater - Pre-Heat Before Cheapest" @@ -141,10 +149,15 @@ automation: temperature: 60 ``` +
+ ### Use Case: Protect Against Rising Prices Stop or reduce consumption when prices are climbing: +
+Show YAML: EV charger — stop when prices rising + ```yaml automation: - alias: "EV Charger - Stop When Prices Rising" @@ -171,6 +184,8 @@ automation: Next trend change in ~{{ state_attr('sensor._next_price_trend_change', 'minutes_until_change') }} minutes. ``` +
+ ### Use Case: Multi-Window Trend Strategy for Flexible Loads Combine short-term and long-term trend sensors for smarter decisions. This example manages a heat pump boost: @@ -180,6 +195,9 @@ Combine short-term and long-term trend sensors for smarter decisions. This examp - If **both** say `falling` → prices are dropping, definitely wait - If long-term says `falling` → cheaper hours ahead, no rush +
+Show YAML: Heat pump — multi-window trend strategy + ```yaml automation: - alias: "Heat Pump - Smart Boost Using Multi-Window Trends" @@ -248,6 +266,8 @@ automation: temperature: 20.5 ``` +
+ :::tip Why "rising" means "act now" A common misconception: **"rising" does NOT mean "too late"**. It means your current price is **lower** than the future average — so right now is actually a good time. See [How to Use Trend Sensors for Decisions](sensors.md#how-to-use-trend-sensors-for-decisions) in the sensor documentation for details. ::: @@ -275,6 +295,9 @@ On days with low price variation, the difference between "cheap" and "expensive" **Best Practice:** Instead of checking a numeric percentage, this automation checks the sensor's classified state. This makes the automation simpler and respects the volatility thresholds you have configured centrally in the integration's options. +
+Show YAML: Home battery — charge on best price (volatility-aware) + ```yaml automation: - alias: "Home Battery - Charge During Best Price (Moderate+ Volatility)" @@ -307,6 +330,8 @@ automation: ``` +
+ **Why this works:** - The automation only runs if volatility is `moderate`, `high`, or `very_high`. @@ -317,6 +342,9 @@ automation: This is the most robust approach. It trusts the "Best Price" classification on volatile days but adds a backup absolute price check for low-volatility days. This handles situations where prices are globally low, even if the daily variation is minimal. +
+Show YAML: EV charging — combined volatility + absolute price strategy + ```yaml automation: - alias: "EV Charging - Smart Strategy" @@ -352,6 +380,8 @@ automation: Today's volatility is {{ state_attr('sensor._today_s_price_volatility', 'price_volatility') }}. ``` +
+ **Why this works:** - On days with meaningful price swings, it charges during any `Best Price` period. @@ -362,6 +392,9 @@ automation: For maximum simplicity, you can use the attributes of the `best_price_period` sensor itself. It contains the volatility classification for the day the period belongs to. This is especially useful for periods that span across midnight. +
+Show YAML: Heat pump — smart heating using period volatility attribute + ```yaml automation: - alias: "Heat Pump - Smart Heating Using Period's Volatility" @@ -383,6 +416,8 @@ automation: temperature: 22 # Boost temperature during cheap period ``` +
+ **Why this works:** - Each detected period has its own `volatility` attribute (`low`, `moderate`, etc.). @@ -398,6 +433,9 @@ automation: Use future average sensors to determine the cheapest upcoming window for a timed appliance (e.g., dishwasher with 2-hour ECO program): +
+Show YAML: Dishwasher — schedule for cheapest 2h window + ```yaml automation: - alias: "Dishwasher - Schedule for Cheapest 2h Window" @@ -431,10 +469,15 @@ automation: {% endif %} ``` +
+ ### Use Case: Notify When Cheapest Window Starts Get a push notification when the best price period begins: +
+Show YAML: Notification — when cheap window starts + ```yaml automation: - alias: "Notify - Cheap Window Started" @@ -455,6 +498,8 @@ automation: {{ state_attr('sensor._current_electricity_price', 'unit_of_measurement') }}. ``` +
+ --- ## ApexCharts Cards diff --git a/docs/user/docs/dashboard-examples.md b/docs/user/docs/dashboard-examples.md index 777b059..d84c993 100644 --- a/docs/user/docs/dashboard-examples.md +++ b/docs/user/docs/dashboard-examples.md @@ -42,6 +42,9 @@ cards: ### Price Level Card +
+Show YAML: Price level card with color gradients (custom:button-card) + ```yaml type: custom:button-card entity: sensor._current_price_level @@ -60,12 +63,17 @@ styles: ]]] ``` +
+ ## Lovelace Layouts ### Compact Mobile View Optimized for mobile devices: +
+Show YAML: Compact mobile layout + ```yaml type: vertical-stack cards: @@ -84,10 +92,15 @@ cards: name: Active Now ``` +
+ ### Desktop Dashboard Full-width layout for desktop: +
+Show YAML: Desktop 3-column grid layout + ```yaml type: grid columns: 3 @@ -114,10 +127,15 @@ cards: - sensor._today_s_highest_price ``` +
+ ## Icon Color Integration Using the `icon_color` attribute for dynamic colors: +
+Show YAML: Dynamic icon colors with mushroom chips + ```yaml type: custom:mushroom-chips-card chips: @@ -134,12 +152,17 @@ chips: icon_color: red ``` +
+ See [Icon Colors](icon-colors.md) for detailed color mapping. ## Picture Elements Dashboard Advanced interactive dashboard: +
+Show YAML: Picture elements interactive dashboard + ```yaml type: picture-elements image: /local/electricity_dashboard_bg.png @@ -161,10 +184,15 @@ elements: # Add more elements... ``` +
+ ## Auto-Entities Dynamic Lists Automatically list all price sensors: +
+Show YAML: Auto-entities card for all price sensors + ```yaml type: custom:auto-entities card: @@ -180,6 +208,8 @@ sort: numeric: true ``` +
+ --- 💡 **Related:** diff --git a/docs/user/docs/icon-colors.md b/docs/user/docs/icon-colors.md index 0ee1145..6520394 100644 --- a/docs/user/docs/icon-colors.md +++ b/docs/user/docs/icon-colors.md @@ -137,6 +137,9 @@ styles: Use Home Assistant's built-in entities card with card_mod for icon and state colors: +
+Show YAML: Entities card with card_mod + ```yaml type: entities entities: @@ -153,6 +156,8 @@ card_mod: } ``` +
+ ### Method 3: Mushroom Cards The [Mushroom cards](https://github.com/piitaya/lovelace-mushroom) support card_mod for icon and text colors: @@ -173,6 +178,9 @@ card_mod: **Icon and state value:** +
+Show YAML: Mushroom card — icon and state value with same color + ```yaml type: custom:mushroom-entity-card entity: sensor._current_price_level @@ -185,10 +193,15 @@ card_mod: } ``` +
+ ### Method 4: Glance Card with card_mod Combine multiple sensors with dynamic colors: +
+Show YAML: Glance card with card_mod for multiple sensors + ```yaml type: glance entities: @@ -208,10 +221,15 @@ card_mod: } ``` +
+ ## Complete Dashboard Example Here's a complete example combining multiple sensors with dynamic colors: +
+Show YAML: Complete dashboard with dynamic colors for all sensor types + ```yaml type: vertical-stack cards: @@ -293,6 +311,8 @@ cards: ]]] ``` +
+ ## CSS Color Variables The integration uses Home Assistant's standard CSS variables for theme compatibility: @@ -331,6 +351,9 @@ Instead of using `icon_color`, read the sensor state and apply your own colors: **Example: Custom colors for price level** +
+Show YAML: Price level — 5-color JavaScript mapping + ```yaml type: custom:button-card entity: sensor._current_price_level @@ -351,8 +374,13 @@ styles: ]]] ``` +
+ **Example: Custom colors for binary sensor** +
+Show YAML: Binary sensor — on/off color + background highlight + ```yaml type: custom:button-card entity: binary_sensor._best_price_period @@ -373,8 +401,13 @@ styles: ]]] ``` +
+ **Example: Custom colors for volatility** +
+Show YAML: Volatility sensor — 4-level color mapping + ```yaml type: custom:button-card entity: sensor._today_s_price_volatility @@ -393,8 +426,13 @@ styles: ]]] ``` +
+ **Example: Custom colors for price rating** +
+Show YAML: Price rating — 3-state color mapping + ```yaml type: custom:button-card entity: sensor._current_price_rating @@ -412,6 +450,8 @@ styles: ]]] ``` +
+ ### Which Approach Should You Use? | Use Case | Recommended Approach | diff --git a/docs/user/docs/period-calculation.md b/docs/user/docs/period-calculation.md index 696ea36..91b8c0a 100644 --- a/docs/user/docs/period-calculation.md +++ b/docs/user/docs/period-calculation.md @@ -583,6 +583,9 @@ Relaxation tried all configured attempts but couldn't reach your target. Options **Key attributes to check:** +
+Show YAML: Sensor attribute reference for best_price_period + ```yaml # Entity: binary_sensor._best_price_period @@ -609,6 +612,8 @@ flat_days_detected: 1 # Days where prices were so flat that 1 peri relaxation_incomplete: true # Some days couldn't reach the configured target ``` +
+ #### What the diagnostic attributes mean **`min_periods_configured` / `periods_found_total`** @@ -678,6 +683,9 @@ This is **mathematically correct behavior** caused by how electricity prices are **Example:** +
+Show YAML: How identical prices can flip between best/peak across midnight + ```yaml # Day 1 (low volatility, narrow range) Price range: 18-22 ct/kWh (4 ct span) @@ -695,6 +703,8 @@ Daily average: 19 ct/kWh # - Day 2: Near the middle/top of the range ``` +
+ **When This Occurs:** - **Low-volatility days:** When price span is narrow (< 5 ct/kWh) - **Stable weather:** Similar conditions across multiple days @@ -719,6 +729,9 @@ sensor._tomorrow_s_price_volatility: 7.9% # Also low You can make your automations volatility-aware: +
+Show YAML: 3 automation strategies for volatility-aware period control + ```yaml # Option 1: Only act on high-volatility days automation: @@ -767,6 +780,8 @@ automation: entity_id: switch.ev_charger ``` +
+ **Available Per-Period Attributes:** Each period sensor exposes day volatility and price statistics: diff --git a/docs/user/docs/sensors.md b/docs/user/docs/sensors.md index 88c3ebb..2cfa73c 100644 --- a/docs/user/docs/sensors.md +++ b/docs/user/docs/sensors.md @@ -102,6 +102,9 @@ sensor: Run dishwasher only when price is significantly below the daily typical level: +
+Show YAML: Automation — start dishwasher when cheap + ```yaml automation: - alias: "Start Dishwasher When Cheap" @@ -121,10 +124,15 @@ automation: entity_id: switch.dishwasher ``` +
+ **Example 2: Cost-aware heating control** Use mean for actual cost calculations: +
+Show YAML: Automation — cost-aware heating control + ```yaml automation: - alias: "Heating Budget Control" @@ -143,10 +151,15 @@ automation: message: "Expected cost today: €{{ daily_cost }} (avg price: {{ mean_price }} ct/kWh)" ``` +
+ **Example 3: Smart charging based on rolling average** Use trailing average to understand recent price trends: +
+Show YAML: Automation — EV charging based on rolling average + ```yaml automation: - alias: "EV Charging - Price Trend Based" @@ -169,6 +182,8 @@ automation: entity_id: switch.ev_charger ``` +
+ #### Key Attributes All average sensors provide these attributes: @@ -490,6 +505,9 @@ After updating the integration, the `energy_price` and `tax` attributes will app In countries like the Netherlands, solar feed-in compensation is based on the **raw energy/spot price**, not the total consumer price. The `energy_price` attribute gives you exactly this value — no more reverse-engineering from the total price with fragile template calculations. +
+Show YAML: Automation — solar export or consume decision + ```yaml # Example: Decide whether to export solar power or consume it # Compare energy price (what you'd earn by exporting) vs. total price (what you'd pay) @@ -511,10 +529,15 @@ automation: entity_id: switch.battery_charging # Don't charge battery, export instead ``` +
+ #### Price Composition Analysis Understand how your electricity price is structured — useful for comparing across days or spotting trends in market prices vs. fees: +
+Show YAML: Template sensor — electricity tax share percentage + ```yaml # Template sensor showing tax share template: @@ -531,6 +554,8 @@ template: {% endif %} ``` +
+ #### Dashboard: Daily Cost Breakdown Show users how today's average price splits into energy vs. tax: @@ -603,6 +628,9 @@ icon: mdi:clock-fast **Display period progress bar:** +
+Show YAML: Bar card for period progress + ```yaml type: custom:bar-card entity: sensor._best_price_progress @@ -621,8 +649,13 @@ severity: color: red ``` +
+ **Automation: notify when period is almost over:** +
+Show YAML: Automation — notify when best price period is ending + ```yaml automation: - alias: "Warn: Best Price Ending Soon" @@ -641,6 +674,8 @@ automation: message: "Only {{ states('sensor._best_price_remaining_minutes') }} minutes left!" ``` +
+ ## Trend Sensors Trend sensors help you understand **whether to act now or wait**. The integration provides two complementary families: