mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-03-30 13:23:41 +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

4.7 KiB

Raw Blame History

FAQ - Frequently Asked Questions

Common questions about the Tibber Prices integration.

General Questions

Why don't I see tomorrow's prices yet?

Tomorrow's prices are published by Tibber around 13:00 CET (12:00 UTC in winter, 11:00 UTC in summer).

Before publication: Sensors show unavailable or use today's data
After publication: Integration automatically fetches new data within 15 minutes
No manual refresh needed - polling happens automatically

How often does the integration update data?

API Polling: Every 15 minutes
Sensor Updates: On quarter-hour boundaries (00, 15, 30, 45 minutes)
Cache: Price data cached until midnight (reduces API load)

Can I use multiple Tibber homes?

Yes! Use the "Add another home" option:

Settings → Devices & Services → Tibber Prices
Click "Configure" → "Add another home"
Select additional home from dropdown
Each home gets separate sensors with unique entity IDs

Does this work without a Tibber subscription?

No, you need:

Active Tibber electricity contract
API token from developer.tibber.com

The integration is free, but requires Tibber as your electricity provider.

Configuration Questions

What are good values for price thresholds?

Default values work for most users:

High Price Threshold: 30% above average
Low Price Threshold: 15% below average

Adjust if:

You're in a market with high volatility → increase thresholds
You want more sensitive ratings → decrease thresholds
Seasonal changes → review every few months

How do I optimize Best Price Period detection?

Key parameters:

Flex: 15-20% is optimal (default 15%)
Min Distance: 5-10% recommended (default 5%)
Rating Levels: Start with "CHEAP + VERY_CHEAP" (default)
Relaxation: Keep enabled (helps find periods on expensive days)

See Period Calculation for detailed tuning guide.

Why do I sometimes only get 1 period instead of 2?

This happens on high-price days when:

Few intervals meet your criteria
Relaxation is disabled
Flex is too low
Min Distance is too strict

Solutions:

Enable relaxation (recommended)
Increase flex to 20-25%
Reduce min_distance to 3-5%
Add more rating levels (include "NORMAL")

Troubleshooting

Sensors show "unavailable"

Common causes:

API Token invalid → Check token at developer.tibber.com
No internet connection → Check HA network
Tibber API down → Check status.tibber.com
Integration not loaded → Restart Home Assistant

Best Price Period is ON all day

This means all intervals meet your criteria (very cheap day!):

Not an error - enjoy the low prices!
Consider tightening filters (lower flex, higher min_distance)
Or add automation to only run during first detected period

Prices are in wrong currency or wrong units

Currency is determined by your Tibber subscription (cannot be changed).

Display mode (base vs. subunit) is configurable:

Configure in: Settings > Devices & Services > Tibber Prices > Configure
Options:
- Base currency: €/kWh, kr/kWh (decimal values like 0.25)
- Subunit: ct/kWh, øre/kWh (larger values like 25.00)
Smart defaults: EUR → subunit, NOK/SEK/DKK → base currency

If you see unexpected units, check your configuration in the integration options.

Tomorrow data not appearing at all

Check:

Your Tibber home has hourly price contract (not fixed price)
API token has correct permissions
Integration logs for API errors (/config/home-assistant.log)
Tibber actually published data (check Tibber app)

Automation Questions

How do I run dishwasher during cheap period?

automation:
  - alias: "Dishwasher during Best Price"
    trigger:
      - platform: state
        entity_id: binary_sensor.tibber_home_best_price_period
        to: "on"
    condition:
      - condition: time
        after: "20:00:00"  # Only start after 8 PM
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.dishwasher

See Automation Examples for more recipes.

Can I avoid peak prices automatically?

Yes! Use Peak Price Period binary sensor:

automation:
  - alias: "Disable charging during peak prices"
    trigger:
      - platform: state
        entity_id: binary_sensor.tibber_home_peak_price_period
        to: "on"
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.ev_charger

💡 Still need help?

4.7 KiB Raw Blame History