Registry / communication / aiohomematic-config

aiohomematic-config

JSON →
library2026.5.0pypypiunverified

Aiohomematic-config is a presentation-layer library for generating and managing configuration schemas for Homematic devices. It forms a core component of the Homematic(IP) Local Home Assistant integration, abstracting complex device parameter logic into a structured format suitable for user interfaces. The library is actively maintained with frequent releases, currently at version 2026.4.2.

pip install aiohomematic-config
INSTALL
IMPORT
SIG · AIOHOMEMATIC-CONFI
A
aiohomematic-config
communicationpythonv2026.5.0
Install
5.4s avg
Import
Disk
58MB
Pass rate
2/ 10
Env Coverage2 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2026.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.12
✕ build_error
✕ build_error
py 3.13
✓ —
✓ 5.38s
py 3.9
✕ build_error
✕ build_error
58MB installed
● package 58MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FormSchemaGenerator
from aiohomematic_config.config_schema import FormSchemaGenerator
ConfigChangeLog
from aiohomematic_config.config_change_log import ConfigChangeLog
DeviceScheduleData
from aiohomematic_config.models import DeviceScheduleData
set_schedule_enabled
from aiohomematic_config.facades import set_schedule_enabled

This quickstart demonstrates how to instantiate the `FormSchemaGenerator` and use it to generate a configuration schema for a hypothetical Homematic device channel. It involves setting up a `CentralUnit` (mocked for simplicity here, but would connect to a real CCU/Homegear in practice) and then calling `generate` with device and channel details to get a structured `FormSchema` object.

import asyncio from aiohomematic_config.config_schema import FormSchemaGenerator from aiohomematic.central import CentralConfig, CentralUnit from aiohomematic.const import Interface async def main(): # This is a simplified example. In a real scenario, you'd connect to a CCU. # We'll mock a CentralUnit to demonstrate FormSchemaGenerator usage. # 1. Setup a dummy CentralUnit (usually connected to a real CCU/Homegear) config = CentralConfig( name="mock-ccu", host="127.0.0.1", # Not actually connecting, just for object creation port=2001, interfaces={Interface.BIDCOS_RF: "0"} ) central = CentralUnit(config) await central.start_connection() # 2. Assume you have a device and channel address # In a real setup, you'd get these from `central.devices` device_address = "ABC1234567" channel_address = f"{device_address}:1" # Mock a device and channel for schema generation demonstration # In reality, central.get_device() would return a real device. # For this quickstart, we'll create a placeholder. class MockDevice: def __init__(self, address): self.address = address self.channels = {1: MockChannel(f'{address}:1')} class MockChannel: def __init__(self, address): self.address = address self.type = 'CLIMATE_CONTROL_RT_TRANSCEIVER' # The FormSchemaGenerator needs access to the CentralUnit for metadata # and potentially to fetch current parameter values. schema_generator = FormSchemaGenerator(central=central) try: # 3. Generate a form schema for a specific device channel # In a real application, you'd pass a real device_type and channel_type # from aiohomematic.device or aiohomematic.channel objects. form_schema = await schema_generator.generate( device_address=device_address, device_type="HM-CC-RT-DN", # Example device type channel_address=channel_address, channel_type="CLIMATE_CONTROL_RT_TRANSCEIVER", # Example channel type is_hmip=False # Indicate if it's a Homematic IP device ) print(f"Generated Form Schema for {channel_address}:") # The form_schema object would contain fields, constraints, etc. # print(form_schema.json(indent=2)) # Requires pydantic to_json (or similar) method if FormSchema is Pydantic model print(f"Schema has {len(form_schema.fields)} fields.") print(f"Schema title: {form_schema.title}") except Exception as e: print(f"Error generating schema: {e}") finally: await central.stop_connection() if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
breakingAs of version 2026.3.2, aiohomematic-config requires Python 3.14 or newer. Support for Python 3.13 and older versions has been dropped.
fix
Upgrade your Python environment to 3.14 or later. Ensure your deployment environment (e.g., Home Assistant OS) meets this requirement.
affects: >=2026.3.2
breakingThe `aiohomematic` dependency is frequently updated, and `aiohomematic-config` often bumps its minimum required `aiohomematic` version. Ensure `aiohomematic` is kept up-to-date alongside `aiohomematic-config` to avoid compatibility issues.
fix
Always install the latest version of `aiohomematic` when upgrading `aiohomematic-config`, or ensure `pip` resolves to a compatible `aiohomematic` version (e.g., `pip install aiohomematic-config 'aiohomematic>=<REQUIRED_VERSION>'`).
affects: All versions
gotchaWhen used within Home Assistant, users often confuse the version of `aiohomematic` or `aiohomematic-config` with the `homematicip_local` integration version or Home Assistant Core version. This can lead to misdiagnosed problems when reporting issues.
fix
Always provide the explicit version of `homematicip_local` (from Home Assistant's integrations page) and the specific library versions (`aiohomematic`, `aiohomematic-config`) when seeking support.
affects: All versions
breakingVersion 2026.4.0 introduced receiver type alias resolution and applied them in `ProfileStore` and `ParameterGrouper`. Custom logic relying on previous raw channel types might need adjustment.
fix
Review any custom code that directly interacts with channel types or profile lookups to ensure compatibility with the new alias resolution, especially for channels sharing profiles (e.g., `OPTICAL_SIGNAL_RECEIVER` aliasing to `DIMMER_VIRTUAL_RECEIVER`).
affects: >=2026.4.0
breakingSeveral schema generation features like `CrossValidationConstraint`, semantic parameter grouping, and metadata-based parameter ordering were added in 2026.3.5 and 2026.3.4. Consumers of `FormSchema` might see new fields or structural changes.
fix
Update frontend or consuming logic to properly handle new fields like `cross_validation`, `parameter_groups`, `visible_when`, `presets`, `allow_custom_value`, `subset_group_id`, `SubsetOption`, `SubsetGroup` within the `FormSchema` and `FormParameter` models.
affects: >=2026.3.4
Upgrade
Version history
2026.5.0latest on PyPI · released May 29, 2026
Audit
Dependencies
aiohomematicrequiredProvides the core asynchronous interface to Homematic devices; aiohomematic-config builds presentation logic on top of it.
PythonrequiredRequires Python 3.14 or newer.
Agent activity
56 hits · last 30 days
node
46
OpenAI (training)
1
Resources
aiohomematic-config — pip install aiohomematic-config · libregistry