CentralUnit¶

The CentralUnit class is the core orchestrator that manages the connection to Homematic backends, device discovery, and event handling.

Overview¶

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()

Class Reference¶

aiohomematic.central.CentralUnit ¶

CentralUnit(*, central_config: CentralConfigProtocol)

Bases: PayloadMixin, LogContextMixin, CentralProtocol

Central unit that collects everything to handle communication from/to the backend.

Initialize the central unit.

Dependency Graph (initialization order)::

config, url, looper
     │
     ▼
event_bus ──────────────────────────────────┐
     │                                      │
     ▼                                      │
state_machine ─── health_tracker            │
                                            │
storage_factory                             │
     │                                      │
     ▼                                      │
client_coordinator ─┬─ cache_coordinator    │
                    │       │               │
                    ▼       ▼               │
            event_coordinator               │
                    │                       │
                    ▼                       │
connection_state ── json_rpc_client ◄───────┘
                                            │
device_registry ── device_coordinator ◄─────┤
                          │                 │
                          ▼                 │
                hub_coordinator ◄───────────┤
                          │                 │
                          ▼                 │
query_facade, configuration_coordinator     │
                          │                 │
                          ▼                 │
scheduler, recovery_coordinator ◄───────────┘
                          │
                          ▼
          metrics_observer, metrics_aggregator

has_ping_pong `property` ¶

has_ping_pong: bool

Return the backend supports ping pong.

system_information `property` ¶

system_information: SystemInformation

Return the system_information of the backend.

model ¶

model() -> str | None

Return the model of the backend.

version ¶

version() -> str | None

Return the version of the backend.

accept_device_in_inbox `async` ¶

accept_device_in_inbox(*, device_address: str) -> bool

Accept a device from the CCU inbox.

Parameters:

Name	Type	Description	Default
`device_address`	`str`	The address of the device to accept.	required

Returns:

Type	Description
`bool`	True if the device was successfully accepted, False otherwise.

create_backup_and_download `async` ¶

create_backup_and_download() -> BackupData | None

Create a backup on the CCU and download it.

Returns:

Type	Description
`BackupData \| None`	BackupData with filename and content, or None if backup creation or download failed.

create_client_instance `async` ¶

create_client_instance(*, interface_config: InterfaceConfig) -> ClientProtocol

Create a client for the given interface configuration.

This method implements the ClientFactoryProtocol protocol to enable dependency injection without requiring the full CentralUnit.

interface_config: Configuration for the interface

Client instance for the interface

get_data_point_by_custom_id ¶

get_data_point_by_custom_id(*, custom_id: str) -> CallbackDataPointProtocol | None

Return Homematic data_point by custom_id.

get_readable_generic_data_points ¶

get_readable_generic_data_points(*, paramset_key: ParamsetKey | None = None, interface: Interface | None = None) -> tuple[GenericDataPointProtocolAny, ...]

Return the readable generic data points.

init_install_mode `async` ¶

init_install_mode() -> Mapping[Interface, InstallModeDpType]

Initialize install mode data points (internal use - use hub_coordinator for external access).

Creates data points, fetches initial state from backend, and publishes refresh event. Returns a dict of InstallModeDpType by Interface.

load_and_refresh_data_point_data `async` ¶

load_and_refresh_data_point_data(*, interface: Interface, paramset_key: ParamsetKey | None = None, direct_call: bool = False) -> None

Refresh data_point data.

rename_device `async` ¶

rename_device(*, device_address: str, name: str, include_channels: bool = False) -> bool

Rename a device on the CCU.

Parameters:

Name	Type	Description	Default
`device_address`	`str`	The address of the device to rename.	required
`name`	`str`	The new name for the device.	required
`include_channels`	`bool`	If True, also rename all channels using the format "name:channel_no".	`False`

Returns:

Type	Description
`bool`	True if the device was successfully renamed, False otherwise.

save_files `async` ¶

save_files(*, save_device_descriptions: bool = False, save_paramset_descriptions: bool = False) -> None

Save files if they have unsaved changes.

This method uses save_if_changed() to avoid unnecessary disk writes when caches have no unsaved changes. This is particularly important during shutdown or reconnection scenarios where event-based auto-save may have already persisted the changes.

For internal use only - external code should use cache_coordinator directly.

set_install_mode `async` ¶

set_install_mode(*, interface: Interface, on: bool = True, time: int = 60, mode: int = 1, device_address: str | None = None) -> bool

Set the install mode on the backend for a specific interface.

Parameters:

Name	Type	Description	Default
`interface`	`Interface`	The interface to set install mode on (HMIP_RF or BIDCOS_RF).	required
`on`	`bool`	Enable or disable install mode.	`True`
`time`	`int`	Duration in seconds (default 60).	`60`
`mode`	`int`	Mode 1=normal, 2=set all ROAMING devices into install mode.	`1`
`device_address`	`str \| None`	Optional device address to limit pairing.	`None`

Returns:

Type	Description
`bool`	True if successful.

start `async` ¶

start() -> None

Start processing of the central unit.

stop `async` ¶

stop() -> None

Stop processing of the central unit.

validate_config_and_get_system_information `async` ¶

validate_config_and_get_system_information() -> SystemInformation

Validate the central configuration.

options: show_root_heading: true show_source: false members: - start - stop - devices - configuration - link - event_bus - state - connection_state - device_coordinator - client_coordinator - hub_coordinator - event_coordinator - cache_coordinator - query_facade - health

CentralUnit¶

Overview¶

Class Reference¶

aiohomematic.central.CentralUnit ¶

has_ping_pong property ¶

system_information property ¶

model ¶

version ¶

accept_device_in_inbox async ¶

create_backup_and_download async ¶

create_client_instance async ¶

get_data_point_by_custom_id ¶

get_readable_generic_data_points ¶

init_install_mode async ¶

load_and_refresh_data_point_data async ¶

rename_device async ¶

save_files async ¶

set_install_mode async ¶

start async ¶

stop async ¶

validate_config_and_get_system_information async ¶

has_ping_pong `property` ¶

system_information `property` ¶

accept_device_in_inbox `async` ¶

create_backup_and_download `async` ¶

create_client_instance `async` ¶

init_install_mode `async` ¶

load_and_refresh_data_point_data `async` ¶

rename_device `async` ¶

save_files `async` ¶

set_install_mode `async` ¶

start `async` ¶

stop `async` ¶

validate_config_and_get_system_information `async` ¶