From 9c4ac6bce404813d93e7f7b1b6e4c73e333bfb88 Mon Sep 17 00:00:00 2001 From: Julian Pawlowski Date: Thu, 9 Apr 2026 18:28:06 +0000 Subject: [PATCH] docs(user): document energy price and tax breakdown Add new section 'Energy Price & Tax Breakdown' to sensors.md: - Attribute overview table (interval, min/max, daily avg sensors) - Use cases: solar feed-in/net metering, price composition analysis, dashboard cost breakdown with example YAML templates - Cache transition note for gradual data availability after update Add 'Energy & Tax Fields in get_chartdata' section to actions.md: - Parameter documentation with defaults - Example service call YAML - ApexCharts integration example with custom field names Impact: Users can discover and utilize the new energy/tax attributes with ready-to-use automation and dashboard examples. --- docs/user/docs/actions.md | 36 ++++++++++++++++ docs/user/docs/sensors.md | 87 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+) diff --git a/docs/user/docs/actions.md b/docs/user/docs/actions.md index 59e5255..1cc4010 100644 --- a/docs/user/docs/actions.md +++ b/docs/user/docs/actions.md @@ -134,6 +134,42 @@ data: 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 {#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_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 [Sensors — Energy Price & Tax Breakdown](sensors.md#energy-price--tax-breakdown) for more use cases. + --- ### tibber_prices.get_apexcharts_yaml diff --git a/docs/user/docs/sensors.md b/docs/user/docs/sensors.md index d9b9381..8cdcc28 100644 --- a/docs/user/docs/sensors.md +++ b/docs/user/docs/sensors.md @@ -466,6 +466,93 @@ All min/max sensors include: | `price_diff_from_daily_min` | Difference from daily minimum | | `price_diff_from_daily_min_%` | Percentage difference | +## Energy Price & Tax Breakdown + +Many price sensors expose the **raw energy price** (spot price) and the **tax component** as additional attributes. These are sourced directly from the Tibber API's `energy` and `tax` fields, which together make up the `total` price you see in the sensor state: + +$$\text{total} = \text{energy} + \text{tax}$$ + +### Where These Attributes Appear + +| Sensor Group | Attributes | Description | +|---|---|---| +| **Current/Next/Previous Interval Price** | `energy_price`, `tax` | Raw values for that specific 15-minute interval | +| **Today's/Tomorrow's Min/Max Price** | `energy_price`, `tax` | Values from the interval with the extreme price | +| **Today's/Tomorrow's Average Price** | `energy_price_mean`, `energy_price_median`, `tax_mean`, `tax_median` | Mean and median values across all intervals of the day | + +:::note Transition After Update +After updating the integration, the `energy_price` and `tax` attributes will appear gradually as new price data is fetched from the Tibber API. Existing cached intervals (up to ~2 days old) won't have these fields yet — the attributes will simply be absent until fresh data replaces them. No action needed. +::: + +### Use Cases + +#### Solar Feed-In & Net Metering (Saldering) + +In countries like the Netherlands, solar feed-in compensation is based on the **raw energy/spot price**, not the total consumer price. The `energy_price` attribute gives you exactly this value — no more reverse-engineering from the total price with fragile template calculations. + +```yaml +# Example: Decide whether to export solar power or consume it +# Compare energy price (what you'd earn by exporting) vs. total price (what you'd pay) +automation: + - alias: "Solar: Export or Consume" + trigger: + - platform: numeric_state + entity_id: sensor.solar_production_power + above: 2000 # Producing more than 2 kW + condition: + - condition: template + value_template: > + {% set energy = state_attr('sensor._current_electricity_price', 'energy_price') %} + {% set total = states('sensor._current_electricity_price') | float %} + {# Export when energy price is high relative to total — you earn more #} + {{ energy is not none and energy > (total * 0.4) }} + action: + - service: switch.turn_off + entity_id: switch.battery_charging # Don't charge battery, export instead +``` + +#### Price Composition Analysis + +Understand how your electricity price is structured — useful for comparing across days or spotting trends in market prices vs. fees: + +```yaml +# Template sensor showing tax share +template: + - sensor: + - name: "Electricity Tax Share" + unit_of_measurement: "%" + state: > + {% set tax = state_attr('sensor._current_electricity_price', 'tax') %} + {% set total = states('sensor._current_electricity_price') | float %} + {% if tax is not none and total > 0 %} + {{ ((tax / total) * 100) | round(1) }} + {% else %} + unavailable + {% endif %} +``` + +#### Dashboard: Daily Cost Breakdown + +Show users how today's average price splits into energy vs. tax: + +```yaml +# Mushroom chips card showing the split +type: custom:mushroom-chips-card +chips: + - type: template + icon: mdi:flash + content: > + ⚡ {{ state_attr('sensor._price_today', 'energy_price_mean') | round(1) }} ct + - type: template + icon: mdi:receipt-text + content: > + 🏛️ {{ state_attr('sensor._price_today', 'tax_mean') | round(1) }} ct +``` + +### In Chart Data Actions + +The `energy_price` and `tax` fields are also available in the `get_chartdata` action. See [Actions — Energy & Tax Fields](#energy--tax-fields-in-get_chartdata) for details. + ## Timing Sensors 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.