SukramJ/homematicip_local 2.2.0b0

on GitHub

What's Changed

Bug Fixes

• Fix Translation Error When Skipping Backend Detection: Fixed "The intl string context variable 'detected_interfaces' was not provided" error when using the "Skip automatic backend detection" option in the config flow. The interface step now provides a default placeholder value when detection results are not available.
• Fix Missing device_class for Update Entities: Update entities for device firmware and hub updates now correctly report device_class: firmware. Previously the device_class was not set despite having an entity description rule defined.

Internal

• Remove Unused UpdateEntityDescription Defaults: Removed UpdateEntityDescription entries for UPDATE and HUB_UPDATE from defaults.py since Update entities don't use the generic entity helper system. The device_class is now set directly on the entity classes.
• Migrate Event Platform to ChannelEventGroup: Migrated the event platform from individual GenericEvent subscriptions to the new ChannelEventGroupProtocol pattern. Event groups are now virtual data points bound to channels, providing unified subscription management via subscribe_to_data_point_updated(). This simplifies subscription handling (single subscription per entity instead of one per event type) and aligns with the standard CallbackDataPointProtocol pattern.
• Config Entry Migration v14: Added entity registry migration for event entities to update unique_ids from the old channel-based format (homematicip_local_{channel_unique_id}) to the new event_group-based format (homematicip_local_event_group_homematic.keypress_{channel_unique_id}). This ensures existing event entities are preserved when upgrading from version 2.1.2.
• Config Entry Migration v15: Added migration to remove deprecated OptionalSettings values from config entry data. Removes ENABLE_LINKED_ENTITY_CLIMATE_ACTIVITY (now always enabled) and USE_INTERFACE_CLIENT (legacy client removed) that were removed in aiohomematic 2026.1.44.
• Local Validators: Implemented local voluptuous validators (validate_channel_no, validate_wait_for, validate_device_address, validate_channel_address, validate_paramset_key) in support.py to replace validators removed from aiohomematic after its migration to Pydantic.

Bump aiohomematic to 2026.1.45

New Features

• Free-Threaded Python Support: Added compatibility with Python 3.14 free-threaded builds (no GIL) through a new compatibility module. Includes detection functions and a conditional JSON backend that automatically selects orjson on standard builds while falling back to stdlib json on free-threaded versions.
• CentralRegistry for Thread-Safe Instance Management: New thread-safe registry replaces the previous module-level dictionary for managing CentralUnit instances, employing a copy-on-read pattern safe for both GIL-enabled and free-threaded Python environments.
• orjson Now Optional: orjson is no longer a required dependency. Install via pip install aiohomematic[fast] for enhanced JSON serialization on standard Python builds. All JSON operations now use a compatibility module that automatically selects the best available backend.
• Paramset Description Patching System: Added a generic mechanism to correct faulty paramset_descriptions from the CCU. The system applies device-specific corrections during data ingestion using declarative patch definitions. Initial patch corrects HM-CC-VG-1 channel 1 SET_TEMPERATURE MIN/MAX values (4.5/30.5) instead of the incorrect CCU-provided values.
• translation_key for Data Points: All data point types now provide a consistent translation_key property for translations. This includes hub sensors, metrics sensors, inbox, install mode, device/system updates, and calculated data points.
• Startup Resilience for Authentication Errors: Added a 3-stage validation approach for improved startup reliability: TCP pre-flight check validates port availability, client creation & RPC validation verifies backend communication, and retry with exponential backoff handles transient errors before failing. New TimeoutConfig parameters: startup_max_init_attempts (default: 5), startup_init_retry_delay (default: 3s), and startup_max_init_retry_delay (default: 30s).
• Device Availability Events for Forced Availability: The force_device_availability method now fires DeviceLifecycleEventType.AVAILABILITY_CHANGED events, ensuring the integration receives proper notifications when device availability is manually changed.
• SensorValueMixin: New mixin class consolidating duplicated value transformation logic between DpSensor (generic) and SysvarDpSensor (hub). Provides standardized handling for value list lookup, converter functions, and string length validation.

Changed

• ChannelEventGroup as Virtual Data Point: Refactored ChannelEventGroup from a helper class to a virtual data point bound to the Channel. Event groups now extend CallbackDataPoint and follow the standard subscription pattern with subscribe_to_data_point_updated(). See migration guide: docs/migrations/channel_event_group_migration_2026_01.md.
• Replace Voluptuous with Pydantic: Migrated all validation from voluptuous to Pydantic for improved type safety and validation. Address validation patterns (DEVICE_ADDRESS_PATTERN, CHANNEL_ADDRESS_PATTERN) remain available as compiled regex patterns in aiohomematic.const.
• Async RPC Server is Now Standard: The async XML-RPC server (using aiohttp) is now the only RPC server implementation. The legacy thread-based XML-RPC server has been removed along with OptionalSettings.ASYNC_RPC_SERVER.
• InterfaceClient is Now Standard: The legacy client implementations (ClientCCU, ClientJsonCCU, ClientHomegear) and handler classes have been removed. InterfaceClient with the Backend Strategy Pattern is now the only implementation. OptionalSettings.USE_INTERFACE_CLIENT has been removed.
• Linked Entity Climate Activity Always Enabled: The OptionalSettings.ENABLE_LINKED_ENTITY_CLIMATE_ACTIVITY feature flag has been removed - linked entity climate activity is now always enabled.

Bug Fixes

• Automatic Reconnection After Startup Failures: Fixed scenarios where the backend was unavailable during Home Assistant startup. The integration previously remained in FAILED state indefinitely. Now the heartbeat timer automatically activates when central transitions to FAILED state during startup, with recovery attempts every 60 seconds (configurable). Port resolution for TCP checks falls back to interface configuration when client doesn't exist.
• Cache Schema v3: Cache schema bumped to v3 with automatic rebuild when the schema version changes.
• Legacy Cache Migration for Climate Schedules: Fixed ValidationException: Time 360 is invalid error when starting with cached schedule data. The issue was old cached endtime values stored as numeric strings ("360") instead of integers or time strings. A new helper handles all three formats.
• Coordinated Cache Clearing on Version Mismatch: Fixed issue where only one cache was cleared on schema version change. Now both device and paramset description caches are cleared together, preventing incomplete rebuilds.
• Sound Player Soundfile Default Handling: Fixed turn_on() to use the entity's current value or default when soundfile is not provided, instead of always defaulting to "INTERNAL_SOUNDFILE".
• Backend Detection Timeout Support: Fixed TypeError: ServerProxy.__init__() got an unexpected keyword argument 'timeout'. Introduced custom transport classes for proper socket timeout handling.