Skip to content

CentralConfig

The CentralConfig class defines the configuration for connecting to a Homematic backend.

Overview

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,
        ),
    },
)

Class Reference

aiohomematic.central.CentralConfig

Bases: BaseModel

Configuration for CentralUnit initialization and behavior.

central_id instance-attribute 

central_id: str

Unique identifier for the central unit.

host instance-attribute 

host: str

Hostname or IP address of the CCU/Homegear.

interface_configs instance-attribute 

interface_configs: frozenset[InterfaceConfig]

Set of interface configurations.

name instance-attribute 

name: str

Name identifier for the central unit.

password instance-attribute 

password: str

Password for authentication.

username instance-attribute 

username: str

Username for authentication.

client_session class-attribute instance-attribute 

client_session: SkipValidation[ClientSession | None] = None

Optional aiohttp client session to use.

callback_host class-attribute instance-attribute 

callback_host: str | None = None

Hostname/IP for XML-RPC callback server.

callback_port_xml_rpc class-attribute instance-attribute 

callback_port_xml_rpc: int | None = None

Port for XML-RPC callback server.

default_callback_port_xml_rpc class-attribute instance-attribute 

default_callback_port_xml_rpc: int = PORT_ANY

Default port for XML-RPC callback if not specified.

delay_new_device_creation class-attribute instance-attribute 

delay_new_device_creation: bool = DEFAULT_DELAY_NEW_DEVICE_CREATION

Delay creation of new devices.

enable_device_firmware_check class-attribute instance-attribute 

enable_device_firmware_check: bool = DEFAULT_ENABLE_DEVICE_FIRMWARE_CHECK

Enable periodic device firmware checks.

enable_program_scan class-attribute instance-attribute 

enable_program_scan: bool = DEFAULT_ENABLE_PROGRAM_SCAN

Enable scanning of CCU programs.

enable_sysvar_scan class-attribute instance-attribute 

enable_sysvar_scan: bool = DEFAULT_ENABLE_SYSVAR_SCAN

Enable scanning of CCU system variables.

ignore_custom_device_definition_models class-attribute instance-attribute 

ignore_custom_device_definition_models: frozenset[str] = DEFAULT_IGNORE_CUSTOM_DEVICE_DEFINITION_MODELS

Device models to ignore for custom definitions.

interfaces_requiring_periodic_refresh class-attribute instance-attribute 

interfaces_requiring_periodic_refresh: frozenset[Interface] = DEFAULT_INTERFACES_REQUIRING_PERIODIC_REFRESH

Interfaces that need periodic refresh instead of push updates.

json_port class-attribute instance-attribute 

json_port: int | None = None

Port for JSON-RPC communication.

listen_ip_addr class-attribute instance-attribute 

listen_ip_addr: str | None = None

IP address to listen on for callback server.

listen_port_xml_rpc class-attribute instance-attribute 

listen_port_xml_rpc: int | None = None

Port to listen on for XML-RPC callback server.

max_read_workers class-attribute instance-attribute 

max_read_workers: int = DEFAULT_MAX_READ_WORKERS

Maximum number of concurrent read workers.

optional_settings class-attribute instance-attribute 

optional_settings: frozenset[OptionalSettings | str] = frozenset(DEFAULT_OPTIONAL_SETTINGS)

Optional feature flags.

program_markers class-attribute instance-attribute 

program_markers: tuple[DescriptionMarker | str, ...] = DEFAULT_PROGRAM_MARKERS

Markers to filter programs.

schedule_timer_config class-attribute instance-attribute 

schedule_timer_config: ScheduleTimerConfig = DEFAULT_SCHEDULE_TIMER_CONFIG

Timer configuration for scheduled tasks.

start_direct class-attribute instance-attribute 

start_direct: bool = False

Start without XML-RPC server (direct mode).

storage_directory class-attribute instance-attribute 

storage_directory: str = DEFAULT_STORAGE_DIRECTORY

Directory for persistent storage.

storage_factory class-attribute instance-attribute 

storage_factory: SkipValidation[StorageFactoryProtocol | None] = None

Optional storage factory for custom storage implementations.

sysvar_markers class-attribute instance-attribute 

sysvar_markers: tuple[DescriptionMarker | str, ...] = DEFAULT_SYSVAR_MARKERS

Markers to filter system variables.

timeout_config class-attribute instance-attribute 

timeout_config: TimeoutConfig = DEFAULT_TIMEOUT_CONFIG

Timeout configuration for various operations.

tls class-attribute instance-attribute 

tls: bool = DEFAULT_TLS

Enable TLS encryption.

un_ignore_list class-attribute instance-attribute 

un_ignore_list: frozenset[str] = DEFAULT_UN_IGNORES

List of parameters to un-ignore.

use_group_channel_for_cover_state class-attribute instance-attribute 

use_group_channel_for_cover_state: bool = DEFAULT_USE_GROUP_CHANNEL_FOR_COVER_STATE

Use group channel for cover state.

verify_tls class-attribute instance-attribute 

verify_tls: bool = DEFAULT_VERIFY_TLS

Verify TLS certificates.

locale class-attribute instance-attribute 

locale: str = DEFAULT_LOCALE

Locale for translations.

connection_check_port property 

connection_check_port: int

Return the connection check port.

enable_xml_rpc_server property 

enable_xml_rpc_server: bool

Return if server and connection checker should be started.

enabled_interface_configs property 

enabled_interface_configs: frozenset[InterfaceConfig]

Return the interface configs.

load_un_ignore property 

load_un_ignore: bool

Return if un_ignore should be loaded.

requires_xml_rpc_server property 

requires_xml_rpc_server: bool

Return if XML-RPC server is required.

session_recorder_randomize_output property writable 

session_recorder_randomize_output: bool

Return if session recorder should randomize output.

session_recorder_start property writable 

session_recorder_start: bool

Return if session recorder should start.

session_recorder_start_for_seconds property 

session_recorder_start_for_seconds: int

Return session recorder start duration in seconds.

use_caches property 

use_caches: bool

Return if store should be used.

for_ccu classmethod 

for_ccu(*, host: str, username: str, password: str, name: str = 'ccu', central_id: str | None = None, tls: bool = False, enable_hmip: bool = True, enable_bidcos_rf: bool = True, enable_bidcos_wired: bool = False, enable_virtual_devices: bool = False, **kwargs: Any) -> CentralConfig

Create a CentralConfig preset for CCU3/CCU2 backends.

This factory method simplifies configuration for CCU backends by automatically setting up common interfaces with their default ports.

Parameters:

Name Type Description Default
host str

Hostname or IP address of the CCU.

 required
username str

CCU username for authentication.

 required
password str

CCU password for authentication.

 required
name str

Name identifier for the central unit.

 'ccu'
central_id str | None

Unique identifier for the central. Auto-generated if not provided.

 None
tls bool

Enable TLS encryption for connections.

 False
enable_hmip bool

Enable HomematicIP wireless interface (port 2010/42010).

 True
enable_bidcos_rf bool

Enable BidCos RF interface (port 2001/42001).

 True
enable_bidcos_wired bool

Enable BidCos wired interface (port 2000/42000).

 False
enable_virtual_devices bool

Enable virtual devices interface (port 9292/49292).

 False
**kwargs Any

Additional arguments passed to CentralConfig constructor.

 {}

Returns:

Type Description
CentralConfig

Configured CentralConfig instance ready for create_central().
Example

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

for_homegear classmethod 

for_homegear(*, host: str, username: str, password: str, name: str = 'homegear', central_id: str | None = None, tls: bool = False, port: int | None = None, **kwargs: Any) -> CentralConfig

Create a CentralConfig preset for Homegear backends.

This factory method simplifies configuration for Homegear backends with the BidCos-RF interface.

Parameters:

Name Type Description Default
host str

Hostname or IP address of the Homegear server.

 required
username str

Homegear username for authentication.

 required
password str

Homegear password for authentication.

 required
name str

Name identifier for the central unit.

 'homegear'
central_id str | None

Unique identifier for the central. Auto-generated if not provided.

 None
tls bool

Enable TLS encryption for connections.

 False
port int | None

Custom port for BidCos-RF interface. Uses default (2001/42001) if not set.

 None
**kwargs Any

Additional arguments passed to CentralConfig constructor.

 {}

Returns:

Type Description
CentralConfig

Configured CentralConfig instance ready for create_central().
Example

config = CentralConfig.for_homegear( host="192.168.1.50", username="homegear", password="secret", ) central = await config.create_central()

check_config async 

check_config() -> None

Check central config asynchronously.

create_central async 

create_central() -> CentralUnit

Create the central asynchronously.

create_central_url 

create_central_url() -> str

Return the required url.

model_post_init 

model_post_init(_context: Any) -> None

Initialize computed private attributes after model creation.

options: show_root_heading: true show_source: false

InterfaceConfig

aiohomematic.client.InterfaceConfig

Bases: BaseModel

Configuration for a single Homematic interface connection.

central_name instance-attribute 

central_name: str

Name of the central unit this interface belongs to.

interface instance-attribute 

interface: Interface

The interface type (e.g., HMIP_RF, BIDCOS_RF, CUXD).

port class-attribute instance-attribute 

port: int | None = None

XML-RPC port (required for standard interfaces, ignored for CUxD/CCU-Jack).

remote_path class-attribute instance-attribute 

remote_path: str | None = None

Optional remote path for the interface.

enabled property 

enabled: bool

Return whether this interface is enabled.

interface_id property 

interface_id: str

Return the unique interface identifier.

rpc_server property 

rpc_server: RpcServerType

Return the RPC server type for this interface.

disable 

disable() -> None

Disable the interface config.

options: show_root_heading: true show_source: false