github SukramJ/homematicip_local 2.3.0b5
on GitHub

pre-release4 hours ago

What's Changed

Breaking Changes (Schedule Services)

  • All schedule services have been migrated from entity-based to device-based. Services now use device_id or device_address instead of targeting entities. Existing automations using old service names must be updated.

  • Renamed services:

    • get_schedule_simple_profile → 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
    • set_schedule_active_profile → set_current_schedule_profile

  • Renamed entity attributes (Climate & Week Profile Sensor):

    • active_profile → current_schedule_profile

Added

  • Week profile sensor entity: New AioHomematicWeekProfileSensor entity for every device with schedule support. Exposes schedule metadata (schedule type, max entries, schedule data) as state attributes. Climate devices additionally expose temperature bounds and available profiles (P1-P6).

  • Device-based schedule services: All schedule services now use device_id or device_address for device identification. This replaces the previous domain-specific (entity-based) approach with a unified API that works for all device types.

  • 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.

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

  • device_active_profile_index attribute: Climate and week profile sensor entities now expose the 1-based profile index as reported by the device hardware. This value is automatically synced from the device's ACTIVE_PROFILE (IP) or WEEK_PROGRAM_POINTER (RF) parameter.

  • current_schedule_profile attribute: Climate and week profile sensor entities expose the currently selected schedule profile (P1–P6). Automatically synchronized with the device's active profile parameter.

  • Climate entity subscribes to week profile changes: The climate entity now subscribes to device.week_profile_data_point updates, ensuring schedule attributes (schedule_data, current_schedule_profile, available_profiles) update in real-time when the schedule changes on the device.

  • Device configuration panel: New sidebar panel for editing Homematic device MASTER parameters directly from the Home Assistant UI. Provides a form-based interface with per-channel configuration, validation, and reset-to-defaults. Enable via Advanced Options in the integration config flow. Requires aiohomematic-config.

  • Panel translations: The configuration panel UI (sidebar title, section headers, parameter labels, enum values, toggle labels) is fully translated based on the Home Assistant language setting (German and English). Parameter filtering matches the CCU WebUI easymode behavior — only parameters with known translations are shown.

  • Database recording optimization: Added _unrecorded_attributes to light, cover, switch, valve, siren, and week profile sensor entities. Static metadata attributes (e.g. available colors, channel positions, available soundfiles, schedule metadata) are now excluded from the HA recorder database, reducing storage usage.

  • Paramset inconsistency repair issue: Displays a Home Assistant repair issue when aiohomematic detects missing parameters on HmIP/HmIPW devices after firmware updates. Informs the user about affected devices and recommends a factory reset via the CCU WebUI.

  • WRC6 Blueprint: Community blueprint for 6-button wall remote (HmIP-WRC6) now supports multiple devices and includes optional direct connection collision checks. Not backwards compatible — existing automations using this blueprint need to be reconfigured.

  • Translated interface display names: Interface names in config flow error messages and detection info now use translated, user-friendly names (e.g. "Homematic IP" instead of "HmIP-RF") with full German translation support. Warning messages for undetected interfaces are also translated.

Changed

  • Entity names from backend translations: Removed redundant local entity translations (binary_sensor, button, lock, number, select, sensor, switch, valve) from strings.json and translation files. Entity names are now provided by the backend CCU translation system via translated_name. Only climate (preset modes) and event (keypress types) translations remain local.

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

Bug Fixes

  • Sub-device entity name deduplication: Fixed entity_id duplication when sub-devices are enabled. When the HA device name (channel group name) was a prefix of the backend's translated_name, the device name appeared twice in the entity_id (e.g. binary_sensor.atbm_terrasse_atbm_terrasse_schaltausgang). The device name prefix is now stripped from the entity name, producing the correct entity_id (e.g. binary_sensor.atbm_terrasse_schaltausgang).

Bump aiohomematic to 2026.2.16

Architecture (aiohomematic)

  • Architecture cleanup (2026.2.8): Query methods extracted from CentralUnit to DeviceQueryFacade (central.query_facade). Support module split into submodules (support.address, support.file_ops, support.mixins). Protocol hierarchy reorganized with new interfaces.central and interfaces.model modules. Optimistic update logic extracted to model.optimistic.

New Features (aiohomematic)

  • CCU translation extraction (2026.2.10): New script (script/extract_ccu_translations.py) that extracts human-readable translations from the OpenCCU/RaspberryMatic WebUI for channel types, device models, parameter names, and parameter enum values. Supports local OCCU checkout and remote CCU fetch. Resolves two-level stringtable indirection, URL-decodes Latin-1 characters, and strips HTML from values. 2500+ translation entries across 8 JSON files (4 categories x 2 locales).

  • CCU translations loader module (2026.2.10): New module (aiohomematic/ccu_translations.py) providing typed lookup functions for CCU-sourced translations: get_channel_type_translation(), get_device_model_description(), get_parameter_translation(), get_parameter_value_translation(). All lookups are thread-safe and asyncio event loop safe (lazy initialization, then pure dict reads with zero I/O).

  • Translated data point names (2026.2.11): Data points now expose translated name_label and name_label_with_index properties via the CCU translation system. Provides human-readable parameter names (e.g. "Temperature Offset" instead of "TEMPERATURE_OFFSET") for UI rendering.

  • Value-only translation fallback (2026.2.13): get_parameter_value_translation now has a three-tier lookup: channel-specific → parameter-specific → value-only. The new value-only fallback builds an index of standalone enum values mapped to their shortest (most generic) translation, so shared values like weekday names resolve even for unknown parameters.

  • Configurable channel filtering (2026.2.13): get_configurable_channels now applies CCU-compatible filtering rules: channels must have the VISIBLE flag set and must not have the INTERNAL flag. WEEK_PROGRAM channels are excluded as they are handled by schedule cards.

  • parameter_tools module (2026.2.9): New standalone module providing pure-function utilities for working with parameter descriptions, independent of DataPoint instances. Includes ParameterHelper (flag/operation checks, enum resolution, step size calculation), ParameterValidator (value validation, type coercion), and ParamsetDiff (type-aware paramset comparison).

  • ConfigurationCoordinator (2026.2.9): New high-level facade for device configuration operations, exposed as central.configuration. Provides get_paramset_description(), get_all_paramset_descriptions(), get_paramset(), put_paramset(), get_configurable_channels(), and get_parameter_data().

  • Paramset consistency checker (2026.2.7): Automatically detects missing parameters on HmIP/HmIPW devices after firmware updates. The HmIPServer (crRFD) on the CCU sometimes fails to refresh its stored parameter data, creating a mismatch between getParamsetDescription() (schema) and getParamset() (actual values). Reports inconsistencies via IntegrationIssue events, log warnings, and diagnostics data.

  • WeekProfileDataPoint (2026.2.6): Device-level data points that serve as the central interface for schedule data — both for climate and non-climate devices. One data point per device exposes schedule metadata, target channel mappings, and delegates read/write operations to the underlying WeekProfile. Schedule access has been removed from custom data points (BaseCustomDpClimate, CustomDataPoint) and is now exclusively available via device.week_profile_data_point.

  • Automatic profile sync from device (2026.2.6): ClimateWeekProfileDataPoint now binds the device's ACTIVE_PROFILE (IP) or WEEK_PROGRAM_POINTER (RF) generic data point. current_schedule_profile updates automatically when the thermostat switches profiles.

  • Climate CDP notification on schedule change (2026.2.6): When schedule data changes (e.g., after CONFIG_PENDING=False reload), the linked Climate CDP is automatically notified via an internal subscription, causing the HA Climate Entity to update.

  • device_active_profile_index property (2026.2.6): Returns the 1-based profile index from the device parameter (int | None). RF values are normalised from 0-based to 1-based.

  • 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 (2026.2.1): 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)

Improved (aiohomematic)

  • CCU translation loading via pkgutil (2026.2.12): Replaced Path.read_text() with pkgutil.get_data() for loading CCU translation files. Avoids blocking file I/O detection in Home Assistant's event loop. Translations are eagerly initialized at import time.

  • Robust JSON parsing with stdlib fallback (2026.2.11): When orjson fails to parse JSON from CCU Rega scripts (e.g., due to non-standard literals like NaN or Infinity), the parser now falls through to Python's stdlib json module. Extended control character sanitization to include DEL (U+007F). Diagnostic logging for JSON parse errors now includes exact codepoint, position, and surrounding context.

  • Extraction script improvements (2026.2.13): Added PNAME.txt and easymode TCL file parsing, improved HTML entity decoding. Parameters: 841 → 1029 (+188), parameter values: 1256 → 1326 (+70). Removed 17 redundant custom translation entries now covered by improved extraction.

  • Empty parameter translation suppresses parameter name (2026.2.14): When a CCU parameter translation resolves to an empty string (""), the parameter name is now omitted from translated_name and translated_full_name. This allows translations to explicitly suppress redundant parameter names when the channel name already conveys the meaning. None (no translation found) still falls back to the original untranslated name.

  • Custom data point postfix translation (2026.2.16): Custom data points now translate their data_point_name_postfix via the CCU translation system, providing localized names (e.g. translating parameter postfixes like BUTTON_LOCK) consistent with generic data points.

Bug Fixes (aiohomematic)

  • i18n: Allow multiple CentralUnit instances (2026.2.15): set_locale() is now idempotent — calling it again with the same locale is a no-op. When called with a different locale, it logs a message and keeps the original. Previously, creating a second CentralUnit raised RuntimeError because set_locale() was strictly one-shot.
  • XML-RPC server race condition on multi-hub startup (2026.2.7): Fixed a race condition in AsyncXmlRpcServer.start() that caused "address in use" errors when multiple central units started concurrently. The singleton server is now protected by an asyncio.Lock.
  • Optimistic rollback now clears unconfirmed value (2026.2.7): _rollback_optimistic_value() now properly clears the unconfirmed value before restoring the previous confirmed value, preventing the unconfirmed value from undermining the rollback.
  • CallbackDataPoint ownership reset on unsubscribe (2026.2.6): When the owning custom_id fully unsubscribes from a data point, _custom_id is now reset to None. This allows re-registration with a different custom_id (e.g. after an entity_id rename in Home Assistant), preventing AioHomematicException on resubscription.
  • 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.
  • 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.
  • 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.

Breaking Changes (aiohomematic)

  • Schedule access moved to WeekProfileDataPoint (2026.2.6): All schedule methods and properties removed from BaseCustomDpClimate and CustomDataPoint. Schedule operations are now exclusively available via device.week_profile_data_point.

  • Climate profile property renames (2026.2.6): On ClimateWeekProfileDataPointProtocol, active_profile → current_schedule_profile, active_schedule → current_profile_schedule, set_active_profile() → set_current_schedule_profile(). This avoids a naming conflict with the device parameter ACTIVE_PROFILE. copy_schedule and copy_schedule_profile parameter renamed from target_climate_data_point to target_data_point.

  • HA-Addon renamed to HA-App (2026.2.6): SystemInformation.is_ha_addon renamed to is_ha_app.

  • 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.

Changed (aiohomematic)

  • Rename _temporary_value to _unconfirmed_value (2026.2.7): All internal references renamed to clarify the role of the second value tier in the three-tier resolution model (optimistic → unconfirmed → confirmed).
  • DelegatedProperty expansion (2026.2.6): Replaced 56 boilerplate @property methods with DelegatedProperty descriptors across 23 files. Reduces repetitive delegation code while preserving runtime behavior.
  • ClimateWeekProfile: Simple schedule format now uses Pydantic models for automatic validation. The existing user-facing format remains unchanged, 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.

Bump aiohomematic-config to 2026.2.4

New companion library providing device configuration utilities for the integration.

  • FormSchemaGenerator: Generate UI form schemas from paramset descriptions
  • ParameterGrouper: Group parameters into logical sections with locale-aware section titles (German translations)
  • LabelResolver: Translate parameter IDs to human-readable labels using upstream CCU translations from aiohomematic. Includes has_translation() check for filtering parameters without known translations.
  • ConfigSession: Change tracking with undo/redo and validation
  • ConfigExporter: Export/import device configurations as JSON
  • WidgetType mapping: Type-aware widget selection
  • option_labels: VALUE_LIST parameters always include option_labels with translated enum values and humanized fallback
  • FormSchema metadata: model_description and channel_type_label fields for translated device/channel names
  • CCU-compatible parameter filtering: Only parameters with known CCU translations are shown, matching CCU WebUI easymode behavior
Check out latest releases or
releases around SukramJ/homematicip_local 2.3.0b5

Don't miss a new homematicip_local release

NewReleases is sending notifications on new releases.

Get notifications