check_min_distance_from_avg() computed the distance threshold as
range_avg * (1 ± ratio). Tibber prices can go negative during grid
oversupply, and multiplying a negative range_avg directly flips the
intended direction: e.g. avg * 1.05 makes a negative average MORE
negative (i.e. cheaper), which is the wrong direction for a
"most expensive" threshold check, and analogously wrong for
"cheapest" checks.
Compute the threshold as range_avg ± abs(range_avg) * ratio instead,
matching the sign-safe normalization pattern already used for
min_distance_from_avg in the period system
(coordinator/period_handlers/level_filtering.py). Behavior for
positive averages (the common case) is unchanged.
Used by find_cheapest_block, find_cheapest_hours, and plan_charging.
Impact: min_distance_from_avg now correctly filters cheapest/most
expensive windows during negative-price periods instead of silently
accepting windows in the wrong direction relative to the search range
average.
find_cheapest_block, find_cheapest_hours, and find_cheapest_schedule
accept an optional power_profile (fixed per-interval watt array
matching the requested duration/task length). When allow_relaxation
was enabled and no full-duration window could be found, the
duration-reduction relaxation phase silently reduced the interval
count without shrinking power_profile accordingly. Downstream code
(find_cheapest_contiguous_window, calculate_window_statistics,
_find_cheapest_window_in_pool) then truncated the profile from the
front to match, dropping trailing appliance-cycle phases and using
the wrong per-interval weights for both window selection and the
reported cost estimate.
Disable duration-reduction relaxation whenever a power_profile is
supplied (find_cheapest_schedule guards per-task via
any_task_has_power_profile); distance and level-filter relaxation
phases remain available since they don't affect interval count.
Impact: Services with a power_profile no longer silently pick a
shorter window with mismatched power weighting during relaxation;
they now correctly report no window found if the full duration isn't
available, preserving the accuracy of appliance-cycle cost estimates.
Add a real (non-mocked) end-to-end test exercising apply_must_finish_by
and resolve_search_range together with a range-filtering fake pool,
reproducing the exact scenario from GH #168: a naive must_finish_by
datetime combined with search_start_day_offset: 0. The underlying fix
already landed in db5d172 but had no test covering the full request
pipeline (only individual helpers were mocked in existing tests).
Release-Notes: skip
User-Impact: none
_find_cheapest_window_in_pool() scans for contiguous available blocks
when scheduling multiple tasks. When a block-in-progress hit a
temporal gap (e.g. from price-level filtering removing intervals from
the middle of the search range, or missing API data), the scanner
jumped to i = j + 1 instead of i = j, silently skipping the interval
right after the gap as a valid — sometimes cheaper — window start.
Distinguish 'unavailable slot' (correctly skipped via j + 1) from
'temporal gap' (must retry at j, since that slot was never actually
tested as a window start).
Impact: find_cheapest_schedule can now find the true cheapest window
for a task when the search range contains time gaps, instead of
occasionally picking a more expensive window right after such a gap.
apply_segment_constraints could add far more grid energy than requested when
max_cycles_per_day or min_charge_duration_minutes forced bridging across
expensive gaps between cheap intervals. With max_cycles_per_day=1, isolated
cheap intervals were merged into one continuous segment by filling every gap
in between, without ever trimming the surplus back down, resulting in
achieved_soc_percent far above 100%.
Add a post-bridging trim step that removes segment-edge intervals (highest
price first) until total grid energy matches the requested target again,
while still respecting max_cycles_per_day/min_charge_duration_minutes and
never dropping below the target itself (fixed-power mode's expected
last-interval rounding overshoot is preserved).
A related edge case is also fixed: trimming could previously remove an
interval required to satisfy a must_reach_by deadline, silently flipping
deadline_met to False even though the overall energy target was still
reached. Deadline-critical intervals are now passed through as
protected_starts and are never removed during trimming.
Fixes#167
Impact: plan_charging no longer overcharges the battery/EV past the
requested target SoC when max_cycles_per_day or min_charge_duration_minutes
is set, and must_reach_by deadlines are honored even when those constraints
require bridging across expensive price gaps.
* fix(services): preserve service call data through coordinator data fetch
In `_handle_find_block` and `_handle_find_hours`, the local `data`
variable holding the resolved service call data was rebound to the
coordinator data dict returned by `get_entry_and_data()`. As a result,
the subsequent calls to `validate_search_params(data)`,
`apply_must_finish_by(data, ...)` and `resolve_search_range(...)` read
search-range parameters from coordinator data instead of from the
service call, silently ignoring:
- must_finish_by
- search_scope
- search_start, search_end
- search_start_time, search_end_time
- search_start_day_offset, search_end_day_offset
- search_start_offset_minutes, search_end_offset_minutes
- include_current_interval
The functions fell back to the default range ("now → end of tomorrow")
for every call that depended on these parameters.
Rename the third return value of `get_entry_and_data()` to
`coordinator_data` so the service call `data` survives, restoring
deadline and search-scope semantics. `find_cheapest_schedule.py`
already uses `data_dict` for the same purpose and was not affected.
Verified locally against v0.31.0: a call with
`must_finish_by: 2026-06-01T20:00:00+02:00` now correctly produces
`search_end: 2026-06-01T20:00:00+02:00` (was end-of-tomorrow before).
* refactor(services): update data handling in find_cheapest_schedule service
Refactor the data retrieval process to use coordinator data instead of entry data for improved clarity and consistency.
Impact: Enhances maintainability of the service code without altering user-facing functionality.
---------
Co-authored-by: “WouterK” <kwaken.geringd0w@icloud.com”git config --global user.name “WouterK”git config --global user.email kwaken.geringd0w@icloud.com”>
Co-authored-by: Julian Pawlowski <jpawlowski@users.noreply.github.com>
Add `include_current_interval` parameter to `find_cheapest_block` and
`find_cheapest_schedule` services, controlling whether the currently
active price interval can be the start of the selected window.
Add power-profile weighting to `find_cheapest_contiguous_window`: accepts
an optional `power_profile` list that weights each interval's price by
relative power draw (e.g. heat-up phase heavier than steady state). Without
a profile the behaviour is unchanged (uniform weighting).
Extend search-range tests and add price-window unit tests covering weighted
and unweighted scenarios, edge cases, and sequential scheduling interactions.
Update scheduling-actions documentation with parameter and profile examples.
Impact: Users can now model appliances with non-uniform power draw (e.g. heat
pumps, washing machines) to find truly cheapest windows based on actual energy
cost rather than average price.
Add a dedicated type-check-tests helper, wire it into check-all behind --with-test-types, and align the affected tests with current typing and helper contracts.
Impact: No direct user-facing change.
User-Impact: none
Accepts battery parameters (capacity, current/target SoC, max power) and
returns a cost-minimized charging schedule with per-interval power, SoC
progression, and total cost — no manual duration calculation needed.
Supports fixed, continuous (min_charge_power_w), and stepped
(charge_power_steps_w) charging modes, deadline-aware two-pass planning
(must_reach_soc + must_reach_by / must_reach_by_event), and round-trip
economics (expected_discharge_price, reserve_for_discharge,
max_cost_per_kwh) for arbitrage use cases. Includes min_charge_duration
and max_cycles_per_day constraints.
Groups deadline fields (must_reach_soc_*, must_reach_by,
must_reach_by_event) into a dedicated section so a deadline use case can
be configured in one place. Battery section lists capacity before the
percent SoC fields that depend on it. Response exposes stable reason
codes (already_at_target, energy_unreachable, energy_unreachable_by_
deadline, no_intervals_after_economic_filter, …) documented in the
service description and user docs.
When sequential: true, tasks are placed in declaration order instead of
being sorted by duration. Each task's search window starts after the
previous task ends (plus gap_minutes). If a task cannot be placed, all
subsequent tasks in the chain are also marked unscheduled.
Adds 12 tests covering ordering, chaining, gap enforcement, and
chain-breaking behavior.
Impact: Users can now schedule dependent appliances (e.g., washing
machine → dryer) in a single find_cheapest_schedule call with guaranteed
order, instead of chaining two find_cheapest_block calls.
Implement a new service that progressively relaxes user-defined filters to ensure a result is always returned when price data is available. This includes three phases: halving the minimum distance from average, expanding level filters, and reducing duration.
Impact: Users will receive results even when strict filters would otherwise yield no matches, improving the reliability of scheduling actions.
feat(pricing): enhance scheduling actions with new parameters
Introduce new parameters `smooth_outliers`, `min_distance_from_avg`, and `allow_relaxation` to scheduling actions, allowing for better control over price selection and ensuring results are meaningfully different from average prices.
Impact: Users can now fine-tune their scheduling actions to avoid marginal savings and ensure more uniform pricing within selected windows.
docs(scheduling): update documentation for new features
Revise the scheduling actions documentation to include new parameters and their effects, such as outlier smoothing and minimum distance from average, along with examples for better user understanding.
Impact: Users will have clearer guidance on how to utilize new features effectively in their automations.
test(scheduling): add tests for new relaxation logic
Implement unit tests to verify the behavior of the new relaxation logic in scheduling actions, ensuring that filters are correctly relaxed and results are returned as expected.
Impact: Increased test coverage and reliability of the scheduling features.
_resolve_time_with_day_offset() was calling dt_util.now() internally
instead of using the injected now parameter. This caused incorrect date
calculations in tests and any caller that passes a specific reference time.
Also add missing price_rank_* sensor keys to TIME_SENSITIVE_ENTITY_KEYS
in coordinator/constants.py so quarter-hour refresh is registered for all
11 price rank sensors (current/next/previous interval and hour variants).
Rename dt as dt_utils → dt as dt_util (ICN001) across 11 files to follow
the project-wide import alias convention. Apply ruff auto-fixes for import
ordering and collapsing single-item imports throughout the codebase.
Released-Bug: no
Add structured reason codes to no-result responses for find_cheapest_block,
find_cheapest_hours, and find_cheapest_schedule. Each handler now classifies
why no result was returned: no_data_in_range, no_intervals_matching_level_filter,
insufficient_intervals_after_filter, or insufficient_contiguous_window.
Add include_comparison_details flag to find_cheapest_schedule. When enabled,
each scheduled task includes a price_comparison field showing the most expensive
alternative window (mean, min, max, start, end) for cost-savings context.
Document stable reason code contracts in en.json service descriptions.
Add corresponding field translations to all locales (de, nb, nl, sv).
Impact: Automations and scripts can now react to why no window was found,
and schedules can display concrete savings vs. worst-case pricing.
New services for finding optimal electricity price windows:
- find_cheapest_block: Cheapest contiguous time block (e.g., dishwasher)
- find_cheapest_hours: Cheapest N hours, non-contiguous (e.g., EV charging)
- find_cheapest_schedule: Multi-task scheduling with no-overlap (e.g., shared circuit)
- find_most_expensive_block: Most expensive contiguous block (peak avoidance)
- find_most_expensive_hours: Most expensive N hours (consumption shifting)
Key features:
- Flexible search range (today, tomorrow, today+tomorrow, rolling window)
- Power profile support for variable consumption patterns
- Price level filtering (e.g., only CHEAP/VERY_CHEAP intervals)
- Comparison details showing savings vs. alternatives
- Sliding window algorithm (O(n)) for block search, greedy scheduling
for multi-task optimization
Also includes:
- Shared validation utilities (search range, price level, power profile)
- entry_id now optional on all services (auto-selects single home)
- Input validation for existing services (time range, filter conflicts)
- Service icons for all new and existing services
- Translations for all 5 languages (en, de, nb, nl, sv)
- Removed 10 unused config.error translation keys (replaced by exceptions)
- Tests for price window algorithms and search range resolution
Impact: Users can find optimal time windows for appliances, EV charging,
and multi-device scheduling via HA service calls. Existing services
improved with optional entry_id and better input validation.
Period data in array_of_arrays format now generates proper segment structure
for stepline charts. Each period produces 2-3 data points depending on
insert_nulls parameter:
1. Start time with price (begin period)
2. End time with price (hold price level)
3. End time with NULL (terminate segment, only if insert_nulls='segments'/'all')
This enables ApexCharts to correctly display periods as continuous blocks with
clean gaps between them. Previously only start point was generated, causing
periods to render as single points instead of continuous segments.
Changes:
- formatters.py: Updated get_period_data() to generate 2-3 points per period
- formatters.py: Added insert_nulls parameter to control NULL termination
- get_chartdata.py: Pass insert_nulls parameter to get_period_data()
- get_apexcharts_yaml.py: Set insert_nulls='segments' for period overlay
- get_apexcharts_yaml.py: Preserve NULL values in data_generator mapping
- get_apexcharts_yaml.py: Store original price for potential tooltip access
- tests: Added comprehensive period data format tests
Impact: Best price and peak price period overlays now display correctly as
continuous blocks with proper segment separation in ApexCharts cards.
Simplifies the connect_segments implementation to use a unified bridge-point
approach for all price transitions (up/down/same). Previously used
direction-dependent logic (hold vs connect points) which was unnecessarily
complex.
Changes:
- get_chartdata.py: Bridge points now always use next interval's price at
boundary timestamp, creating smooth visual connection between segments
- get_chartdata.py: Trailing NULL removal now conditional on insert_nulls mode
('segments' removes for header fix, 'all' preserves intentional gaps)
- get_apexcharts_yaml.py: Enable connect_segments by default, activate
show_states for header min/max display
- get_apexcharts_yaml.py: Remove extrema series (not compatible with
data_generator approach - ApexCharts requires entity time-series data)
- tests: Move test_connect_segments.py to tests/services/ to mirror source
structure
Impact: ApexCharts cards now show clean visual connections between price level
segments with proper header statistics display. Trailing NULLs no longer cause
"N/A" in headers for filtered data. Test organization improved for
maintainability.
