aiohomematic-config

2026.4.2 · active · verified Thu Apr 16

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.

Common errors

Warnings

Install

Imports

Quickstart

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())

view raw JSON →