mirror of
https://github.com/jpawlowski/hass.tibber_prices.git
synced 2026-03-29 21:03:40 +00:00
457fa7c03f
BREAKING CHANGE: Period overlap resolution now merges adjacent/overlapping periods
instead of marking them as extensions. This simplifies automation logic and provides
clearer period boundaries for users.
Previous Behavior:
- Adjacent periods created by relaxation were marked with is_extension=true
- Multiple short periods instead of one continuous period
- Complex logic needed to determine actual period length in automations
New Behavior:
- Adjacent/overlapping periods are merged into single continuous periods
- Newer period's relaxation attributes override older period's
- Simpler automation: one period = one continuous time window
Changes:
- Period Overlap Resolution (new file: period_overlap.py):
* Added merge_adjacent_periods() to combine periods and preserve attributes
* Rewrote resolve_period_overlaps() with simplified merge logic
* Removed split_period_by_overlaps() (no longer needed)
* Removed is_extension marking logic
* Removed unused parameters: min_period_length, baseline_periods
- Relaxation Strategy (relaxation.py):
* Removed all is_extension filtering from period counting
* Simplified standalone counting to just len(periods)
* Changed from period_merging import to period_overlap import
* Added MAX_FLEX_HARD_LIMIT constant (0.50)
* Improved debug logging for merged periods
- Code Quality:
* Fixed all remaining linter errors (N806, PLR2004, PLR0912)
* Extracted magic values to module-level constants:
- FLEX_SCALING_THRESHOLD = 0.20
- SCALE_FACTOR_WARNING_THRESHOLD = 0.8
- MAX_FLEX_HARD_LIMIT = 0.50
* Added appropriate noqa comments for unavoidable patterns
- Configuration (from previous work in this session):
* Removed CONF_RELAXATION_STEP_BEST, CONF_RELAXATION_STEP_PEAK
* Hard-coded 3% relaxation increment for reliability
* Optimized defaults: RELAXATION_ATTEMPTS 8→11, ENABLE_MIN_PERIODS False→True,
MIN_PERIODS undefined→2
* Removed relaxation_step UI fields from config flow
* Updated all 5 translation files
- Documentation:
* Updated period_handlers/__init__.py: period_merging → period_overlap
* No user-facing docs changes needed (already described continuous periods)
Rationale - Period Merging:
User experience was complicated by fragmented periods:
- Automations had to check multiple adjacent periods
- Binary sensors showed ON/OFF transitions within same cheap time
- No clear way to determine actual continuous period length
With merging:
- One continuous cheap time = one period
- Binary sensor clearly ON during entire period
- Attributes show merge history via merged_from dict
- Relaxation info preserved from newest/highest flex period
Rationale - Hard-Coded Relaxation Increment:
The configurable relaxation_step parameter proved problematic:
- High base flex + high step → rapid explosion (40% base + 10% step → 100% in 6 steps)
- Users don't understand the multiplicative nature
- 3% increment provides optimal balance: 11 attempts to reach 50% hard cap
Impact:
- Existing installations: Periods may appear longer (merged instead of split)
- Automations benefit from simpler logic (no is_extension checks needed)
- Custom relaxation_step values will use new 3% increment
- Users may need to adjust relaxation_attempts if they relied on high step sizes
|
||
|---|---|---|
| .. | ||
| automation-examples.md | ||
| configuration.md | ||
| dynamic-icons.md | ||
| icon-colors.md | ||
| installation.md | ||
| period-calculation.md | ||
| README.md | ||
| sensors.md | ||
| services.md | ||
| troubleshooting.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
- Installation - How to install via HACS and configure the integration
- Configuration - Setting up your Tibber API token and price thresholds
- Period Calculation - How Best/Peak Price periods are calculated and configured
- Sensors - Available sensors, their states, and attributes
- Dynamic Icons - State-based automatic icon changes
- Dynamic Icon Colors - Using icon_color attribute for color-coded dashboards
- Services - Custom services and how to use them
- Automation Examples - Ready-to-use automation recipes
- Troubleshooting - Common issues and solutions
🚀 Quick Start
- Install via HACS (add as custom repository)
- Add Integration in Home Assistant → Settings → Devices & Services
- Enter Tibber API Token (get yours at developer.tibber.com)
- Configure Price Thresholds (optional, defaults work for most users)
- 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?
- Check the Troubleshooting Guide
- Search existing issues
- Open a new issue if needed
Note: These guides are for end users. If you want to contribute to development, see the Developer Documentation.