{"id":6964,"library":"aiohomematic-config","title":"aiohomematic-config","description":"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.","status":"active","version":"2026.4.2","language":"en","source_language":"en","source_url":"https://github.com/sukramj/aiohomematic-config","tags":["homematic","home-automation","configuration","asyncio","smart-home"],"install":[{"cmd":"pip install aiohomematic-config","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the core asynchronous interface to Homematic devices; aiohomematic-config builds presentation logic on top of it.","package":"aiohomematic","optional":false},{"reason":"Requires Python 3.14 or newer.","package":"Python","optional":false}],"imports":[{"symbol":"FormSchemaGenerator","correct":"from aiohomematic_config.config_schema import FormSchemaGenerator"},{"symbol":"ConfigChangeLog","correct":"from aiohomematic_config.config_change_log import ConfigChangeLog"},{"symbol":"DeviceScheduleData","correct":"from aiohomematic_config.models import DeviceScheduleData"},{"symbol":"set_schedule_enabled","correct":"from aiohomematic_config.facades import set_schedule_enabled"}],"quickstart":{"code":"import asyncio\nfrom aiohomematic_config.config_schema import FormSchemaGenerator\nfrom aiohomematic.central import CentralConfig, CentralUnit\nfrom aiohomematic.const import Interface\n\nasync def main():\n    # This is a simplified example. In a real scenario, you'd connect to a CCU.\n    # We'll mock a CentralUnit to demonstrate FormSchemaGenerator usage.\n    \n    # 1. Setup a dummy CentralUnit (usually connected to a real CCU/Homegear)\n    config = CentralConfig(\n        name=\"mock-ccu\",\n        host=\"127.0.0.1\", # Not actually connecting, just for object creation\n        port=2001,\n        interfaces={Interface.BIDCOS_RF: \"0\"}\n    )\n    central = CentralUnit(config)\n    await central.start_connection()\n\n    # 2. Assume you have a device and channel address\n    # In a real setup, you'd get these from `central.devices`\n    device_address = \"ABC1234567\"\n    channel_address = f\"{device_address}:1\"\n    \n    # Mock a device and channel for schema generation demonstration\n    # In reality, central.get_device() would return a real device.\n    # For this quickstart, we'll create a placeholder.\n    class MockDevice:\n        def __init__(self, address):\n            self.address = address\n            self.channels = {1: MockChannel(f'{address}:1')}\n\n    class MockChannel:\n        def __init__(self, address):\n            self.address = address\n            self.type = 'CLIMATE_CONTROL_RT_TRANSCEIVER'\n    \n    # The FormSchemaGenerator needs access to the CentralUnit for metadata\n    # and potentially to fetch current parameter values.\n    schema_generator = FormSchemaGenerator(central=central)\n    \n    try:\n        # 3. Generate a form schema for a specific device channel\n        # In a real application, you'd pass a real device_type and channel_type\n        # from aiohomematic.device or aiohomematic.channel objects.\n        form_schema = await schema_generator.generate(\n            device_address=device_address,\n            device_type=\"HM-CC-RT-DN\", # Example device type\n            channel_address=channel_address,\n            channel_type=\"CLIMATE_CONTROL_RT_TRANSCEIVER\", # Example channel type\n            is_hmip=False # Indicate if it's a Homematic IP device\n        )\n        \n        print(f\"Generated Form Schema for {channel_address}:\")\n        # The form_schema object would contain fields, constraints, etc.\n        # print(form_schema.json(indent=2)) # Requires pydantic to_json (or similar) method if FormSchema is Pydantic model\n        print(f\"Schema has {len(form_schema.fields)} fields.\")\n        print(f\"Schema title: {form_schema.title}\")\n\n    except Exception as e:\n        print(f\"Error generating schema: {e}\")\n    finally:\n        await central.stop_connection()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.14 or later. Ensure your deployment environment (e.g., Home Assistant OS) meets this requirement.","message":"As of version 2026.3.2, aiohomematic-config requires Python 3.14 or newer. Support for Python 3.13 and older versions has been dropped.","severity":"breaking","affected_versions":">=2026.3.2"},{"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>'`).","message":"The `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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"Version 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.","severity":"breaking","affected_versions":">=2026.4.0"},{"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.","message":"Several 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.","severity":"breaking","affected_versions":">=2026.3.4"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `aiohomematic-config` is installed (`pip install aiohomematic-config`) and use the correct import path: `from aiohomematic_config.config_schema import FormSchemaGenerator`.","cause":"The `FormSchemaGenerator` was moved or the import path is incorrect. Or, `aiohomematic-config` might not be installed or is an older version.","error":"ImportError: cannot import name 'FormSchemaGenerator' from 'aiohomematic_config'"},{"fix":"Upgrade your Python environment to version 3.14 or later. For Home Assistant users, ensure your Home Assistant OS or container is updated to a version with Python 3.14.","cause":"The installed version of `aiohomematic-config` requires Python 3.14 or newer, but an older Python version is being used.","error":"RuntimeError: Python version 3.13 or lower is not supported. Please upgrade to Python 3.14 or higher."},{"fix":"Verify the IP address and port configured for your CCU/Homegear. Check network connectivity between your Python environment and the CCU. Ensure the CCU's RPC/XML-RPC services are running and accessible (e.g., firewall rules). For RaspberryMatic, ensure all necessary hardware interfaces are connected for services to start.","cause":"This error typically originates from the underlying `aiohomematic` library, indicating `aiohomematic-config` cannot reach the Homematic Central Control Unit. Common causes include incorrect IP address/port, network issues, firewall blocking, or the CCU's services not running.","error":"Failed to connect to CCU/Homegear: [Errno 113] Connect call failed"}]}