SukramJ/homematicip_local 2.3.0b1

on GitHub

What's Changed

Added

• Command throttle interval config option: Added command_throttle_interval to Advanced Options (config flow and options flow). Controls the minimum delay between consecutive device commands per RF interface to ensure smooth operation and prevent packet loss during bulk operations. Default: 0.1s. Set to 0.0 to disable.

• Optimistic rollback events: Added homematicip_local.optimistic_rollback event and logbook integration. When an optimistic state update is rolled back (e.g. CCU rejects the value or times out), the event is fired and displayed in the logbook with the parameter name and rollback reason.

• Command throttle diagnostics: Added per-interface command throttle statistics to the diagnostics export, including interval, queue size, throttled/critical/burst counts, and burst detection thresholds.

• Domain-specific schedule services: Replaced generic set_schedule/get_schedule with domain-specific services for better validation and IDE support:

  Domain	Set Schedule	Get Schedule
  switch	switch_set_schedule	switch_get_schedule
  light	light_set_schedule	light_get_schedule
  cover	cover_set_schedule	cover_get_schedule
  valve	valve_set_schedule	valve_get_schedule

• Domain-specific Voluptuous schemas: Added comprehensive input validation at service call level:

  • Switch: Level must be binary (0.0 or 1.0), no ramp_time, no level_2
  • Light: Supports ramp_time for smooth dimming, no level_2
  • Cover: Supports level_2 for slat position, no duration/ramp_time
  • Valve: Supports duration, no level_2/ramp_time

• Improved error handling: Extended handle_homematic_errors decorator to catch ValueError and pydantic.ValidationError, converting them to user-friendly HomeAssistantError messages

Changed

• Config entry migration v16: Existing config entries are migrated to include command_throttle_interval with the default value

Removed (Deprecated Services)

The following deprecated climate services have been removed earlier than the announced April 2026 date. Due to the complexity of maintaining both old and new schedule APIs alongside the aiohomematic Pydantic model migration, these services were removed now:

• get_schedule_profile → Use get_schedule_simple_profile instead
• get_schedule_weekday → Use get_schedule_simple_weekday instead
• set_schedule_profile → Use set_schedule_simple_profile instead
• set_schedule_weekday → Use set_schedule_simple_weekday instead

The "simple" services remain fully backward compatible and continue to work as before.

Bump aiohomematic to 2026.2.5

New Features (aiohomematic)

• Optimistic updates (2026.2.4): Data points immediately update their state when send_value() is called, then rollback if the CCU rejects the value or times out. Fires OptimisticRollbackEvent on rollback. Configurable via TimeoutConfig.optimistic_update_timeout (default: 30s).

• Command throttle (2026.2.4): Configurable per-interface rate limiting for outgoing device commands. Enforces a minimum delay between consecutive commands on the same RF interface to ensure smooth operation and prevent packet loss. Configurable via TimeoutConfig.command_throttle_interval.

• Command priority queue (2026.2.4): Three-tier priority system for command throttling:

  • CRITICAL (priority 0): Security commands (locks, sirens) bypass throttle entirely
  • HIGH (priority 1): Interactive user commands use normal throttle
  • LOW (priority 2): Burst detection automatically downgrades commands when thresholds are exceeded

• CRITICAL queue purge (2026.2.4): When a CRITICAL command arrives (e.g. cover STOP), all pending queued commands for the same channel group are purged from the throttle queue, preventing queued movement commands from overriding STOP.

• Domain-specific schedule validation (2026.2.3): Added validation for schedule data based on device category (SWITCH, LIGHT, COVER, VALVE). The validation enforces that only appropriate fields are used for each device type. Backward-compatible: validation is only applied when domain context is provided.

• Schedule Pydantic Models: New validated Pydantic models for automatic validation with clear error messages:

  Climate devices:

  • ClimateSchedulePeriod: Validates temperature periods with starttime, endtime, temperature
  • ClimateWeekdaySchedule: Validates daily schedules with base_temperature and periods
  • ClimateProfileSchedule: Validates weekly schedules (MONDAY-SUNDAY)
  • ClimateSchedule: Validates complete profiles (P1-P6)

  Non-climate devices:

  • SimpleScheduleEntry: Validated schedule entry with weekdays, time, condition, target_channels, level, duration, ramp_time
  • SimpleSchedule: Container for multiple schedule entries keyed by group number (1-24)

Bug Fixes (aiohomematic)

• Optimistic mismatch false positives (2026.2.5): Fixed false OPTIMISTIC_MISMATCH warnings when the CCU rounds float values (e.g., optimistic 0.3803… vs CCU-confirmed 0.38). Float values are now rounded to 2 decimal places before comparison.
• Optimistic burst false rollbacks (2026.2.5): Fixed false OptimisticRollbackEvent and logbook entries during rapid command bursts (e.g., dimming a light through multiple values). Intermediate CCU confirmations are now silently accepted; mismatch is only evaluated on the final confirmation when all pending sends have been acknowledged.
• Optimistic mismatch no longer fires rollback events (2026.2.5): VALUE_MISMATCH no longer publishes OptimisticRollbackEvent. When the CCU confirms a different value (e.g., clamping to minimum dimming level), the CCU value is silently accepted as authoritative. Rollback events are now only published for actual rollbacks (TIMEOUT, SEND_ERROR).
• i18n format specs (2026.2.5): Fixed i18n.tr() silently dropping format specifiers like {interval:.3f}. Placeholders with format specs now render correctly in log messages.
• Optimistic updates in collector path (2026.2.4): Fixed optimistic values interfering with is_state_change() checks in parent service methods. Optimistic values are now deferred until send_data() when using CallParameterCollector.
• Cover target levels (2026.2.4): Fixed _target_level and _target_tilt_level properties to check for None before calling float(), preventing type errors.
• JSON control character sanitization (2026.2.2): Fixed JSONDecodeError when ReGa scripts return JSON containing unescaped control characters in device names or values. The sanitization is now selective - it only escapes control characters within JSON string values, preserving structural whitespace.
• CustomDataPoint schedule conversion (2026.2.2): Fixed get_schedule() and set_schedule() methods to correctly convert between ScheduleDict and SimpleSchedule Pydantic model.
• LINK Paramset Validation (2026.2.1): Fixed put_paramset with check_against_pd=True for LINK paramsets. Validation is now automatically skipped for LINK calls to prevent "Parameter not found" errors.
• Schedule Pydantic Models JSON Serialization (2026.2.1): Added _JsonSerializableMixin to all schedule Pydantic models to support orjson/Home Assistant JSON serialization.
• ClimateWeekProfile Type Signature (2026.2.1): Fixed incorrect type annotation in convert_dict_to_raw_schedule().

Breaking Changes (aiohomematic)

• Climate Schedule API Unified to Pydantic Models (2026.2.1): The old dual-format API (TypedDict + Pydantic) has been removed. All schedule methods now use Pydantic models exclusively.

  Renamed methods in BaseCustomDpClimate:

  • simple_schedule → schedule
  • get_schedule_simple_profile() → removed (use get_schedule_profile())
  • get_schedule_simple_schedule() → get_schedule()
  • get_schedule_simple_weekday() → get_schedule_weekday()
  • set_simple_schedule() → set_schedule()
  • set_simple_schedule_profile() → set_schedule_profile()
  • set_simple_schedule_weekday() → set_schedule_weekday()

Changed (aiohomematic)

• ClimateWeekProfile: Simple schedule format now uses Pydantic models for automatic validation. The existing user-facing format remains unchanged (no breaking changes), but input validation is now more robust with clear error messages.
• DefaultWeekProfile: Refactored schedule cache to use human-readable Pydantic models (SimpleSchedule, SimpleScheduleEntry) instead of complex dictionary format.

Validation Improvements (aiohomematic)

Climate schedule validation now checks:

• Time format (HH:MM, supports 24:00 for end-of-day)
• Required fields (starttime, endtime, temperature)
• Time sequence (start < end)
• No overlapping periods
• Valid weekdays (MONDAY-SUNDAY)
• Valid profiles (P1-P6)

Documentation (aiohomematic)

• Week profile: Added comprehensive documentation for SimpleScheduleEntry fields including device-type-specific meanings, condition types, and field summary table