aiohomematic 2025.9.1

Homematic interface for Home Assistant running on Python 3.

AIO Homematic (hahomematic)

A lightweight Python 3 library that powers Home Assistant integrations for controlling and monitoring HomeMatic and HomematicIP devices. Some third‑party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.

This project is the modern successor to pyhomematic, focusing on automatic entity creation, fewer manual device definitions, and faster startups.

How it works

Unlike pyhomematic, which required manual device mappings, aiohomematic automatically creates entities for each relevant parameter on every device channel (unless blacklisted). To achieve this it:

• Fetches and caches device paramsets (VALUES) for fast successive startups.
• Provides hooks for custom entity classes where complex behavior is needed (e.g., thermostats, lights, covers, climate, locks, sirens).
• Includes helpers for robust operation, such as automatic reconnection after CCU restarts.

Key features

• Automatic entity discovery from device/channel parameters.
• Extensible via custom entity classes for complex devices.
• Caching of paramsets to speed up restarts.
• Designed to integrate with Home Assistant.

Quickstart for Home Assistant

Use the Home Assistant custom integration "Homematic(IP) Local", which is powered by aiohomematic.

1. Prerequisites
   • Home Assistant 2024.6 or newer recommended.
   • A CCU3, RaspberryMatic, or Homegear instance reachable from Home Assistant.
   • For HomematicIP devices, ensure CCU firmware meets the minimum versions listed below.
2. Install the integration
   • Add the custom repository and install: https://github.com/sukramj/homematicip_local
   • Follow the installation guide: https://github.com/sukramj/homematicip_local/wiki/Installation
3. Configure via Home Assistant UI
   • In Home Assistant: Settings → Devices & Services → Add Integration → search for "Homematic(IP) Local".
   • Enter the CCU/Homegear host (IP or hostname). If you use HTTPS on the CCU, enable SSL and accept the certificate if self‑signed.
   • Provide credentials if your CCU requires them.
   • Choose which interfaces to enable (HM, HmIP, Virtual). Default ports are typically 2001 (HM), 2010 (HmIP), 9292 (Virtual).
4. Network callbacks
   • The integration needs to receive XML‑RPC callbacks from the CCU. Make sure Home Assistant is reachable from the CCU (no NAT/firewall blocking). The default callback port is 43439; you can adjust it in advanced options.
5. Verify
   • After setup, devices should appear under Devices & Services → Homematic(IP) Local. Discovery may take a few seconds after the first connection while paramsets are fetched and cached for faster restarts.

If you need to use aiohomematic directly in Python, see the Public API and example below.

Requirements

Due to a bug in earlier CCU2/CCU3 firmware, aiohomematic requires at least the following versions when used with HomematicIP devices:

• CCU2: 2.53.27
• CCU3: 3.53.26

See details here: https://github.com/jens-maus/RaspberryMatic/issues/843. Other CCU‑like platforms using the buggy HmIPServer version are not supported.

Public API and imports

• The public API of aiohomematic is explicitly defined via all in each module and subpackage.
• Backwards‑compatible imports should target these modules:
  • aiohomematic.central: CentralUnit, CentralConfig and related schemas
  • aiohomematic.client: Client, InterfaceConfig, create_client, get_client
  • aiohomematic.model: device/data point abstractions (see subpackages for details)
  • aiohomematic.exceptions: library exception types intended for consumers
  • aiohomematic.const: constants and enums (stable subset; see module all)
• The top‑level package only exposes version to avoid import cycles and keep startup lean. Prefer importing from the specific submodules listed above.

Example:

from aiohomematic.central import CentralConfig
from aiohomematic import client as hmcl

cfg = CentralConfig(
    central_id="ccu-main",
    host="ccu.local",
    username="admin",
    password="secret",
    default_callback_port=43439,
    interface_configs={hmcl.InterfaceConfig(interface=hmcl.Interface.HMIP, port=2010, enabled=True)},
)
central = cfg.create_central()

Useful links

• Changelog: see for release history and latest changes.
• Definition of calculated data points: see
• Naming: see for how device, channel and data point names are created.
• Homematic(IP) Local integration: https://github.com/sukramj/homematicip_local
• Input select helper: see for an overview of how to use the input select helper.
• Troubleshooting with Home Assistant: see for common issues and how to debug them.
• Unignore mechanism: see for how to unignore devices that are ignored by default.

Useful developer links

• Architecture overview: see for an overview of the architecture of the library.
• Data flow: see for an overview of how data flows through the library.
• Extending the model: see for adding custom device profiles and calculated data points.
• Home Assistant lifecycle (discovery, updates, teardown): see for details on how the integration works and how to debug issues.
• RSSI fix: see for how RSSI values are fixed for Home Assistant.
• Sequence diagrams: see for a sequence diagram of how the library works.