aiohomematic

https://sukramj.github.io/aiohomematic
Admin
aiohomematic is an asynchronous Python library for Homematic and HomematicIP devices, enabling local...
Tokens:512,732
Snippets:4,219
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install documentation dependencies and serve locally

Source: https://sukramj.github.io/aiohomematic/contributor/contributing

Install the documentation requirements and start the MkDocs development server. Open http://127.0.0.1:8000 to preview the site.

```bash
pip install -r requirements_docs.txt
mkdocs serve
# Open http://127.0.0.1:8000
```

--------------------------------

### Complete Example

Source: https://sukramj.github.io/aiohomematic/quickstart?q=

Full quick start example: connects to a CCU, lists devices, finds a specific device, subscribes to updates, toggles a switch, and waits for events. Includes error handling and cleanup.

```python
"""Complete aiohomematic quick start example."""

import asyncio

from aiohomematic.central import CentralConfig
from aiohomematic.central.events import DataPointValueReceivedEvent
from aiohomematic.const import ParamsetKey


async def on_update(*, event: DataPointValueReceivedEvent) -> None:
    """Handle value updates."""
    print(f"UPDATE: {event.dpk.channel_address}.{event.dpk.parameter} = {event.value}")


async def main() -> None:
    """Main entry point."""
    config = CentralConfig.for_ccu(
        host="192.168.1.100",
        username="Admin",
        password="your-password",
    )
    central = await config.create_central()
    await central.start()

    try:
        # 1. List devices
        print("=== Devices ===")
        for device in central.devices:
            print(f"  {device.address}: {device.name}")

        # 2. Find a specific device
        device = central.device_coordinator.get_device(address="VCU0000001")
        if device:
            print("\n=== Device Details ===")
            print(f"  Model: {device.model}")
            print(f"  Firmware: {device.firmware}")

            # 3. List channels and data points (channels is keyed by channel address)
            for channel_address, channel in device.channels.items():
                print(f"\n  Channel {channel.no} ({channel_address}):")
                for dp in channel.generic_data_points:
                    print(f"    {dp.parameter}: {dp.value}")

        # 4. Subscribe to updates
        unsubscribe = central.event_bus.subscribe(
            event_type=DataPointValueReceivedEvent,
            event_key=None,
            handler=on_update,
        )

        # 5. Toggle a switch (if exists)
        try:
            client = central.client_coordinator.get_client(interface_id=device.interface_id)
            current = await client.get_value(
                channel_address="VCU0000001:3",
                paramset_key=ParamsetKey.VALUES,
                parameter="STATE",
            )
            await client.set_value(
                channel_address="VCU0000001:3",
                paramset_key=ParamsetKey.VALUES,
                parameter="STATE",
                value=not current,
            )
            print(f"\nToggled switch from {current} to {not current}")
        except Exception as e:
            print(f"\nCould not toggle switch: {e}")

        # 6. Wait for some events
        print("\nWaiting for events (10 seconds)...")
        await asyncio.sleep(10)

        unsubscribe()
        print("\nDone!")
    finally:
        await central.stop()


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Complete aiohomematic Quick Start Example

Source: https://sukramj.github.io/aiohomematic/quickstart

Full example that initializes a central, lists devices, toggles a switch, subscribes to events, and waits for 10 seconds. Requires a CCU with host, username, and password.

```python
"""Complete aiohomematic quick start example."""

import asyncio

from aiohomematic.central import CentralConfig
from aiohomematic.central.events import DataPointValueReceivedEvent
from aiohomematic.const import ParamsetKey


async def on_update(*, event: DataPointValueReceivedEvent) -> None:
    """Handle value updates."""
    print(f"UPDATE: {event.dpk.channel_address}.{event.dpk.parameter} = {event.value}")


async def main() -> None:
    """Main entry point."""
    config = CentralConfig.for_ccu(
        host="192.168.1.100",
        username="Admin",
        password="your-password",
    )
    central = await config.create_central()
    await central.start()

    try:
        # 1. List devices
        print("=== Devices ===")
        for device in central.devices:
            print(f"  {device.address}: {device.name}")

        # 2. Find a specific device
        device = central.device_coordinator.get_device(address="VCU0000001")
        if device:
            print("\n=== Device Details ===")
            print(f"  Model: {device.model}")
            print(f"  Firmware: {device.firmware}")

            # 3. List channels and data points (channels is keyed by channel address)
            for channel_address, channel in device.channels.items():
                print(f"\n  Channel {channel.no} ({channel_address}):")
                for dp in channel.generic_data_points:
                    print(f"    {dp.parameter}: {dp.value}")

        # 4. Subscribe to updates
        unsubscribe = central.event_bus.subscribe(
            event_type=DataPointValueReceivedEvent,
            event_key=None,
            handler=on_update,
        )

        # 5. Toggle a switch (if exists)
        try:
            client = central.client_coordinator.get_client(interface_id=device.interface_id)
            current = await client.get_value(
                channel_address="VCU0000001:3",
                paramset_key=ParamsetKey.VALUES,
                parameter="STATE",
            )
            await client.set_value(
                channel_address="VCU0000001:3",
                paramset_key=ParamsetKey.VALUES,
                parameter="STATE",
                value=not current,
            )
            print(f"\nToggled switch from {current} to {not current}")
        except Exception as e:
            print(f"\nCould not toggle switch: {e}")

        # 6. Wait for some events
        print("\nWaiting for events (10 seconds)...")
        await asyncio.sleep(10)

        unsubscribe()
        print("\nDone!")
    finally:
        await central.stop()


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Set up and run local documentation preview with MkDocs

Source: https://sukramj.github.io/aiohomematic/contributor/contributing?q=

Install documentation dependencies and start the MkDocs development server. After running 'mkdocs serve', open http://127.0.0.1:8000 in a browser to preview the documentation locally.

```bash
pip install -r requirements_docs.txt
mkdocs serve
# Open http://127.0.0.1:8000

```

--------------------------------

### Install and run pytest-markdown-docs on docs

Source: https://sukramj.github.io/aiohomematic/contributor/testing/docs_drift_check?q=

Commands to install pytest-markdown-docs and run it on the Quick Start and Getting Started pages. Not currently wired into CI.

```bash
pip install pytest-markdown-docs
pytest --markdown-docs docs/quickstart.md docs/getting_started.md

```

--------------------------------

### CentralUnit overview example

Source: https://sukramj.github.io/aiohomematic/reference/api/central?q=

Shows how to configure and start a CentralUnit using CentralConfig.for_ccu, access devices, and stop the central.

```python
from aiohomematic.central import CentralConfig

config = CentralConfig.for_ccu(
    host="192.168.1.100",
    username="Admin",
    password="secret",
)

central = config.create_central()
await central.start()

# Access devices
for device in central.devices:
    print(device.name)

await central.stop()
```

--------------------------------

### Basic Setup with CentralConfig and InterfaceConfig

Source: https://sukramj.github.io/aiohomematic/developer/consumer_api

Creates a CentralConfig with multiple interface configurations (HMIP_RF and BIDCOS_RF), then creates and starts the central unit. The create_central() method is async, and the central must be stopped in a finally block.

```python
from aiohomematic.central import CentralConfig
from aiohomematic.client import InterfaceConfig
from aiohomematic.const import Interface

# Create configuration
config = CentralConfig(
    name="my-central",
    host="192.168.1.100",
    username="admin",
    password="secret",
    central_id="unique-id-123",
    interface_configs={
        InterfaceConfig(
            central_name="my-central",
            interface=Interface.HMIP_RF,
            port=2010,
        ),
        InterfaceConfig(
            central_name="my-central",
            interface=Interface.BIDCOS_RF,
            port=2001,
        ),
    },
)

# Create and start (create_central() is async)
central = await config.create_central()
await central.start()

try:
    # Work with devices
    for device in central.devices:
        print(f"{device.address}: {device.name}")
finally:
    await central.stop()
```

--------------------------------

### Install aiohomematic with pip

Source: https://sukramj.github.io/aiohomematic

Install the aiohomematic library using pip. This is the first step in the quick start guide.

```bash
pip install aiohomematic

```

--------------------------------

### Set Up Development Environment

Source: https://sukramj.github.io/aiohomematic/contributor/contributing

Create a virtual environment, install dependencies, and set up pre-commit hooks. Note: the command 'prek install' appears to be a typo for 'pre-commit install'.

```bash
# Create virtual environment
python3.14 -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt
pip install -r requirements_test.txt

# Install pre-commit hooks
prek install

```

--------------------------------

### FactoryWithClient setup for session playback

Source: https://sukramj.github.io/aiohomematic/contributor/testing/session_playback

Creates a test factory with a session player and mocked client, then gets the default central. The central is ready for testing with mocked RPC calls, and devices can be accessed via the device coordinator.

```python
factory = FactoryWithClient(
    player=session_player,
    do_mock_client=True,
    ignore_devices_on_create=["VCU0000099"],
)
central = await factory.get_default_central(start=True)

# central is now ready for testing with mocked RPC calls
device = central.device_coordinator.get_device(address="VCU0000001")
```

--------------------------------

### Create and start async XML-RPC server

Source: https://sukramj.github.io/aiohomematic/adr/0012-async-xml-rpc-server-poc

Creates and starts an AsyncXmlRpcServer instance. If the server is not already started, it starts it and logs the listening address and port. Returns the server instance.

```python
async def create_async_xml_rpc_server(
    *,
    ip_addr: str = IP_ANY_V4,
    port: int = PORT_ANY,
) -> AsyncXmlRpcServer:
    """Create and start an async XML-RPC server."""
    server = AsyncXmlRpcServer(ip_addr=ip_addr, port=port)
    if not server.started:
        await server.start()
        _LOGGER.debug(
            "Created AsyncXmlRpcServer on %s:%d",
            server.listen_ip_addr,
            server.listen_port,
        )
    return server

```

--------------------------------

### Example 3: Missing __init__ Documentation - Before

Source: https://sukramj.github.io/aiohomematic/contributor/coding/docstring_standards

Before example of a missing __init__ docstring.

```python
def __init__(self, central, addr, channel_no):
    """Init custom entity."""

```

--------------------------------

### Property Examples

Source: https://sukramj.github.io/aiohomematic/contributor/coding/docstring_templates?q=

Examples of properties with one-line docstrings.

```python
@property
def device_address(self) -> str:
    """Return the device address."""
```

```python
@property
def available(self) -> bool:
    """Return whether device is available."""
```

```python
@property
def value(self) -> Any:
    """Return current data point value."""
```

--------------------------------

### Simple Method Examples

Source: https://sukramj.github.io/aiohomematic/contributor/coding/docstring_templates?q=

Examples of simple methods with one-line docstrings.

```python
def get_device_by_address(self, address: str) -> Device | None:
    """Return device by address."""
```

```python
def is_connected(self) -> bool:
    """Return connection status."""
```

```python
def clear_cache(self) -> None:
    """Clear all cached data."""
```

--------------------------------

### Tier 1: Core API Module Docstring Example

Source: https://sukramj.github.io/aiohomematic/contributor/coding/docstring_standards?q=

Example docstring for a core API module, showing the structure with overview, public API, and quick start sections.

```python
"""
Central unit and core orchestration for Homematic CCU and compatible backends.

Overview
--------
This package provides the central coordination layer for aiohomematic. The
CentralUnit class manages client lifecycles, device creation, event handling,
and background tasks. It serves as the primary entry point for interacting
with Homematic systems.

Public API
----------
- CentralUnit: Main coordination class for managing all operations
- CentralConfig: Configuration dataclass for central initialization

Quick start
-----------
Typical usage is to create a CentralConfig, instantiate CentralUnit,
and call start():

    config = CentralConfig(name="ccu", host="192.168.1.100", ...)
    central = config.create_central()
    await central.start()
"""

```

--------------------------------

### Simple __init__ Method Docstring Examples

Source: https://sukramj.github.io/aiohomematic/contributor/coding/docstring_templates

Examples of simple __init__ methods with one-line docstrings, showing how to document initialization of a coordinator and an event bus.

```python
def __init__(self) -> None:
    """Initialize the coordinator."""

def __init__(self) -> None:
    """Initialize the event bus."""

```

--------------------------------

### Simple __init__ Method Examples

Source: https://sukramj.github.io/aiohomematic/contributor/coding/docstring_templates?q=

Examples of simple __init__ methods with one-line docstrings.

```python
def __init__(self) -> None:
    """Initialize the coordinator."""
```

```python
def __init__(self) -> None:
    """Initialize the event bus."""
```

--------------------------------

### Simplified Setup Methods for CCU3/CCU2 and Homegear

Source: https://sukramj.github.io/aiohomematic/developer/consumer_api

Shows two convenience constructors: CentralConfig.for_ccu() for CCU3/CCU2 and CentralConfig.for_homegear() for Homegear. Both require name, host, username, and password.

```python
# For CCU3/CCU2
config = CentralConfig.for_ccu(
    name="ccu",
    host="192.168.1.100",
    username="admin",
    password="secret",
)

# For Homegear
config = CentralConfig.for_homegear(
    name="homegear",
    host="192.168.1.100",
    username="admin",
    password="secret",
)
```

--------------------------------

### Read a value from a device

Source: https://sukramj.github.io/aiohomematic/quickstart?q=

Reads the switch state of a device using the client for the device's interface. Uses ParamsetKey.VALUES and the parameter 'STATE'. The example assumes a central unit is already created and started.

```python
from aiohomematic.const import ParamsetKey

# Read switch state via the client for the device's interface
device = central.device_coordinator.get_device(address="VCU0000001")
client = central.client_coordinator.get_client(interface_id=device.interface_id)
state = await client.get_value(
    channel_address="VCU0000001:3",
    paramset_key=ParamsetKey.VALUES,
    parameter="STATE",
)
print(f"Switch is {'ON' if state else 'OFF'}")

```

--------------------------------

### Example 3: Missing __init__ Documentation - After

Source: https://sukramj.github.io/aiohomematic/contributor/coding/docstring_standards

After example of a complete __init__ docstring with parameter descriptions.

```python
def __init__(
    self,
    *,
    central: CentralUnit,
    device_address: str,
    channel_no: int,
) -> None:
    """
    Initialize custom climate entity.

    Args:
        central: Central unit instance
        device_address: Device address
        channel_no: Channel number
    """

```

--------------------------------

### Connect and list devices with CentralConfig

Source: https://sukramj.github.io/aiohomematic/quickstart?q=

Creates a central unit using CentralConfig.for_ccu, starts it, iterates over discovered devices, and stops the central unit in a finally block. The output shows example device addresses, names, and models.

```python
import asyncio
from aiohomematic.central import CentralConfig


async def main():
    config = CentralConfig.for_ccu(
        host="192.168.1.100",     
        username="Admin",         
        password="your-password", 
    )
    central = await config.create_central()
    await central.start()

    try:
        # Iterate over all discovered devices
        for device in central.devices:
            print(f"{device.address}: {device.name} ({device.model})")
    finally:
        # Always stop the central unit to release resources
        await central.stop()


asyncio.run(main())

```

```text
VCU0000001: Living Room Light (HmIP-BSM)
VCU0000002: Hallway Switch (HmIP-PS)
VCU0000003: Bedroom Thermostat (HmIP-eTRV-2)

```

--------------------------------

### Install godevccu and record session

Source: https://sukramj.github.io/aiohomematic/contributor/testing/session_playback

Commands to install godevccu and run the recording script. The script runs a central with start_direct=True and optional settings SR_RECORD_SYSTEM_INIT and SR_DISABLE_RANDOMIZE_OUTPUT. Do not randomize this recording because playback tests reference devices by address.

```bash
script/install_godevccu.sh
PYTHONPATH=. python script/record_godevccu_session.py
```

--------------------------------

### CentralConfig factory method and full configuration

Source: https://sukramj.github.io/aiohomematic/reference/api/config?q=

Shows two ways to create a CentralConfig: using the for_ccu factory method for a simple setup, and the full constructor with interface_configs for advanced configuration. The example imports CentralConfig, InterfaceConfig, and Interface.

```python
from aiohomematic.central import CentralConfig
from aiohomematic.client import InterfaceConfig
from aiohomematic.const import Interface

# Simple: Use factory methods
config = CentralConfig.for_ccu(
    host="192.168.1.100",
    username="Admin",
    password="secret",
)

# Advanced: Full configuration
config = CentralConfig(
    name="my-ccu",
    host="192.168.1.100",
    username="Admin",
    password="secret",
    central_id="unique-id",
    interface_configs={
        InterfaceConfig(
            central_name="my-ccu",
            interface=Interface.HMIP_RF,
            port=2010,
        ),
    },
)
```

--------------------------------

### init_install_mode method

Source: https://sukramj.github.io/aiohomematic/reference/api/central?q=

Initializes install mode data points. Internal use - use hub_coordinator for external access.

```python
init_install_mode() -> Mapping[Interface, InstallModeDpType]
```

--------------------------------

### CentralState STARTING attribute

Source: https://sukramj.github.io/aiohomematic/reference/api/const

The STARTING attribute of CentralState, with value 'starting'.

```python
STARTING = 'starting'
```

--------------------------------

### Complex __init__ Method Docstring Example

Source: https://sukramj.github.io/aiohomematic/contributor/coding/docstring_templates

Example of a complex __init__ method that initializes a device coordinator with three parameters, documenting each parameter.

```python
def __init__(
    self,
    *,
    central_info: CentralInfo,
    device_provider: DeviceProvider,
    client_provider: ClientProvider,
) -> None:
    """
    Initialize the device coordinator.

    Args:
        central_info: System information provider
        device_provider: Device registry access
        client_provider: Client lookup functionality
    """

```

--------------------------------

### start

Source: https://sukramj.github.io/aiohomematic/reference/api/central?q=

Starts processing of the central unit.

```APIDOC
## start

### Description
Starts processing of the central unit.

### Method
start (async)

### Signature
```
start() -> None
```

### Returns
- **None**
```

--------------------------------

### Verify Setup

Source: https://sukramj.github.io/aiohomematic/contributor/dev-environment?q=

Commands to run tests, linters, and type checking to verify the development environment is correctly set up.

```bash
# Run tests
pytest tests/

# Run linters
pre-commit run --all-files

# Type check
mypy

```
Tokens:
Raw