Convert four-space-indented list items (`- item`) to standard two-space
(`- item`) in AGENTS.md, CONTRIBUTING.md, README.md, and all Docusaurus
documentation pages (developer and user, including versioned snapshots).
No content changes.
Release-Notes: skip
Update sensors-volatility.md to cover the three new price rank sensors and the
IQR-based volatility attributes (typical price band / price spike count).
Section headers include technical terms in parentheses for experts:
"Typical Price Band Statistics (IQR)" and "Price Rank Sensors (Percentile Rank)".
Attribute tables list Tukey fence formulas and plain-language explanations
side-by-side.
Regenerate sensor-reference.md to include price_rank_today,
price_rank_tomorrow, and price_rank_today_tomorrow with translations for all
five supported languages.
Impact: Users have full documentation for the new sensors including examples,
formulas, and a multi-language lookup table.
Consistent naming with the period_count_* family introduced in the
previous commit (period_count_total, period_count_today,
period_count_tomorrow).
periods_remaining was the last attribute in the navigation triplet
using the old plural form. Renamed to period_count_remaining to follow
the established pattern: all countable period metrics use the
period_count_* prefix.
BREAKING CHANGE: periods_remaining renamed to period_count_remaining.
Impact: All four period count attributes now share the same prefix
(period_count_total, period_count_today, period_count_tomorrow,
period_count_remaining), making automation templates more predictable.
Removed periods_found_total and replaced with period_count_today /
period_count_tomorrow. The old attribute counted all periods including
yesterday (coordinator scope), causing a discrepancy vs. the displayed
list (sensor scope, today+tomorrow only).
Renamed periods_total → period_count_total for naming consistency with
the new per-day attributes. Recalculate period_position / period_count_total /
periods_remaining after the today+tomorrow filter so all three navigation
attributes reflect the filtered scope.
period_count_tomorrow is always present (0 when no tomorrow data or no
periods found), enabling automations without default(0) guards.
Removed internal periods_found key from relaxation metadata — it was
only consumed by add_calculation_summary_attributes which is now removed.
BREAKING CHANGE: periods_found_total removed (replace with
period_count_today + period_count_tomorrow). periods_total renamed to
period_count_total.
Impact: Period navigation attributes (position/total/remaining) now
correctly reflect today+tomorrow scope. Per-day counts allow automations
to distinguish "2 periods today, 0 tomorrow" from "1+1".
Introduces a new day_pattern.py module that analyses the 15-min price curve
for each calendar day (yesterday/today/tomorrow) and classifies its shape.
New sensors:
day_pattern_yesterday / day_pattern_today / day_pattern_tomorrow
EntityCategory.DIAGNOSTIC, SensorDeviceClass.ENUM
Patterns: valley, peak, double_valley, double_peak, flat, rising, falling, mixed
The detector uses centred-rolling smoothing, prominence-filtered extrema,
Kneedle-based knee detection, and monotone segment building.
Coordinator populates transformed_data["dayPatterns"] after priceInfo enrichment.
Impact: Users can trigger automations based on the shape of the day's price
curve, e.g. pre-heat when tomorrow is a valley day.
Wrap most user-guide code examples in collapsible details sections to reduce visual noise while keeping Mermaid diagrams expanded.
Standardized summary labels across the user docs to a small set of readable patterns and removed technical or awkward wording from visible collapse titles.
Impact: User documentation is easier to scan, with long examples hidden by default and more consistent expand/collapse labels.
New comprehensive documentation page for all 5 scheduling services:
- Decision flowchart for choosing the right service
- Detailed parameter reference with examples for each service
- Response format examples with realistic data
- Practical automation examples (overnight scheduling, EV charging,
peak price avoidance)
- Power profile and search range explanations
Also updated:
- actions.md: Added scheduling services overview, entry_id as optional
- automation-examples.md: Cross-reference to scheduling services guide
- Sidebar: Added scheduling-services to Reference category
Impact: Users have comprehensive documentation with a decision guide,
practical examples, and automation templates for the new services.
Disable autoCollapseCategories to prevent unwanted collapsing when
clicking an active category header twice.
Add hideOnScroll to navbar for more reading space on long pages.
Add category link targets in both sidebars so category headers are
clickable and navigate to the section overview page.
Impact: Sidebar navigation no longer collapses unexpectedly.
Category titles are now direct navigation links. Navbar hides while
scrolling, giving more screen space for content.
Add a comprehensive entity reference system that helps users find
entities across all 5 supported languages (EN, DE, NO, NL, SV).
Core components:
- Generator script (scripts/docs/generate-sensor-reference) that
builds sensor-reference.md from translation files with --check
mode for CI validation
- EntityRef component for compact inline entity annotations with
tooltip and version-aware linking to the reference table
- EntitySearch component with live filtering, clickable results,
keyboard navigation, "/" shortcut to focus, category filter chips,
match highlighting, copy-entity-ID button per row, back-links to
documentation pages, persistent row highlights, hash-based deep
linking, and mobile-responsive layout
- MDXComponents theme override for global component registration
Documentation updates:
- New sensor-reference.md page (115 entities x 5 languages)
- EntityRef annotations across 10 documentation pages
- Sidebar entry for quick navigation
- CI integration (docusaurus.yml + scripts/check)
- Ruff per-file-ignores for scripts/ (T201, INP001)
Impact: Users can now find any entity by its localized display name
regardless of their UI language. Inline EntityRef annotations link
directly to the multi-language lookup table with version-aware URLs.
All YAML code blocks >12-14 lines in example and concept pages are now
wrapped in HTML <details>/<summary> elements, reducing scroll depth
and making complex pages easier to navigate.
Pages affected:
- automation-examples.md: 9 blocks (heat pump, EV, battery automations)
- dashboard-examples.md: 6 blocks (button-card, mushroom, grid layouts)
- sensors.md: 7 blocks (practical examples, energy/tax templates, timing)
- icon-colors.md: 8 blocks (card_mod methods, complete dashboard, custom colors)
- period-calculation.md: 3 blocks (sensor attr reference, midnight example, automations)
Blocks left visible: short examples (<13 lines), Good/Bad comparisons,
Method 1 (primary recommended approach in icon-colors.md).
Impact: Users can scan page structure without scrolling past long YAML.
Code is still one click away, not hidden behind navigation.
New dedicated page for community-contributed examples, starting with
Dutch solar feed-in compensation (saldering) patterns adapted from
GitHub Discussion #105 (OdynBrouwer). Includes input_number helpers
for country-specific tax rates, template sensors for feed-in with
and without saldering, smart export automation, and dashboard card.
German spot price share template as starting point. Norwegian/Swedish
sections as placeholders for future contributions.
YAML code blocks use collapsible details elements to keep the page
scannable. Page is framed generically to accommodate any type of
community example in the future (not just country-specific).
Added cross-reference from sensors.md Energy Price section and new
"Community" sidebar category.
Impact: Users (especially Netherlands) can find ready-to-adapt template
examples for country-specific price calculations using the energy_price
and tax attributes. Framework ready for additional community examples.
Replace the inline KaTeX block in the Energy Price & Tax Breakdown
section with a plain inline equation string.
The previous expression caused a Docusaurus SSG runtime failure on the
sensors page (ReferenceError during static rendering).
Impact: User docs build now succeeds consistently for the sensors page.
Add new section 'Energy Price & Tax Breakdown' to sensors.md:
- Attribute overview table (interval, min/max, daily avg sensors)
- Use cases: solar feed-in/net metering, price composition analysis,
dashboard cost breakdown with example YAML templates
- Cache transition note for gradual data availability after update
Add 'Energy & Tax Fields in get_chartdata' section to actions.md:
- Parameter documentation with defaults
- Example service call YAML
- ApexCharts integration example with custom field names
Impact: Users can discover and utilize the new energy/tax attributes
with ready-to-use automation and dashboard examples.
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.
versioned_docs/ was already tracked but versioned_sidebars/ was never
committed. Docusaurus requires both to render sidebar navigation for
old versions — without the sidebar files, all versioned pages show
no navigation.
Adds sidebar snapshots for user and developer docs:
v0.21.0, v0.22.0, v0.22.1, v0.23.0, v0.23.1, v0.24.0, v0.27.0, v0.28.0
Future versions: CI (docusaurus.yml) runs docs:version on each stable
tag push, which generates both versioned_docs/ and versioned_sidebars/.
The workflow should be updated to commit these files back, or they need
to be added manually after each release.
Impact: Sidebar navigation now appears correctly for all existing
versioned documentation pages.
Swizzled @docusaurus/theme-mermaid's Mermaid component to wrap
every diagram with a portal-based lightbox overlay.
An expand icon appears on diagram hover. Clicking opens the SVG
in a full-screen overlay (90vw × 85vh, scrollable). Closes via
backdrop click, Escape key, or close button. SSR-safe, no
external dependencies. Matches Tibber electric color theme.
Impact: Users can inspect complex flowcharts (e.g. the Options
Flow wizard) without squinting at small embedded diagrams.
Switched Giscus mapping from 'pathname' to 'og:title' with strict=1.
Discussions are now titled after the readable page title (e.g.
'Chart Examples | Tibber Prices Integration') instead of the URL path,
making them immediately identifiable in the GitHub Discussions list.
Added a small hint above every comment box pointing users to open
a dedicated Discussion on GitHub for new questions/ideas, so
page-specific comments don't accumulate unrelated threads.
Note: Existing Discussion #94 (pathname-mapped) will no longer appear
on chart-examples — a new og:title-mapped discussion will be created
on the next comment. #94 remains visible on GitHub.
Impact: Maintainer can identify discussion origin at a glance.
Users are guided toward proper Discussion threads for new topics.
Added a dedicated 'Finding Your Entry ID' section to actions.md
explaining the two workflows: dropdown in the Action UI vs.
'Copy Config Entry ID' from the integration's three-dot menu in YAML.
Added matching :::info callouts to chart-examples.md and
automation-examples.md where entry_id: YOUR_ENTRY_ID appears in code
examples, and a new 'Config Entry ID' entry in the glossary.
Addresses user confusion reported in GitHub Discussions #94.
Impact: Users no longer get stuck on YOUR_ENTRY_ID placeholders.
Both GUI and YAML workflows are clearly explained at the point of need.
Add coverage for the state_class/statistics table optimization across
both user and developer documentation.
docs/user/docs/configuration.md:
- Add 'Price Sensor Statistics' section explaining that only 3 sensors
write to the HA statistics database (current_interval_price,
current_interval_price_base, average_price_today)
- Fix incorrect entity ID examples: remove non-existent _override suffix
from recorder exclude globs, Developer Tools example, and seasonal
automation example (actual IDs: number.*_best_price_flexibility etc.)
docs/developer/docs/recorder-optimization.md:
- Add 'Long-Term Statistics Optimization (state_class)' section covering
the statistics/statistics_short_term table dimension, which is distinct
from _unrecorded_attributes (state_attributes table)
- Documents the MONETARY device_class constraint (MEASUREMENT blocked by
hassfest, only TOTAL or None valid), the 3 sensors keeping TOTAL with
rationale, the 23 sensors set to None, and ~88% write reduction
- Includes comparison table: _unrecorded_attributes vs state_class
Impact: Users now understand the built-in statistics optimization and
have correct recorder exclude examples. Developers understand both
optimization layers and their interaction.
User docs (period-calculation.md):
- New troubleshooting section "Fewer Periods Than Configured" (most
common confusing scenario, added before "No Periods Found")
- Extended "Understanding Sensor Attributes" section: all four diagnostic
attributes documented with concrete YAML examples and prose explanations
- Updated Table of Contents
Developer docs (period-calculation-theory.md):
- New section "Flat Day and Low-Price Adaptations" (between Flex Limits
and Relaxation Strategy) documenting all three mechanisms with
implementation details, scaling tables, and rationale for hardcoding
- Two new scenarios: 2b (flat day with adaptive min_periods) and 2c
(solar surplus / absolute low-price day) with expected logs and
sensor attribute examples
- Debugging checklist point 6: flat day / low-price checks with
exact log string patterns to grep for
- Diagnostic attribute reference table in the debugging section
Impact: Users can self-diagnose "fewer periods than configured" without
support. Contributors understand why the three thresholds are hardcoded
and cannot be user-configured.
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.
When runtime config override entities (number/switch) are enabled,
the Options Flow now displays warning indicators at the top of each
affected section. Users see which fields are being managed by config
entities and can still edit the base values if needed.
Changes:
- Add ConstantSelector warnings in Best Price/Peak Price sections
- Implement multi-language support for override warnings (de, en, nb, nl, sv)
- Add _get_override_translations() to load translated field labels
- Add _get_active_overrides() to detect enabled override entities
- Extend get_best_price_schema/get_peak_price_schema with translations param
- Add 14 number/switch config entities for runtime period tuning
- Document runtime configuration entities in user docs
Warning format adapts to overridden fields:
- Single: "⚠️ Flexibility controlled by config entity"
- Multiple: "⚠️ Flexibility and Minimum Distance controlled by config entity"
Impact: Users can now dynamically adjust period calculation parameters
via Home Assistant automations, scripts, or dashboards without entering
the Options Flow. Clear UI indicators show which settings are currently
overridden.
