diff --git a/docs/user/docs/config-best-price.md b/docs/user/docs/config-best-price.md new file mode 100644 index 0000000..2c853e2 --- /dev/null +++ b/docs/user/docs/config-best-price.md @@ -0,0 +1,88 @@ +--- +sidebar_label: ๐Ÿ’š Best Price Period +--- + +# ๐Ÿ’š Best Price Period + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ ๐Ÿ’š Best Price Period** + +--- + +Best Price Period sensors detect windows of time when electricity is cheap enough to be worth scheduling loads (dishwasher, washing machine, EV charging, water heater). The binary sensor `is_best_price_period` is `on` during these windows. + +See **[Period Calculation](period-calculation.md)** for an in-depth explanation of the detection algorithm and [Period Relaxation](period-relaxation.md) for how the relaxation strategy works. + +## Settings + +### Period Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| **Minimum period length** | 60 min | Shortest window to report as a period โ€” filters out tiny sub-hour dips | +| **Maximum price level** | CHEAP | Only intervals at this Tibber level or cheaper qualify | +| **Gap tolerance** | 1 | Consecutive above-threshold intervals allowed inside a period โ€” bridges small price bumps between two cheap windows | + +### Flexibility Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| **Flex percentage** | 15% | How far above the daily minimum a price can be and still qualify. Higher = more intervals qualify | +| **Minimum distance from average** | 5% | Qualifying intervals must be at least this far below the daily average โ€” ensures periods are meaningfully cheap, not just "not expensive" | + +### Relaxation & Target + +| Setting | Default | Description | +|---------|---------|-------------| +| **Enable minimum period target** | On | Automatically loosens criteria (relaxation) until the target count is reached | +| **Target periods per day** | 2 | How many distinct periods the algorithm aims to find per day | +| **Relaxation attempts** | 11 | How many times to loosen the criteria before giving up. 11 steps ร— 3% increment = up to ~48% flex | + +:::tip Start with defaults +The defaults are tuned for typical European electricity markets. If you're unsure, leave them as-is and observe the binary sensor over a few days. +::: + +## Runtime Override Entities + +You can override these settings at runtime through automations โ€” useful for seasonal adjustments or dynamic schedules โ€” without opening the configuration menu. + +These entities are **disabled by default**. Enable them in **Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Entities**. + +| Entity | Type | Range | Overrides | +|--------|------|-------|-----------| +| `number._best_price_flexibility` | Number | 0โ€“50% | Flex percentage | +| `number._best_price_minimum_distance` | Number | -50โ€“0% | Minimum distance from average | +| `number._best_price_minimum_period_length` | Number | 15โ€“180 min | Minimum period length | +| `number._best_price_minimum_periods` | Number | 1โ€“10 | Target periods per day | +| `number._best_price_relaxation_attempts` | Number | 1โ€“12 | Relaxation attempts | +| `number._best_price_gap_tolerance` | Number | 0โ€“8 | Gap tolerance | +| `switch._best_price_enable_relaxation` | Switch | On/Off | Enable relaxation | + +When an override entity is **enabled**, its value takes precedence over the menu setting. When **disabled** (default), the menu setting is used. + +Changing a value triggers immediate period recalculation. Entity values are restored automatically after HA restarts. + +### Example: Stricter detection in winter + +
+Show YAML: Seasonal override automation + +```yaml +automation: + - alias: "Winter: Stricter Best Price Detection" + trigger: + - platform: time + at: "00:00:00" + condition: + - condition: template + value_template: "{{ now().month in [11, 12, 1, 2] }}" + action: + - service: number.set_value + target: + entity_id: number._best_price_flexibility + data: + value: 10 # Stricter than default 15% +``` + +
+ +See **[Runtime Override Entities](config-runtime-overrides.md)** for more details, including how overrides work, how to view entity descriptions, and recorder optimization. diff --git a/docs/user/docs/config-chart-export.md b/docs/user/docs/config-chart-export.md new file mode 100644 index 0000000..c0a2869 --- /dev/null +++ b/docs/user/docs/config-chart-export.md @@ -0,0 +1,23 @@ +--- +sidebar_label: ๐Ÿ“Š Chart Data Export +--- + +# ๐Ÿ“Š Chart Data Export Sensor (Legacy) + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ ๐Ÿ“Š Chart Data Export** + +--- + +:::caution Legacy feature +The Chart Data Export **sensor** is a legacy mechanism from early versions of this integration. For new setups, use the **[get_chartdata action](chart-actions.md)** instead โ€” it is more flexible, does not require a dedicated sensor, and returns data on demand. +::: + +## What this page does + +This configuration page controls whether the legacy chart data export sensor is active. If you already use this sensor in existing dashboards or automations and don't want to migrate yet, leave it enabled. + +## Migration to actions + +The [Chart Actions](chart-actions.md) page covers the recommended approach for fetching chart data via HA actions (formerly services), including ready-to-use examples for ApexCharts and other chart cards. + +If you have existing automations or cards using the legacy sensor, the [Chart Data Export legacy reference](chart-actions.md) includes migration guidance. diff --git a/docs/user/docs/config-currency.md b/docs/user/docs/config-currency.md new file mode 100644 index 0000000..0a5cc5d --- /dev/null +++ b/docs/user/docs/config-currency.md @@ -0,0 +1,62 @@ +--- +sidebar_label: ๐Ÿ’ฑ Currency Display +--- + +# ๐Ÿ’ฑ Currency Display + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ ๐Ÿ’ฑ Currency Display** + +--- + +## Display Mode + +Choose whether price sensor states show values in **base currency** or **subunit**: + +| Mode | Example | Smart default | +|------|---------|---------------| +| **Base currency** | 0.2534 โ‚ฌ/kWh, 2.53 kr/kWh | NOK, SEK, DKK | +| **Subunit** (default for EUR) | 25.34 ct/kWh, 25.3 รธre/kWh | EUR | + +The smart default is automatically applied when you first set up the integration based on your Tibber account currency. + +:::caution Decide before building automations +Switching the display mode later changes **all** price sensor state values (e.g., 25.34 โ†’ 0.2534). This will break: +- Numeric thresholds in automations and conditions +- Template sensors and conditional cards with hardcoded values + +**If you do switch later:** + +1. A **repair notification** from this integration appears immediately in your sidebar โ€” it reminds you to update automations and dashboards. +2. HA's Recorder detects the unit mismatch and shows a **"The unit has changed"** dialog (may take a few minutes or until the next statistics run). Choose **"Delete all old statistic data"** to start fresh. Do _not_ choose "Update the unit without converting" โ€” that re-labels old numbers with the new unit, making historical values factually wrong. +3. Update every **automation trigger and condition** with a numeric price value. +4. Update **dashboard cards** with hardcoded thresholds or unit labels. +::: + +## Price Precision and Rounding + +All prices are received from the Tibber API in base currency and processed without loss of precision. The sensor **state value** is rounded and stored as follows: + +| Display Mode | Stored precision | Example | +|---|---|---| +| **Subunit** (ct, รธre) | 2 decimal places | 25.34 ct/kWh | +| **Base currency** (โ‚ฌ, kr) | 4 decimal places | 0.2534 โ‚ฌ/kWh | + +This applies to both sensor states and attributes (e.g., `energy_price`, `price_mean`, `price_min`). + +### Default display precision + +Home Assistant shows fewer decimals than the stored value by default โ€” enough for a quick glance. The integration sets these defaults per sensor type: + +| Sensor type | Subunit default | Base currency default | +|---|---|---| +| **Current / Next / Previous interval price** | 2 decimals (25.34 ct) | 4 decimals (0.2534 โ‚ฌ) | +| **All other price sensors** (averages, min/max, โ€ฆ) | 1 decimal (25.3 ct) | 2 decimals (0.25 โ‚ฌ) | +| **Energy Dashboard sensor** | โ€” | 4 decimals (always) | + +You can override the displayed precision per entity in the HA UI: + +1. Go to **Settings โ†’ Devices & Services โ†’ Entities** +2. Select a price sensor โ†’ click the gear icon +3. Change **Display precision** to your preference + +**Practical ceiling:** Subunit values have exactly 2 decimal places stored โ€” setting more than 2 shows trailing zeros. Base currency values have 4 decimal places stored โ€” 3โ€“4 decimals are meaningful. diff --git a/docs/user/docs/config-general.md b/docs/user/docs/config-general.md new file mode 100644 index 0000000..0952a6b --- /dev/null +++ b/docs/user/docs/config-general.md @@ -0,0 +1,73 @@ +--- +sidebar_label: โš™๏ธ General Settings +--- + +# โš™๏ธ General Settings + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ โš™๏ธ General Settings** + +--- + +## Extended Entity Descriptions + +Controls whether sensor attributes include detailed explanations and usage tips. + +| State | Attributes included | +|-------|---------------------| +| **Disabled** (default) | `description` only โ€” brief one-liner | +| **Enabled** | `description` + `long_description` + `usage_tips` | + +Enable this while getting familiar with the integration. Once you know what each sensor does, disabling it reduces attribute clutter in your Developer Tools / history views. + +## Average Sensor Display + +Controls which statistical measure the sensor **state value** shows for all average price sensors. The other value is always available as an attribute regardless of this setting. + +| Mode | Shows | Best for | +|------|-------|----------| +| **Median** (default) | Middle value when prices are sorted | Dashboards, typical price level | +| **Arithmetic Mean** | Mathematical average of all prices | Cost calculations, budgeting | + +### Why the difference matters + +Consider a day with these prices: `10, 12, 13, 15, 80 ct/kWh` + +- **Median = 13 ct/kWh** โ€” "typical" price (ignores the expensive spike) +- **Mean = 26 ct/kWh** โ€” average cost if consuming evenly (spike included) + +The median gives a better feel for what the day was like. The mean is more accurate for calculating what you actually paid on average. + +### Both values always available + +You can always access both values as attributes from any average sensor, regardless of this display setting: + +```yaml +{{ state_attr('sensor._price_today', 'price_median') }} +{{ state_attr('sensor._price_today', 'price_mean') }} +``` + +This means you can change the display setting at any time without breaking automations that use attributes. + +### Affected sensors + +This setting applies to: +- Daily average sensors (today, tomorrow) +- 24-hour rolling averages (trailing, leading) +- Hourly smoothed prices (current hour, next hour) +- Future forecast sensors (next 1h, 2h, 3h, โ€ฆ 12h) + +See **[Average Sensors](sensors-average.md)** for detailed examples. + +### Choosing your mode + +**Choose Median if:** +- ๐Ÿ‘ฅ You show prices to users ("What's today like?") +- ๐Ÿ“Š You want dashboard values representing typical conditions +- ๐ŸŽฏ You compare price levels across days + +**Choose Mean if:** +- ๐Ÿ’ฐ You calculate costs and budgets +- ๐Ÿงฎ You need mathematical accuracy for financial planning +- ๐Ÿ“Š You track actual average costs over time + +**Pro tip:** Most users prefer **Median** for displays, but use the `price_mean` attribute in cost calculation automations. diff --git a/docs/user/docs/config-peak-price.md b/docs/user/docs/config-peak-price.md new file mode 100644 index 0000000..0a39017 --- /dev/null +++ b/docs/user/docs/config-peak-price.md @@ -0,0 +1,56 @@ +--- +sidebar_label: ๐Ÿ”ด Peak Price Period +--- + +# ๐Ÿ”ด Peak Price Period + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ ๐Ÿ”ด Peak Price Period** + +--- + +Peak Price Period sensors detect windows of time when electricity is expensive enough that you should avoid or postpone consumption. The binary sensor `is_peak_price_period` is `on` during these windows. + +The detection algorithm mirrors [Best Price Period](config-best-price.md), but in reverse โ€” looking for expensive intervals rather than cheap ones. + +See **[Period Calculation](period-calculation.md)** for an in-depth explanation of the detection algorithm and [Period Relaxation](period-relaxation.md) for how relaxation works. + +## Settings + +### Period Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| **Minimum period length** | 60 min | Shortest window to report as a period | +| **Minimum price level** | EXPENSIVE | Only intervals at this Tibber level or more expensive qualify | +| **Gap tolerance** | 1 | Consecutive below-threshold intervals allowed inside a period โ€” bridges small price dips between two expensive windows | + +### Flexibility Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| **Flex percentage** | -20% | How far below the daily maximum a price can be and still qualify (negative value = below maximum) | +| **Minimum distance from average** | 5% | Qualifying intervals must be at least this far above the daily average | + +### Relaxation & Target + +| Setting | Default | Description | +|---------|---------|-------------| +| **Enable minimum period target** | On | Automatically loosens criteria until the target count is reached | +| **Target periods per day** | 2 | How many distinct peak periods the algorithm aims to find per day | +| **Relaxation attempts** | 11 | How many times to loosen the criteria before giving up | + +## Runtime Override Entities + +Same concept as [Best Price overrides](config-best-price.md#runtime-override-entities) โ€” disabled by default, enable individually in Entities. + +| Entity | Type | Range | Overrides | +|--------|------|-------|-----------| +| `number._peak_price_flexibility` | Number | -50โ€“0% | Flex percentage | +| `number._peak_price_minimum_distance` | Number | 0โ€“50% | Minimum distance from average | +| `number._peak_price_minimum_period_length` | Number | 15โ€“180 min | Minimum period length | +| `number._peak_price_minimum_periods` | Number | 1โ€“10 | Target periods per day | +| `number._peak_price_relaxation_attempts` | Number | 1โ€“12 | Relaxation attempts | +| `number._peak_price_gap_tolerance` | Number | 0โ€“8 | Gap tolerance | +| `switch._peak_price_enable_relaxation` | Switch | On/Off | Enable relaxation | + +See **[Runtime Override Entities](config-runtime-overrides.md)** for full details on how overrides work, viewing entity descriptions, and recorder optimization. diff --git a/docs/user/docs/config-price-level.md b/docs/user/docs/config-price-level.md new file mode 100644 index 0000000..5bac6f4 --- /dev/null +++ b/docs/user/docs/config-price-level.md @@ -0,0 +1,37 @@ +--- +sidebar_label: ๐Ÿท๏ธ Price Level +--- + +# ๐Ÿท๏ธ Price Level Gap Tolerance + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ ๐Ÿท๏ธ Price Level** + +--- + +Tibber's API assigns each interval a price level: VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, or VERY_EXPENSIVE. In practice, a single interval can jump to a different level briefly before jumping back โ€” creating isolated "noise" intervals that make sensors flicker. + +Gap tolerance smooths this out. + +## Setting + +| Setting | Default | Description | +|---------|---------|-------------| +| **Gap tolerance** | 1 | Number of consecutive "mismatched" intervals to fill in automatically | + +### Example + +With gap tolerance = 1, a lone NORMAL interval surrounded by CHEAP on both sides is automatically corrected to CHEAP: + +``` +Before: CHEAP CHEAP NORMAL CHEAP CHEAP +After: CHEAP CHEAP CHEAP CHEAP CHEAP + โ†‘ filled in +``` + +With gap tolerance = 0, no smoothing is applied and every interval uses the raw API level. + +## Notes + +- This applies to Tibber's own level classification (separate from the [Price Rating](config-price-rating.md) which is calculated by this integration) +- Increasing gap tolerance beyond 2 is rarely useful โ€” larger gaps usually represent genuine price differences +- The gap tolerance here only affects level sensors; the separate gap tolerance in [Best Price](config-best-price.md) and [Peak Price](config-peak-price.md) settings controls period merging behavior diff --git a/docs/user/docs/config-price-rating.md b/docs/user/docs/config-price-rating.md new file mode 100644 index 0000000..c76f965 --- /dev/null +++ b/docs/user/docs/config-price-rating.md @@ -0,0 +1,44 @@ +--- +sidebar_label: ๐Ÿ“Š Price Rating +--- + +# ๐Ÿ“Š Price Rating Thresholds + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ ๐Ÿ“Š Price Rating** + +--- + +Price ratings classify each 15-minute interval as **LOW**, **NORMAL**, or **HIGH** relative to the 24-hour trailing average. Sensors and automations can use these ratings to decide when to run appliances. + +See **[Ratings & Levels](sensors-ratings-levels.md)** for a full explanation of how ratings work and which sensors expose them. + +## Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| **Low threshold** | -10% | Prices this far below the trailing average โ†’ rated **LOW** | +| **High threshold** | +10% | Prices this far above the trailing average โ†’ rated **HIGH** | +| **Hysteresis** | 2% | Buffer zone around thresholds โ€” prevents rapid flickering when a price hovers right at the boundary | +| **Gap tolerance** | 1 | Smooths isolated rating blocks: a lone NORMAL interval surrounded by LOW on both sides gets corrected to LOW | + +## How thresholds are applied + +``` +Trailing 24h average: 20 ct/kWh +Low threshold: -10% โ†’ prices โ‰ค 18 ct โ†’ LOW +High threshold: +10% โ†’ prices โ‰ฅ 22 ct โ†’ HIGH +Everything else โ†’ NORMAL +``` + +Hysteresis adds an inner dead-band: once a rating is set to LOW, it stays LOW until the price rises above `18 ct + 2% = 18.36 ct`. This prevents sensors from flickering between LOW and NORMAL when prices are right at the boundary. + +## Adjusting for your market + +**Markets with low daily price variation** (e.g., day typically stays within ยฑ5%): +- Lower the thresholds: try -5% / +5% +- This keeps meaningful LOW/HIGH periods even on calm days + +**Markets with high daily variation** (e.g., ยฑ30% swings): +- Raise the thresholds: try -15% / +15% +- This reserves LOW/HIGH for genuinely exceptional periods only +- Consider using [Volatility](config-volatility.md) sensors alongside ratings on such days diff --git a/docs/user/docs/config-price-trend.md b/docs/user/docs/config-price-trend.md new file mode 100644 index 0000000..df8c3a7 --- /dev/null +++ b/docs/user/docs/config-price-trend.md @@ -0,0 +1,40 @@ +--- +sidebar_label: ๐Ÿ“ˆ Price Trend +--- + +# ๐Ÿ“ˆ Price Trend Thresholds + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ ๐Ÿ“ˆ Price Trend** + +--- + +Price trend sensors compare the upcoming price average to the current price and report whether prices are rising, falling, or stable. These thresholds define how much of a change is required before the trend sensor changes state. + +See **[Trend Sensors](sensors-trends.md)** for a full explanation of all trend sensors, how volatility-adaption works, and automation examples. + +## Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| **Rising** | +3% | Future average this much above current โ†’ `rising` | +| **Strongly rising** | +9% | Future average far above current โ†’ `strongly_rising` | +| **Falling** | -3% | Future average this much below current โ†’ `falling` | +| **Strongly falling** | -9% | Future average far below current โ†’ `strongly_falling` | + +Prices within the rising/falling range are reported as `stable`. + +## Volatility-adaptive thresholds + +On high-volatility days, the thresholds automatically widen to prevent the trend sensor from flickering constantly due to natural price variation. The effective threshold is scaled based on the day's [volatility level](config-volatility.md): + +- **Low volatility**: Thresholds used as-is +- **Moderate volatility**: Thresholds slightly widened +- **High / Very High volatility**: Thresholds significantly widened + +This means the same `rising` threshold (3%) may correspond to a 5% effective threshold on a volatile day. The scaling is automatic โ€” you only need to configure the baseline values here. + +## Adjusting for your market + +- If trend sensors flicker too often on typical days โ†’ increase all thresholds slightly (e.g., 4% / 12%) +- If trend sensors rarely change even on obviously moving price days โ†’ decrease thresholds (e.g., 2% / 6%) +- For markets with structural day/night patterns, consider using the `strongly_*` states in automations to ensure only major movements trigger actions diff --git a/docs/user/docs/config-runtime-overrides.md b/docs/user/docs/config-runtime-overrides.md new file mode 100644 index 0000000..0140ee6 --- /dev/null +++ b/docs/user/docs/config-runtime-overrides.md @@ -0,0 +1,110 @@ +--- +sidebar_label: ๐Ÿ” Runtime Override Entities +--- + +# Runtime Override Entities + +The integration provides optional **number** and **switch** entities that let you change Best Price and Peak Price detection settings at runtime โ€” through automations or the HA UI โ€” without going into the configuration menu. + +These entities are **disabled by default**. Enable them individually in: + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Entities** + +--- + +## How overrides work + +1. **Entity disabled** (default): The configuration menu setting is used +2. **Entity enabled**: The entity value overrides the menu setting +3. **Value changes**: Trigger immediate period recalculation +4. **HA restart**: Entity values are restored automatically + +This lets you write automations that adjust detection criteria seasonally, based on weather forecasts, or based on other conditions โ€” without manual configuration changes. + +## Available entities + +### Best Price Period + +| Entity | Type | Range | Overrides | +|--------|------|-------|-----------| +| `number._best_price_flexibility` | Number | 0โ€“50% | [Flex percentage](config-best-price.md) | +| `number._best_price_minimum_distance` | Number | -50โ€“0% | [Minimum distance from average](config-best-price.md) | +| `number._best_price_minimum_period_length` | Number | 15โ€“180 min | [Minimum period length](config-best-price.md) | +| `number._best_price_minimum_periods` | Number | 1โ€“10 | [Target periods per day](config-best-price.md) | +| `number._best_price_relaxation_attempts` | Number | 1โ€“12 | [Relaxation attempts](config-best-price.md) | +| `number._best_price_gap_tolerance` | Number | 0โ€“8 | [Gap tolerance](config-best-price.md) | +| `switch._best_price_enable_relaxation` | Switch | On/Off | [Enable relaxation](config-best-price.md) | + +### Peak Price Period + +| Entity | Type | Range | Overrides | +|--------|------|-------|-----------| +| `number._peak_price_flexibility` | Number | -50โ€“0% | [Flex percentage](config-peak-price.md) | +| `number._peak_price_minimum_distance` | Number | 0โ€“50% | [Minimum distance from average](config-peak-price.md) | +| `number._peak_price_minimum_period_length` | Number | 15โ€“180 min | [Minimum period length](config-peak-price.md) | +| `number._peak_price_minimum_periods` | Number | 1โ€“10 | [Target periods per day](config-peak-price.md) | +| `number._peak_price_relaxation_attempts` | Number | 1โ€“12 | [Relaxation attempts](config-peak-price.md) | +| `number._peak_price_gap_tolerance` | Number | 0โ€“8 | [Gap tolerance](config-peak-price.md) | +| `switch._peak_price_enable_relaxation` | Switch | On/Off | [Enable relaxation](config-peak-price.md) | + +## Viewing entity descriptions + +Each override entity has a `description` attribute explaining what the setting does โ€” the same text shown in the configuration menu. + +**Note for Number entities:** Home Assistant shows a history graph by default in the entity detail view, which hides the attributes panel. To see the description: + +1. Go to **Developer Tools โ†’ States** +2. Search for the entity (e.g., `number._best_price_flexibility`) +3. Expand the attributes section + +Switch entities show their attributes normally in the entity details view. + +## Example: Seasonal adjustment + +
+Show YAML: Stricter detection in winter months + +```yaml +automation: + - alias: "Winter: Stricter Best Price Detection" + trigger: + - platform: time + at: "00:00:00" + condition: + - condition: template + value_template: "{{ now().month in [11, 12, 1, 2] }}" + action: + - service: number.set_value + target: + entity_id: number._best_price_flexibility + data: + value: 10 # Stricter than default 15% +``` + +
+ +## Recorder optimization (optional) + +These entities are already designed to minimize database impact: +- **EntityCategory.CONFIG** โ€” excluded from Long-Term Statistics +- All attributes excluded from history recording +- Only state value (the number/switch state) is recorded + +If you want to **completely exclude** these entities from the recorder (no history graph, no database entries at all): + +
+Show YAML: Exclude from recorder + +```yaml +recorder: + exclude: + entity_globs: + - number.*_best_price_* + - number.*_peak_price_* + - switch.*_best_price_* + - switch.*_peak_price_* +``` + +
+ +This is useful if you rarely change these settings and want the smallest possible database footprint. diff --git a/docs/user/docs/config-volatility.md b/docs/user/docs/config-volatility.md new file mode 100644 index 0000000..e9466ce --- /dev/null +++ b/docs/user/docs/config-volatility.md @@ -0,0 +1,36 @@ +--- +sidebar_label: ๐Ÿ’จ Price Volatility +--- + +# ๐Ÿ’จ Price Volatility Thresholds + +**Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ ๐Ÿ’จ Price Volatility** + +--- + +Volatility sensors measure how much prices vary throughout the day using the **Coefficient of Variation (CV)** โ€” the ratio of the standard deviation to the mean. A higher CV means more extreme price swings and greater optimization potential. + +See **[Volatility Sensors](sensors-volatility.md)** for a full explanation of all volatility sensors and how to use them in automations. + +## Thresholds + +These thresholds define the boundaries between volatility levels: + +| Level | Default CV | Meaning | +|-------|-----------|---------| +| **Moderate** | โ‰ฅ 15% | Noticeable variation โ€” some optimization potential | +| **High** | โ‰ฅ 30% | Significant swings โ€” good for timing optimization | +| **Very High** | โ‰ฅ 50% | Extreme volatility โ€” maximum optimization benefit | + +Days below the Moderate threshold are classified as **Low** volatility. + +## Adjusting for your market + +The defaults work well for most European electricity markets. You may want to adjust if: + +- **Your market rarely exceeds 20% CV**: Lower the Moderate threshold to 10% so you still get meaningful classifications +- **Your market routinely hits 50%+ CV**: Raise the Very High threshold to 70%+ to distinguish truly exceptional days + +:::tip Volatility affects Trend thresholds too +The [Price Trend](config-price-trend.md) thresholds automatically widen on high-volatility days to prevent constant state changes. Changes here indirectly affect trend sensitivity. +::: diff --git a/docs/user/docs/configuration.md b/docs/user/docs/configuration.md index b7391c4..1ea828a 100644 --- a/docs/user/docs/configuration.md +++ b/docs/user/docs/configuration.md @@ -26,347 +26,43 @@ If you have multiple Tibber homes (e.g., different locations): 3. Select the additional home from the dropdown 4. Each home gets its own set of sensors with unique entity IDs -## Options Flow (Configuration Wizard) +## Options Menu -After initial setup, configure the integration through a multi-step wizard: +After initial setup, open the configuration menu at: **Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure** +A menu appears with all configuration sections. Pick any section, adjust settings, then return to the menu โ€” there is no required order. All sections have sensible defaults and can be revisited independently at any time. + ```mermaid -flowchart LR - S1["โ‘  General"] --> S2["โ‘ก Currency"] - S2 --> S3["โ‘ข Ratings"] - S3 --> S4["โ‘ฃ Levels"] - S4 --> S5["โ‘ค Volatility"] - S5 --> S6["โ‘ฅ Best Price"] - S6 --> S7["โ‘ฆ Peak Price"] - S7 --> S8["โ‘ง Trends"] - S8 --> S9["โ‘จ Chart"] +graph LR + Menu["โš™๏ธ Configure"] + Menu --> GS["โš™๏ธ General Settings"] + Menu --> DS["๐Ÿ’ฑ Currency Display"] + Menu --> PR["๐Ÿ“Š Price Rating"] + Menu --> PL["๐Ÿท๏ธ Price Level"] + Menu --> VO["๐Ÿ’จ Price Volatility"] + Menu --> BP["๐Ÿ’š Best Price Period"] + Menu --> PP["๐Ÿ”ด Peak Price Period"] + Menu --> PT["๐Ÿ“ˆ Price Trend"] + Menu --> CD["๐Ÿ“Š Chart Data Export"] + Menu --> RD["๐Ÿ”„ Reset to Defaults"] - style S1 fill:#e6f7ff,stroke:#00b9e7,stroke-width:2px - style S6 fill:#e6fff5,stroke:#00c853,stroke-width:2px - style S7 fill:#fff0f0,stroke:#ff5252,stroke-width:2px + style Menu fill:#e6f7ff,stroke:#00b9e7,stroke-width:2px + style BP fill:#e6fff5,stroke:#00c853,stroke-width:2px + style PP fill:#fff0f0,stroke:#ff5252,stroke-width:2px ``` -All steps have sensible defaults โ€” you can click through without changes and fine-tune later. - -### Step 1: General Settings - -- **Extended entity descriptions**: Show `description`, `long_description`, and `usage_tips` attributes on all sensors (useful for learning, can be disabled later to reduce attribute clutter) -- **Average sensor display**: Choose **Median** (typical price, spike-resistant) or **Mean** (mathematical average for cost calculations) - -### Step 2: Currency Display - -- **Base currency**: Shows prices as โ‚ฌ/kWh, kr/kWh (e.g., 0.25 โ‚ฌ/kWh) -- **Subunit**: Shows prices as ct/kWh, รธre/kWh (e.g., 25.3 ct/kWh) -- Smart defaults: EUR โ†’ subunit (cents), NOK/SEK/DKK โ†’ base currency (kroner) - -:::caution Choose early -Decide on your currency display mode **before** building automations or dashboard cards that rely on price sensor states or attributes. Switching later changes all price values (e.g., 25.34 ct โ†’ 0.2534 โ‚ฌ), which will break numeric thresholds in your automations, template sensors, and conditional cards. - -**If you do switch later:** - -1. A **repair notification** (from this integration) appears **immediately** in your sidebar โ€” it reminds you to update automations and dashboards. -2. Home Assistant's Recorder will detect the unit mismatch and show a **"The unit has changed"** dialog โ€” this may take a few minutes or until the next statistics run. Log warnings appear earlier. When it shows, choose **"Delete all old statistic data"** to start fresh. (Do not choose "Update the unit without converting" โ€” that re-labels the old numbers with the new unit, making historic values factually wrong.) -3. Update every **automation trigger and condition** that references a numeric price value. -4. Update **dashboard cards** with hardcoded thresholds or unit labels. -::: - -#### Price Precision and Rounding - -All prices are received from the Tibber API in base currency and processed without loss of precision. The sensor **state value** is stored with the following rounded precision: - -| Display Mode | Stored precision | Example | -|---|---|---| -| **Subunit** (ct, รธre) | 2 decimal places | 25.34 ct/kWh | -| **Base currency** (โ‚ฌ, kr) | 4 decimal places | 0.2534 โ‚ฌ/kWh | - -This applies to both **sensor states** and **attributes** (e.g., `energy_price`, `price_mean`, `price_min`, etc.). - -**Default display precision:** By default, HA shows fewer decimals than the stored value โ€” enough for a quick glance. The integration sets these defaults per sensor type: - -| Sensor type | Subunit default | Base currency default | -|---|---|---| -| **Current / Next / Previous interval price** | 2 decimals (25.34 ct) | 4 decimals (0.2534 โ‚ฌ) | -| **All other price sensors** (averages, min/max, โ€ฆ) | 1 decimal (25.3 ct) | 2 decimals (0.25 โ‚ฌ) | -| **Energy Dashboard sensor** | โ€” | 4 decimals (always) | - -You can increase the displayed precision per entity in the HA UI: - -1. Go to **Settings โ†’ Devices & Services โ†’ Entities** -2. Select a price sensor โ†’ click the gear icon -3. Change **Display precision** to your preference - -**Practical ceiling:** Subunit values (ct, รธre) have exactly 2 decimal places stored โ€” setting more than 2 will show trailing zeros. Base currency values have 4 decimal places stored โ€” 3โ€“4 decimals are meaningful. - -### Step 3: Price Rating Thresholds - -Configure how the integration classifies prices relative to the 24-hour trailing average: - -| Setting | Default | Description | -|---------|---------|-------------| -| **Low threshold** | -10% | Prices this much below average โ†’ **LOW** rating | -| **High threshold** | +10% | Prices this much above average โ†’ **HIGH** rating | -| **Hysteresis** | 2% | Prevents flickering at threshold boundaries | -| **Gap tolerance** | 1 | Smooth isolated rating blocks (e.g., lone NORMAL between two LOWs) | - -### Step 4: Price Level Gap Tolerance - -- **Gap tolerance** for Tibber's API-provided levels (VERY_CHEAP through VERY_EXPENSIVE) -- Smooths isolated level flickers: a single NORMAL surrounded by CHEAP โ†’ corrected to CHEAP -- Default: 1 interval tolerance - -### Step 5: Price Volatility Thresholds - -Configure the Coefficient of Variation (CV) boundaries: - -| Level | Default | Meaning | -|-------|---------|---------| -| **Moderate** | 15% | Noticeable price variation, some optimization potential | -| **High** | 30% | Significant price swings, good for timing optimization | -| **Very High** | 50% | Extreme volatility, maximum optimization benefit | - -### Step 6: Best Price Period - -Configure detection of favorable price windows. Three collapsible sections: - -**Period Settings:** -- Minimum period length (default: 60 min) -- Maximum price level to include (default: CHEAP) -- Gap tolerance: how many expensive intervals to bridge (default: 1) - -**Flexibility Settings:** -- Flex percentage (default: 15%): how far above the daily minimum a price can be to qualify -- Minimum distance from daily average (default: 5%): ensures periods are meaningfully cheaper - -**Relaxation & Target:** -- Enable minimum period target (default: on) -- Target periods per day (default: 2) -- Relaxation attempts (default: 11): steps to loosen criteria if target not met - -See [Period Calculation](period-calculation.md) for an in-depth explanation. - -### Step 7: Peak Price Period - -Mirrors Best Price configuration but for expensive windows. Detects periods to **avoid** consumption. - -### Step 8: Price Trend Thresholds - -Configure when trend sensors report rising/falling: - -| Setting | Default | Description | -|---------|---------|-------------| -| **Rising** | 3% | Future average this much above current โ†’ "rising" | -| **Strongly rising** | 9% | Future average far above current โ†’ "strongly_rising" | -| **Falling** | -3% | Future average this much below current โ†’ "falling" | -| **Strongly falling** | -9% | Future average far below current โ†’ "strongly_falling" | - -Thresholds are [volatility-adaptive](sensors-trends.md): automatically widened on volatile days to prevent constant state changes. - -### Step 9: Chart Data Export (Legacy) - -Information page for the legacy chart data export sensor. For new setups, use the [get_chartdata action](chart-actions.md) instead. - -## Configuration Options - -### Average Sensor Display Settings - -**Location:** Settings โ†’ Devices & Services โ†’ Tibber Prices โ†’ Configure โ†’ **General Settings** - -The integration allows you to choose how average price sensors display their values. This setting affects all average sensors (daily, 24h rolling, hourly smoothed, and future forecasts). - -#### Display Modes - -**Median (Default):** -- Shows the "middle value" when all prices are sorted -- **Resistant to extreme spikes** - one expensive hour doesn't skew the result -- Best for understanding **typical price levels** -- Example: "What was the typical price today?" - -**Arithmetic Mean:** -- Shows the mathematical average of all prices -- **Includes effect of spikes** - reflects actual cost if consuming evenly -- Best for **cost calculations and budgeting** -- Example: "What was my average cost per kWh today?" - -#### Why This Matters - -Consider a day with these hourly prices: -
-Show example: Mean vs Median - -``` -10, 12, 13, 15, 80 ct/kWh -``` - -
- -- **Median = 13 ct/kWh** โ† "Typical" price (middle value, ignores spike) -- **Mean = 26 ct/kWh** โ† Average cost (spike pulls it up) - -The median tells you the price was **typically** around 13 ct/kWh (4 out of 5 hours). The mean tells you if you consumed evenly, your **average cost** was 26 ct/kWh. - -#### Automation-Friendly Design - -**Both values are always available as attributes**, regardless of your display choice: - -
-Show YAML: Median and Mean Attributes - -```yaml -# These attributes work regardless of display setting: -{{ state_attr('sensor._price_today', 'price_median') }} -{{ state_attr('sensor._price_today', 'price_mean') }} -``` - -
- -This means: -- โœ… You can change the display anytime without breaking automations -- โœ… Automations can use both values for different purposes -- โœ… No need to create template sensors for the "other" value - -#### Affected Sensors - -This setting applies to: -- Daily average sensors (today, tomorrow) -- 24-hour rolling averages (trailing, leading) -- Hourly smoothed prices (current hour, next hour) -- Future forecast sensors (next 1h, 2h, 3h, ... 12h) - -See the **[Average Sensors](sensors-average.md)** for detailed examples. - -#### Choosing Your Display - -**Choose Median if:** -- ๐Ÿ‘ฅ You show prices to users ("What's today like?") -- ๐Ÿ“Š You want dashboard values that represent typical conditions -- ๐ŸŽฏ You compare price levels across days -- ๐Ÿ” You analyze volatility (comparing typical vs extremes) - -**Choose Mean if:** -- ๐Ÿ’ฐ You calculate costs and budgets -- ๐Ÿ“ˆ You forecast energy expenses -- ๐Ÿงฎ You need mathematical accuracy for financial planning -- ๐Ÿ“Š You track actual average costs over time - -**Pro Tip:** Most users prefer **Median** for displays (more intuitive), but use `price_mean` attribute in cost calculation automations. - -## Runtime Configuration Entities - -The integration provides optional configuration entities that allow you to override period calculation settings at runtime through automations. These entities are **disabled by default** and can be enabled individually as needed. - -### Available Configuration Entities - -When enabled, these entities override the corresponding Options Flow settings: - -#### Best Price Period Settings - -| Entity | Type | Range | Description | -|--------|------|-------|-------------| -| Best Price: Flexibility | Number | 0-50% | Maximum above daily minimum for "best price" intervals | -| Best Price: Minimum Distance | Number | -50-0% | Required distance below daily average | -| Best Price: Minimum Period Length | Number | 15-180 min | Shortest period duration to consider | -| Best Price: Minimum Periods | Number | 1-10 | Target number of periods per day | -| Best Price: Relaxation Attempts | Number | 1-12 | Steps to try when relaxing criteria | -| Best Price: Gap Tolerance | Number | 0-8 | Consecutive intervals allowed above threshold | -| Best Price: Achieve Minimum Count | Switch | On/Off | Enable relaxation algorithm | - -#### Peak Price Period Settings - -| Entity | Type | Range | Description | -|--------|------|-------|-------------| -| Peak Price: Flexibility | Number | -50-0% | Maximum below daily maximum for "peak price" intervals | -| Peak Price: Minimum Distance | Number | 0-50% | Required distance above daily average | -| Peak Price: Minimum Period Length | Number | 15-180 min | Shortest period duration to consider | -| Peak Price: Minimum Periods | Number | 1-10 | Target number of periods per day | -| Peak Price: Relaxation Attempts | Number | 1-12 | Steps to try when relaxing criteria | -| Peak Price: Gap Tolerance | Number | 0-8 | Consecutive intervals allowed below threshold | -| Peak Price: Achieve Minimum Count | Switch | On/Off | Enable relaxation algorithm | - -### How Runtime Overrides Work - -1. **Disabled (default):** The Options Flow setting is used -2. **Enabled:** The entity value overrides the Options Flow setting -3. **Value changes:** Trigger immediate period recalculation -4. **HA restart:** Entity values are restored automatically - -### Viewing Entity Descriptions - -Each configuration entity includes a detailed description attribute explaining what the setting does - the same information shown in the Options Flow. - -**Note:** For **Number entities**, Home Assistant displays a history graph by default, which hides the attributes panel. To view the `description` attribute: - -1. Go to **Developer Tools โ†’ States** -2. Search for the entity (e.g., `number._best_price_flexibility`) -3. Expand the attributes section to see the full description - -**Switch entities** display their attributes normally in the entity details view. - -### Example: Seasonal Automation - -
-Show YAML: Seasonal Runtime Override - -```yaml -automation: - - alias: "Winter: Stricter Best Price Detection" - trigger: - - platform: time - at: "00:00:00" - condition: - - condition: template - value_template: "{{ now().month in [11, 12, 1, 2] }}" - action: - - service: number.set_value - target: - entity_id: number._best_price_flexibility - data: - value: 10 # Stricter than default 15% -``` - -
- -### Recorder Optimization (Optional) - -These configuration entities are designed to minimize database impact: -- **EntityCategory.CONFIG** - Excluded from Long-Term Statistics -- All attributes excluded from history recording -- Only state value changes are recorded - -If you frequently adjust these settings via automations or want to track configuration changes over time, the default behavior is fine. - -However, if you prefer to **completely exclude** these entities from the recorder (no history graph, no database entries), add this to your `configuration.yaml`: - -
-Show YAML: Exclude Runtime Config Entities - -```yaml -recorder: - exclude: - entity_globs: - # Exclude all Tibber Prices configuration entities - - number.*_best_price_* - - number.*_peak_price_* - - switch.*_best_price_* - - switch.*_peak_price_* -``` - -
- -This is especially useful if: -- You rarely change these settings -- You want the smallest possible database footprint -- You don't need to see the history graph for these entities - -#### Price Sensor Statistics - -The integration also minimizes long-term statistics growth for price sensors. Only 3 sensors write to the HA statistics database (which is never auto-purged): - -- **Current Electricity Price** โ€” Long-term price trend over weeks/months -- **Current Electricity Price (Energy Dashboard)** โ€” Required for Energy Dashboard integration -- **Today's Average Price** โ€” Seasonal price comparison - -All other price sensors (forecasts, rolling averages, daily min/max, future averages) have long-term statistics disabled. Their **state history** (the step chart in the History panel) still works normally for ~10 days โ€” only the smooth statistics line-chart on the entity detail page is absent for these sensors. - -No configuration changes are needed โ€” this optimization is built into the integration. +| Section | What you configure | +|---------|-------------------| +| [โš™๏ธ General Settings](config-general.md) | Extended descriptions, average sensor display mode (Median / Mean) | +| [๐Ÿ’ฑ Currency Display](config-currency.md) | Base currency vs. subunit display, price precision | +| [๐Ÿ“Š Price Rating](config-price-rating.md) | LOW / HIGH thresholds, hysteresis, gap tolerance | +| [๐Ÿท๏ธ Price Level](config-price-level.md) | Gap tolerance for Tibber's API-provided level classifications | +| [๐Ÿ’จ Price Volatility](config-volatility.md) | CV thresholds for Moderate / High / Very High volatility | +| [๐Ÿ’š Best Price Period](config-best-price.md) | Cheap window detection: flex, distance, relaxation, runtime overrides | +| [๐Ÿ”ด Peak Price Period](config-peak-price.md) | Expensive window detection: same settings, opposite direction | +| [๐Ÿ“ˆ Price Trend](config-price-trend.md) | Rising / Falling thresholds for trend sensors | +| [๐Ÿ“Š Chart Data Export](config-chart-export.md) | Legacy chart export sensor (new setups: use [Chart Actions](chart-actions.md)) | + +Advanced: [๐Ÿ” Runtime Override Entities](config-runtime-overrides.md) โ€” number and switch entities for automating configuration changes at runtime. diff --git a/docs/user/sidebars.ts b/docs/user/sidebars.ts index 7b86dd1..89686af 100644 --- a/docs/user/sidebars.ts +++ b/docs/user/sidebars.ts @@ -19,7 +19,28 @@ const sidebars: SidebarsConfig = { type: 'category', label: '๐Ÿš€ Getting Started', link: { type: 'doc', id: 'installation' }, - items: ['installation', 'configuration'], + items: [ + 'installation', + { + type: 'category', + label: 'โš™๏ธ Configuration', + link: { type: 'doc', id: 'configuration' }, + items: [ + 'config-general', + 'config-currency', + 'config-price-rating', + 'config-price-level', + 'config-volatility', + 'config-best-price', + 'config-peak-price', + 'config-price-trend', + 'config-chart-export', + 'config-runtime-overrides', + ], + collapsible: true, + collapsed: true, + }, + ], collapsible: true, collapsed: false, },