diff --git a/docs/user/docs/configuration.md b/docs/user/docs/configuration.md index 71af28f..be69eec 100644 --- a/docs/user/docs/configuration.md +++ b/docs/user/docs/configuration.md @@ -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... diff --git a/docs/user/docs/installation.md b/docs/user/docs/installation.md index f071e22..9c7bc21 100644 --- a/docs/user/docs/installation.md +++ b/docs/user/docs/installation.md @@ -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) diff --git a/docs/user/docs/sensors.md b/docs/user/docs/sensors.md index 77f4512..c62c4ac 100644 --- a/docs/user/docs/sensors.md +++ b/docs/user/docs/sensors.md @@ -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 diff --git a/docs/user/versioned_docs/version-v0.21.0/configuration.md b/docs/user/versioned_docs/version-v0.21.0/configuration.md index 71af28f..59a8b2a 100644 --- a/docs/user/versioned_docs/version-v0.21.0/configuration.md +++ b/docs/user/versioned_docs/version-v0.21.0/configuration.md @@ -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 diff --git a/docs/user/versioned_docs/version-v0.21.0/installation.md b/docs/user/versioned_docs/version-v0.21.0/installation.md index f071e22..9c7bc21 100644 --- a/docs/user/versioned_docs/version-v0.21.0/installation.md +++ b/docs/user/versioned_docs/version-v0.21.0/installation.md @@ -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) diff --git a/docs/user/versioned_docs/version-v0.21.0/sensors.md b/docs/user/versioned_docs/version-v0.21.0/sensors.md index 77f4512..3871113 100644 --- a/docs/user/versioned_docs/version-v0.21.0/sensors.md +++ b/docs/user/versioned_docs/version-v0.21.0/sensors.md @@ -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. diff --git a/docs/user/versioned_docs/version-v0.22.0/configuration.md b/docs/user/versioned_docs/version-v0.22.0/configuration.md index 71af28f..59a8b2a 100644 --- a/docs/user/versioned_docs/version-v0.22.0/configuration.md +++ b/docs/user/versioned_docs/version-v0.22.0/configuration.md @@ -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 diff --git a/docs/user/versioned_docs/version-v0.22.0/installation.md b/docs/user/versioned_docs/version-v0.22.0/installation.md index f071e22..9c7bc21 100644 --- a/docs/user/versioned_docs/version-v0.22.0/installation.md +++ b/docs/user/versioned_docs/version-v0.22.0/installation.md @@ -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) diff --git a/docs/user/versioned_docs/version-v0.22.0/sensors.md b/docs/user/versioned_docs/version-v0.22.0/sensors.md index 77f4512..3871113 100644 --- a/docs/user/versioned_docs/version-v0.22.0/sensors.md +++ b/docs/user/versioned_docs/version-v0.22.0/sensors.md @@ -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.