jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-07-28 01:26:49 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
795 commits 10 branches 41 tags 20 MiB
Commit graph

6 commits

Author SHA1 Message Date
Julian Pawlowski
4f2bea6720 docs(concepts): clarify V-shaped and U-shaped price day definitions 
Enhanced descriptions for V-shaped and U-shaped price days to include their characteristics and how they are classified as 'valley' by the Day Pattern sensor.

Impact: Users gain a clearer understanding of price patterns and their implications for automation.

docs(glossary): update V-Shaped Day definition for clarity

Revised the definition of V-Shaped Day to include U-Shaped Day as an informal term, emphasizing the classification as 'valley' by the Day Pattern sensor.

Impact: Users receive a more comprehensive explanation of price day classifications.

docs(period-calculation): improve algorithm overview and phase descriptions

Added detailed explanations for each phase of the period calculation algorithm, including visual aids and clarifications on the importance of each phase.

Impact: Users can better understand the underlying logic of price period calculations.

docs(sensors-price-phases): refine sensor descriptions for clarity

Updated descriptions of price phase sensors to clarify the shapes and conditions they represent, including distinctions between V-shaped and U-shaped curves.

Impact: Users benefit from improved clarity on sensor classifications and their applications in automations.
 2026-04-17 22:23:55 +00:00
Julian Pawlowski
cbbfadbf4f refactor(docs): restructure navigation and split large pages 
Split sensors.md (1,693 lines) into 7 focused pages:
- sensors-overview: binary sensors, core price, min/max, diagnostics
- sensors-average: median/mean, automation examples, key attributes
- sensors-ratings-levels: 3-level ratings + 5-level system
- sensors-volatility: CV formula, 4 sensors, configuration
- sensors-trends: outlook, trajectory, current/next, decision guide
- sensors-timing: period timing state diagram + examples
- sensors-energy-tax: energy/tax breakdown + use cases

Extract relaxation deep-dive from period-calculation.md into
dedicated period-relaxation.md. Remove duplicate ApexCharts section
from automation-examples.md (cross-references chart-examples.md).

Reorganize sidebar into semantic categories:
- Sensors (7 pages), Price Periods (2), Dashboards & Charts (4),
  Reference (sensor-reference + actions)

Update all cross-references across 10 pages, EntitySearch DOC_NAMES,
and generator template for new page slugs.

Impact: Users can find information faster with shorter, focused pages
and a clearer navigation structure. No content was removed — only
reorganized and deduplicated.
 2026-04-11 10:33:58 +00:00
Julian Pawlowski
d8f005d3bb docs: explain how to find the config entry_id 
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.
 2026-04-07 14:01:33 +00:00
Julian Pawlowski
190c979e9c docs(user): comprehensive trend decision model and automation guides 
sensors.md:
- Added "How to Use Trend Sensors for Decisions" section with :::danger
  "Common Misconception — Don't Wait for Stable!" box
- Comparison table (rising/falling/stable → what it means → action)
- Basic automation YAML pattern
- Multi-window combination table (1h + 6h → interpretation)
- Dashboard quick-glance guide
- Documented trend_change_in_minutes sensor

automation-examples.md:
- Replaced placeholder with full automation examples
- V-shaped price days explanation with mermaid timeline
- "Ride the Full Cheap Wave" heat pump automation
- "Pre-Emptive Start Before Best Price" pattern
- "Protect Against Rising Prices" EV charging automation
- "Multi-Window Trend Strategy" (1h + 6h + best_price_period)
- Sensor Combination Quick Reference table
- Volatility-based automation examples
- Best hour detection automation
- ApexCharts card configuration guide

Other docs: trend-related updates to concepts, configuration,
glossary, installation, period-calculation, troubleshooting.

Impact: Users have comprehensive guides for trend-based automations
with real YAML examples and clear decision frameworks.
 2026-04-07 13:45:40 +00:00
Julian Pawlowski
60e05e0815 refactor(currency)!: rename major/minor to base/subunit currency terminology 
Complete terminology migration from confusing "major/minor" to clearer
"base/subunit" currency naming throughout entire codebase, translations,
documentation, tests, and services.

BREAKING CHANGES:

1. **Service API Parameters Renamed**:
   - `get_chartdata`: `minor_currency` → `subunit_currency`
   - `get_apexcharts_yaml`: Updated service_data references from
     `minor_currency: true` to `subunit_currency: true`
   - All automations/scripts using these parameters MUST be updated

2. **Configuration Option Key Changed**:
   - Config entry option: Display mode setting now uses new terminology
   - Internal key: `currency_display_mode` values remain "base"/"subunit"
   - User-facing labels updated in all 5 languages (de, en, nb, nl, sv)

3. **Sensor Entity Key Renamed**:
   - `current_interval_price_major` → `current_interval_price_base`
   - Entity ID changes: `sensor.tibber_home_current_interval_price_major`
     → `sensor.tibber_home_current_interval_price_base`
   - Energy Dashboard configurations MUST update entity references

4. **Function Signatures Changed**:
   - `format_price_unit_major()` → `format_price_unit_base()`
   - `format_price_unit_minor()` → `format_price_unit_subunit()`
   - `get_price_value()`: Parameter `in_euro` deprecated in favor of
     `config_entry` (backward compatible for now)

5. **Translation Keys Renamed**:
   - All language files: Sensor translation key
     `current_interval_price_major` → `current_interval_price_base`
   - Service parameter descriptions updated in all languages
   - Selector options updated: Display mode dropdown values

Changes by Category:

**Core Code (Python)**:
- const.py: Renamed all format_price_unit_*() functions, updated docstrings
- entity_utils/helpers.py: Updated get_price_value() with config-driven
  conversion and backward-compatible in_euro parameter
- sensor/__init__.py: Added display mode filtering for base currency sensor
- sensor/core.py:
  * Implemented suggested_display_precision property for dynamic decimal places
  * Updated native_unit_of_measurement to use get_display_unit_string()
  * Updated all price conversion calls to use config_entry parameter
- sensor/definitions.py: Renamed entity key and updated all
  suggested_display_precision values (2 decimals for most sensors)
- sensor/calculators/*.py: Updated all price conversion calls (8 calculators)
- sensor/helpers.py: Updated aggregate_price_data() signature with config_entry
- sensor/attributes/future.py: Updated future price attributes conversion

**Services**:
- services/chartdata.py: Renamed parameter minor_currency → subunit_currency
  throughout (53 occurrences), updated metadata calculation
- services/apexcharts.py: Updated service_data references in generated YAML
- services/formatters.py: Renamed parameter use_minor_currency →
  use_subunit_currency in aggregate_hourly_exact() and get_period_data()
- sensor/chart_metadata.py: Updated default parameter name

**Translations (5 Languages)**:
- All /translations/*.json:
  * Added new config step "display_settings" with comprehensive explanations
  * Renamed current_interval_price_major → current_interval_price_base
  * Updated service parameter descriptions (subunit_currency)
  * Added selector.currency_display_mode.options with translated labels
- All /custom_translations/*.json:
  * Renamed sensor description keys
  * Updated chart_metadata usage_tips references

**Documentation**:
- docs/user/docs/actions.md: Updated parameter table and feature list
- docs/user/versioned_docs/version-v0.21.0/actions.md: Backported changes

**Tests**:
- Updated 7 test files with renamed parameters and conversion logic:
  * test_connect_segments.py: Renamed minor/major to subunit/base
  * test_period_data_format.py: Updated period price conversion tests
  * test_avg_none_fallback.py: Fixed tuple unpacking for new return format
  * test_best_price_e2e.py: Added config_entry parameter to all calls
  * test_cache_validity.py: Fixed cache data structure (price_info key)
  * test_coordinator_shutdown.py: Added repair_manager mock
  * test_midnight_turnover.py: Added config_entry parameter
  * test_peak_price_e2e.py: Added config_entry parameter, fixed price_avg → price_mean
  * test_percentage_calculations.py: Added config_entry mock

**Coordinator/Period Calculation**:
- coordinator/periods.py: Added config_entry parameter to
  calculate_periods_with_relaxation() calls (2 locations)

Migration Guide:

1. **Update Service Calls in Automations/Scripts**:
   \`\`\`yaml
   # Before:
   service: tibber_prices.get_chartdata
   data:
     minor_currency: true

   # After:
   service: tibber_prices.get_chartdata
   data:
     subunit_currency: true
   \`\`\`

2. **Update Energy Dashboard Configuration**:
   - Settings → Dashboards → Energy
   - Replace sensor entity:
     `sensor.tibber_home_current_interval_price_major` →
     `sensor.tibber_home_current_interval_price_base`

3. **Review Integration Configuration**:
   - Settings → Devices & Services → Tibber Prices → Configure
   - New "Currency Display Settings" step added
   - Default mode depends on currency (EUR → subunit, Scandinavian → base)

Rationale:

The "major/minor" terminology was confusing and didn't clearly communicate:
- **Major** → Unclear if this means "primary" or "large value"
- **Minor** → Easily confused with "less important" rather than "smaller unit"

New terminology is precise and self-explanatory:
- **Base currency** → Standard ISO currency (€, kr, $, £)
- **Subunit currency** → Fractional unit (ct, øre, ¢, p)

This aligns with:
- International terminology (ISO 4217 standard)
- Banking/financial industry conventions
- User expectations from payment processing systems

Impact: Aligns currency terminology with international standards. Users must
update service calls, automations, and Energy Dashboard configuration after
upgrade.

Refs: User feedback session (December 2025) identified terminology confusion
 2025-12-11 08:26:30 +00:00
Julian Pawlowski
d73eda4b2f git commit -m "feat(docs): add dual Docusaurus sites with custom branding and Giscus integration 
- Split documentation into separate User and Developer sites
- Migrated existing docs to proper Docusaurus structure
- Added custom Tibber-themed header logos (light + dark mode variants)
- Implemented custom color scheme matching integration branding
  - Hero gradient: Cyan → Dark Cyan → Gold
  - Removed standard Docusaurus purple/green theme
- Integrated Giscus comments system for community collaboration
  - User docs: Comments enabled on guides, examples, FAQ
  - User docs: Comments disabled on reference pages (glossary, sensors, troubleshooting)
  - Developer docs: No comments (GitHub Issues/PRs preferred)
- Added categorized sidebars with emoji navigation
- Created 8 new placeholder documentation pages
- Fixed image paths for baseUrl compatibility (local + GitHub Pages)
- Escaped MDX special characters in performance metrics
- Added GitHub Actions workflow for automated deployment
- Created helper scripts: dev-user, dev-developer, build-all

Breaking changes:
- Moved /docs/user/*.md to /docs/user/docs/*.md
- Moved /docs/development/*.md to /docs/developer/docs/*.md
 2025-12-06 01:37:06 +00:00