From cbf5e1a3fee2d4b20aa8c36a6cde29f757dec01e Mon Sep 17 00:00:00 2001 From: Julian Pawlowski Date: Thu, 9 Apr 2026 16:09:04 +0000 Subject: [PATCH] =?UTF-8?q?docs(sensors):=20rename=20trend=E2=86=92outlook?= =?UTF-8?q?,=20document=20price=5Ftrajectory=20sensors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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._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. --- docs/user/docs/automation-examples.md | 22 ++++---- docs/user/docs/icon-colors.md | 6 +- docs/user/docs/sensors.md | 81 ++++++++++++++++++++------- 3 files changed, 74 insertions(+), 35 deletions(-) diff --git a/docs/user/docs/automation-examples.md b/docs/user/docs/automation-examples.md index c82e0aa..7f47587 100644 --- a/docs/user/docs/automation-examples.md +++ b/docs/user/docs/automation-examples.md @@ -124,14 +124,14 @@ automation: # Conditions: Prices are falling AND we're approaching cheap levels - condition: template value_template: > - {% set trend_value = state_attr('sensor._price_trend_3h', 'trend_value') | int(0) %} + {% set trend_value = state_attr('sensor._price_outlook_3h', 'trend_value') | int(0) %} {% set level = state_attr('sensor._current_electricity_price', 'rating_level') %} {{ trend_value <= -1 and level in ['CHEAP', 'NORMAL'] }} # AND: The next 3 hours will be cheaper on average - condition: template value_template: > {% set current = states('sensor._current_electricity_price') | float %} - {% set future_avg = state_attr('sensor._price_trend_3h', 'next_3h_avg') | float %} + {% set future_avg = state_attr('sensor._price_outlook_3h', 'next_3h_avg') | float %} {{ future_avg < current }} action: - service: water_heater.set_temperature @@ -189,9 +189,9 @@ automation: Falling = current price is HIGHER than future average = wait. trigger: - platform: state - entity_id: sensor._price_trend_1h + entity_id: sensor._price_outlook_1h - platform: state - entity_id: sensor._price_trend_6h + entity_id: sensor._price_outlook_6h condition: # Only consider if best price period is NOT active # (if it IS active, a separate automation handles it) @@ -204,8 +204,8 @@ automation: - conditions: - condition: template value_template: > - {% set t1 = state_attr('sensor._price_trend_1h', 'trend_value') | int(0) %} - {% set t6 = state_attr('sensor._price_trend_6h', 'trend_value') | int(0) %} + {% set t1 = state_attr('sensor._price_outlook_1h', 'trend_value') | int(0) %} + {% set t6 = state_attr('sensor._price_outlook_6h', 'trend_value') | int(0) %} {{ t1 >= 1 and t6 >= 1 }} sequence: - service: climate.set_temperature @@ -217,8 +217,8 @@ automation: - conditions: - condition: template value_template: > - {% set t1 = state_attr('sensor._price_trend_1h', 'trend_value') | int(0) %} - {% set t6 = state_attr('sensor._price_trend_6h', 'trend_value') | int(0) %} + {% set t1 = state_attr('sensor._price_outlook_1h', 'trend_value') | int(0) %} + {% set t6 = state_attr('sensor._price_outlook_6h', 'trend_value') | int(0) %} {{ t1 <= -1 and t6 >= 1 }} sequence: # Short-term dip — wait for it to bottom out @@ -231,7 +231,7 @@ automation: - conditions: - condition: template value_template: > - {% set t6 = state_attr('sensor._price_trend_6h', 'trend_value') | int(0) %} + {% set t6 = state_attr('sensor._price_outlook_6h', 'trend_value') | int(0) %} {{ t6 <= -1 }} sequence: - service: climate.set_temperature @@ -414,8 +414,8 @@ automation: action: # Compare different future windows to find cheapest start - variables: - next_2h: "{{ state_attr('sensor._price_trend_2h', 'next_2h_avg') | float(999) }}" - next_4h: "{{ state_attr('sensor._price_trend_4h', 'next_4h_avg') | float(999) }}" + next_2h: "{{ state_attr('sensor._price_outlook_2h', 'next_2h_avg') | float(999) }}" + next_4h: "{{ state_attr('sensor._price_outlook_4h', 'next_4h_avg') | float(999) }}" daily_avg: "{{ state_attr('sensor._price_today', 'price_median') | float(999) }}" - service: notify.mobile_app data: diff --git a/docs/user/docs/icon-colors.md b/docs/user/docs/icon-colors.md index 8e1a868..0ee1145 100644 --- a/docs/user/docs/icon-colors.md +++ b/docs/user/docs/icon-colors.md @@ -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 rating sensors (e.g., `current_price_rating`) - 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`) - Timing sensors (e.g., `best_price_time_until_start`, `best_price_progress`) @@ -282,8 +282,8 @@ cards: ]]] - type: custom:button-card - entity: sensor._price_trend_3h - name: Next 3h Trend + entity: sensor._price_outlook_3h + name: Next 3h Outlook show_state: true styles: icon: diff --git a/docs/user/docs/sensors.md b/docs/user/docs/sensors.md index 72e9086..d9b9381 100644 --- a/docs/user/docs/sensors.md +++ b/docs/user/docs/sensors.md @@ -552,32 +552,35 @@ automation: ## 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: | Sensor | Compares Against | |--------|-----------------| -| **Price Trend (1h)** | Average of next 1 hour | -| **Price Trend (2h)** | Average of next 2 hours | -| **Price Trend (3h)** | Average of next 3 hours | -| **Price Trend (4h)** | Average of next 4 hours | -| **Price Trend (5h)** | Average of next 5 hours | -| **Price Trend (6h)** | Average of next 6 hours | -| **Price Trend (8h)** | Average of next 8 hours | -| **Price Trend (12h)** | Average of next 12 hours | +| **Price Outlook (1h)** | Average of next 1 hour | +| **Price Outlook (2h)** | Average of next 2 hours | +| **Price Outlook (3h)** | Average of next 3 hours | +| **Price Outlook (4h)** | Average of next 4 hours | +| **Price Outlook (5h)** | Average of next 5 hours | +| **Price Outlook (6h)** | Average of next 6 hours | +| **Price Outlook (8h)** | Average of next 8 hours | +| **Price Outlook (12h)** | Average of next 12 hours | -:::info Same Starting Point — All 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. +:::info Same Starting Point — All Outlook Sensors Use Your Current Price +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:** -- `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 - 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: @@ -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. +### 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 **Entity ID:** `sensor._current_price_trend` @@ -701,16 +740,16 @@ A natural intuition is to treat trend states like a stock ticker: #### 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 # Example: Start dishwasher when prices are favorable trigger: - platform: state - entity_id: sensor.my_home_price_trend_3h + entity_id: sensor.my_home_price_outlook_3h condition: - condition: numeric_state - entity_id: sensor.my_home_price_trend_3h + entity_id: sensor.my_home_price_outlook_3h attribute: trend_value # rising (1) or strongly_rising (2) = act now above: 0 @@ -724,7 +763,7 @@ action: 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** | | `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" - 🟡 **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: -| | Trend Sensors | Average Sensors | -|--|---------------|-----------------| +| | Outlook/Trajectory Sensors | Average Sensors | +|--|---------------------------|-----------------| | **Purpose** | Dashboard display, quick visual overview | Automations, precise numeric comparisons | | **Output** | Classification (falling/stable/rising) | Exact price values (ct/kWh) | | **Best for** | "Should I worry about prices?" | "Is the future average below 15 ct?" |