jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-05-28 18:43:40 +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
@ -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.
:::
## 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 |
|--------|-------------|
| `find_cheapest_block` | Cheapest contiguous window (dishwasher, dryer) |
| `find_cheapest_hours` | Cheapest N hours, non-contiguous OK (EV, battery) |
| `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) |
| [`get_chartdata`](chart-actions.md#tibber_pricesget_chartdata) | Price data in chart-friendly formats (arrays, filtering, rolling windows) |
| [`get_apexcharts_yaml`](chart-actions.md#tibber_pricesget_apexcharts_yaml) | Auto-generated ApexCharts card configuration with color-coded price levels |
**→ 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:**
- **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
**→ [Data & Utility Actions — Full Guide](data-actions.md)** with parameters and response formats.

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

@ -7,7 +7,7 @@
- [Price-Based Automations](#price-based-automations)
- [Volatility-Aware Automations](#volatility-aware-automations)
- [Best Hour Detection](#best-hour-detection)
- [Scheduling Services](#scheduling-services)
- [Scheduling Actions](#scheduling-actions)
- [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.
>
> **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
@ -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!
> **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`)
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
**Generate:**
<details>
<summary>Show YAML example (generate rolling 48h window)</summary>
```yaml
service: tibber_prices.get_apexcharts_yaml
data:
@ -78,6 +83,8 @@ data:
highlight_best_price: true
```
</details>
**Screenshot:**
![Rolling 48h Window with Dynamic Y-Axis Scaling](/img/charts/rolling-window.jpg)
@ -103,6 +110,9 @@ data:
**Dependencies:** ApexCharts Card + Config Template Card
**Generate:**
<details>
<summary>Show YAML example (generate rolling auto-zoom)</summary>
```yaml
service: tibber_prices.get_apexcharts_yaml
data:
@ -112,6 +122,8 @@ data:
highlight_best_price: true
```
</details>
**Screenshot:**
![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:
<details>
<summary>Show YAML example (custom color palette)</summary>
```yaml
apex_config:
colors:
@ -258,10 +273,15 @@ apex_config:
- "#FF0000" # Change HIGH/VERY_EXPENSIVE color
```
</details>
### Changing Chart Height
Add to the card configuration:
<details>
<summary>Show YAML example (custom chart height)</summary>
```yaml
type: custom:apexcharts-card
graph_span: 48h
@ -273,10 +293,15 @@ apex_config:
height: 400 # Adjust height in pixels
```
</details>
### Combining with Other Cards
Wrap in a vertical stack for dashboard integration:
<details>
<summary>Show YAML example (vertical stack integration)</summary>
```yaml
type: vertical-stack
cards:
@ -286,11 +311,13 @@ cards:
# ... generated chart config
```
</details>
---
## 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
- **[Period Calculation Guide](period-calculation.md)**: Configure best price period detection

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

@ -1,6 +1,8 @@
# 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
@ -125,7 +127,7 @@ Thresholds are [volatility-adaptive](sensors-trends.md): automatically widened o
### 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
@ -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:
<details>
<summary>Show YAML example (median and mean attributes)</summary>
```yaml
# These attributes work regardless of display setting:
{{ state_attr('sensor.<home_name>_price_today', 'price_median') }}
{{ state_attr('sensor.<home_name>_price_today', 'price_mean') }}
```
</details>
This means:
- ✅ You can change the display anytime without breaking automations
- ✅ 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
<details>
<summary>Show YAML example (seasonal runtime override)</summary>
```yaml
automation:
- alias: "Winter: Stricter Best Price Detection"
@ -272,6 +282,8 @@ automation:
value: 10 # Stricter than default 15%
```
</details>
### Recorder Optimization (Optional)
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`:
<details>
<summary>Show YAML example (exclude runtime config entities from recorder)</summary>
```yaml
recorder:
exclude:
@ -294,6 +309,8 @@ recorder:
- switch.*_peak_price_*
```
</details>
This is especially useful if:
- You rarely change these settings
- 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.
> **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

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.
> **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?
@ -50,6 +52,9 @@ The icons will update automatically as the sensor states change.
### Glance Card
<details>
<summary>Show YAML example (Glance card)</summary>
```yaml
type: glance
entities:
@ -61,8 +66,13 @@ entities:
name: Best Price
```
</details>
### Custom Button Card
<details>
<summary>Show YAML example (custom button card)</summary>
```yaml
type: custom:button-card
entity: sensor.<home_name>_current_price_level
@ -71,8 +81,13 @@ show_state: true
# Icon updates automatically - no need to specify it!
```
</details>
### Mushroom Entity Card
<details>
<summary>Show YAML example (Mushroom entity card)</summary>
```yaml
type: custom:mushroom-entity-card
entity: sensor.<home_name>_today_s_price_volatility
@ -80,12 +95,17 @@ name: Price Volatility
# Icon changes automatically based on volatility level
```
</details>
## Overriding Dynamic Icons
If you want to use a fixed icon instead of the dynamic one:
### In Entity Cards
<details>
<summary>Show YAML example (fixed icon in entity card)</summary>
```yaml
type: entities
entities:
@ -93,8 +113,13 @@ entities:
icon: mdi:lightning-bolt # Fixed icon, won't change
```
</details>
### In Custom Button Card
<details>
<summary>Show YAML example (fixed icon in button card)</summary>
```yaml
type: custom:button-card
entity: sensor.<home_name>_current_price_rating
@ -103,12 +128,17 @@ icon: mdi:chart-line # Fixed icon overrides dynamic behavior
show_state: true
```
</details>
## Combining with Dynamic Colors
Dynamic icons work great together with dynamic colors! See the **[Dynamic Icon Colors Guide](icon-colors.md)** for examples.
**Example: Dynamic icon AND color**
<details>
<summary>Show YAML example (dynamic icon + dynamic color)</summary>
```yaml
type: custom:button-card
entity: sensor.<home_name>_current_price_level
@ -123,6 +153,8 @@ styles:
]]]
```
</details>
This gives you both:
- ✅ 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
> **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?

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.
> **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?
@ -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:**
<details>
<summary>Show YAML comparison (complex conversion vs direct state logic)</summary>
```yaml
# ❌ DON'T: Converting icon_color requires if/else anyway
card:
@ -87,6 +92,8 @@ card:
]]]
```
</details>
The advantage of `icon_color` is simplicity - if you need complex logic, you lose that advantage.
## How to Use icon_color in Your Dashboard
@ -113,6 +120,9 @@ styles:
**Example: Icon AND state value with same color**
<details>
<summary>Show YAML example (button-card icon + state text in same color)</summary>
```yaml
type: custom:button-card
entity: sensor.<home_name>_current_price_level
@ -133,6 +143,8 @@ styles:
- font-weight: bold
```
</details>
### Method 2: Entities Card with card_mod
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:**
<details>
<summary>Show YAML example (Mushroom icon color only)</summary>
```yaml
type: custom:mushroom-entity-card
entity: binary_sensor.<home_name>_best_price_period
@ -176,6 +191,8 @@ card_mod:
}
```
</details>
**Icon and state value:**
<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`):
<details>
<summary>Show YAML example (theme-level color overrides)</summary>
```yaml
my_custom_theme:
# Override standard variables
@ -343,6 +363,8 @@ my_custom_theme:
info-color: "#0288D1" # Custom blue
```
</details>
The `icon_color` attribute will automatically use your custom theme colors.
#### 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
- **[Dynamic Icons](dynamic-icons.md)** - State-based automatic icon changes
- **[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
- **[Automation Examples](automation-examples.md)** - Ready-to-use automation recipes
- **[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.
> **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
@ -262,11 +264,16 @@ peak_price_min_distance_from_avg: 5
**Default:** `any` (disabled)
**Options:** `any` | `cheap` | `very_cheap` (Best Price) | `expensive` | `very_expensive` (Peak Price)
<details>
<summary>Show YAML example (level filter)</summary>
```yaml
best_price_max_level: any # Show any period below average
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"
**ℹ️ 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)
**Range:** 0-10
<details>
<summary>Show YAML example (gap tolerance)</summary>
```yaml
best_price_max_level: cheap
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"
### 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:
<details>
<summary>Show YAML example (relaxation defaults)</summary>
```yaml
enable_min_periods_best: true # Already default!
min_periods_best: 2 # 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.
#### 2. **Adjust Period Length (Simple)**
If periods are too short/long for your use case:
<details>
<summary>Show YAML example (longer or shorter periods)</summary>
```yaml
best_price_min_period_length: 90 # Increase from 60 for longer periods
# OR
best_price_min_period_length: 45 # Decrease from 60 for shorter periods
```
</details>
**Safe to change:** This only affects duration, not price selection logic.
#### 3. **Fine-tune Flexibility (Moderate)**
If you consistently want more/fewer periods:
<details>
<summary>Show YAML example (flexibility tuning)</summary>
```yaml
best_price_flex: 20 # Increase from 15% for more periods
# OR
best_price_flex: 10 # Decrease from 15% for stricter selection
```
</details>
**⚠️ Watch out:** Values >25% may conflict with distance filter. Use relaxation instead.
#### 4. **Adjust Distance from Average (Advanced)**
Only if periods seem "mediocre" (not really cheap/expensive):
<details>
<summary>Show YAML example (distance from average)</summary>
```yaml
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.
#### 5. **Enable Level Filter (Expert)**
Only if you want absolute quality requirements:
<details>
<summary>Show YAML example (strict level filter)</summary>
```yaml
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!**
### Common Mistakes to Avoid
@ -397,6 +434,9 @@ best_price_min_distance_from_avg: 5 # (default)
**Automation example:**
<details>
<summary>Show YAML automation example (run dishwasher in best price period)</summary>
```yaml
automation:
- trigger:
@ -409,6 +449,8 @@ automation:
entity_id: switch.dishwasher
```
</details>
---
## 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.
<details>
<summary>Show YAML example (flat day detection)</summary>
```yaml
min_periods_configured: 2
periods_found_total: 1
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.
**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:
1. **Increase relaxation attempts** (tries more flexibility levels before giving up)
<details>
<summary>Show YAML example (increase relaxation attempts)</summary>
```yaml
relaxation_attempts_best: 12 # Default: 11
```
</details>
2. **Reduce minimum period count**
<details>
<summary>Show YAML example (reduce min periods)</summary>
```yaml
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
---
@ -454,25 +511,40 @@ Relaxation tried all configured attempts but couldn't reach your target. Options
**Common Solutions:**
1. **Check if relaxation is enabled**
<details>
<summary>Show YAML example (relaxation enabled)</summary>
```yaml
enable_min_periods_best: true # Should be true (default)
min_periods_best: 2 # Try to find at least 2 periods
```
</details>
2. **If still no periods, check filters**
- Look at sensor attributes: `relaxation_active` and `relaxation_level`
- If relaxation exhausted all attempts: Filters too strict or flat price day
3. **Try increasing flexibility slightly**
<details>
<summary>Show YAML example (increase flexibility)</summary>
```yaml
best_price_flex: 20 # Increase from default 15%
```
</details>
4. **Or reduce period length requirement**
<details>
<summary>Show YAML example (reduce period length)</summary>
```yaml
best_price_min_period_length: 45 # Reduce from default 60 minutes
```
</details>
### Periods Split Into Small Pieces
**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:**
1. **If using level filter, add gap tolerance**
<details>
<summary>Show YAML example (level gap tolerance)</summary>
```yaml
best_price_max_level: cheap
best_price_max_level_gap_count: 2 # Allow 2 NORMAL intervals
```
</details>
2. **Slightly increase flexibility**
<details>
<summary>Show YAML example (wider flexibility)</summary>
```yaml
best_price_flex: 20 # From 15% → captures wider price range
```
</details>
3. **Check for price spikes**
- Automatic smoothing should handle this
- 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:
<details>
<summary>Show YAML examples (configured target vs. found periods)</summary>
```yaml
min_periods_configured: 2 # You asked for 2 periods per day
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
```
</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.
**`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):
<details>
<summary>Show YAML example (flat_days_detected)</summary>
```yaml
min_periods_configured: 2
periods_found_total: 1
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.
**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:
<details>
<summary>Show YAML example (relaxation_incomplete)</summary>
```yaml
min_periods_configured: 2
periods_found_total: 1
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:
- Reducing `min_periods_best` to 1
- 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:
<details>
<summary>Show YAML example (daily volatility check)</summary>
```yaml
# Check daily volatility (available in integration)
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
```
</details>
**Handling in Automations:**
You can make your automations volatility-aware:
@ -702,6 +804,9 @@ automation:
Each period sensor exposes day volatility and price statistics:
<details>
<summary>Show YAML example (per-period volatility attributes)</summary>
```yaml
binary_sensor.<home_name>_best_price_period:
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
```
</details>
These attributes allow automations to check: "Is the classification meaningful on this particular day?"
**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:
- [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

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

@ -1,6 +1,8 @@
# 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.

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.
@ -64,6 +64,9 @@ data:
For full control, specify exact datetime values:
<details>
<summary>Show YAML example (explicit start and end datetimes)</summary>
```yaml
service: tibber_prices.find_cheapest_block
data:
@ -72,10 +75,15 @@ data:
search_end: "2026-04-12T06:00:00+02:00"
```
</details>
### Time-of-Day with Day Offset
Schedule relative to today using time + day offset:
<details>
<summary>Show YAML example (time-of-day with day offset)</summary>
```yaml
service: tibber_prices.find_cheapest_block
data:
@ -85,10 +93,15 @@ data:
search_end_day_offset: 1 # 06:00 tomorrow
```
</details>
### Minute Offsets from Now
For relative searches:
<details>
<summary>Show YAML example (relative minute offsets)</summary>
```yaml
service: tibber_prices.find_cheapest_block
data:
@ -97,6 +110,8 @@ data:
search_end_offset_minutes: 480 # Next 8 hours
```
</details>
### Default Behavior
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**:
<details>
<summary>Show YAML example (power profile per 15-minute interval)</summary>
```yaml
# Washing machine: high power for heating, then less
service: tibber_prices.find_cheapest_block
@ -151,6 +169,8 @@ data:
- 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.
:::info Duration and profile must match
@ -177,6 +197,9 @@ response_variable: result
### Example with All Options
<details>
<summary>Show YAML example (find_cheapest_block with all options)</summary>
```yaml
service: tibber_prices.find_cheapest_block
data:
@ -189,6 +212,8 @@ data:
response_variable: result
```
</details>
### Response
```json
@ -243,6 +268,9 @@ response_variable: result
### Use in Automations
<details>
<summary>Show YAML automation example (start dishwasher at cheapest time)</summary>
```yaml
automation:
- alias: "Start dishwasher at cheapest time"
@ -270,6 +298,8 @@ automation:
entity_id: switch.dishwasher_smart_plug
```
</details>
---
## Find Cheapest Hours
@ -400,6 +430,9 @@ response_variable: result
### With Gap and Power Profiles
<details>
<summary>Show YAML example (multi-appliance schedule with gaps and power profiles)</summary>
```yaml
service: tibber_prices.find_cheapest_schedule
data:
@ -420,6 +453,8 @@ data:
response_variable: result
```
</details>
### Response
```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:
<details>
<summary>Show YAML automation example (overnight appliance scheduling)</summary>
```yaml
automation:
- alias: "Schedule overnight appliances"
@ -587,8 +625,13 @@ automation:
Total cost: {{ schedule.total_estimated_cost | round(2) }} ct
```
</details>
### EV Charging During Cheapest 4 Hours
<details>
<summary>Show YAML automation example (EV charging in cheapest 4 hours)</summary>
```yaml
automation:
- alias: "Smart EV charging"
@ -620,8 +663,13 @@ automation:
```
</details>
### Peak Price Warning
<details>
<summary>Show YAML automation example (peak price warning)</summary>
```yaml
automation:
- alias: "Peak price warning"
@ -646,6 +694,8 @@ automation:
Average price: {{ peak.window.price_mean | round(1) }} ct/kWh
```
</details>
---
## 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:
<details>
<summary>Show YAML example (comparison details enabled)</summary>
```yaml
service: tibber_prices.find_cheapest_block
data:
@ -665,6 +718,8 @@ data:
include_comparison_details: true
```
</details>
This adds `comparison_price_min`, `comparison_price_max`, and `comparison_window_end` to the `price_comparison` object.
### Response When No Window Found

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

@ -1,6 +1,8 @@
# 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.

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

@ -1,6 +1,8 @@
# 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:
@ -107,4 +109,4 @@ The composition of the `tax` field varies by country (Norway, Sweden, Germany, N
## 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.
> **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.

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

@ -1,6 +1,8 @@
# 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.

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

@ -1,6 +1,8 @@
# 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.

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

@ -1,6 +1,8 @@
# 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:

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

@ -1,6 +1,8 @@
# 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.

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:
<details>
<summary>Show YAML example (targeted subsystem logging)</summary>
```yaml
logger:
default: warning
@ -103,6 +106,8 @@ logger:
custom_components.tibber_prices.sensor: debug
```
</details>
### Temporary Debug Logging (No Restart)
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**
2. Call service: `logger.set_level`
3. Data:
<details>
<summary>Show YAML example (temporary logger.set_level payload)</summary>
```yaml
custom_components.tibber_prices: debug
```
</details>
This resets when HA restarts.
### Downloading Diagnostics

10
docs/user/sidebars.ts
View file

@ -71,11 +71,19 @@ const sidebars: SidebarsConfig = {
collapsible: true,
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',
label: '📖 Reference',
link: { type: 'doc', id: 'sensor-reference' },
items: ['sensor-reference', 'actions', 'scheduling-services'],
items: ['sensor-reference'],
collapsible: true,
collapsed: false,
},