jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-05-28 18:43:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs(sensors): rename trend→outlook, document price_trajectory sensors

Browse source 
Updated user documentation to reflect renamed and new sensors.

sensors.md:
  - Section renamed "Simple Trend Sensors" → "Price Outlook Sensors (1h–12h)"
  - All price_trend_Xh entity references → price_outlook_Xh
  - Callout box updated: explains that outlook sensors can mislead at a
    price minimum and recommends combining with trajectory sensors
  - New section "Price Trajectory Sensors (2h–12h)" added before
    "Current Price Trend":
    - Table showing which halves are compared per window
    - Callout box with the 4 outlook+trajectory combination patterns
      (falling+rising = AT the minimum, etc.)
    - Key attributes table (first_half_avg, second_half_avg, half_diff_%)
  - "Trend Sensors vs Average Sensors" → "Outlook & Trajectory Sensors vs
    Average Sensors"

icon-colors.md:
  - "Price trend sensors (e.g., price_trend_3h)" → "Price outlook sensors
    (e.g., price_outlook_3h)"
  - Example entity updated to sensor.<home_name>_price_outlook_3h

automation-examples.md:
  - All price_trend_1h/2h/3h/4h/6h references → price_outlook_Xh
  - current_price_trend and next_price_trend_change unchanged (correct names)

Impact: Documentation matches actual entity names. New trajectory section
helps users understand when to use outlook vs trajectory sensors together.
This commit is contained in:
Julian Pawlowski 2026-04-09 16:09:04 +00:00
parent 2b96ccc650
commit cbf5e1a3fe
3 changed files with 74 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
docs/user/docs/automation-examples.md
View file

@ -124,14 +124,14 @@ automation:
# Conditions: Prices are falling AND we're approaching cheap levels # Conditions: Prices are falling AND we're approaching cheap levels
- condition: template - condition: template
value_template: > value_template: >
{% set trend_value = state_attr('sensor.<home_name>_price_trend_3h', 'trend_value') | int(0) %} {% set trend_value = state_attr('sensor.<home_name>_price_outlook_3h', 'trend_value') | int(0) %}
{% set level = state_attr('sensor.<home_name>_current_electricity_price', 'rating_level') %} {% set level = state_attr('sensor.<home_name>_current_electricity_price', 'rating_level') %}
{{ trend_value <= -1 and level in ['CHEAP', 'NORMAL'] }} {{ trend_value <= -1 and level in ['CHEAP', 'NORMAL'] }}
# AND: The next 3 hours will be cheaper on average # AND: The next 3 hours will be cheaper on average
- condition: template - condition: template
value_template: > value_template: >
{% set current = states('sensor.<home_name>_current_electricity_price') | float %} {% set current = states('sensor.<home_name>_current_electricity_price') | float %}
{% set future_avg = state_attr('sensor.<home_name>_price_trend_3h', 'next_3h_avg') | float %} {% set future_avg = state_attr('sensor.<home_name>_price_outlook_3h', 'next_3h_avg') | float %}
{{ future_avg < current }} {{ future_avg < current }}
action: action:
- service: water_heater.set_temperature - service: water_heater.set_temperature
@ -189,9 +189,9 @@ automation:
Falling = current price is HIGHER than future average = wait. Falling = current price is HIGHER than future average = wait.
trigger: trigger:
- platform: state - platform: state
entity_id: sensor.<home_name>_price_trend_1h entity_id: sensor.<home_name>_price_outlook_1h
- platform: state - platform: state
entity_id: sensor.<home_name>_price_trend_6h entity_id: sensor.<home_name>_price_outlook_6h
condition: condition:
# Only consider if best price period is NOT active # Only consider if best price period is NOT active
# (if it IS active, a separate automation handles it) # (if it IS active, a separate automation handles it)
@ -204,8 +204,8 @@ automation:
- conditions: - conditions:
- condition: template - condition: template
value_template: > value_template: >
{% set t1 = state_attr('sensor.<home_name>_price_trend_1h', 'trend_value') | int(0) %} {% set t1 = state_attr('sensor.<home_name>_price_outlook_1h', 'trend_value') | int(0) %}
{% set t6 = state_attr('sensor.<home_name>_price_trend_6h', 'trend_value') | int(0) %} {% set t6 = state_attr('sensor.<home_name>_price_outlook_6h', 'trend_value') | int(0) %}
{{ t1 >= 1 and t6 >= 1 }} {{ t1 >= 1 and t6 >= 1 }}
sequence: sequence:
- service: climate.set_temperature - service: climate.set_temperature
@ -217,8 +217,8 @@ automation:
- conditions: - conditions:
- condition: template - condition: template
value_template: > value_template: >
{% set t1 = state_attr('sensor.<home_name>_price_trend_1h', 'trend_value') | int(0) %} {% set t1 = state_attr('sensor.<home_name>_price_outlook_1h', 'trend_value') | int(0) %}
{% set t6 = state_attr('sensor.<home_name>_price_trend_6h', 'trend_value') | int(0) %} {% set t6 = state_attr('sensor.<home_name>_price_outlook_6h', 'trend_value') | int(0) %}
{{ t1 <= -1 and t6 >= 1 }} {{ t1 <= -1 and t6 >= 1 }}
sequence: sequence:
# Short-term dip — wait for it to bottom out # Short-term dip — wait for it to bottom out
@ -231,7 +231,7 @@ automation:
- conditions: - conditions:
- condition: template - condition: template
value_template: > value_template: >
{% set t6 = state_attr('sensor.<home_name>_price_trend_6h', 'trend_value') | int(0) %} {% set t6 = state_attr('sensor.<home_name>_price_outlook_6h', 'trend_value') | int(0) %}
{{ t6 <= -1 }} {{ t6 <= -1 }}
sequence: sequence:
- service: climate.set_temperature - service: climate.set_temperature
@ -414,8 +414,8 @@ automation:
action: action:
# Compare different future windows to find cheapest start # Compare different future windows to find cheapest start
- variables: - variables:
next_2h: "{{ state_attr('sensor.<home_name>_price_trend_2h', 'next_2h_avg') | float(999) }}" next_2h: "{{ state_attr('sensor.<home_name>_price_outlook_2h', 'next_2h_avg') | float(999) }}"
next_4h: "{{ state_attr('sensor.<home_name>_price_trend_4h', 'next_4h_avg') | float(999) }}" next_4h: "{{ state_attr('sensor.<home_name>_price_outlook_4h', 'next_4h_avg') | float(999) }}"
daily_avg: "{{ state_attr('sensor.<home_name>_price_today', 'price_median') | float(999) }}" daily_avg: "{{ state_attr('sensor.<home_name>_price_today', 'price_median') | float(999) }}"
- service: notify.mobile_app - service: notify.mobile_app
data: data:

6
docs/user/docs/icon-colors.md
View file

@ -43,7 +43,7 @@ Many sensors provide the `icon_color` attribute for dynamic styling. To see if a
- Price level sensors (e.g., `current_price_level`) - Price level sensors (e.g., `current_price_level`)
- Price rating sensors (e.g., `current_price_rating`) - Price rating sensors (e.g., `current_price_rating`)
- Volatility sensors (e.g., `today_s_price_volatility`) - Volatility sensors (e.g., `today_s_price_volatility`)
- Price trend sensors (e.g., `price_trend_3h`) - Price outlook sensors (e.g., `price_outlook_3h`)
- Binary sensors (e.g., `best_price_period`, `peak_price_period`) - Binary sensors (e.g., `best_price_period`, `peak_price_period`)
- Timing sensors (e.g., `best_price_time_until_start`, `best_price_progress`) - Timing sensors (e.g., `best_price_time_until_start`, `best_price_progress`)
@ -282,8 +282,8 @@ cards:
]]] ]]]
- type: custom:button-card - type: custom:button-card
entity: sensor.<home_name>_price_trend_3h entity: sensor.<home_name>_price_outlook_3h
name: Next 3h Trend name: Next 3h Outlook
show_state: true show_state: true
styles: styles:
icon: icon:

81
docs/user/docs/sensors.md
View file

@ -552,32 +552,35 @@ automation:
## Trend Sensors ## Trend Sensors
Trend sensors help you understand **where prices are heading**. They answer the question: "Should I use electricity now, or wait?" Trend sensors help you understand **whether to act now or wait**. The integration provides two complementary families:
The integration provides two families of trend sensors for different use cases: - **Price Outlook Sensors (1h–12h):** Compare current price vs. future window average — "Is now cheaper than the next Nh on average?"
- **Price Trajectory Sensors (2h–12h):** Compare first half vs. second half of the window — "Are prices rising or falling *within* the window?"
### Simple Trend Sensors (1h–12h) ### Price Outlook Sensors (1h–12h)
These sensors compare the **current price** with the **average price** of the next N hours: These sensors compare the **current price** with the **average price** of the next N hours:
| Sensor | Compares Against | | Sensor | Compares Against |
|--------|-----------------| |--------|-----------------|
| **Price Trend (1h)** | Average of next 1 hour | | **Price Outlook (1h)** | Average of next 1 hour |
| **Price Trend (2h)** | Average of next 2 hours | | **Price Outlook (2h)** | Average of next 2 hours |
| **Price Trend (3h)** | Average of next 3 hours | | **Price Outlook (3h)** | Average of next 3 hours |
| **Price Trend (4h)** | Average of next 4 hours | | **Price Outlook (4h)** | Average of next 4 hours |
| **Price Trend (5h)** | Average of next 5 hours | | **Price Outlook (5h)** | Average of next 5 hours |
| **Price Trend (6h)** | Average of next 6 hours | | **Price Outlook (6h)** | Average of next 6 hours |
| **Price Trend (8h)** | Average of next 8 hours | | **Price Outlook (8h)** | Average of next 8 hours |
| **Price Trend (12h)** | Average of next 12 hours | | **Price Outlook (12h)** | Average of next 12 hours |
:::info Same Starting Point — All Sensors Use Your Current Price :::info Same Starting Point — All Outlook Sensors Use Your Current Price
All trend sensors share the **same base: your current 15-minute price**. They differ only in how far ahead they average. The windows **overlap** — the 3h average includes ALL intervals from the 1h and 2h windows, plus one more hour. All outlook sensors share the **same base: your current 15-minute price**. They differ only in how far ahead they average. The windows **overlap** — the 3h average includes ALL intervals from the 1h and 2h windows, plus one more hour.
**This means:** **This means:**
- `price_trend_3h` shows "current price vs. average of the **entire** next 3 hours" — **not** "what happens between hour 2 and hour 3" - `price_outlook_3h` shows "current price vs. average of the **entire** next 3 hours" — **not** "what happens between hour 2 and hour 3"
- If 1h shows `falling` but 6h shows `rising`: near-term prices are below your current price, but looking at the full 6h window (which includes expensive evening hours), the overall average is above your current price - If 1h shows `falling` but 6h shows `rising`: near-term prices are below your current price, but looking at the full 6h window (which includes expensive evening hours), the overall average is above your current price
- Larger windows smooth out short-term fluctuations — a 30-minute price spike affects the 1h average more than the 6h average - Larger windows smooth out short-term fluctuations — a 30-minute price spike affects the 1h average more than the 6h average
**⚠️ At a price minimum, outlook sensors can be misleading!** If you're at the minimum and prices are about to rise, `price_outlook_3h` may still show `strongly_falling` because the cheap minimum pulls the 3h average below your current high price. Use `price_trajectory_3h` to see the direction *within* the window.
::: :::
**States:** Each sensor has one of five states: **States:** Each sensor has one of five states:
@ -626,6 +629,42 @@ stateDiagram-v2
**Tip:** The `trend_value` attribute (`-2` to `+2`) is ideal for automations — use numeric comparisons instead of matching translated state strings. **Tip:** The `trend_value` attribute (`-2` to `+2`) is ideal for automations — use numeric comparisons instead of matching translated state strings.
### Price Trajectory Sensors (2h–12h)
These sensors compare the **first half** of the future window against the **second half** — revealing the price *direction within* the window.
| Sensor | Compares |
|--------|----------|
| **Price Trajectory (2h)** | Avg of hour 1 vs avg of hour 2 |
| **Price Trajectory (3h)** | Avg of first 1.5h vs avg of second 1.5h |
| **Price Trajectory (4h)** | Avg of first 2h vs avg of second 2h |
| **Price Trajectory (5h)** | Avg of first 2.5h vs avg of second 2.5h |
| **Price Trajectory (6h)** | Avg of first 3h vs avg of second 3h |
| **Price Trajectory (8h)** | Avg of first 4h vs avg of second 4h |
| **Price Trajectory (12h)** | Avg of first 6h vs avg of second 6h |
**States:** Same 5-level scale as outlook sensors (`strongly_falling` → `strongly_rising`).
:::info Why trajectory sensors complement outlook sensors
**At a price minimum** — the exact moment you should act — `price_outlook_3h` may show `strongly_falling` because the cheap minimum pulls the entire 3h average below your current high price. But `price_trajectory_3h` shows `rising` because the second half (after the minimum) is more expensive than the first half.
| Combination | Interpretation |
|-------------|----------------|
| Outlook `falling` + Trajectory `rising` | **You're AT the minimum** — act now |
| Outlook `falling` + Trajectory `falling` | Prices still dropping — wait |
| Outlook `rising` + Trajectory `rising` | Strong signal to act now |
| Outlook `rising` + Trajectory `falling` | Short spike, then cheaper — wait |
:::
**Key attributes:**
| Attribute | Description | Example |
|-----------|-------------|---------|
| `trend_value` | Numeric value for automations (-2 to +2) | `1` |
| `first_half_avg` | Average price in first half of window | `12.4` |
| `second_half_avg` | Average price in second half of window | `18.1` |
| `half_diff_%` | Percentage difference (second vs first half) | `46.0` |
### Current Price Trend ### Current Price Trend
**Entity ID:** `sensor.<home_name>_current_price_trend` **Entity ID:** `sensor.<home_name>_current_price_trend`
@ -701,16 +740,16 @@ A natural intuition is to treat trend states like a stock ticker:
#### Basic Automation Pattern #### Basic Automation Pattern
For most appliances (dishwasher, washing machine, dryer), a single trend sensor is enough: For most appliances (dishwasher, washing machine, dryer), a single outlook sensor is enough:
```yaml ```yaml
# Example: Start dishwasher when prices are favorable # Example: Start dishwasher when prices are favorable
trigger: trigger:
- platform: state - platform: state
entity_id: sensor.my_home_price_trend_3h entity_id: sensor.my_home_price_outlook_3h
condition: condition:
- condition: numeric_state - condition: numeric_state
entity_id: sensor.my_home_price_trend_3h entity_id: sensor.my_home_price_outlook_3h
attribute: trend_value attribute: trend_value
# rising (1) or strongly_rising (2) = act now # rising (1) or strongly_rising (2) = act now
above: 0 above: 0
@ -724,7 +763,7 @@ action:
When short-term and long-term trends disagree, you get richer insight: When short-term and long-term trends disagree, you get richer insight:
| 1h Trend | 6h Trend | Interpretation | Recommendation | | 1h Outlook | 6h Outlook | Interpretation | Recommendation |
|----------|----------|---------------|----------------| |----------|----------|---------------|----------------|
| `rising` | `rising` | Prices going up across the board | **Start now** | | `rising` | `rising` | Prices going up across the board | **Start now** |
| `falling` | `falling` | Prices dropping across the board | **Wait** | | `falling` | `falling` | Prices dropping across the board | **Wait** |
@ -740,12 +779,12 @@ On your dashboard, trend sensors give an instant overview:
- 🔴 All **rising/strongly_rising** → "Start everything you can — it only gets more expensive" - 🔴 All **rising/strongly_rising** → "Start everything you can — it only gets more expensive"
- 🟡 **Mixed** → Compare short-term vs. long-term sensors, or check the Best Price Period sensor - 🟡 **Mixed** → Compare short-term vs. long-term sensors, or check the Best Price Period sensor
### Trend Sensors vs Average Sensors ### Outlook & Trajectory Sensors vs Average Sensors
Both sensor families provide future price information, but serve different purposes: Both sensor families provide future price information, but serve different purposes:
| | Trend Sensors | Average Sensors | | | Outlook/Trajectory Sensors | Average Sensors |
|--|---------------|-----------------| |--|---------------------------|-----------------|
| **Purpose** | Dashboard display, quick visual overview | Automations, precise numeric comparisons | | **Purpose** | Dashboard display, quick visual overview | Automations, precise numeric comparisons |
| **Output** | Classification (falling/stable/rising) | Exact price values (ct/kWh) | | **Output** | Classification (falling/stable/rising) | Exact price values (ct/kWh) |
| **Best for** | "Should I worry about prices?" | "Is the future average below 15 ct?" | | **Best for** | "Should I worry about prices?" | "Is the future average below 15 ct?" |