jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-07-27 17:26:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs(user): wrap large YAML blocks in collapsible details elements

Browse source 
All YAML code blocks >12-14 lines in example and concept pages are now
wrapped in HTML <details>/<summary> elements, reducing scroll depth
and making complex pages easier to navigate.

Pages affected:
- automation-examples.md: 9 blocks (heat pump, EV, battery automations)
- dashboard-examples.md: 6 blocks (button-card, mushroom, grid layouts)
- sensors.md: 7 blocks (practical examples, energy/tax templates, timing)
- icon-colors.md: 8 blocks (card_mod methods, complete dashboard, custom colors)
- period-calculation.md: 3 blocks (sensor attr reference, midnight example, automations)

Blocks left visible: short examples (<13 lines), Good/Bad comparisons,
Method 1 (primary recommended approach in icon-colors.md).

Impact: Users can scan page structure without scrolling past long YAML.
Code is still one click away, not hidden behind navigation.
This commit is contained in:
Julian Pawlowski 2026-04-11 08:30:25 +00:00
parent 5314454a26
commit 89de3dcadf
5 changed files with 165 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
docs/user/docs/automation-examples.md
View file

@ -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. 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.
<details>
<summary>Show YAML: Heat pump — extended cheap period</summary>
```yaml ```yaml
automation: automation:
- alias: "Heat Pump - Extended Cheap Period" - alias: "Heat Pump - Extended Cheap Period"
@ -103,6 +106,8 @@ automation:
temperature: 22 temperature: 22
``` ```
</details>
**How it works:** **How it works:**
1. Starts when the best price period triggers 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: Use the trend to start slightly before the cheapest period — useful for appliances with warm-up time:
<details>
<summary>Show YAML: Water heater — pre-heat before cheapest window</summary>
```yaml ```yaml
automation: automation:
- alias: "Water Heater - Pre-Heat Before Cheapest" - alias: "Water Heater - Pre-Heat Before Cheapest"
@ -141,10 +149,15 @@ automation:
temperature: 60 temperature: 60
``` ```
</details>
### Use Case: Protect Against Rising Prices ### Use Case: Protect Against Rising Prices
Stop or reduce consumption when prices are climbing: Stop or reduce consumption when prices are climbing:
<details>
<summary>Show YAML: EV charger — stop when prices rising</summary>
```yaml ```yaml
automation: automation:
- alias: "EV Charger - Stop When Prices Rising" - alias: "EV Charger - Stop When Prices Rising"
@ -171,6 +184,8 @@ automation:
Next trend change in ~{{ state_attr('sensor.<home_name>_next_price_trend_change', 'minutes_until_change') }} minutes. Next trend change in ~{{ state_attr('sensor.<home_name>_next_price_trend_change', 'minutes_until_change') }} minutes.
``` ```
</details>
### Use Case: Multi-Window Trend Strategy for Flexible Loads ### 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: 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 **both** say `falling` → prices are dropping, definitely wait
- If long-term says `falling` → cheaper hours ahead, no rush - If long-term says `falling` → cheaper hours ahead, no rush
<details>
<summary>Show YAML: Heat pump — multi-window trend strategy</summary>
```yaml ```yaml
automation: automation:
- alias: "Heat Pump - Smart Boost Using Multi-Window Trends" - alias: "Heat Pump - Smart Boost Using Multi-Window Trends"
@ -248,6 +266,8 @@ automation:
temperature: 20.5 temperature: 20.5
``` ```
</details>
:::tip Why "rising" means "act now" :::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. 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. **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.
<details>
<summary>Show YAML: Home battery — charge on best price (volatility-aware)</summary>
```yaml ```yaml
automation: automation:
- alias: "Home Battery - Charge During Best Price (Moderate+ Volatility)" - alias: "Home Battery - Charge During Best Price (Moderate+ Volatility)"
@ -307,6 +330,8 @@ automation:
``` ```
</details>
**Why this works:** **Why this works:**
- The automation only runs if volatility is `moderate`, `high`, or `very_high`. - 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. 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.
<details>
<summary>Show YAML: EV charging — combined volatility + absolute price strategy</summary>
```yaml ```yaml
automation: automation:
- alias: "EV Charging - Smart Strategy" - alias: "EV Charging - Smart Strategy"
@ -352,6 +380,8 @@ automation:
Today's volatility is {{ state_attr('sensor.<home_name>_today_s_price_volatility', 'price_volatility') }}. Today's volatility is {{ state_attr('sensor.<home_name>_today_s_price_volatility', 'price_volatility') }}.
``` ```
</details>
**Why this works:** **Why this works:**
- On days with meaningful price swings, it charges during any `Best Price` period. - 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. 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.
<details>
<summary>Show YAML: Heat pump — smart heating using period volatility attribute</summary>
```yaml ```yaml
automation: automation:
- alias: "Heat Pump - Smart Heating Using Period's Volatility" - alias: "Heat Pump - Smart Heating Using Period's Volatility"
@ -383,6 +416,8 @@ automation:
temperature: 22 # Boost temperature during cheap period temperature: 22 # Boost temperature during cheap period
``` ```
</details>
**Why this works:** **Why this works:**
- Each detected period has its own `volatility` attribute (`low`, `moderate`, etc.). - 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): Use future average sensors to determine the cheapest upcoming window for a timed appliance (e.g., dishwasher with 2-hour ECO program):
<details>
<summary>Show YAML: Dishwasher — schedule for cheapest 2h window</summary>
```yaml ```yaml
automation: automation:
- alias: "Dishwasher - Schedule for Cheapest 2h Window" - alias: "Dishwasher - Schedule for Cheapest 2h Window"
@ -431,10 +469,15 @@ automation:
{% endif %} {% endif %}
``` ```
</details>
### Use Case: Notify When Cheapest Window Starts ### Use Case: Notify When Cheapest Window Starts
Get a push notification when the best price period begins: Get a push notification when the best price period begins:
<details>
<summary>Show YAML: Notification — when cheap window starts</summary>
```yaml ```yaml
automation: automation:
- alias: "Notify - Cheap Window Started" - alias: "Notify - Cheap Window Started"
@ -455,6 +498,8 @@ automation:
{{ state_attr('sensor.<home_name>_current_electricity_price', 'unit_of_measurement') }}. {{ state_attr('sensor.<home_name>_current_electricity_price', 'unit_of_measurement') }}.
``` ```
</details>
--- ---
## ApexCharts Cards ## ApexCharts Cards

30
docs/user/docs/dashboard-examples.md
View file

@ -42,6 +42,9 @@ cards:
### Price Level Card ### Price Level Card
<details>
<summary>Show YAML: Price level card with color gradients (custom:button-card)</summary>
```yaml ```yaml
type: custom:button-card type: custom:button-card
entity: sensor.<home_name>_current_price_level entity: sensor.<home_name>_current_price_level
@ -60,12 +63,17 @@ styles:
]]] ]]]
``` ```
</details>
## Lovelace Layouts ## Lovelace Layouts
### Compact Mobile View ### Compact Mobile View
Optimized for mobile devices: Optimized for mobile devices:
<details>
<summary>Show YAML: Compact mobile layout</summary>
```yaml ```yaml
type: vertical-stack type: vertical-stack
cards: cards:
@ -84,10 +92,15 @@ cards:
name: Active Now name: Active Now
``` ```
</details>
### Desktop Dashboard ### Desktop Dashboard
Full-width layout for desktop: Full-width layout for desktop:
<details>
<summary>Show YAML: Desktop 3-column grid layout</summary>
```yaml ```yaml
type: grid type: grid
columns: 3 columns: 3
@ -114,10 +127,15 @@ cards:
- sensor.<home_name>_today_s_highest_price - sensor.<home_name>_today_s_highest_price
``` ```
</details>
## Icon Color Integration ## Icon Color Integration
Using the `icon_color` attribute for dynamic colors: Using the `icon_color` attribute for dynamic colors:
<details>
<summary>Show YAML: Dynamic icon colors with mushroom chips</summary>
```yaml ```yaml
type: custom:mushroom-chips-card type: custom:mushroom-chips-card
chips: chips:
@ -134,12 +152,17 @@ chips:
icon_color: red icon_color: red
``` ```
</details>
See [Icon Colors](icon-colors.md) for detailed color mapping. See [Icon Colors](icon-colors.md) for detailed color mapping.
## Picture Elements Dashboard ## Picture Elements Dashboard
Advanced interactive dashboard: Advanced interactive dashboard:
<details>
<summary>Show YAML: Picture elements interactive dashboard</summary>
```yaml ```yaml
type: picture-elements type: picture-elements
image: /local/electricity_dashboard_bg.png image: /local/electricity_dashboard_bg.png
@ -161,10 +184,15 @@ elements:
# Add more elements... # Add more elements...
``` ```
</details>
## Auto-Entities Dynamic Lists ## Auto-Entities Dynamic Lists
Automatically list all price sensors: Automatically list all price sensors:
<details>
<summary>Show YAML: Auto-entities card for all price sensors</summary>
```yaml ```yaml
type: custom:auto-entities type: custom:auto-entities
card: card:
@ -180,6 +208,8 @@ sort:
numeric: true numeric: true
``` ```
</details>
--- ---
💡 **Related:** 💡 **Related:**

40
docs/user/docs/icon-colors.md
View file

@ -137,6 +137,9 @@ styles:
Use Home Assistant's built-in entities card with card_mod for icon and state colors: Use Home Assistant's built-in entities card with card_mod for icon and state colors:
<details>
<summary>Show YAML: Entities card with card_mod</summary>
```yaml ```yaml
type: entities type: entities
entities: entities:
@ -153,6 +156,8 @@ card_mod:
} }
``` ```
</details>
### Method 3: Mushroom Cards ### Method 3: Mushroom Cards
The [Mushroom cards](https://github.com/piitaya/lovelace-mushroom) support card_mod for icon and text colors: 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:** **Icon and state value:**
<details>
<summary>Show YAML: Mushroom card — icon and state value with same color</summary>
```yaml ```yaml
type: custom:mushroom-entity-card type: custom:mushroom-entity-card
entity: sensor.<home_name>_current_price_level entity: sensor.<home_name>_current_price_level
@ -185,10 +193,15 @@ card_mod:
} }
``` ```
</details>
### Method 4: Glance Card with card_mod ### Method 4: Glance Card with card_mod
Combine multiple sensors with dynamic colors: Combine multiple sensors with dynamic colors:
<details>
<summary>Show YAML: Glance card with card_mod for multiple sensors</summary>
```yaml ```yaml
type: glance type: glance
entities: entities:
@ -208,10 +221,15 @@ card_mod:
} }
``` ```
</details>
## Complete Dashboard Example ## Complete Dashboard Example
Here's a complete example combining multiple sensors with dynamic colors: Here's a complete example combining multiple sensors with dynamic colors:
<details>
<summary>Show YAML: Complete dashboard with dynamic colors for all sensor types</summary>
```yaml ```yaml
type: vertical-stack type: vertical-stack
cards: cards:
@ -293,6 +311,8 @@ cards:
]]] ]]]
``` ```
</details>
## CSS Color Variables ## CSS Color Variables
The integration uses Home Assistant's standard CSS variables for theme compatibility: 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** **Example: Custom colors for price level**
<details>
<summary>Show YAML: Price level — 5-color JavaScript mapping</summary>
```yaml ```yaml
type: custom:button-card type: custom:button-card
entity: sensor.<home_name>_current_price_level entity: sensor.<home_name>_current_price_level
@ -351,8 +374,13 @@ styles:
]]] ]]]
``` ```
</details>
**Example: Custom colors for binary sensor** **Example: Custom colors for binary sensor**
<details>
<summary>Show YAML: Binary sensor — on/off color + background highlight</summary>
```yaml ```yaml
type: custom:button-card type: custom:button-card
entity: binary_sensor.<home_name>_best_price_period entity: binary_sensor.<home_name>_best_price_period
@ -373,8 +401,13 @@ styles:
]]] ]]]
``` ```
</details>
**Example: Custom colors for volatility** **Example: Custom colors for volatility**
<details>
<summary>Show YAML: Volatility sensor — 4-level color mapping</summary>
```yaml ```yaml
type: custom:button-card type: custom:button-card
entity: sensor.<home_name>_today_s_price_volatility entity: sensor.<home_name>_today_s_price_volatility
@ -393,8 +426,13 @@ styles:
]]] ]]]
``` ```
</details>
**Example: Custom colors for price rating** **Example: Custom colors for price rating**
<details>
<summary>Show YAML: Price rating — 3-state color mapping</summary>
```yaml ```yaml
type: custom:button-card type: custom:button-card
entity: sensor.<home_name>_current_price_rating entity: sensor.<home_name>_current_price_rating
@ -412,6 +450,8 @@ styles:
]]] ]]]
``` ```
</details>
### Which Approach Should You Use? ### Which Approach Should You Use?
| Use Case | Recommended Approach | | Use Case | Recommended Approach |

15
docs/user/docs/period-calculation.md
View file

@ -583,6 +583,9 @@ Relaxation tried all configured attempts but couldn't reach your target. Options
**Key attributes to check:** **Key attributes to check:**
<details>
<summary>Show YAML: Sensor attribute reference for best_price_period</summary>
```yaml ```yaml
# Entity: binary_sensor.<home_name>_best_price_period # Entity: binary_sensor.<home_name>_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 relaxation_incomplete: true # Some days couldn't reach the configured target
``` ```
</details>
#### What the diagnostic attributes mean #### What the diagnostic attributes mean
**`min_periods_configured` / `periods_found_total`** **`min_periods_configured` / `periods_found_total`**
@ -678,6 +683,9 @@ This is **mathematically correct behavior** caused by how electricity prices are
**Example:** **Example:**
<details>
<summary>Show YAML: How identical prices can flip between best/peak across midnight</summary>
```yaml ```yaml
# Day 1 (low volatility, narrow range) # Day 1 (low volatility, narrow range)
Price range: 18-22 ct/kWh (4 ct span) 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 # - Day 2: Near the middle/top of the range
``` ```
</details>
**When This Occurs:** **When This Occurs:**
- **Low-volatility days:** When price span is narrow (< 5 ct/kWh) - **Low-volatility days:** When price span is narrow (< 5 ct/kWh)
- **Stable weather:** Similar conditions across multiple days - **Stable weather:** Similar conditions across multiple days
@ -719,6 +729,9 @@ sensor.<home_name>_tomorrow_s_price_volatility: 7.9% # Also low
You can make your automations volatility-aware: You can make your automations volatility-aware:
<details>
<summary>Show YAML: 3 automation strategies for volatility-aware period control</summary>
```yaml ```yaml
# Option 1: Only act on high-volatility days # Option 1: Only act on high-volatility days
automation: automation:
@ -767,6 +780,8 @@ automation:
entity_id: switch.ev_charger entity_id: switch.ev_charger
``` ```
</details>
**Available Per-Period Attributes:** **Available Per-Period Attributes:**
Each period sensor exposes day volatility and price statistics: Each period sensor exposes day volatility and price statistics:

35
docs/user/docs/sensors.md
View file

@ -102,6 +102,9 @@ sensor:
Run dishwasher only when price is significantly below the daily typical level: Run dishwasher only when price is significantly below the daily typical level:
<details>
<summary>Show YAML: Automation — start dishwasher when cheap</summary>
```yaml ```yaml
automation: automation:
- alias: "Start Dishwasher When Cheap" - alias: "Start Dishwasher When Cheap"
@ -121,10 +124,15 @@ automation:
entity_id: switch.dishwasher entity_id: switch.dishwasher
``` ```
</details>
**Example 2: Cost-aware heating control** **Example 2: Cost-aware heating control**
Use mean for actual cost calculations: Use mean for actual cost calculations:
<details>
<summary>Show YAML: Automation — cost-aware heating control</summary>
```yaml ```yaml
automation: automation:
- alias: "Heating Budget Control" - alias: "Heating Budget Control"
@ -143,10 +151,15 @@ automation:
message: "Expected cost today: €{{ daily_cost }} (avg price: {{ mean_price }} ct/kWh)" message: "Expected cost today: €{{ daily_cost }} (avg price: {{ mean_price }} ct/kWh)"
``` ```
</details>
**Example 3: Smart charging based on rolling average** **Example 3: Smart charging based on rolling average**
Use trailing average to understand recent price trends: Use trailing average to understand recent price trends:
<details>
<summary>Show YAML: Automation — EV charging based on rolling average</summary>
```yaml ```yaml
automation: automation:
- alias: "EV Charging - Price Trend Based" - alias: "EV Charging - Price Trend Based"
@ -169,6 +182,8 @@ automation:
entity_id: switch.ev_charger entity_id: switch.ev_charger
``` ```
</details>
#### Key Attributes #### Key Attributes
All average sensors provide these 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. 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.
<details>
<summary>Show YAML: Automation — solar export or consume decision</summary>
```yaml ```yaml
# Example: Decide whether to export solar power or consume it # 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) # 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 entity_id: switch.battery_charging # Don't charge battery, export instead
``` ```
</details>
#### Price Composition Analysis #### Price Composition Analysis
Understand how your electricity price is structured — useful for comparing across days or spotting trends in market prices vs. fees: Understand how your electricity price is structured — useful for comparing across days or spotting trends in market prices vs. fees:
<details>
<summary>Show YAML: Template sensor — electricity tax share percentage</summary>
```yaml ```yaml
# Template sensor showing tax share # Template sensor showing tax share
template: template:
@ -531,6 +554,8 @@ template:
{% endif %} {% endif %}
``` ```
</details>
#### Dashboard: Daily Cost Breakdown #### Dashboard: Daily Cost Breakdown
Show users how today's average price splits into energy vs. tax: Show users how today's average price splits into energy vs. tax:
@ -603,6 +628,9 @@ icon: mdi:clock-fast
**Display period progress bar:** **Display period progress bar:**
<details>
<summary>Show YAML: Bar card for period progress</summary>
```yaml ```yaml
type: custom:bar-card type: custom:bar-card
entity: sensor.<home_name>_best_price_progress entity: sensor.<home_name>_best_price_progress
@ -621,8 +649,13 @@ severity:
color: red color: red
``` ```
</details>
**Automation: notify when period is almost over:** **Automation: notify when period is almost over:**
<details>
<summary>Show YAML: Automation — notify when best price period is ending</summary>
```yaml ```yaml
automation: automation:
- alias: "Warn: Best Price Ending Soon" - alias: "Warn: Best Price Ending Soon"
@ -641,6 +674,8 @@ automation:
message: "Only {{ states('sensor.<home_name>_best_price_remaining_minutes') }} minutes left!" message: "Only {{ states('sensor.<home_name>_best_price_remaining_minutes') }} minutes left!"
``` ```
</details>
## Trend Sensors ## Trend Sensors
Trend sensors help you understand **whether to act now or wait**. The integration provides two complementary families: Trend sensors help you understand **whether to act now or wait**. The integration provides two complementary families: