jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-03-30 05:13:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
hass.tibber_prices/docs/user
History
Julian Pawlowski 47b0a298d4 feat(periods): add midnight-crossing periods and day volatility attributes 
Periods can now naturally cross midnight boundaries, and new diagnostic
attributes help users understand price classification changes at midnight.

**New Features:**

1. Midnight-Crossing Period Support (relaxation.py):
   - group_periods_by_day() assigns periods to ALL spanned days
   - Periods crossing midnight appear in both yesterday and today
   - Enables period formation across calendar day boundaries
   - Ensures min_periods checking works correctly at midnight

2. Extended Price Data Window (relaxation.py):
   - Period calculation now uses full 3-day data (yesterday+today+tomorrow)
   - Enables natural period formation without artificial midnight cutoff
   - Removed date filter that excluded yesterday's prices

3. Day Volatility Diagnostic Attributes (period_statistics.py, core.py):
   - day_volatility_%: Daily price spread as percentage (span/avg × 100)
   - day_price_min/max/span: Daily price range in minor currency (ct/øre)
   - Helps detect when midnight classification changes are economically significant
   - Uses period start day's reference prices for consistency

**Documentation:**

4. Design Principles (period-calculation-theory.md):
   - Clarified per-day evaluation principle (always was the design)
   - Added comprehensive section on midnight boundary handling
   - Documented volatility threshold separation (sensor vs period filters)
   - Explained market context for midnight price jumps (EPEX SPOT timing)

5. User Guides (period-calculation.md, automation-examples.md):
   - Added \"Midnight Price Classification Changes\" troubleshooting section
   - Provided automation examples using volatility attributes
   - Explained why Best→Peak classification can change at midnight
   - Documented level filter volatility threshold behavior

**Architecture:**

- Per-day evaluation: Each interval evaluated against its OWN day's min/max/avg
  (not period start day) ensures mathematical correctness across midnight
- Period boundaries: Periods can naturally cross midnight but may split when
  consecutive days differ significantly (intentional, mathematically correct)
- Volatility thresholds: Sensor thresholds (user-configurable) remain separate
  from period filter thresholds (fixed internal) to prevent unexpected behavior

Impact: Periods crossing midnight are now consistently visible before and
after midnight turnover. Users can understand and handle edge cases where
price classification changes at midnight on low-volatility days.
2025-11-21 23:18:46 +00:00
..
automation-examples.md feat(periods): add midnight-crossing periods and day volatility attributes 2025-11-21 23:18:46 +00:00
configuration.md docs: restructure documentation and add AI development disclosure 2025-11-09 14:25:27 +00:00
dynamic-icons.md docs(user): add dynamic icon and color guides for dashboard customization 2025-11-15 18:00:38 +00:00
icon-colors.md docs(user): add dynamic icon and color guides for dashboard customization 2025-11-15 18:00:38 +00:00
installation.md docs: restructure documentation and add AI development disclosure 2025-11-09 14:25:27 +00:00
period-calculation.md feat(periods): add midnight-crossing periods and day volatility attributes 2025-11-21 23:18:46 +00:00
README.md docs(user): add dynamic icon and color guides for dashboard customization 2025-11-15 18:00:38 +00:00
sensors.md feat(sensor): migrate chart_data_export from binary_sensor to sensor platform 2025-11-17 04:11:10 +00:00
services.md feat(sensor): migrate chart_data_export from binary_sensor to sensor platform 2025-11-17 04:11:10 +00:00
troubleshooting.md docs: restructure documentation and add AI development disclosure 2025-11-09 14:25:27 +00:00

README.md

User Documentation

Welcome to Tibber Prices! This integration provides enhanced electricity price data from Tibber with quarter-hourly precision, statistical analysis, and intelligent ratings.

📚 Documentation

🚀 Quick Start

  1. Install via HACS (add as custom repository)
  2. Add Integration in Home Assistant → Settings → Devices & Services
  3. Enter Tibber API Token (get yours at developer.tibber.com)
  4. Configure Price Thresholds (optional, defaults work for most users)
  5. Start Using Sensors in automations, dashboards, and scripts!

✨ Key Features

  • Quarter-hourly precision - 15-minute intervals for accurate price tracking
  • Statistical analysis - Trailing/leading 24h averages for context
  • Price ratings - LOW/NORMAL/HIGH classification based on your thresholds
  • Best/Peak hour detection - Automatic detection of cheapest/peak periods with configurable filters (learn how)
  • ApexCharts integration - Custom services for beautiful price charts
  • Multi-currency support - EUR, NOK, SEK with proper minor units (ct, øre, öre)

🔗 Useful Links

🤝 Need Help?

Note: These guides are for end users. If you want to contribute to development, see the Developer Documentation.