mirror of
https://github.com/jpawlowski/hass.tibber_prices.git
synced 2026-03-30 05:13:40 +00:00
docs(user): add comprehensive average sensor documentation
Expanded user documentation with detailed guidance on average sensors: 1. sensors.md (+182 lines): - New 'Average Price Sensors' section with mean vs median explanation - 3 real-world automation examples (heat pump, dishwasher, EV charging) - Display configuration guide with use-case recommendations 2. configuration.md (+75 lines): - New 'Average Sensor Display Settings' section - Comparison table of display modes (mean/median/both) - Attribute availability details and recorder implications 3. Minor updates to installation.md and versioned docs Impact: Users can now understand when to use mean vs median and how to configure display format for their specific automation needs.
This commit is contained in:
Julian Pawlowski
parent
0a06e12afb
commit
b815aea8bf
9 changed files with 259 additions and 12 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Configuration
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for configuration instructions.
|
||||
> **Note:** This guide is under construction. For detailed setup instructions, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md).
|
||||
|
||||
## Initial Setup
|
||||
|
||||
|
|
@ -8,8 +8,77 @@ Coming soon...
|
|||
|
||||
## Configuration Options
|
||||
|
||||
Coming soon...
|
||||
### Average Sensor Display Settings
|
||||
|
||||
## Price Thresholds
|
||||
**Location:** Settings → Devices & Services → Tibber Prices → Configure → Step 6
|
||||
|
||||
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:
|
||||
```
|
||||
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:
|
||||
|
||||
```yaml
|
||||
# These attributes work regardless of display setting:
|
||||
{{ state_attr('sensor.tibber_home_average_price_today', 'price_median') }}
|
||||
{{ state_attr('sensor.tibber_home_average_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 **[Sensors Guide](sensors.md#average-price-sensors)** 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.
|
||||
|
||||
Coming soon...
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Installation
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for installation instructions.
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for installation instructions.
|
||||
|
||||
## HACS Installation (Recommended)
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ comments: false
|
|||
|
||||
# Sensors
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for available sensors.
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for available sensors.
|
||||
|
||||
> **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.
|
||||
|
||||
|
|
@ -23,7 +23,185 @@ Both sensors include rich attributes with period details, intervals, relaxation
|
|||
|
||||
## Core Price Sensors
|
||||
|
||||
Coming soon...
|
||||
### Average Price Sensors
|
||||
|
||||
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.
|
||||
|
||||
#### Available Average Sensors
|
||||
|
||||
| Sensor | Description | Time Window |
|
||||
|--------|-------------|-------------|
|
||||
| **Average Price Today** | Typical price for current calendar day | 00:00 - 23:59 today |
|
||||
| **Average Price Tomorrow** | Typical price for next calendar day | 00:00 - 23:59 tomorrow |
|
||||
| **Trailing Price Average** | Typical price for last 24 hours | Rolling 24h backward |
|
||||
| **Leading Price Average** | Typical price for next 24 hours | Rolling 24h forward |
|
||||
| **Current Hour Average** | Smoothed price around current time | 5 intervals (~75 min) |
|
||||
| **Next Hour Average** | Smoothed price around next hour | 5 intervals (~75 min) |
|
||||
| **Next N Hours Average** | Future price forecast | 1h, 2h, 3h, 4h, 5h, 6h, 8h, 12h |
|
||||
|
||||
#### Configurable Display: Median vs Mean
|
||||
|
||||
All average sensors support **two different calculation methods** for the state value:
|
||||
|
||||
- **Median** (default): The "middle value" when all prices are sorted. Resistant to extreme price spikes, shows the **typical** price level you experienced.
|
||||
- **Arithmetic Mean**: The mathematical average including all prices. Better for **cost calculations** but affected by extreme spikes.
|
||||
|
||||
**Why two values matter:**
|
||||
|
||||
```yaml
|
||||
# Example price data for one day:
|
||||
# Prices: 10, 12, 13, 15, 80 ct/kWh (one extreme spike)
|
||||
#
|
||||
# Median = 13 ct/kWh ← "Typical" price level (middle value)
|
||||
# Mean = 26 ct/kWh ← Mathematical average (affected by spike)
|
||||
```
|
||||
|
||||
The median shows you what price level was **typical** during that period, while the mean shows the actual **average cost** if you consumed evenly throughout the period.
|
||||
|
||||
#### Configuring the Display
|
||||
|
||||
You can choose which value is displayed in the sensor state:
|
||||
|
||||
1. Go to **Settings → Devices & Services → Tibber Prices**
|
||||
2. Click **Configure** on your home
|
||||
3. Navigate to **Step 6: Average Sensor Display Settings**
|
||||
4. Choose between:
|
||||
- **Median** (default) - Shows typical price level, resistant to spikes
|
||||
- **Arithmetic Mean** - Shows actual mathematical average
|
||||
|
||||
**Important:** Both values are **always available** as sensor attributes, regardless of your choice! This ensures your automations continue to work if you change the display setting.
|
||||
|
||||
#### Using Both Values in Automations
|
||||
|
||||
Both `price_mean` and `price_median` are always available as attributes:
|
||||
|
||||
```yaml
|
||||
# Example: Get both values regardless of display setting
|
||||
sensor:
|
||||
- platform: template
|
||||
sensors:
|
||||
daily_price_analysis:
|
||||
friendly_name: "Daily Price Analysis"
|
||||
value_template: >
|
||||
{% set median = state_attr('sensor.tibber_home_average_price_today', 'price_median') %}
|
||||
{% set mean = state_attr('sensor.tibber_home_average_price_today', 'price_mean') %}
|
||||
{% set current = states('sensor.tibber_home_current_interval_price') | float %}
|
||||
|
||||
{% if current < median %}
|
||||
Below typical ({{ ((1 - current/median) * 100) | round(1) }}% cheaper)
|
||||
{% elif current < mean %}
|
||||
Typical price range
|
||||
{% else %}
|
||||
Above average ({{ ((current/mean - 1) * 100) | round(1) }}% more expensive)
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
#### Practical Examples
|
||||
|
||||
**Example 1: Smart dishwasher control**
|
||||
|
||||
Run dishwasher only when price is significantly below the daily typical level:
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
- alias: "Start Dishwasher When Cheap"
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: binary_sensor.tibber_home_best_price_period
|
||||
to: "on"
|
||||
condition:
|
||||
# Only if current price is at least 20% below typical (median)
|
||||
- condition: template
|
||||
value_template: >
|
||||
{% set current = states('sensor.tibber_home_current_interval_price') | float %}
|
||||
{% set median = state_attr('sensor.tibber_home_average_price_today', 'price_median') | float %}
|
||||
{{ current < (median * 0.8) }}
|
||||
action:
|
||||
- service: switch.turn_on
|
||||
entity_id: switch.dishwasher
|
||||
```
|
||||
|
||||
**Example 2: Cost-aware heating control**
|
||||
|
||||
Use mean for actual cost calculations:
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
- alias: "Heating Budget Control"
|
||||
trigger:
|
||||
- platform: time
|
||||
at: "06:00:00"
|
||||
action:
|
||||
# Calculate expected daily heating cost
|
||||
- variables:
|
||||
mean_price: "{{ state_attr('sensor.tibber_home_average_price_today', 'price_mean') | float }}"
|
||||
heating_kwh_per_day: 15 # Estimated consumption
|
||||
daily_cost: "{{ (mean_price * heating_kwh_per_day / 100) | round(2) }}"
|
||||
- service: notify.mobile_app
|
||||
data:
|
||||
title: "Heating Cost Estimate"
|
||||
message: "Expected cost today: €{{ daily_cost }} (avg price: {{ mean_price }} ct/kWh)"
|
||||
```
|
||||
|
||||
**Example 3: Smart charging based on rolling average**
|
||||
|
||||
Use trailing average to understand recent price trends:
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
- alias: "EV Charging - Price Trend Based"
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: sensor.ev_battery_level
|
||||
condition:
|
||||
# Start charging if current price < 90% of recent 24h average
|
||||
- condition: template
|
||||
value_template: >
|
||||
{% set current = states('sensor.tibber_home_current_interval_price') | float %}
|
||||
{% set trailing_avg = state_attr('sensor.tibber_home_trailing_price_average', 'price_median') | float %}
|
||||
{{ current < (trailing_avg * 0.9) }}
|
||||
# And battery < 80%
|
||||
- condition: numeric_state
|
||||
entity_id: sensor.ev_battery_level
|
||||
below: 80
|
||||
action:
|
||||
- service: switch.turn_on
|
||||
entity_id: switch.ev_charger
|
||||
```
|
||||
|
||||
#### Key Attributes
|
||||
|
||||
All average sensors provide these attributes:
|
||||
|
||||
| Attribute | Description | Example |
|
||||
|-----------|-------------|---------|
|
||||
| `price_mean` | Arithmetic mean (always available) | 25.3 ct/kWh |
|
||||
| `price_median` | Median value (always available) | 22.1 ct/kWh |
|
||||
| `interval_count` | Number of intervals included | 96 |
|
||||
| `timestamp` | Reference time for calculation | 2025-12-18T00:00:00+01:00 |
|
||||
|
||||
**Note:** The `price_mean` and `price_median` attributes are **always present** regardless of which value you configured for display. This ensures automation compatibility when changing the display setting.
|
||||
|
||||
#### When to Use Which Value
|
||||
|
||||
**Use Median for:**
|
||||
- ✅ Comparing "typical" price levels across days
|
||||
- ✅ Determining if current price is unusually high/low
|
||||
- ✅ User-facing displays ("What was today like?")
|
||||
- ✅ Volatility analysis (comparing typical vs extremes)
|
||||
|
||||
**Use Mean for:**
|
||||
- ✅ Cost calculations and budgeting
|
||||
- ✅ Energy cost estimations
|
||||
- ✅ Comparing actual average costs between periods
|
||||
- ✅ Financial planning and forecasting
|
||||
|
||||
**Both values tell different stories:**
|
||||
- High median + much higher mean = Expensive spikes occurred
|
||||
- Low median + higher mean = Generally cheap with occasional spikes
|
||||
- Similar median and mean = Stable prices (low volatility)
|
||||
|
||||
|
||||
|
||||
## Statistical Sensors
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Configuration
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for configuration instructions.
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for configuration instructions.
|
||||
|
||||
## Initial Setup
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Installation
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for installation instructions.
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for installation instructions.
|
||||
|
||||
## HACS Installation (Recommended)
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ comments: false
|
|||
|
||||
# Sensors
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for available sensors.
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for available sensors.
|
||||
|
||||
> **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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Configuration
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for configuration instructions.
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for configuration instructions.
|
||||
|
||||
## Initial Setup
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Installation
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for installation instructions.
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for installation instructions.
|
||||
|
||||
## HACS Installation (Recommended)
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ comments: false
|
|||
|
||||
# Sensors
|
||||
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/v0.20.0/README.md) for available sensors.
|
||||
> **Note:** This guide is under construction. For now, please refer to the [main README](https://github.com/jpawlowski/hass.tibber_prices/blob/main/README.md) for available sensors.
|
||||
|
||||
> **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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue