{"id":5838,"library":"aiohomematic","title":"aiohomematic","description":"aiohomematic is an asynchronous Python library providing an interface to Homematic CCU (Central Control Unit) devices, primarily designed for integration with Home Assistant. It handles XML-RPC communication with the CCU, managing device states and controlling Homematic devices. The library follows a rapid release cadence, often aligning with Home Assistant core updates.","status":"active","version":"2026.4.11","language":"en","source_language":"en","source_url":"https://github.com/sukramj/aiohomematic","tags":["homematic","home-automation","async","home-assistant","xml-rpc"],"install":[{"cmd":"pip install aiohomematic","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Asynchronous HTTP client/server for network communication.","package":"aiohttp"},{"reason":"Async timeout utilities for network operations.","package":"async_timeout"},{"reason":"Asynchronous XML-RPC client for communicating with Homematic CCU.","package":"xmlrpc_client_async"}],"imports":[{"symbol":"CentralUnit","correct":"from aiohomematic.central import CentralUnit"},{"symbol":"Client","correct":"from aiohomematic.client import Client"},{"symbol":"HostConfig","correct":"from aiohomematic.config import HostConfig"},{"note":"CallbackService is directly exposed via aiohomematic.client since recent versions.","wrong":"from aiohomematic.client.callback_service import CallbackService","symbol":"CallbackService","correct":"from aiohomematic.client import CallbackService"}],"quickstart":{"code":"import asyncio\nimport logging\nimport os\nfrom aiohomematic.central import CentralUnit\nfrom aiohomematic.client import Client, CallbackService\nfrom aiohomematic.config import HostConfig\n\n_LOGGER = logging.getLogger(__name__)\n\nasync def main():\n    logging.basicConfig(level=logging.INFO)\n\n    # Replace with your CCU IP, port, and RPC username/password\n    ccu_host = os.environ.get('HOMEMATIC_CCU_HOST', '192.168.1.100')\n    ccu_port = int(os.environ.get('HOMEMATIC_CCU_PORT', '2001')) # or 2010 for IP, 2000 for wired\n    ccu_username = os.environ.get('HOMEMATIC_CCU_USERNAME', 'Admin')\n    ccu_password = os.environ.get('HOMEMATIC_CCU_PASSWORD', 'password')\n\n    # The local IP/port aiohomematic's XML-RPC client listens on for CCU callbacks\n    client_host = os.environ.get('HOMEMATIC_CLIENT_HOST', '192.168.1.50') # Must be reachable by CCU\n    client_port = int(os.environ.get('HOMEMATIC_CLIENT_PORT', '8080'))\n\n    print(f\"Connecting to CCU at {ccu_host}:{ccu_port}\")\n    print(f\"Listening for callbacks on {client_host}:{client_port}\")\n\n    # 1. Configure the Homematic CCU connection\n    host_config = HostConfig(\n        name=\"my_ccu\",\n        host=ccu_host,\n        port=ccu_port,\n        path='/xmlrpc',\n        username=ccu_username,\n        password=ccu_password,\n        tls=False\n    )\n\n    # 2. Setup the callback service (the local XML-RPC server)\n    callback_service = CallbackService(client_host, client_port)\n    await callback_service.start()\n\n    # 3. Create the aiohomematic client that connects to the CCU\n    client = Client(callback_service, client_host, client_port, skip_certificates=True) # skip_certificates if no valid certs\n\n    # 4. Create the CentralUnit and pass the host_config and client\n    central = CentralUnit(client, host_config)\n\n    try:\n        # 5. Start the central unit (connect to CCU, fetch devices)\n        await central.start()\n        print(\"CentralUnit started. Waiting for devices...\")\n\n        # Example: print some device info after a delay\n        await asyncio.sleep(10) # Give time for devices to be discovered\n        for device_address, device in central.devices.items():\n            print(f\"Device: {device.device_type} ({device_address})\")\n            for channel_address, channel in device.channels.items():\n                print(f\"  Channel: {channel.channel_type} ({channel_address})\")\n\n        # Keep running to receive events\n        print(\"Running indefinitely. Press Ctrl+C to exit.\")\n        while True:\n            await asyncio.sleep(3600)\n\n    except asyncio.CancelledError:\n        print(\"Application cancelled.\")\n    except Exception as e:\n        _LOGGER.exception(\"An error occurred: %s\", e)\n    finally:\n        # 6. Stop the central unit and callback service\n        await central.stop()\n        await callback_service.stop()\n        print(\"CentralUnit and CallbackService stopped.\")\n\nif __name__ == '__main__':\n    try:\n        asyncio.run(main())\n    except KeyboardInterrupt:\n        print(\"Exiting.\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to a Homematic CCU using `aiohomematic`. It involves configuring the CCU's connection details (`HostConfig`), setting up a local XML-RPC server (`CallbackService`) for the CCU to push updates, and then initializing `CentralUnit` to manage devices. Ensure the client's host IP and port are reachable by your Homematic CCU."},"warnings":[{"fix":"Upgrade your Python installation to version 3.14 or later.","message":"The library now requires Python 3.14 or newer. Users on older Python versions (e.g., 3.10, 3.11, 3.12, 3.13) must upgrade their Python environment to use recent versions of `aiohomematic`.","severity":"breaking","affected_versions":">=2026.4.11"},{"fix":"Verify network connectivity and firewall settings. Use an IP address for `client_host` that the CCU can route to. Double-check the CCU's settings for the remote script interface if manually configured.","message":"Homematic CCUs communicate with `aiohomematic` via an XML-RPC callback service. You must ensure the IP address and port configured for the `CallbackService` are accessible from the CCU (e.g., firewall rules, correct network interface selection, no NAT issues).","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure a stable network connection between your Python application and the CCU. Monitor Homematic device status in the CCU. The built-in retry mechanism in `aiohomematic` helps, but persistent issues may require hardware or network troubleshooting.","message":"Homematic devices and CCUs can be prone to transient errors such as network timeouts, device unreachability, and duty cycle exhaustion. `aiohomematic` includes a `CommandRetryHandler` to mitigate these, but users should be aware of the underlying challenges.","severity":"gotcha","affected_versions":"All"},{"fix":"Refer to the GitHub release notes and Home Assistant Homematic integration documentation for any significant changes related to device interaction or configuration when upgrading.","message":"Due to its close integration with Home Assistant's Homematic component, `aiohomematic`'s internal APIs or device representations might evolve. While efforts are made to maintain a stable public interface, specific device models or complex interactions may require adapting to changes.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}