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

docs(actions): restructure into dedicated Actions category

Browse source 
Split monolithic actions.md into focused sub-pages:
- actions.md: lightweight overview with links
- scheduling-actions.md: renamed from scheduling-services.md
- chart-actions.md: get_chartdata + get_apexcharts_yaml
- data-actions.md: get_price + refresh_user_data

New ⚡ Actions sidebar category. Reference keeps only sensor-reference.
Updated cross-references in 6 files.

Impact: Clearer navigation — users find actions by purpose instead of
scrolling a long page. Consistent "actions" terminology (HA standard).
This commit is contained in:
Julian Pawlowski 2026-04-11 19:25:17 +00:00
parent 83ec3910bd
commit 4cc150df6f
23 changed files with 746 additions and 378 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

382
docs/user/docs/actions.md
View file

@ -1,8 +1,8 @@
# Actions (Services) # Actions Overview
Home Assistant now surfaces these backend service endpoints as **Actions** in the UI (for example, Developer Tools → Actions or the Action editor inside dashboards). Behind the scenes they are still Home Assistant services that use the `service:` key, but this guide uses the word “action” whenever we refer to the user interface. Tibber Prices provides **actions** (formerly called "services") that you can use in automations, scripts, and dashboards. Home Assistant surfaces them in **Developer Tools → Actions** and in the automation/script editor.
You can still call them from automations, scripts, and dashboards the same way as before (`service: tibber_prices.get_chartdata`, etc.), just remember that the frontend officially lists them as actions. Behind the scenes, YAML still uses the `service:` key — but the UI calls them "actions".
## Finding Your Config Entry ID ## Finding Your Config Entry ID
@ -28,362 +28,40 @@ The ID looks like a long alphanumeric string, for example `01JKPC7AB3EF4GH5IJ6KL
If you have configured more than one Tibber home, each home has its own config entry ID. Repeat the steps above for each integration card to get the individual IDs. If you have configured more than one Tibber home, each home has its own config entry ID. Repeat the steps above for each integration card to get the individual IDs.
::: :::
## Available Actions ## All Actions at a Glance
### Scheduling Services ### Scheduling Actions
Find the cheapest (or most expensive) time windows for your appliances: Find the cheapest (or most expensive) time windows for your appliances. Ideal for automating when to run devices based on real price data.
| Action | Description | Best For |
|--------|-------------|----------|
| [`find_cheapest_block`](scheduling-actions.md#find-cheapest-block) | Cheapest contiguous window | Dishwasher, washing machine, dryer |
| [`find_cheapest_hours`](scheduling-actions.md#find-cheapest-hours) | Cheapest N hours (non-contiguous OK) | EV charging, battery storage, pool pump |
| [`find_cheapest_schedule`](scheduling-actions.md#find-cheapest-schedule) | Multiple appliances, no overlap | Dishwasher + washing machine overnight |
| [`find_most_expensive_block`](scheduling-actions.md#find-most-expensive-block) | Most expensive contiguous window | Peak avoidance, battery discharge |
| [`find_most_expensive_hours`](scheduling-actions.md#find-most-expensive-hours) | Most expensive N hours | Demand response, consumption shifting |
**→ [Scheduling Actions — Full Guide](scheduling-actions.md)** with parameters, response formats, decision flowchart, and automation examples.
### Chart & Visualization Actions
Generate chart-ready data and ApexCharts configurations for your dashboards.
| Action | Description | | Action | Description |
|--------|-------------| |--------|-------------|
| `find_cheapest_block` | Cheapest contiguous window (dishwasher, dryer) | | [`get_chartdata`](chart-actions.md#tibber_pricesget_chartdata) | Price data in chart-friendly formats (arrays, filtering, rolling windows) |
| `find_cheapest_hours` | Cheapest N hours, non-contiguous OK (EV, battery) | | [`get_apexcharts_yaml`](chart-actions.md#tibber_pricesget_apexcharts_yaml) | Auto-generated ApexCharts card configuration with color-coded price levels |
| `find_cheapest_schedule` | Multiple appliances, no overlap |
| `find_most_expensive_block` | Most expensive contiguous window (peak avoidance) |
| `find_most_expensive_hours` | Most expensive N hours (battery discharge) |
**→ See [Scheduling Services](scheduling-services.md) for full documentation, parameters, response formats, and automation examples.** **→ [Chart & Visualization Actions — Full Guide](chart-actions.md)** with parameters, examples, rolling window modes, and migration guide.
### Data & Chart Services ### Data & Utility Actions
### tibber_prices.get_chartdata Fetch raw price data or refresh cached information.
**Purpose:** Returns electricity price data in chart-friendly formats for visualization and analysis. | Action | Description |
|--------|-------------|
| [`get_price`](data-actions.md#tibber_pricesget_price) | Fetch raw price intervals for any time range (with intelligent caching) |
| [`refresh_user_data`](data-actions.md#tibber_pricesrefresh_user_data) | Force-refresh user data (homes, subscriptions) from Tibber API |
**Key Features:** **→ [Data & Utility Actions — Full Guide](data-actions.md)** with parameters and response formats.
- **Flexible Output Formats**: Array of objects or array of arrays
- **Time Range Selection**: Filter by day (yesterday, today, tomorrow)
- **Price Filtering**: Filter by price level or rating
- **Period Support**: Return best/peak price period summaries instead of intervals
- **Resolution Control**: Interval (15-minute) or hourly aggregation
- **Customizable Field Names**: Rename output fields to match your chart library
- **Currency Control**: Override integration default - use base (€/kWh, kr/kWh) or subunit (ct/kWh, øre/kWh)
**Basic Example:**
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
day: ["today", "tomorrow"]
output_format: array_of_objects
response_variable: chart_data
```
**Response Format:**
```json
{
"data": [
{
"start_time": "2025-11-17T00:00:00+01:00",
"price_per_kwh": 0.2534
},
{
"start_time": "2025-11-17T00:15:00+01:00",
"price_per_kwh": 0.2498
}
]
}
```
**Common Parameters:**
| Parameter | Description | Default |
| ---------------- | ------------------------------------------- | ----------------------- |
| `entry_id` | Config entry ID (optional — auto-selects if only one home) | Auto |
| `day` | Days to include: yesterday, today, tomorrow | `["today", "tomorrow"]` |
| `output_format` | `array_of_objects` or `array_of_arrays` | `array_of_objects` |
| `resolution` | `interval` (15-min) or `hourly` | `interval` |
| `subunit_currency` | Override display mode: `true` for subunit (ct/øre), `false` for base (€/kr) | Integration setting |
| `round_decimals` | Decimal places (0-10) | 2 (subunit) or 4 (base) |
**Rolling Window Mode:**
Omit the `day` parameter to get a dynamic 48-hour rolling window that automatically adapts to data availability:
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
# Omit 'day' for rolling window
output_format: array_of_objects
response_variable: chart_data
```
**Behavior:**
- **When tomorrow data available** (typically after ~13:00): Returns today + tomorrow
- **When tomorrow data not available**: Returns yesterday + today
This is useful for charts that should always show a 48-hour window without manual day selection.
**Period Filter Example:**
Get best price periods as summaries instead of intervals:
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
period_filter: best_price # or peak_price
day: ["today", "tomorrow"]
include_level: true
include_rating_level: true
response_variable: periods
```
**Advanced Filtering:**
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
level_filter: ["VERY_CHEAP", "CHEAP"] # Only cheap periods
rating_level_filter: ["LOW"] # Only low-rated prices
insert_nulls: segments # Add nulls at segment boundaries
```
**Complete Documentation:**
For detailed parameter descriptions, open **Developer Tools → Actions** (the UI label) and select `tibber_prices.get_chartdata`. The inline documentation is still stored in `services.yaml` because actions are backed by services.
#### Energy & Tax Fields in get_chartdata
You can include the raw energy price (spot price) and/or tax component in chart data output. This is useful for visualizing how the total price is composed over time, or for feed-in calculations.
| Parameter | Description | Default |
|-----------|-------------|---------|
| `include_energy` | Include raw energy/spot price per data point | `false` |
| `include_tax` | Include tax/fees component per data point | `false` |
| `energy_field` | Custom field name for energy price | `energy_price` |
| `tax_field` | Custom field name for tax | `tax` |
**Example: Chart with price composition**
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
day: ["today", "tomorrow"]
include_energy: true
include_tax: true
response_variable: chart_data
```
Returns data points like:
```json
{
"start_time": "2025-11-17T14:00:00+01:00",
"price_per_kwh": 25.34,
"energy_price": 12.18,
"tax": 13.16
}
```
**Use case — Solar feed-in chart:** Overlay the energy price (what you earn by exporting) alongside the total price to visualize the best export windows. See [Energy & Tax Attributes](sensors-energy-tax.md) for more use cases.
---
### tibber_prices.get_apexcharts_yaml
> ⚠️ **IMPORTANT:** This action generates a **basic example configuration** as a starting point, NOT a complete solution for all ApexCharts features.
>
> This integration is primarily a **data provider**. The generated YAML demonstrates how to use the `get_chartdata` action to fetch price data. Due to the segmented nature of our data (different time periods per series) and the use of Home Assistant's service API instead of entity attributes, many advanced ApexCharts features (like `in_header`, certain transformations) are **not compatible** or require manual customization.
>
> **You are welcome to customize** the generated YAML for your specific needs, but comprehensive ApexCharts configuration support is beyond the scope of this integration. Community contributions with improved configurations are always appreciated!
>
> **For custom solutions:** Use the `get_chartdata` action directly to build your own charts with full control over the data format and visualization.
**Purpose:** Generates a basic ApexCharts card YAML configuration example for visualizing electricity prices with automatic color-coding by price level.
**Prerequisites:**
- [ApexCharts Card](https://github.com/RomRider/apexcharts-card) (required for all configurations)
- [Config Template Card](https://github.com/iantrich/config-template-card) (required only for rolling window modes - enables dynamic Y-axis scaling)
**✨ Key Features:**
- **Automatic Color-Coded Series**: Separate series for each price level (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE) or rating (LOW, NORMAL, HIGH)
- **Dynamic Y-Axis Scaling**: Rolling window modes automatically use `chart_metadata` sensor for optimal Y-axis bounds
- **Best Price Period Highlights**: Optional vertical bands showing detected best price periods
- **Translated Labels**: Automatically uses your Home Assistant language setting
- **Clean Gap Visualization**: Proper NULL insertion for missing data segments
**Quick Example:**
```yaml
service: tibber_prices.get_apexcharts_yaml
data:
entry_id: YOUR_CONFIG_ENTRY_ID
day: today # Optional: yesterday, today, tomorrow, rolling_window, rolling_window_autozoom
level_type: rating_level # or "level" for 5-level classification
highlight_best_price: true # Show best price period overlays
response_variable: apexcharts_config
```
**Day Parameter Options:**
- **Fixed days** (`yesterday`, `today`, `tomorrow`): Static 24-hour views, no additional dependencies
- **Rolling Window** (default when omitted or `rolling_window`): Dynamic 48-hour window that automatically shifts between yesterday+today and today+tomorrow based on data availability
- **✨ Includes dynamic Y-axis scaling** via `chart_metadata` sensor
- **Rolling Window (Auto-Zoom)** (`rolling_window_autozoom`): Same as rolling window, but additionally zooms in progressively (2h lookback + remaining time until midnight, graph span decreases every 15 minutes)
- **✨ Includes dynamic Y-axis scaling** via `chart_metadata` sensor
**Dynamic Y-Axis Scaling (Rolling Window Modes):**
Rolling window configurations automatically integrate with the `chart_metadata` sensor for optimal chart appearance:
- **Automatic bounds**: Y-axis min/max adjust to data range
- **No manual configuration**: Works out of the box if sensor is enabled
- **Fallback behavior**: If sensor is disabled, uses ApexCharts auto-scaling
- **Real-time updates**: Y-axis adapts when price data changes
**Example: Today's Prices (Static View)**
```yaml
service: tibber_prices.get_apexcharts_yaml
data:
entry_id: YOUR_CONFIG_ENTRY_ID
day: today
level_type: rating_level
response_variable: config
# Use in dashboard:
type: custom:apexcharts-card
# ... paste generated config
```
**Example: Rolling 48h Window (Dynamic View)**
```yaml
service: tibber_prices.get_apexcharts_yaml
data:
entry_id: YOUR_CONFIG_ENTRY_ID
# Omit 'day' for rolling window (or use 'rolling_window')
level_type: level # 5-level classification
highlight_best_price: true
response_variable: config
# Use in dashboard:
type: custom:config-template-card
entities:
- binary_sensor.<home_name>_tomorrow_s_data_available
- sensor.<home_name>_chart_metadata # For dynamic Y-axis
card:
# ... paste generated config
```
**Screenshots:**
_Screenshots coming soon for all 4 modes: today, tomorrow, rolling_window, rolling_window_autozoom_
**Level Type Options:**
- **`rating_level`** (default): 3 series (LOW, NORMAL, HIGH) - based on your personal thresholds
- **`level`**: 5 series (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE) - absolute price ranges
**Best Price Period Highlights:**
When `highlight_best_price: true`:
- Vertical bands overlay the chart showing detected best price periods
- Tooltip shows "Best Price Period" label when hovering over highlighted areas
- Only appears when best price periods are configured and detected
**Important Notes:**
- **Config Template Card** is only required for rolling window modes (enables dynamic Y-axis)
- Fixed day views (`today`, `tomorrow`, `yesterday`) work with ApexCharts Card alone
- Generated YAML is a starting point - customize colors, styling, features as needed
- All labels are automatically translated to your Home Assistant language
Use the response in Lovelace dashboards by copying the generated YAML.
**Documentation:** Refer to **Developer Tools → Actions** for descriptions of the fields exposed by this action.
---
### tibber_prices.refresh_user_data
**Purpose:** Forces an immediate refresh of user data (homes, subscriptions) from the Tibber API.
**Example:**
```yaml
service: tibber_prices.refresh_user_data
data:
entry_id: YOUR_CONFIG_ENTRY_ID
```
**Note:** User data is cached for 24 hours. Trigger this action only when you need immediate updates (e.g., after changing Tibber subscriptions).
---
### tibber_prices.get_price
**Purpose:** Fetches raw price interval data for any time range. Uses intelligent caching — only intervals not already cached are fetched from the Tibber API.
**Parameters:**
| Parameter | Description | Required |
|-----------|-------------|----------|
| `entry_id` | Config entry ID | Yes |
| `start_time` | Start of the time range | Yes |
| `end_time` | End of the time range | Yes |
**Example:**
```yaml
service: tibber_prices.get_price
data:
entry_id: YOUR_CONFIG_ENTRY_ID
start_time: "2025-11-01T00:00:00"
end_time: "2025-11-02T00:00:00"
response_variable: price_data
```
**Response Format:**
```json
{
"home_id": "abc-123",
"start_time": "2025-11-01T00:00:00+01:00",
"end_time": "2025-11-02T00:00:00+01:00",
"interval_count": 96,
"price_info": [
{
"startsAt": "2025-11-01T00:00:00+01:00",
"total": 0.2534,
"energy": 0.1218,
"tax": 0.1316
}
]
}
```
**Use cases:**
- Fetching historical price data for analysis
- Comparing prices across arbitrary date ranges
- Building custom charts with historical data
**Note:** Times are automatically converted to your Tibber home's timezone. The interval pool caches previously fetched intervals, so repeated calls for the same range are fast.
---
## Migration from Chart Data Export Sensor
If you're still using the `sensor.<home_name>_chart_data_export` sensor, consider migrating to the `tibber_prices.get_chartdata` action:
**Benefits:**
- No HA restart required for configuration changes
- More flexible filtering and formatting options
- Better performance (on-demand instead of polling)
- Future-proof (active development)
**Migration Steps:**
1. Note your current sensor configuration (Step 7 in Options Flow)
2. Create automation/script that calls `tibber_prices.get_chartdata` with the same parameters
3. Test the new approach
4. Disable the old sensor when satisfied

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

@ -7,7 +7,7 @@
- [Price-Based Automations](#price-based-automations) - [Price-Based Automations](#price-based-automations)
- [Volatility-Aware Automations](#volatility-aware-automations) - [Volatility-Aware Automations](#volatility-aware-automations)
- [Best Hour Detection](#best-hour-detection) - [Best Hour Detection](#best-hour-detection)
- [Scheduling Services](#scheduling-services) - [Scheduling Actions](#scheduling-actions)
- [Charts & Visualizations](#charts--visualizations) - [Charts & Visualizations](#charts--visualizations)
--- ---
@ -20,7 +20,9 @@
> >
> These examples provide a good starting point but must be tailored to your individual Home Assistant setup. > These examples provide a good starting point but must be tailored to your individual Home Assistant setup.
> >
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
## Price-Based Automations ## Price-Based Automations
@ -503,9 +505,9 @@ automation:
--- ---
## Scheduling Services ## Scheduling Actions
> **Looking for service-based scheduling?** The **[Scheduling Services Guide](scheduling-services.md)** covers `find_cheapest_block`, `find_cheapest_hours`, `find_cheapest_schedule`, and their "most expensive" counterparts — ideal for automations that need to find optimal time windows dynamically (e.g., EV charging, heat pump scheduling, appliance timing). > **Looking for scheduling actions?** The **[Scheduling Actions Guide](scheduling-actions.md)** covers `find_cheapest_block`, `find_cheapest_hours`, `find_cheapest_schedule`, and their "most expensive" counterparts — ideal for automations that need to find optimal time windows dynamically (e.g., EV charging, heat pump scheduling, appliance timing).
--- ---

310
docs/user/docs/chart-actions.md Normal file
View file

@ -0,0 +1,310 @@
# Chart & Visualization Actions
Actions for generating chart data and ApexCharts configurations from your Tibber price data.
:::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
---
## tibber_prices.get_chartdata
**Purpose:** Returns electricity price data in chart-friendly formats for visualization and analysis.
**Key Features:**
- **Flexible Output Formats**: Array of objects or array of arrays
- **Time Range Selection**: Filter by day (yesterday, today, tomorrow)
- **Price Filtering**: Filter by price level or rating
- **Period Support**: Return best/peak price period summaries instead of intervals
- **Resolution Control**: Interval (15-minute) or hourly aggregation
- **Customizable Field Names**: Rename output fields to match your chart library
- **Currency Control**: Override integration default - use base (€/kWh, kr/kWh) or subunit (ct/kWh, øre/kWh)
**Basic Example:**
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
day: ["today", "tomorrow"]
output_format: array_of_objects
response_variable: chart_data
```
**Response Format:**
```json
{
"data": [
{
"start_time": "2025-11-17T00:00:00+01:00",
"price_per_kwh": 0.2534
},
{
"start_time": "2025-11-17T00:15:00+01:00",
"price_per_kwh": 0.2498
}
]
}
```
**Common Parameters:**
| Parameter | Description | Default |
| ---------------- | ------------------------------------------- | ----------------------- |
| `entry_id` | Config entry ID (optional — auto-selects if only one home) | Auto |
| `day` | Days to include: yesterday, today, tomorrow | `["today", "tomorrow"]` |
| `output_format` | `array_of_objects` or `array_of_arrays` | `array_of_objects` |
| `resolution` | `interval` (15-min) or `hourly` | `interval` |
| `subunit_currency` | Override display mode: `true` for subunit (ct/øre), `false` for base (€/kr) | Integration setting |
| `round_decimals` | Decimal places (0-10) | 2 (subunit) or 4 (base) |
**Rolling Window Mode:**
Omit the `day` parameter to get a dynamic 48-hour rolling window that automatically adapts to data availability:
<details>
<summary>Show YAML example (rolling window mode)</summary>
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
# Omit 'day' for rolling window
output_format: array_of_objects
response_variable: chart_data
```
</details>
**Behavior:**
- **When tomorrow data available** (typically after ~13:00): Returns today + tomorrow
- **When tomorrow data not available**: Returns yesterday + today
This is useful for charts that should always show a 48-hour window without manual day selection.
**Period Filter Example:**
Get best price periods as summaries instead of intervals:
<details>
<summary>Show YAML example (period filter)</summary>
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
period_filter: best_price # or peak_price
day: ["today", "tomorrow"]
include_level: true
include_rating_level: true
response_variable: periods
```
</details>
**Advanced Filtering:**
<details>
<summary>Show YAML example (advanced filtering)</summary>
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
level_filter: ["VERY_CHEAP", "CHEAP"] # Only cheap periods
rating_level_filter: ["LOW"] # Only low-rated prices
insert_nulls: segments # Add nulls at segment boundaries
```
</details>
**Complete Documentation:**
For detailed parameter descriptions, open **Developer Tools → Actions** and select `tibber_prices.get_chartdata`. The inline documentation is stored in `services.yaml` because actions are backed by services.
### Energy & Tax Fields
You can include the raw energy price (spot price) and/or tax component in chart data output. This is useful for visualizing how the total price is composed over time, or for feed-in calculations.
| Parameter | Description | Default |
|-----------|-------------|---------|
| `include_energy` | Include raw energy/spot price per data point | `false` |
| `include_tax` | Include tax/fees component per data point | `false` |
| `energy_field` | Custom field name for energy price | `energy_price` |
| `tax_field` | Custom field name for tax | `tax` |
**Example: Chart with price composition**
<details>
<summary>Show YAML example (include energy and tax fields)</summary>
```yaml
service: tibber_prices.get_chartdata
data:
entry_id: YOUR_CONFIG_ENTRY_ID
day: ["today", "tomorrow"]
include_energy: true
include_tax: true
response_variable: chart_data
```
</details>
Returns data points like:
```json
{
"start_time": "2025-11-17T14:00:00+01:00",
"price_per_kwh": 25.34,
"energy_price": 12.18,
"tax": 13.16
}
```
**Use case — Solar feed-in chart:** Overlay the energy price (what you earn by exporting) alongside the total price to visualize the best export windows. See [Energy & Tax Attributes](sensors-energy-tax.md) for more use cases.
---
## tibber_prices.get_apexcharts_yaml
> ⚠️ **IMPORTANT:** This action generates a **basic example configuration** as a starting point, NOT a complete solution for all ApexCharts features.
>
> This integration is primarily a **data provider**. The generated YAML demonstrates how to use the `get_chartdata` action to fetch price data. Due to the segmented nature of our data (different time periods per series) and the use of Home Assistant's service API instead of entity attributes, many advanced ApexCharts features (like `in_header`, certain transformations) are **not compatible** or require manual customization.
>
> **You are welcome to customize** the generated YAML for your specific needs, but comprehensive ApexCharts configuration support is beyond the scope of this integration. Community contributions with improved configurations are always appreciated!
>
> **For custom solutions:** Use the `get_chartdata` action directly to build your own charts with full control over the data format and visualization.
**Purpose:** Generates a basic ApexCharts card YAML configuration example for visualizing electricity prices with automatic color-coding by price level.
**Prerequisites:**
- [ApexCharts Card](https://github.com/RomRider/apexcharts-card) (required for all configurations)
- [Config Template Card](https://github.com/iantrich/config-template-card) (required only for rolling window modes - enables dynamic Y-axis scaling)
**Key Features:**
- **Automatic Color-Coded Series**: Separate series for each price level (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE) or rating (LOW, NORMAL, HIGH)
- **Dynamic Y-Axis Scaling**: Rolling window modes automatically use `chart_metadata` sensor for optimal Y-axis bounds
- **Best Price Period Highlights**: Optional vertical bands showing detected best price periods
- **Translated Labels**: Automatically uses your Home Assistant language setting
- **Clean Gap Visualization**: Proper NULL insertion for missing data segments
**Quick Example:**
```yaml
service: tibber_prices.get_apexcharts_yaml
data:
entry_id: YOUR_CONFIG_ENTRY_ID
day: today # Optional: yesterday, today, tomorrow, rolling_window, rolling_window_autozoom
level_type: rating_level # or "level" for 5-level classification
highlight_best_price: true # Show best price period overlays
response_variable: apexcharts_config
```
**Day Parameter Options:**
- **Fixed days** (`yesterday`, `today`, `tomorrow`): Static 24-hour views, no additional dependencies
- **Rolling Window** (default when omitted or `rolling_window`): Dynamic 48-hour window that automatically shifts between yesterday+today and today+tomorrow based on data availability
- **Includes dynamic Y-axis scaling** via `chart_metadata` sensor
- **Rolling Window (Auto-Zoom)** (`rolling_window_autozoom`): Same as rolling window, but additionally zooms in progressively (2h lookback + remaining time until midnight, graph span decreases every 15 minutes)
- **Includes dynamic Y-axis scaling** via `chart_metadata` sensor
**Dynamic Y-Axis Scaling (Rolling Window Modes):**
Rolling window configurations automatically integrate with the `chart_metadata` sensor for optimal chart appearance:
- **Automatic bounds**: Y-axis min/max adjust to data range
- **No manual configuration**: Works out of the box if sensor is enabled
- **Fallback behavior**: If sensor is disabled, uses ApexCharts auto-scaling
- **Real-time updates**: Y-axis adapts when price data changes
**Example: Today's Prices (Static View)**
<details>
<summary>Show YAML example (today, static view)</summary>
```yaml
service: tibber_prices.get_apexcharts_yaml
data:
entry_id: YOUR_CONFIG_ENTRY_ID
day: today
level_type: rating_level
response_variable: config
# Use in dashboard:
type: custom:apexcharts-card
# ... paste generated config
```
</details>
**Example: Rolling 48h Window (Dynamic View)**
<details>
<summary>Show YAML example (rolling 48h dynamic view)</summary>
```yaml
service: tibber_prices.get_apexcharts_yaml
data:
entry_id: YOUR_CONFIG_ENTRY_ID
# Omit 'day' for rolling window (or use 'rolling_window')
level_type: level # 5-level classification
highlight_best_price: true
response_variable: config
# Use in dashboard:
type: custom:config-template-card
entities:
- binary_sensor.<home_name>_tomorrow_s_data_available
- sensor.<home_name>_chart_metadata # For dynamic Y-axis
card:
# ... paste generated config
```
</details>
**Level Type Options:**
- **`rating_level`** (default): 3 series (LOW, NORMAL, HIGH) - based on your personal thresholds
- **`level`**: 5 series (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE) - absolute price ranges
**Best Price Period Highlights:**
When `highlight_best_price: true`:
- Vertical bands overlay the chart showing detected best price periods
- Tooltip shows "Best Price Period" label when hovering over highlighted areas
- Only appears when best price periods are configured and detected
**Important Notes:**
- **Config Template Card** is only required for rolling window modes (enables dynamic Y-axis)
- Fixed day views (`today`, `tomorrow`, `yesterday`) work with ApexCharts Card alone
- Generated YAML is a starting point - customize colors, styling, features as needed
- All labels are automatically translated to your Home Assistant language
Use the response in Lovelace dashboards by copying the generated YAML.
**Documentation:** Refer to **Developer Tools → Actions** for descriptions of the fields exposed by this action.
---
## Migration from Chart Data Export Sensor
If you're still using the `sensor.<home_name>_chart_data_export` sensor, consider migrating to the `tibber_prices.get_chartdata` action:
**Benefits:**
- No HA restart required for configuration changes
- More flexible filtering and formatting options
- Better performance (on-demand instead of polling)
- Future-proof (active development)
**Migration Steps:**
1. Note your current sensor configuration (Step 7 in Options Flow)
2. Create automation/script that calls `tibber_prices.get_chartdata` with the same parameters
3. Test the new approach
4. Disable the old sensor when satisfied

31
docs/user/docs/chart-examples.md
View file

@ -4,7 +4,9 @@ This guide showcases the different chart configurations available through the `t
> **Quick Start:** Call the action with your desired parameters, copy the generated YAML, and paste it into your Lovelace dashboard! > **Quick Start:** Call the action with your desired parameters, copy the generated YAML, and paste it into your Lovelace dashboard!
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
:::info Finding your Entry ID (`entry_id`) :::info Finding your Entry ID (`entry_id`)
Every example below contains `entry_id: YOUR_CONFIG_ENTRY_ID`. This value identifies which Tibber home (integration instance) the action targets. Every example below contains `entry_id: YOUR_CONFIG_ENTRY_ID`. This value identifies which Tibber home (integration instance) the action targets.
@ -69,6 +71,9 @@ data:
**Dependencies:** ApexCharts Card + Config Template Card **Dependencies:** ApexCharts Card + Config Template Card
**Generate:** **Generate:**
<details>
<summary>Show YAML example (generate rolling 48h window)</summary>
```yaml ```yaml
service: tibber_prices.get_apexcharts_yaml service: tibber_prices.get_apexcharts_yaml
data: data:
@ -78,6 +83,8 @@ data:
highlight_best_price: true highlight_best_price: true
``` ```
</details>
**Screenshot:** **Screenshot:**
![Rolling 48h Window with Dynamic Y-Axis Scaling](/img/charts/rolling-window.jpg) ![Rolling 48h Window with Dynamic Y-Axis Scaling](/img/charts/rolling-window.jpg)
@ -103,6 +110,9 @@ data:
**Dependencies:** ApexCharts Card + Config Template Card **Dependencies:** ApexCharts Card + Config Template Card
**Generate:** **Generate:**
<details>
<summary>Show YAML example (generate rolling auto-zoom)</summary>
```yaml ```yaml
service: tibber_prices.get_apexcharts_yaml service: tibber_prices.get_apexcharts_yaml
data: data:
@ -112,6 +122,8 @@ data:
highlight_best_price: true highlight_best_price: true
``` ```
</details>
**Screenshot:** **Screenshot:**
![Rolling Window Auto-Zoom - Progressive Zoom Effect](/img/charts/rolling-window-autozoom.jpg) ![Rolling Window Auto-Zoom - Progressive Zoom Effect](/img/charts/rolling-window-autozoom.jpg)
@ -250,6 +262,9 @@ Price
Edit the `colors` array in the generated YAML: Edit the `colors` array in the generated YAML:
<details>
<summary>Show YAML example (custom color palette)</summary>
```yaml ```yaml
apex_config: apex_config:
colors: colors:
@ -258,10 +273,15 @@ apex_config:
- "#FF0000" # Change HIGH/VERY_EXPENSIVE color - "#FF0000" # Change HIGH/VERY_EXPENSIVE color
``` ```
</details>
### Changing Chart Height ### Changing Chart Height
Add to the card configuration: Add to the card configuration:
<details>
<summary>Show YAML example (custom chart height)</summary>
```yaml ```yaml
type: custom:apexcharts-card type: custom:apexcharts-card
graph_span: 48h graph_span: 48h
@ -273,10 +293,15 @@ apex_config:
height: 400 # Adjust height in pixels height: 400 # Adjust height in pixels
``` ```
</details>
### Combining with Other Cards ### Combining with Other Cards
Wrap in a vertical stack for dashboard integration: Wrap in a vertical stack for dashboard integration:
<details>
<summary>Show YAML example (vertical stack integration)</summary>
```yaml ```yaml
type: vertical-stack type: vertical-stack
cards: cards:
@ -286,11 +311,13 @@ cards:
# ... generated chart config # ... generated chart config
``` ```
</details>
--- ---
## Next Steps ## Next Steps
- **[Actions Guide](actions.md)**: Complete documentation of `get_apexcharts_yaml` parameters - **[Chart Actions Guide](chart-actions.md)**: Complete documentation of `get_apexcharts_yaml` parameters
- **[Chart Metadata Sensor](sensors-overview.md#chart-metadata)**: Learn about dynamic Y-axis scaling - **[Chart Metadata Sensor](sensors-overview.md#chart-metadata)**: Learn about dynamic Y-axis scaling
- **[Period Calculation Guide](period-calculation.md)**: Configure best price period detection - **[Period Calculation Guide](period-calculation.md)**: Configure best price period detection

21
docs/user/docs/configuration.md
View file

@ -1,6 +1,8 @@
# Configuration # Configuration
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
## Initial Setup ## Initial Setup
@ -125,7 +127,7 @@ Thresholds are [volatility-adaptive](sensors-trends.md): automatically widened o
### Step 9: Chart Data Export (Legacy) ### Step 9: Chart Data Export (Legacy)
Information page for the legacy chart data export sensor. For new setups, use the [get_chartdata action](actions.md) instead. Information page for the legacy chart data export sensor. For new setups, use the [get_chartdata action](chart-actions.md) instead.
## Configuration Options ## Configuration Options
@ -165,12 +167,17 @@ The median tells you the price was **typically** around 13 ct/kWh (4 out of 5 ho
**Both values are always available as attributes**, regardless of your display choice: **Both values are always available as attributes**, regardless of your display choice:
<details>
<summary>Show YAML example (median and mean attributes)</summary>
```yaml ```yaml
# These attributes work regardless of display setting: # These attributes work regardless of display setting:
{{ state_attr('sensor.<home_name>_price_today', 'price_median') }} {{ state_attr('sensor.<home_name>_price_today', 'price_median') }}
{{ state_attr('sensor.<home_name>_price_today', 'price_mean') }} {{ state_attr('sensor.<home_name>_price_today', 'price_mean') }}
``` ```
</details>
This means: This means:
- ✅ You can change the display anytime without breaking automations - ✅ You can change the display anytime without breaking automations
- ✅ Automations can use both values for different purposes - ✅ Automations can use both values for different purposes
@ -255,6 +262,9 @@ Each configuration entity includes a detailed description attribute explaining w
### Example: Seasonal Automation ### Example: Seasonal Automation
<details>
<summary>Show YAML example (seasonal runtime override)</summary>
```yaml ```yaml
automation: automation:
- alias: "Winter: Stricter Best Price Detection" - alias: "Winter: Stricter Best Price Detection"
@ -272,6 +282,8 @@ automation:
value: 10 # Stricter than default 15% value: 10 # Stricter than default 15%
``` ```
</details>
### Recorder Optimization (Optional) ### Recorder Optimization (Optional)
These configuration entities are designed to minimize database impact: These configuration entities are designed to minimize database impact:
@ -283,6 +295,9 @@ If you frequently adjust these settings via automations or want to track configu
However, if you prefer to **completely exclude** these entities from the recorder (no history graph, no database entries), add this to your `configuration.yaml`: However, if you prefer to **completely exclude** these entities from the recorder (no history graph, no database entries), add this to your `configuration.yaml`:
<details>
<summary>Show YAML example (exclude runtime config entities from recorder)</summary>
```yaml ```yaml
recorder: recorder:
exclude: exclude:
@ -294,6 +309,8 @@ recorder:
- switch.*_peak_price_* - switch.*_peak_price_*
``` ```
</details>
This is especially useful if: This is especially useful if:
- You rarely change these settings - You rarely change these settings
- You want the smallest possible database footprint - You want the smallest possible database footprint

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

@ -2,7 +2,9 @@
Beautiful dashboard layouts using Tibber Prices sensors. Beautiful dashboard layouts using Tibber Prices sensors.
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
## Basic Price Display Card ## Basic Price Display Card

80
docs/user/docs/data-actions.md Normal file
View file

@ -0,0 +1,80 @@
# Data & Utility Actions
Actions for fetching raw price data and managing integration state.
---
## tibber_prices.get_price
**Purpose:** Fetches raw price interval data for any time range. Uses intelligent caching — only intervals not already cached are fetched from the Tibber API.
**Parameters:**
| Parameter | Description | Required |
|-----------|-------------|----------|
| `entry_id` | Config entry ID | Yes |
| `start_time` | Start of the time range | Yes |
| `end_time` | End of the time range | Yes |
**Example:**
<details>
<summary>Show YAML example (get_price)</summary>
```yaml
service: tibber_prices.get_price
data:
entry_id: YOUR_CONFIG_ENTRY_ID
start_time: "2025-11-01T00:00:00"
end_time: "2025-11-02T00:00:00"
response_variable: price_data
```
</details>
**Response Format:**
```json
{
"home_id": "abc-123",
"start_time": "2025-11-01T00:00:00+01:00",
"end_time": "2025-11-02T00:00:00+01:00",
"interval_count": 96,
"price_info": [
{
"startsAt": "2025-11-01T00:00:00+01:00",
"total": 0.2534,
"energy": 0.1218,
"tax": 0.1316
}
]
}
```
**Use cases:**
- Fetching historical price data for analysis
- Comparing prices across arbitrary date ranges
- Building custom charts with historical data
**Note:** Times are automatically converted to your Tibber home's timezone. The interval pool caches previously fetched intervals, so repeated calls for the same range are fast.
---
## tibber_prices.refresh_user_data
**Purpose:** Forces an immediate refresh of user data (homes, subscriptions) from the Tibber API.
**Example:**
<details>
<summary>Show YAML example (refresh_user_data)</summary>
```yaml
service: tibber_prices.refresh_user_data
data:
entry_id: YOUR_CONFIG_ENTRY_ID
```
</details>
**Note:** User data is cached for 24 hours. Trigger this action only when you need immediate updates (e.g., after changing Tibber subscriptions).

34
docs/user/docs/dynamic-icons.md
View file

@ -2,7 +2,9 @@
Many sensors in the Tibber Prices integration automatically change their icon based on their current state. This provides instant visual feedback about price levels, trends, and periods without needing to read the actual values. Many sensors in the Tibber Prices integration automatically change their icon based on their current state. This provides instant visual feedback about price levels, trends, and periods without needing to read the actual values.
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
## What are Dynamic Icons? ## What are Dynamic Icons?
@ -50,6 +52,9 @@ The icons will update automatically as the sensor states change.
### Glance Card ### Glance Card
<details>
<summary>Show YAML example (Glance card)</summary>
```yaml ```yaml
type: glance type: glance
entities: entities:
@ -61,8 +66,13 @@ entities:
name: Best Price name: Best Price
``` ```
</details>
### Custom Button Card ### Custom Button Card
<details>
<summary>Show YAML example (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
@ -71,8 +81,13 @@ show_state: true
# Icon updates automatically - no need to specify it! # Icon updates automatically - no need to specify it!
``` ```
</details>
### Mushroom Entity Card ### Mushroom Entity Card
<details>
<summary>Show YAML example (Mushroom entity card)</summary>
```yaml ```yaml
type: custom:mushroom-entity-card type: custom:mushroom-entity-card
entity: sensor.<home_name>_today_s_price_volatility entity: sensor.<home_name>_today_s_price_volatility
@ -80,12 +95,17 @@ name: Price Volatility
# Icon changes automatically based on volatility level # Icon changes automatically based on volatility level
``` ```
</details>
## Overriding Dynamic Icons ## Overriding Dynamic Icons
If you want to use a fixed icon instead of the dynamic one: If you want to use a fixed icon instead of the dynamic one:
### In Entity Cards ### In Entity Cards
<details>
<summary>Show YAML example (fixed icon in entity card)</summary>
```yaml ```yaml
type: entities type: entities
entities: entities:
@ -93,8 +113,13 @@ entities:
icon: mdi:lightning-bolt # Fixed icon, won't change icon: mdi:lightning-bolt # Fixed icon, won't change
``` ```
</details>
### In Custom Button Card ### In Custom Button Card
<details>
<summary>Show YAML example (fixed icon in button card)</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
@ -103,12 +128,17 @@ icon: mdi:chart-line # Fixed icon overrides dynamic behavior
show_state: true show_state: true
``` ```
</details>
## Combining with Dynamic Colors ## Combining with Dynamic Colors
Dynamic icons work great together with dynamic colors! See the **[Dynamic Icon Colors Guide](icon-colors.md)** for examples. Dynamic icons work great together with dynamic colors! See the **[Dynamic Icon Colors Guide](icon-colors.md)** for examples.
**Example: Dynamic icon AND color** **Example: Dynamic icon AND color**
<details>
<summary>Show YAML example (dynamic icon + dynamic color)</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
@ -123,6 +153,8 @@ styles:
]]] ]]]
``` ```
</details>
This gives you both: This gives you both:
- ✅ Different icon based on state (e.g., cash-plus when cheap, cash-remove when expensive) - ✅ Different icon based on state (e.g., cash-plus when cheap, cash-remove when expensive)

4
docs/user/docs/faq.md
View file

@ -112,7 +112,9 @@ If you see unexpected units, check your configuration in the integration options
## Automation Questions ## Automation Questions
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
### How do I run dishwasher during cheap period? ### How do I run dishwasher during cheap period?

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

@ -10,7 +10,9 @@ Many sensors in the Tibber Prices integration provide an `icon_color` attribute
> **Related:** Many sensors also automatically change their **icon** based on state. See the **[Dynamic Icons Guide](dynamic-icons.md)** for details. > **Related:** Many sensors also automatically change their **icon** based on state. See the **[Dynamic Icons Guide](dynamic-icons.md)** for details.
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
## What is icon_color? ## What is icon_color?
@ -65,6 +67,9 @@ The colors adapt to the sensor's state - cheaper prices typically show green, ex
**Example of when NOT to use icon_color:** **Example of when NOT to use icon_color:**
<details>
<summary>Show YAML comparison (complex conversion vs direct state logic)</summary>
```yaml ```yaml
# ❌ DON'T: Converting icon_color requires if/else anyway # ❌ DON'T: Converting icon_color requires if/else anyway
card: card:
@ -87,6 +92,8 @@ card:
]]] ]]]
``` ```
</details>
The advantage of `icon_color` is simplicity - if you need complex logic, you lose that advantage. The advantage of `icon_color` is simplicity - if you need complex logic, you lose that advantage.
## How to Use icon_color in Your Dashboard ## How to Use icon_color in Your Dashboard
@ -113,6 +120,9 @@ styles:
**Example: Icon AND state value with same color** **Example: Icon AND state value with same color**
<details>
<summary>Show YAML example (button-card icon + state text in same color)</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
@ -133,6 +143,8 @@ styles:
- font-weight: bold - font-weight: bold
``` ```
</details>
### Method 2: Entities Card with card_mod ### Method 2: Entities Card with card_mod
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:
@ -164,6 +176,9 @@ The [Mushroom cards](https://github.com/piitaya/lovelace-mushroom) support card_
**Icon color only:** **Icon color only:**
<details>
<summary>Show YAML example (Mushroom icon color only)</summary>
```yaml ```yaml
type: custom:mushroom-entity-card type: custom:mushroom-entity-card
entity: binary_sensor.<home_name>_best_price_period entity: binary_sensor.<home_name>_best_price_period
@ -176,6 +191,8 @@ card_mod:
} }
``` ```
</details>
**Icon and state value:** **Icon and state value:**
<details> <details>
@ -334,6 +351,9 @@ If you want to override the theme colors with your own, you have two options:
Define custom colors in your theme configuration (`themes.yaml`): Define custom colors in your theme configuration (`themes.yaml`):
<details>
<summary>Show YAML example (theme-level color overrides)</summary>
```yaml ```yaml
my_custom_theme: my_custom_theme:
# Override standard variables # Override standard variables
@ -343,6 +363,8 @@ my_custom_theme:
info-color: "#0288D1" # Custom blue info-color: "#0288D1" # Custom blue
``` ```
</details>
The `icon_color` attribute will automatically use your custom theme colors. The `icon_color` attribute will automatically use your custom theme colors.
#### Option 2: Interpret State Value Directly #### Option 2: Interpret State Value Directly

2
docs/user/docs/intro.md
View file

@ -18,7 +18,7 @@ This is an independent, community-maintained custom integration. It is **not** a
- **[Sensors](sensors-overview.md)** - Available sensors, their states, and attributes - **[Sensors](sensors-overview.md)** - Available sensors, their states, and attributes
- **[Dynamic Icons](dynamic-icons.md)** - State-based automatic icon changes - **[Dynamic Icons](dynamic-icons.md)** - State-based automatic icon changes
- **[Dynamic Icon Colors](icon-colors.md)** - Using icon_color attribute for color-coded dashboards - **[Dynamic Icon Colors](icon-colors.md)** - Using icon_color attribute for color-coded dashboards
- **[Actions](actions.md)** - Custom actions (service endpoints) and how to use them - **[Actions](actions.md)** - Scheduling, chart, and data actions for automations and dashboards
- **[Chart Examples](chart-examples.md)** - ✨ ApexCharts visualizations with screenshots - **[Chart Examples](chart-examples.md)** - ✨ ApexCharts visualizations with screenshots
- **[Automation Examples](automation-examples.md)** - Ready-to-use automation recipes - **[Automation Examples](automation-examples.md)** - Ready-to-use automation recipes
- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions - **[Troubleshooting](troubleshooting.md)** - Common issues and solutions

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

@ -2,7 +2,9 @@
Learn how Best Price and Peak Price periods work, and how to configure them for your needs. Learn how Best Price and Peak Price periods work, and how to configure them for your needs.
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
## Table of Contents ## Table of Contents
@ -262,11 +264,16 @@ peak_price_min_distance_from_avg: 5
**Default:** `any` (disabled) **Default:** `any` (disabled)
**Options:** `any` | `cheap` | `very_cheap` (Best Price) | `expensive` | `very_expensive` (Peak Price) **Options:** `any` | `cheap` | `very_cheap` (Best Price) | `expensive` | `very_expensive` (Peak Price)
<details>
<summary>Show YAML example (level filter)</summary>
```yaml ```yaml
best_price_max_level: any # Show any period below average best_price_max_level: any # Show any period below average
best_price_max_level: cheap # Only show if at least one interval is CHEAP best_price_max_level: cheap # Only show if at least one interval is CHEAP
``` ```
</details>
**Use case:** "Only notify me when prices are objectively cheap/expensive" **Use case:** "Only notify me when prices are objectively cheap/expensive"
**ℹ️ Volatility Thresholds:** The level filter also supports volatility-based levels (`volatility_low`, `volatility_medium`, `volatility_high`). These use **fixed internal thresholds** (LOW < 10%, MEDIUM < 20%, HIGH ≥ 20%) that are separate from the sensor volatility thresholds you configure in the UI. This separation ensures that changing sensor display preferences doesn't affect period calculation behavior. **ℹ️ Volatility Thresholds:** The level filter also supports volatility-based levels (`volatility_low`, `volatility_medium`, `volatility_high`). These use **fixed internal thresholds** (LOW < 10%, MEDIUM < 20%, HIGH ≥ 20%) that are separate from the sensor volatility thresholds you configure in the UI. This separation ensures that changing sensor display preferences doesn't affect period calculation behavior.
@ -277,11 +284,16 @@ best_price_max_level: cheap # Only show if at least one interval is CHEAP
**Default:** 0 (strict) **Default:** 0 (strict)
**Range:** 0-10 **Range:** 0-10
<details>
<summary>Show YAML example (gap tolerance)</summary>
```yaml ```yaml
best_price_max_level: cheap best_price_max_level: cheap
best_price_max_level_gap_count: 2 # Allow up to 2 NORMAL intervals per period best_price_max_level_gap_count: 2 # Allow up to 2 NORMAL intervals per period
``` ```
</details>
**Use case:** "Don't split periods just because one interval isn't perfectly CHEAP" **Use case:** "Don't split periods just because one interval isn't perfectly CHEAP"
### Tweaking Strategy: What to Adjust First? ### Tweaking Strategy: What to Adjust First?
@ -292,56 +304,81 @@ When you're not happy with the default behavior, adjust settings in this order:
If you're not finding enough periods: If you're not finding enough periods:
<details>
<summary>Show YAML example (relaxation defaults)</summary>
```yaml ```yaml
enable_min_periods_best: true # Already default! enable_min_periods_best: true # Already default!
min_periods_best: 2 # Already default! min_periods_best: 2 # Already default!
relaxation_attempts_best: 11 # Already default! relaxation_attempts_best: 11 # Already default!
``` ```
</details>
**Why start here?** Relaxation automatically finds the right balance for each day. Much easier than manual tuning. **Why start here?** Relaxation automatically finds the right balance for each day. Much easier than manual tuning.
#### 2. **Adjust Period Length (Simple)** #### 2. **Adjust Period Length (Simple)**
If periods are too short/long for your use case: If periods are too short/long for your use case:
<details>
<summary>Show YAML example (longer or shorter periods)</summary>
```yaml ```yaml
best_price_min_period_length: 90 # Increase from 60 for longer periods best_price_min_period_length: 90 # Increase from 60 for longer periods
# OR # OR
best_price_min_period_length: 45 # Decrease from 60 for shorter periods best_price_min_period_length: 45 # Decrease from 60 for shorter periods
``` ```
</details>
**Safe to change:** This only affects duration, not price selection logic. **Safe to change:** This only affects duration, not price selection logic.
#### 3. **Fine-tune Flexibility (Moderate)** #### 3. **Fine-tune Flexibility (Moderate)**
If you consistently want more/fewer periods: If you consistently want more/fewer periods:
<details>
<summary>Show YAML example (flexibility tuning)</summary>
```yaml ```yaml
best_price_flex: 20 # Increase from 15% for more periods best_price_flex: 20 # Increase from 15% for more periods
# OR # OR
best_price_flex: 10 # Decrease from 15% for stricter selection best_price_flex: 10 # Decrease from 15% for stricter selection
``` ```
</details>
**⚠️ Watch out:** Values >25% may conflict with distance filter. Use relaxation instead. **⚠️ Watch out:** Values >25% may conflict with distance filter. Use relaxation instead.
#### 4. **Adjust Distance from Average (Advanced)** #### 4. **Adjust Distance from Average (Advanced)**
Only if periods seem "mediocre" (not really cheap/expensive): Only if periods seem "mediocre" (not really cheap/expensive):
<details>
<summary>Show YAML example (distance from average)</summary>
```yaml ```yaml
best_price_min_distance_from_avg: 10 # Increase from 5% for stricter quality best_price_min_distance_from_avg: 10 # Increase from 5% for stricter quality
``` ```
</details>
**⚠️ Careful:** High values (>10%) can make it impossible to find periods on flat price days. **⚠️ Careful:** High values (>10%) can make it impossible to find periods on flat price days.
#### 5. **Enable Level Filter (Expert)** #### 5. **Enable Level Filter (Expert)**
Only if you want absolute quality requirements: Only if you want absolute quality requirements:
<details>
<summary>Show YAML example (strict level filter)</summary>
```yaml ```yaml
best_price_max_level: cheap # Only show objectively CHEAP periods best_price_max_level: cheap # Only show objectively CHEAP periods
``` ```
</details>
**⚠️ Very strict:** Many days may have zero qualifying periods. **Always enable relaxation when using this!** **⚠️ Very strict:** Many days may have zero qualifying periods. **Always enable relaxation when using this!**
### Common Mistakes to Avoid ### Common Mistakes to Avoid
@ -397,6 +434,9 @@ best_price_min_distance_from_avg: 5 # (default)
**Automation example:** **Automation example:**
<details>
<summary>Show YAML automation example (run dishwasher in best price period)</summary>
```yaml ```yaml
automation: automation:
- trigger: - trigger:
@ -409,6 +449,8 @@ automation:
entity_id: switch.dishwasher entity_id: switch.dishwasher
``` ```
</details>
--- ---
## Troubleshooting ## Troubleshooting
@ -421,12 +463,17 @@ automation:
This is **expected behavior** on days with very uniform electricity prices. When prices vary by less than ~10% across the day (e.g. on sunny spring days with high solar generation), there is no meaningful second "cheap window" – all hours are equally cheap. The integration automatically reduces the target to 1 period for that day. This is **expected behavior** on days with very uniform electricity prices. When prices vary by less than ~10% across the day (e.g. on sunny spring days with high solar generation), there is no meaningful second "cheap window" – all hours are equally cheap. The integration automatically reduces the target to 1 period for that day.
<details>
<summary>Show YAML example (flat day detection)</summary>
```yaml ```yaml
min_periods_configured: 2 min_periods_configured: 2
periods_found_total: 1 periods_found_total: 1
flat_days_detected: 1 # Uniform prices today → 1 period is the right answer flat_days_detected: 1 # Uniform prices today → 1 period is the right answer
``` ```
</details>
You don't need to change anything. This is the integration protecting you from artificial periods. You don't need to change anything. This is the integration protecting you from artificial periods.
**If `relaxation_incomplete` is present (without `flat_days_detected`):** **If `relaxation_incomplete` is present (without `flat_days_detected`):**
@ -434,15 +481,25 @@ You don't need to change anything. This is the integration protecting you from a
Relaxation tried all configured attempts but couldn't reach your target. Options: Relaxation tried all configured attempts but couldn't reach your target. Options:
1. **Increase relaxation attempts** (tries more flexibility levels before giving up) 1. **Increase relaxation attempts** (tries more flexibility levels before giving up)
<details>
<summary>Show YAML example (increase relaxation attempts)</summary>
```yaml ```yaml
relaxation_attempts_best: 12 # Default: 11 relaxation_attempts_best: 12 # Default: 11
``` ```
</details>
2. **Reduce minimum period count** 2. **Reduce minimum period count**
<details>
<summary>Show YAML example (reduce min periods)</summary>
```yaml ```yaml
min_periods_best: 1 # Only require 1 period per day min_periods_best: 1 # Only require 1 period per day
``` ```
</details>
3. **Check filter settings** – very strict `best_price_min_distance_from_avg` values block relaxation 3. **Check filter settings** – very strict `best_price_min_distance_from_avg` values block relaxation
--- ---
@ -454,25 +511,40 @@ Relaxation tried all configured attempts but couldn't reach your target. Options
**Common Solutions:** **Common Solutions:**
1. **Check if relaxation is enabled** 1. **Check if relaxation is enabled**
<details>
<summary>Show YAML example (relaxation enabled)</summary>
```yaml ```yaml
enable_min_periods_best: true # Should be true (default) enable_min_periods_best: true # Should be true (default)
min_periods_best: 2 # Try to find at least 2 periods min_periods_best: 2 # Try to find at least 2 periods
``` ```
</details>
2. **If still no periods, check filters** 2. **If still no periods, check filters**
- Look at sensor attributes: `relaxation_active` and `relaxation_level` - Look at sensor attributes: `relaxation_active` and `relaxation_level`
- If relaxation exhausted all attempts: Filters too strict or flat price day - If relaxation exhausted all attempts: Filters too strict or flat price day
3. **Try increasing flexibility slightly** 3. **Try increasing flexibility slightly**
<details>
<summary>Show YAML example (increase flexibility)</summary>
```yaml ```yaml
best_price_flex: 20 # Increase from default 15% best_price_flex: 20 # Increase from default 15%
``` ```
</details>
4. **Or reduce period length requirement** 4. **Or reduce period length requirement**
<details>
<summary>Show YAML example (reduce period length)</summary>
```yaml ```yaml
best_price_min_period_length: 45 # Reduce from default 60 minutes best_price_min_period_length: 45 # Reduce from default 60 minutes
``` ```
</details>
### Periods Split Into Small Pieces ### Periods Split Into Small Pieces
**Symptom:** Many short periods instead of one long period **Symptom:** Many short periods instead of one long period
@ -480,16 +552,26 @@ Relaxation tried all configured attempts but couldn't reach your target. Options
**Common Solutions:** **Common Solutions:**
1. **If using level filter, add gap tolerance** 1. **If using level filter, add gap tolerance**
<details>
<summary>Show YAML example (level gap tolerance)</summary>
```yaml ```yaml
best_price_max_level: cheap best_price_max_level: cheap
best_price_max_level_gap_count: 2 # Allow 2 NORMAL intervals best_price_max_level_gap_count: 2 # Allow 2 NORMAL intervals
``` ```
</details>
2. **Slightly increase flexibility** 2. **Slightly increase flexibility**
<details>
<summary>Show YAML example (wider flexibility)</summary>
```yaml ```yaml
best_price_flex: 20 # From 15% → captures wider price range best_price_flex: 20 # From 15% → captures wider price range
``` ```
</details>
3. **Check for price spikes** 3. **Check for price spikes**
- Automatic smoothing should handle this - Automatic smoothing should handle this
- Check attribute: `period_interval_smoothed_count` - Check attribute: `period_interval_smoothed_count`
@ -536,6 +618,9 @@ relaxation_incomplete: true # Some days couldn't reach the configured ta
These two values together quickly show whether the calculation achieved its goal: These two values together quickly show whether the calculation achieved its goal:
<details>
<summary>Show YAML examples (configured target vs. found periods)</summary>
```yaml ```yaml
min_periods_configured: 2 # You asked for 2 periods per day min_periods_configured: 2 # You asked for 2 periods per day
periods_found_total: 6 # 3 days × 2 periods = fully satisfied ✅ periods_found_total: 6 # 3 days × 2 periods = fully satisfied ✅
@ -546,18 +631,25 @@ min_periods_configured: 2
periods_found_total: 5 # 3 days, but one day got only 1 period periods_found_total: 5 # 3 days, but one day got only 1 period
``` ```
</details>
Note that `periods_found_total` counts **all periods across today and tomorrow** – so 4 on a two-day view means 2 per day on average. Note that `periods_found_total` counts **all periods across today and tomorrow** – so 4 on a two-day view means 2 per day on average.
**`flat_days_detected`** **`flat_days_detected`**
This is the most important diagnostic for days with very uniform prices (e.g. sunny spring/summer days with high solar generation): This is the most important diagnostic for days with very uniform prices (e.g. sunny spring/summer days with high solar generation):
<details>
<summary>Show YAML example (flat_days_detected)</summary>
```yaml ```yaml
min_periods_configured: 2 min_periods_configured: 2
periods_found_total: 1 periods_found_total: 1
flat_days_detected: 1 # ← This explains why you got 1 instead of 2 flat_days_detected: 1 # ← This explains why you got 1 instead of 2
``` ```
</details>
When prices barely change across the day – typically a variation of less than 10% – the integration automatically reduces the target from your configured value to 1. There is no meaningful second "best price window" when all prices are essentially equal. When prices barely change across the day – typically a variation of less than 10% – the integration automatically reduces the target from your configured value to 1. There is no meaningful second "best price window" when all prices are essentially equal.
**This is expected and correct behavior**, not a problem. It prevents the sensor from generating artificial periods that don't represent genuinely cheaper windows. **This is expected and correct behavior**, not a problem. It prevents the sensor from generating artificial periods that don't represent genuinely cheaper windows.
@ -566,12 +658,17 @@ When prices barely change across the day – typically a variation of less than
This flag appears when even after all relaxation attempts, at least one day could not reach the configured minimum number of periods: This flag appears when even after all relaxation attempts, at least one day could not reach the configured minimum number of periods:
<details>
<summary>Show YAML example (relaxation_incomplete)</summary>
```yaml ```yaml
min_periods_configured: 2 min_periods_configured: 2
periods_found_total: 1 periods_found_total: 1
relaxation_incomplete: true # ← Relaxation tried everything, still short relaxation_incomplete: true # ← Relaxation tried everything, still short
``` ```
</details>
This is most common on very flat days (see above) or with very strict filter settings. If you see this repeatedly on normal days, consider: This is most common on very flat days (see above) or with very strict filter settings. If you see this repeatedly on normal days, consider:
- Reducing `min_periods_best` to 1 - Reducing `min_periods_best` to 1
- Increasing `relaxation_attempts_best` - Increasing `relaxation_attempts_best`
@ -630,6 +727,9 @@ Daily average: 19 ct/kWh
Check the volatility sensors to understand if a period flip is meaningful: Check the volatility sensors to understand if a period flip is meaningful:
<details>
<summary>Show YAML example (daily volatility check)</summary>
```yaml ```yaml
# Check daily volatility (available in integration) # Check daily volatility (available in integration)
sensor.<home_name>_today_s_price_volatility: 8.2% # Low volatility sensor.<home_name>_today_s_price_volatility: 8.2% # Low volatility
@ -641,6 +741,8 @@ sensor.<home_name>_tomorrow_s_price_volatility: 7.9% # Also low
# - Consider ignoring period classification on such days # - Consider ignoring period classification on such days
``` ```
</details>
**Handling in Automations:** **Handling in Automations:**
You can make your automations volatility-aware: You can make your automations volatility-aware:
@ -702,6 +804,9 @@ automation:
Each period sensor exposes day volatility and price statistics: Each period sensor exposes day volatility and price statistics:
<details>
<summary>Show YAML example (per-period volatility attributes)</summary>
```yaml ```yaml
binary_sensor.<home_name>_best_price_period: binary_sensor.<home_name>_best_price_period:
day_volatility_%: 8.2 # Volatility % of the period's day day_volatility_%: 8.2 # Volatility % of the period's day
@ -710,6 +815,8 @@ binary_sensor.<home_name>_best_price_period:
day_price_span: 400.0 # Difference (max - min) in ct day_price_span: 400.0 # Difference (max - min) in ct
``` ```
</details>
These attributes allow automations to check: "Is the classification meaningful on this particular day?" These attributes allow automations to check: "Is the classification meaningful on this particular day?"
**Summary:** **Summary:**
@ -724,7 +831,7 @@ These attributes allow automations to check: "Is the classification meaningful o
For advanced configuration patterns and technical deep-dive, see: For advanced configuration patterns and technical deep-dive, see:
- [Automation Examples](./automation-examples.md) - Real-world automation patterns - [Automation Examples](./automation-examples.md) - Real-world automation patterns
- [Actions](./actions.md) - Using the `tibber_prices.get_chartdata` action for custom visualizations - [Chart Actions](./chart-actions.md) - Using the `tibber_prices.get_chartdata` action for custom visualizations
### Quick Reference ### Quick Reference

4
docs/user/docs/period-relaxation.md
View file

@ -1,6 +1,8 @@
# Understanding Relaxation # Understanding Relaxation
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
Relaxation is the automatic filter-loosening mechanism that ensures your [Best/Peak Price periods](period-calculation.md) always find results — even on days with unusual price patterns. Relaxation is the automatic filter-loosening mechanism that ensures your [Best/Peak Price periods](period-calculation.md) always find results — even on days with unusual price patterns.

57
docs/user/docs/scheduling-services.md → docs/user/docs/scheduling-actions.md
View file

@ -1,4 +1,4 @@
# Scheduling Services # Scheduling Actions
Find the cheapest (or most expensive) time windows for your appliances — automatically. These actions analyze real Tibber price data and return optimal scheduling recommendations. Find the cheapest (or most expensive) time windows for your appliances — automatically. These actions analyze real Tibber price data and return optimal scheduling recommendations.
@ -64,6 +64,9 @@ data:
For full control, specify exact datetime values: For full control, specify exact datetime values:
<details>
<summary>Show YAML example (explicit start and end datetimes)</summary>
```yaml ```yaml
service: tibber_prices.find_cheapest_block service: tibber_prices.find_cheapest_block
data: data:
@ -72,10 +75,15 @@ data:
search_end: "2026-04-12T06:00:00+02:00" search_end: "2026-04-12T06:00:00+02:00"
``` ```
</details>
### Time-of-Day with Day Offset ### Time-of-Day with Day Offset
Schedule relative to today using time + day offset: Schedule relative to today using time + day offset:
<details>
<summary>Show YAML example (time-of-day with day offset)</summary>
```yaml ```yaml
service: tibber_prices.find_cheapest_block service: tibber_prices.find_cheapest_block
data: data:
@ -85,10 +93,15 @@ data:
search_end_day_offset: 1 # 06:00 tomorrow search_end_day_offset: 1 # 06:00 tomorrow
``` ```
</details>
### Minute Offsets from Now ### Minute Offsets from Now
For relative searches: For relative searches:
<details>
<summary>Show YAML example (relative minute offsets)</summary>
```yaml ```yaml
service: tibber_prices.find_cheapest_block service: tibber_prices.find_cheapest_block
data: data:
@ -97,6 +110,8 @@ data:
search_end_offset_minutes: 480 # Next 8 hours search_end_offset_minutes: 480 # Next 8 hours
``` ```
</details>
### Default Behavior ### Default Behavior
If you omit all range parameters, the search covers **now until the end of tomorrow** — the maximum window with available price data. If you omit all range parameters, the search covers **now until the end of tomorrow** — the maximum window with available price data.
@ -137,6 +152,9 @@ data:
By default, cost estimates assume a constant 1 kW load. If your appliance has variable power draw, provide a power profile — **one watt value per 15-minute interval**: By default, cost estimates assume a constant 1 kW load. If your appliance has variable power draw, provide a power profile — **one watt value per 15-minute interval**:
<details>
<summary>Show YAML example (power profile per 15-minute interval)</summary>
```yaml ```yaml
# Washing machine: high power for heating, then less # Washing machine: high power for heating, then less
service: tibber_prices.find_cheapest_block service: tibber_prices.find_cheapest_block
@ -151,6 +169,8 @@ data:
- 500 # Interval 6: Final rinse - 500 # Interval 6: Final rinse
``` ```
</details>
The service then calculates `estimated_total_cost` using the actual power draw per interval instead of flat 1 kW, and adds `estimated_load_kwh` (total energy consumed) to the response. The service then calculates `estimated_total_cost` using the actual power draw per interval instead of flat 1 kW, and adds `estimated_load_kwh` (total energy consumed) to the response.
:::info Duration and profile must match :::info Duration and profile must match
@ -177,6 +197,9 @@ response_variable: result
### Example with All Options ### Example with All Options
<details>
<summary>Show YAML example (find_cheapest_block with all options)</summary>
```yaml ```yaml
service: tibber_prices.find_cheapest_block service: tibber_prices.find_cheapest_block
data: data:
@ -189,6 +212,8 @@ data:
response_variable: result response_variable: result
``` ```
</details>
### Response ### Response
```json ```json
@ -243,6 +268,9 @@ response_variable: result
### Use in Automations ### Use in Automations
<details>
<summary>Show YAML automation example (start dishwasher at cheapest time)</summary>
```yaml ```yaml
automation: automation:
- alias: "Start dishwasher at cheapest time" - alias: "Start dishwasher at cheapest time"
@ -270,6 +298,8 @@ automation:
entity_id: switch.dishwasher_smart_plug entity_id: switch.dishwasher_smart_plug
``` ```
</details>
--- ---
## Find Cheapest Hours ## Find Cheapest Hours
@ -400,6 +430,9 @@ response_variable: result
### With Gap and Power Profiles ### With Gap and Power Profiles
<details>
<summary>Show YAML example (multi-appliance schedule with gaps and power profiles)</summary>
```yaml ```yaml
service: tibber_prices.find_cheapest_schedule service: tibber_prices.find_cheapest_schedule
data: data:
@ -420,6 +453,8 @@ data:
response_variable: result response_variable: result
``` ```
</details>
### Response ### Response
```json ```json
@ -557,6 +592,9 @@ response_variable: peak
Schedule dishwasher + washing machine to run overnight at cheapest prices, with a 15-minute gap between them: Schedule dishwasher + washing machine to run overnight at cheapest prices, with a 15-minute gap between them:
<details>
<summary>Show YAML automation example (overnight appliance scheduling)</summary>
```yaml ```yaml
automation: automation:
- alias: "Schedule overnight appliances" - alias: "Schedule overnight appliances"
@ -587,8 +625,13 @@ automation:
Total cost: {{ schedule.total_estimated_cost | round(2) }} ct Total cost: {{ schedule.total_estimated_cost | round(2) }} ct
``` ```
</details>
### EV Charging During Cheapest 4 Hours ### EV Charging During Cheapest 4 Hours
<details>
<summary>Show YAML automation example (EV charging in cheapest 4 hours)</summary>
```yaml ```yaml
automation: automation:
- alias: "Smart EV charging" - alias: "Smart EV charging"
@ -620,8 +663,13 @@ automation:
``` ```
</details>
### Peak Price Warning ### Peak Price Warning
<details>
<summary>Show YAML automation example (peak price warning)</summary>
```yaml ```yaml
automation: automation:
- alias: "Peak price warning" - alias: "Peak price warning"
@ -646,6 +694,8 @@ automation:
Average price: {{ peak.window.price_mean | round(1) }} ct/kWh Average price: {{ peak.window.price_mean | round(1) }} ct/kWh
``` ```
</details>
--- ---
## Technical Notes ## Technical Notes
@ -658,6 +708,9 @@ All durations are rounded **up** to the nearest 15 minutes because Tibber price
Add `include_comparison_details: true` to `find_cheapest_block` or `find_cheapest_hours` to get extra fields in the comparison: Add `include_comparison_details: true` to `find_cheapest_block` or `find_cheapest_hours` to get extra fields in the comparison:
<details>
<summary>Show YAML example (comparison details enabled)</summary>
```yaml ```yaml
service: tibber_prices.find_cheapest_block service: tibber_prices.find_cheapest_block
data: data:
@ -665,6 +718,8 @@ data:
include_comparison_details: true include_comparison_details: true
``` ```
</details>
This adds `comparison_price_min`, `comparison_price_max`, and `comparison_window_end` to the `price_comparison` object. This adds `comparison_price_min`, `comparison_price_max`, and `comparison_window_end` to the `price_comparison` object.
### Response When No Window Found ### Response When No Window Found

4
docs/user/docs/sensors-average.md
View file

@ -1,6 +1,8 @@
# Average & Statistics Sensors # Average & Statistics Sensors
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
The integration provides several sensors that calculate average electricity prices over different time windows. These sensors show a **typical** price value that represents the overall price level, helping you make informed decisions about when to use electricity. The integration provides several sensors that calculate average electricity prices over different time windows. These sensors show a **typical** price value that represents the overall price level, helping you make informed decisions about when to use electricity.

6
docs/user/docs/sensors-energy-tax.md
View file

@ -1,6 +1,8 @@
# Energy & Tax Attributes # Energy & Tax Attributes
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
Most price sensors include **energy price** and **tax** attributes that break down the total price into its components: Most price sensors include **energy price** and **tax** attributes that break down the total price into its components:
@ -107,4 +109,4 @@ The composition of the `tax` field varies by country (Norway, Sweden, Germany, N
## In Chart Data Actions ## In Chart Data Actions
The `energy_price` and `tax` fields are also available in the `get_chartdata` action. See [Actions — Energy & Tax Fields](./actions.md#energy--tax-fields-in-get_chartdata) for details. The `energy_price` and `tax` fields are also available in the `get_chartdata` action. See [Chart Actions — Energy & Tax Fields](./chart-actions.md#energy--tax-fields) for details.

4
docs/user/docs/sensors-overview.md
View file

@ -2,7 +2,9 @@
> **Tip:** Many sensors have dynamic icons and colors! See the **[Dynamic Icons Guide](dynamic-icons.md)** and **[Dynamic Icon Colors Guide](icon-colors.md)** to enhance your dashboards. > **Tip:** Many sensors have dynamic icons and colors! See the **[Dynamic Icons Guide](dynamic-icons.md)** and **[Dynamic Icon Colors Guide](icon-colors.md)** to enhance your dashboards.
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
The integration provides **100+ sensors** organized by purpose. This page gives a quick overview and links to detailed guides for each sensor family. The integration provides **100+ sensors** organized by purpose. This page gives a quick overview and links to detailed guides for each sensor family.

4
docs/user/docs/sensors-ratings-levels.md
View file

@ -1,6 +1,8 @@
# Ratings & Levels # Ratings & Levels
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
The integration provides **two** classification systems for electricity prices. Both are useful, but serve different purposes. The integration provides **two** classification systems for electricity prices. Both are useful, but serve different purposes.

4
docs/user/docs/sensors-timing.md
View file

@ -1,6 +1,8 @@
# Timing Sensors # Timing Sensors
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
Timing sensors provide **real-time information about Best Price and Peak Price periods**: when they start, end, how long they last, and your progress through them. Timing sensors provide **real-time information about Best Price and Peak Price periods**: when they start, end, how long they last, and your progress through them.

4
docs/user/docs/sensors-trends.md
View file

@ -1,6 +1,8 @@
# Trend Sensors # Trend Sensors
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
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:

4
docs/user/docs/sensors-volatility.md
View file

@ -1,6 +1,8 @@
# Volatility Sensors # Volatility Sensors
> **Entity ID tip:** `<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language. :::tip Entity ID tip
`<home_name>` is a placeholder for your Tibber home display name in Home Assistant. Entity IDs are derived from the displayed name (localized), so the exact slug may differ. **Can't find a sensor?** Use the **[Entity Reference (All Languages)](sensor-reference.md)** to search by name in your language.
:::
Volatility sensors help you understand how much electricity prices fluctuate over a given period. Instead of just looking at the absolute price, they measure the **relative price variation**, which is a great indicator of whether it's a good day for price-based energy optimization. Volatility sensors help you understand how much electricity prices fluctuate over a given period. Instead of just looking at the absolute price, they measure the **relative price variation**, which is a great indicator of whether it's a good day for price-based energy optimization.

10
docs/user/docs/troubleshooting.md
View file

@ -86,6 +86,9 @@ Restart Home Assistant for the change to take effect.
For specific subsystems, you can enable logging selectively: For specific subsystems, you can enable logging selectively:
<details>
<summary>Show YAML example (targeted subsystem logging)</summary>
```yaml ```yaml
logger: logger:
default: warning default: warning
@ -103,6 +106,8 @@ logger:
custom_components.tibber_prices.sensor: debug custom_components.tibber_prices.sensor: debug
``` ```
</details>
### Temporary Debug Logging (No Restart) ### Temporary Debug Logging (No Restart)
You can also enable debug logging temporarily from the HA UI: You can also enable debug logging temporarily from the HA UI:
@ -110,10 +115,15 @@ You can also enable debug logging temporarily from the HA UI:
1. Go to **Developer Tools → Services** 1. Go to **Developer Tools → Services**
2. Call service: `logger.set_level` 2. Call service: `logger.set_level`
3. Data: 3. Data:
<details>
<summary>Show YAML example (temporary logger.set_level payload)</summary>
```yaml ```yaml
custom_components.tibber_prices: debug custom_components.tibber_prices: debug
``` ```
</details>
This resets when HA restarts. This resets when HA restarts.
### Downloading Diagnostics ### Downloading Diagnostics

10
docs/user/sidebars.ts
View file

@ -71,11 +71,19 @@ const sidebars: SidebarsConfig = {
collapsible: true, collapsible: true,
collapsed: false, collapsed: false,
}, },
{
type: 'category',
label: '⚡ Actions',
link: { type: 'doc', id: 'actions' },
items: ['actions', 'scheduling-actions', 'chart-actions', 'data-actions'],
collapsible: true,
collapsed: false,
},
{ {
type: 'category', type: 'category',
label: '📖 Reference', label: '📖 Reference',
link: { type: 'doc', id: 'sensor-reference' }, link: { type: 'doc', id: 'sensor-reference' },
items: ['sensor-reference', 'actions', 'scheduling-services'], items: ['sensor-reference'],
collapsible: true, collapsible: true,
collapsed: false, collapsed: false,
}, },