Add calculation summary attributes to best_price_period and
peak_price_period binary sensors for diagnostic transparency.
New attributes (all excluded from recorder history):
- min_periods_configured: User's configured target per day (always shown)
- periods_found_total: Actual periods found across all days (always shown)
- flat_days_detected: Days where CV <= 10% reduced target to 1 (only when > 0)
- relaxation_incomplete: Some days couldn't reach the target (only when true)
These attributes explain observed behavior without requiring users to
read logs: seeing "flat_days_detected: 1" alongside
"min_periods_configured: 2, periods_found_total: 1" immediately
explains why the count is lower than configured on uniform-price days.
Implementation:
- _compute_day_effective_min() now returns (dict, int) tuple to propagate
the flat day count through to the metadata dict
- flat_days_detected added to metadata["relaxation"] in
calculate_periods_with_relaxation()
- build_final_attributes_simple() gains optional period_metadata parameter
- New add_calculation_summary_attributes() function handles the rendering
- Attributes are shown even when no period is currently active
Updated recorder-optimization.md: attribute counts + clarified that
timestamp is correctly excluded (entity native_value is recorded
separately by HA as the entity state itself).
Impact: Users can understand why they received fewer periods than
configured without enabling debug logging.
Changed all documentation links from version-specific tags (v0.20.0) to
main branch references. This makes documentation maintenance-free - links
stay current as code evolves.
Updated 38 files across:
- docs/developer/docs/ (7 files)
- docs/developer/versioned_docs/version-v0.21.0/ (8 files)
- docs/developer/versioned_docs/version-v0.22.0/ (8 files)
Impact: Documentation links no longer break when new versions are released.
Links always point to current code implementation.
Add user-configurable option to choose between median and arithmetic mean
as the displayed value for all 14 average price sensors, with the alternate
value exposed as attribute.
BREAKING CHANGE: Average sensor default changed from arithmetic mean to
median. Users who rely on arithmetic mean behavior may use the price_mean attribue now, or must manually reconfigure
via Settings → Devices & Services → Tibber Prices → Configure → General
Settings → "Average Sensor Display" → Select "Arithmetic Mean" to get this as sensor state.
Affected sensors (14 total):
- Daily averages: average_price_today, average_price_tomorrow
- 24h windows: trailing_price_average, leading_price_average
- Rolling hour: current_hour_average_price, next_hour_average_price
- Future forecasts: next_avg_3h, next_avg_6h, next_avg_9h, next_avg_12h
Implementation:
- All average calculators now return (mean, median) tuples
- User preference controls which value appears in sensor state
- Alternate value automatically added to attributes
- Period statistics (best_price/peak_price) extended with both values
Technical changes:
- New config option: CONF_AVERAGE_SENSOR_DISPLAY (default: "median")
- Calculator functions return tuples: (avg, median)
- Attribute builders: add_alternate_average_attribute() helper function
- Period statistics: price_avg → price_mean + price_median
- Translations: Updated all 5 languages (de, en, nb, nl, sv)
- Documentation: AGENTS.md, period-calculation.md, recorder-optimization.md
Migration path:
Users can switch back to arithmetic mean via:
Settings → Integrations → Tibber Prices → Configure
→ General Settings → "Average Sensor Display" → "Arithmetic Mean"
Impact: Median is more resistant to price spikes, providing more stable
automation triggers. Statistical analysis from coordinator still uses
arithmetic mean (e.g., trailing_avg_24h for rating calculations).
Co-developed-with: GitHub Copilot <copilot@github.com>
Add repair notification system with three auto-clearing repair types:
- Tomorrow data missing (after 18:00)
- API rate limit exceeded (3+ consecutive errors)
- Home not found in Tibber account
Includes:
- coordinator/repairs.py: Complete TibberPricesRepairManager implementation
- Enhanced API error handling with explicit 5xx handling
- Translations for 5 languages (EN, DE, NB, NL, SV)
- Developer documentation in docs/developer/docs/repairs-system.md
Impact: Users receive actionable notifications for important issues instead
of only seeing stale data in logs.
Update all references to reflect two separate Docusaurus instances
(user + developer) with proper file paths and navigation management.
Changes:
- AGENTS.md: Document Docusaurus structure and file organization
- CONTRIBUTING.md: Add Docusaurus workflow guidelines
- docs/developer/docs/period-calculation-theory.md: Fix cross-reference
- docs/developer/sidebars.ts: Add recorder-optimization to navigation
Documentation organized as:
- docs/user/docs/*.md (user guides, via sidebars.ts)
- docs/developer/docs/*.md (developer guides, via sidebars.ts)
- AGENTS.md (AI patterns, conventions)
Impact: AI and contributors know where to place new documentation.
Add comprehensive documentation for _unrecorded_attributes
implementation, categorizing all excluded attributes with reasoning,
expected database impact, and decision framework for future attributes.
Added to Developer Docs → Advanced Topics navigation.
Content includes:
- 7 exclusion categories with examples
- Space savings calculations (60-85% reduction)
- Decision framework for new attributes
- Testing and validation guidelines
- SQL queries for verification
