Registry / http-networking / aiohomematic

aiohomematic

JSON →
library2026.8.8pypypi✓ verified 6d ago

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.

pip install aiohomematic
INSTALL
IMPORT
SIG · AIOHOMEMATIC
A
aiohomematic
http-networkingpythonv2026.8.8
Install
5.0s avg
Import
2225ms
Disk
40MB
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
✓ —
✓ 5s
py 3.9
✕ build_error
✕ build_error
40MB installed
● package 40MB
Code
Verified usage

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

CentralUnit
from aiohomematic.central import CentralUnit
Client
from aiohomematic.client import Client
HostConfig
from aiohomematic.config import HostConfig
CallbackService
from aiohomematic.client import CallbackService
from aiohomematic.client.callback_service import CallbackService
CallbackService is directly exposed via aiohomematic.client since recent versions.

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.

import asyncio import logging import os from aiohomematic.central import CentralUnit from aiohomematic.client import Client, CallbackService from aiohomematic.config import HostConfig _LOGGER = logging.getLogger(__name__) async def main(): logging.basicConfig(level=logging.INFO) # Replace with your CCU IP, port, and RPC username/password ccu_host = os.environ.get('HOMEMATIC_CCU_HOST', '192.168.1.100') ccu_port = int(os.environ.get('HOMEMATIC_CCU_PORT', '2001')) # or 2010 for IP, 2000 for wired ccu_username = os.environ.get('HOMEMATIC_CCU_USERNAME', 'Admin') ccu_password = os.environ.get('HOMEMATIC_CCU_PASSWORD', 'password') # The local IP/port aiohomematic's XML-RPC client listens on for CCU callbacks client_host = os.environ.get('HOMEMATIC_CLIENT_HOST', '192.168.1.50') # Must be reachable by CCU client_port = int(os.environ.get('HOMEMATIC_CLIENT_PORT', '8080')) print(f"Connecting to CCU at {ccu_host}:{ccu_port}") print(f"Listening for callbacks on {client_host}:{client_port}") # 1. Configure the Homematic CCU connection host_config = HostConfig( name="my_ccu", host=ccu_host, port=ccu_port, path='/xmlrpc', username=ccu_username, password=ccu_password, tls=False ) # 2. Setup the callback service (the local XML-RPC server) callback_service = CallbackService(client_host, client_port) await callback_service.start() # 3. Create the aiohomematic client that connects to the CCU client = Client(callback_service, client_host, client_port, skip_certificates=True) # skip_certificates if no valid certs # 4. Create the CentralUnit and pass the host_config and client central = CentralUnit(client, host_config) try: # 5. Start the central unit (connect to CCU, fetch devices) await central.start() print("CentralUnit started. Waiting for devices...") # Example: print some device info after a delay await asyncio.sleep(10) # Give time for devices to be discovered for device_address, device in central.devices.items(): print(f"Device: {device.device_type} ({device_address})") for channel_address, channel in device.channels.items(): print(f" Channel: {channel.channel_type} ({channel_address})") # Keep running to receive events print("Running indefinitely. Press Ctrl+C to exit.") while True: await asyncio.sleep(3600) except asyncio.CancelledError: print("Application cancelled.") except Exception as e: _LOGGER.exception("An error occurred: %s", e) finally: # 6. Stop the central unit and callback service await central.stop() await callback_service.stop() print("CentralUnit and CallbackService stopped.") if __name__ == '__main__': try: asyncio.run(main()) except KeyboardInterrupt: print("Exiting.")
Debug
Known issues
breakingThe 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`.
fix
Upgrade your Python installation to version 3.14 or later.
affects: >=2026.4.11
gotchaHomematic 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).
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.
affects: All
gotchaHomematic 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.
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.
affects: All
gotchaDue 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.
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.
affects: All
Upgrade
Version history
2026.8.8latest on PyPI · released Aug 29, 2026
Audit
Dependencies
aiohttprequiredAsynchronous HTTP client/server for network communication.
async_timeoutrequiredAsync timeout utilities for network operations.
xmlrpc_client_asyncrequiredAsynchronous XML-RPC client for communicating with Homematic CCU.
Agent activity
50 hits · last 30 days
node
40
Amazon
1
Resources
aiohomematic — pip install aiohomematic · libregistry