diff --git a/docs/user/docs/actions.md b/docs/user/docs/actions.md index 73f0240..5a8908e 100644 --- a/docs/user/docs/actions.md +++ b/docs/user/docs/actions.md @@ -32,6 +32,10 @@ If you have configured more than one Tibber home, each home has its own config e ### Scheduling Actions +:::warning Experimental +The scheduling actions and `plan_charging` are **experimental** and still undergoing testing. Their parameters and response formats may change in future releases. Use them with care and [report issues](https://github.com/jpawlowski/hass.tibber_prices/issues). +::: + 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 | diff --git a/docs/user/docs/chart-actions.md b/docs/user/docs/chart-actions.md index 1c217bf..517b94c 100644 --- a/docs/user/docs/chart-actions.md +++ b/docs/user/docs/chart-actions.md @@ -68,6 +68,7 @@ response_variable: chart_data | `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` | +| `price_source` | Primary price series: `total`, `energy`, or `tax` | `total` | | `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) | @@ -135,6 +136,39 @@ data: 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. +### Price Source (`price_source`) + +By default, charts use the **total** price (energy + taxes + fees) as the main price series. With `price_source` you can switch the **primary** value to a single component instead: + +| Value | Main price series | +|-------|-------------------| +| `total` (default) | Full price including energy, taxes, and fees | +| `energy` | Raw spot/energy price only (excluding taxes and fees) | +| `tax` | Tax and fee component only | + +
+Show YAML: Chart based on the raw energy price + +```yaml +service: tibber_prices.get_chartdata +data: + entry_id: YOUR_CONFIG_ENTRY_ID + day: ["today", "tomorrow"] + price_source: energy # main price = spot price only +response_variable: chart_data +``` + +
+ +:::tip `price_source` vs. `include_energy` / `include_tax` +These solve different problems: + +- **`price_source`** changes *which* component becomes the **main** price value (one series). +- **`include_energy` / `include_tax`** (see below) keep the total price as main value but **add extra fields** so you can show energy and tax **alongside** the total in the same chart. +::: + +This parameter also applies to [`get_apexcharts_yaml`](#tibber_pricesget_apexcharts_yaml). + ### 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. @@ -291,6 +325,10 @@ card: - **`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 +**Price Source Option:** + +Like `get_chartdata`, this action accepts a `price_source` parameter (`total`, `energy`, or `tax`) to choose which price component the generated chart plots. Defaults to `total`. See [Price Source](#price-source-price_source) above for details. + **Best Price Period Highlights:** When `highlight_best_price: true`: diff --git a/docs/user/docs/concepts.md b/docs/user/docs/concepts.md index d658d09..3442b8e 100644 --- a/docs/user/docs/concepts.md +++ b/docs/user/docs/concepts.md @@ -97,7 +97,7 @@ Both shapes are reported as **`valley`** by the [Day Pattern sensor](sensors-pri **Why this matters:** On these days, the Best Price Period may be short (1–2 hours, covering only the absolute minimum), but prices can remain favorable for 4–6 hours. By combining [trend sensors](sensors-trends.md) with [price levels](sensors-ratings-levels.md) in automations, you can ride the full cheap wave instead of only using the detected period. -See [Automation Examples → V-Shaped Days](automation-examples.md#understanding-v-shaped-price-days) for practical patterns. +See [Automation Examples → Heat Pump Smart Boost](automation-examples.md#heat-pump-smart-boost-with-trend-awareness) for practical patterns. ## Multi-Home Support diff --git a/docs/user/docs/period-calculation.md b/docs/user/docs/period-calculation.md index efaac79..1621eb5 100644 --- a/docs/user/docs/period-calculation.md +++ b/docs/user/docs/period-calculation.md @@ -96,7 +96,7 @@ A Best Price Period is the **cheapest contiguous block** of time — a stretch o On a V-shaped day (prices drop sharply to a minimum, then rise again), the period therefore starts **at** the low point, not before it — because the intervals leading up to the minimum did not yet meet the price criteria. Only the intervals near the bottom of the V qualify as a coherent cheap block. -**For flexible loads** (e.g., heat pump, battery charging): you can easily ride the full cheap wave by combining the period sensor with the price level and trend sensors. See [V-Shaped Price Days in Automation Examples](./automation-examples.md#understanding-v-shaped-price-days). +**For flexible loads** (e.g., heat pump, battery charging): you can easily ride the full cheap wave by combining the period sensor with the price level and trend sensors. See [Heat Pump Smart Boost in Automation Examples](./automation-examples.md#heat-pump-smart-boost-with-trend-awareness). ::: ### Algorithm Overview @@ -586,7 +586,7 @@ As described in [Phase 6](#phase-6-relaxation-adaptive), relaxation automaticall ## Common Scenarios :::tip V-shaped price days -On days with a sharp price dip (e.g. solar midday surplus), the Best Price Period covers only the absolute minimum. The surrounding cheap hours are intentional — the integration shows you the cheapest contiguous block, not a fixed-length window centered on the minimum. To run a device during the full cheap window, see [Understanding V-Shaped Price Days](./automation-examples.md#understanding-v-shaped-price-days) in the Automation Examples. +On days with a sharp price dip (e.g. solar midday surplus), the Best Price Period covers only the absolute minimum. The surrounding cheap hours are intentional — the integration shows you the cheapest contiguous block, not a fixed-length window centered on the minimum. To run a device during the full cheap window, see [Heat Pump Smart Boost](./automation-examples.md#heat-pump-smart-boost-with-trend-awareness) in the Automation Examples. ::: ### Scenario 1: Simple Best Price (Default) diff --git a/docs/user/docs/plan-charging-action.md b/docs/user/docs/plan-charging-action.md index 7e9df36..94ad482 100644 --- a/docs/user/docs/plan-charging-action.md +++ b/docs/user/docs/plan-charging-action.md @@ -2,6 +2,10 @@ The `plan_charging` action turns **battery parameters** into a complete **cost-minimized charging schedule**. Instead of manually computing energy, duration, and power, you describe the battery (capacity, current SoC, target SoC, max power) and the action returns a per-interval plan with SoC progression, cost totals, and segment grouping. +:::warning Experimental +The `plan_charging` action is **experimental** and still undergoing testing. Its parameters, response format, and behavior may change in future releases. Use it in automations with care, and please [report any issues](https://github.com/jpawlowski/hass.tibber_prices/issues). +::: + :::tip When to use this If you already know the duration in minutes and just need the cheapest time window, use [`find_cheapest_hours`](scheduling-actions.md#find-cheapest-hours) or [`find_cheapest_block`](scheduling-actions.md#find-cheapest-block). Use `plan_charging` when you know your battery/EV parameters and want the integration to compute the duration, account for charging losses, and produce a SoC progression. ::: diff --git a/docs/user/docs/scheduling-actions.md b/docs/user/docs/scheduling-actions.md index c2fa22d..605489a 100644 --- a/docs/user/docs/scheduling-actions.md +++ b/docs/user/docs/scheduling-actions.md @@ -2,6 +2,10 @@ Find the cheapest (or most expensive) time windows for your appliances — automatically. These actions analyze real Tibber price data and return optimal scheduling recommendations. +:::warning Experimental +The scheduling actions (`find_cheapest_block`, `find_cheapest_hours`, `find_cheapest_schedule`, `find_most_expensive_block`, `find_most_expensive_hours`) are **experimental** and still undergoing testing. Their parameters, response formats, and behavior may change in future releases. Use them in automations with care, and please [report any issues](https://github.com/jpawlowski/hass.tibber_prices/issues). +::: + :::tip Entity ID tip `` 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. :::