aiohomematic 2025.10.9__py3-none-any.whl → 2025.10.11__py3-none-any.whl

aiohomematic/central/__init__.py

@@ -96,8 +96,10 @@ from aiohomematic.const import (
     DEFAULT_IGNORE_CUSTOM_DEVICE_DEFINITION_MODELS,
     DEFAULT_INTERFACES_REQUIRING_PERIODIC_REFRESH,
     DEFAULT_MAX_READ_WORKERS,
+    DEFAULT_OPTIONAL_SETTINGS,
     DEFAULT_PERIODIC_REFRESH_INTERVAL,
     DEFAULT_PROGRAM_MARKERS,
+    DEFAULT_SESSION_RECORDER_START_FOR_SECONDS,
     DEFAULT_STORAGE_DIRECTORY,
     DEFAULT_SYS_SCAN_INTERVAL,
     DEFAULT_SYSVAR_MARKERS,
@@ -130,6 +132,7 @@ from aiohomematic.const import (
     Interface,
     InterfaceEventType,
     Operations,
+    OptionalSettings,
     Parameter,
     ParamsetKey,
     ProxyInitState,
@@ -223,7 +226,7 @@ class CentralUnit(LogContextMixin, PayloadMixin):
         self._paramset_descriptions: Final = ParamsetDescriptionCache(central=self)
         self._parameter_visibility: Final = ParameterVisibilityCache(central=self)
         self._recorder: Final = SessionRecorder(
-            central=self, default_ttl_seconds=600, active=central_config.start_recorder
+            central=self, ttl_seconds=600, active=central_config.session_recorder_start
         )
         self._primary_client: hmcl.Client | None = None
         # {interface_id, client}
@@ -493,14 +496,14 @@ class CentralUnit(LogContextMixin, PayloadMixin):
             _LOGGER.debug("START: Central %s already started", self.name)
             return
 
-        if self._config.start_recorder:
+        if self._config.session_recorder_start:
             await self._recorder.deactivate(
-                delay=self._config.start_recorder_for_minutes * 60,
+                delay=self._config.session_recorder_start_for_seconds,
                 auto_save=True,
-                randomize_output=True,
-                use_ts_in_filename=False,
+                randomize_output=self._config.session_recorder_randomize_output,
+                use_ts_in_file_name=False,
             )
-            _LOGGER.debug("START: Starting Recorder for %s minutes", self._config.start_recorder_for_minutes)
+            _LOGGER.debug("START: Starting Recorder for %s seconds", self._config.session_recorder_start_for_seconds)
 
         self._state = CentralUnitState.INITIALIZING
         _LOGGER.debug("START: Initializing Central %s", self.name)
@@ -2009,10 +2012,10 @@ class CentralConfig:
         listen_ip_addr: str | None = None,
         listen_port_xml_rpc: int | None = None,
         max_read_workers: int = DEFAULT_MAX_READ_WORKERS,
+        optional_settings: tuple[OptionalSettings | str, ...] = DEFAULT_OPTIONAL_SETTINGS,
         periodic_refresh_interval: int = DEFAULT_PERIODIC_REFRESH_INTERVAL,
         program_markers: tuple[DescriptionMarker | str, ...] = DEFAULT_PROGRAM_MARKERS,
         start_direct: bool = False,
-        start_recorder_for_minutes: int = 0,
         storage_directory: str = DEFAULT_STORAGE_DIRECTORY,
         sys_scan_interval: int = DEFAULT_SYS_SCAN_INTERVAL,
         sysvar_markers: tuple[DescriptionMarker | str, ...] = DEFAULT_SYSVAR_MARKERS,
@@ -2023,6 +2026,7 @@ class CentralConfig:
     ) -> None:
         """Init the client config."""
         self._interface_configs: Final = interface_configs
+        self._optional_settings: Final = frozenset(optional_settings or ())
         self.requires_xml_rpc_server: Final = any(
             ic for ic in interface_configs if ic.rpc_server == RpcServerType.XML_RPC
         )
@@ -2048,8 +2052,15 @@ class CentralConfig:
         self.periodic_refresh_interval = periodic_refresh_interval
         self.program_markers: Final = program_markers
         self.start_direct: Final = start_direct
-        self.start_recorder_for_minutes: Final = start_recorder_for_minutes
-        self.start_recorder = start_recorder_for_minutes > 0
+        self.session_recorder_randomize_output = (
+            OptionalSettings.SR_DISABLE_RANDOMIZE_OUTPUT not in self._optional_settings
+        )
+        self.session_recorder_start_for_seconds: Final = (
+            DEFAULT_SESSION_RECORDER_START_FOR_SECONDS
+            if OptionalSettings.SR_RECORD_SYSTEM_INIT in self._optional_settings
+            else 0
+        )
+        self.session_recorder_start = self.session_recorder_start_for_seconds > 0
         self.storage_directory: Final = storage_directory
         self.sys_scan_interval: Final = sys_scan_interval
         self.sysvar_markers: Final = sysvar_markers

aiohomematic/central/rpc_server.py

@@ -18,7 +18,7 @@ from xmlrpc.server import SimpleXMLRPCRequestHandler, SimpleXMLRPCServer
 from aiohomematic import central as hmcu
 from aiohomematic.central.decorators import callback_backend_system
 from aiohomematic.const import IP_ANY_V4, PORT_ANY, BackendSystemEvent
-from aiohomematic.support import find_free_port, log_boundary_error
+from aiohomematic.support import log_boundary_error
 
 _LOGGER: Final = logging.getLogger(__name__)
 
@@ -177,23 +177,19 @@ class RpcServer(threading.Thread):
     _initialized: bool = False
     _instances: Final[dict[tuple[str, int], RpcServer]] = {}
 
-    def __init__(
-        self,
-        *,
-        ip_addr: str,
-        port: int,
-    ) -> None:
+    def __init__(self, *, server: SimpleXMLRPCServer) -> None:
         """Init XmlRPC server."""
-        if self._initialized:
-            return
+        self._server = server
+        self._server.register_introspection_functions()
+        self._server.register_multicall_functions()
+        self._server.register_instance(RPCFunctions(rpc_server=self), allow_dotted_names=True)
         self._initialized = True
-        self._listen_ip_addr: Final = ip_addr
-        self._listen_port: Final[int] = find_free_port() if port == PORT_ANY else port
-        self._address: Final[tuple[str, int]] = (ip_addr, self._listen_port)
+        self._address: Final[tuple[str, int]] = cast(tuple[str, int], server.server_address)
+        self._listen_ip_addr: Final = self._address[0]
+        self._listen_port: Final = self._address[1]
         self._centrals: Final[dict[str, hmcu.CentralUnit]] = {}
-        self._simple_rpc_server: SimpleXMLRPCServer
         self._instances[self._address] = self
-        threading.Thread.__init__(self, name=f"RpcServer {ip_addr}:{self._listen_port}")
+        threading.Thread.__init__(self, name=f"RpcServer {self._listen_ip_addr}:{self._listen_port}")
 
     def run(self) -> None:
         """Run the RPC-Server thread."""
@@ -202,15 +198,15 @@ class RpcServer(threading.Thread):
             self._listen_ip_addr,
             self._listen_port,
         )
-        if self._simple_rpc_server:
-            self._simple_rpc_server.serve_forever()
+        if self._server:
+            self._server.serve_forever()
 
     def stop(self) -> None:
         """Stop the RPC-Server."""
         _LOGGER.debug("STOP: Shutting down RPC-Server")
-        self._simple_rpc_server.shutdown()
+        self._server.shutdown()
         _LOGGER.debug("STOP: Stopping RPC-Server")
-        self._simple_rpc_server.server_close()
+        self._server.server_close()
         # Ensure the server thread has actually terminated to avoid slow teardown
         with contextlib.suppress(RuntimeError):
             self.join(timeout=1.0)
@@ -269,16 +265,14 @@ class XmlRpcServer(RpcServer):
 
         if self._initialized:
             return
-        super().__init__(ip_addr=ip_addr, port=port)
-        self._simple_rpc_server = HomematicXMLRPCServer(
-            addr=self._address,
-            requestHandler=RequestHandler,
-            logRequests=False,
-            allow_none=True,
+        super().__init__(
+            server=HomematicXMLRPCServer(
+                addr=(ip_addr, port),
+                requestHandler=RequestHandler,
+                logRequests=False,
+                allow_none=True,
+            )
         )
-        self._simple_rpc_server.register_introspection_functions()
-        self._simple_rpc_server.register_multicall_functions()
-        self._simple_rpc_server.register_instance(RPCFunctions(rpc_server=self), allow_dotted_names=True)
 
     def __new__(cls, ip_addr: str, port: int) -> XmlRpcServer:  # noqa: PYI034  # kwonly: disable
         """Create new RPC server."""

aiohomematic/client/__init__.py

@@ -60,7 +60,6 @@ from aiohomematic.client.rpc_proxy import AioXmlRpcProxy, BaseRpcProxy
 from aiohomematic.const import (
     CALLBACK_WARN_INTERVAL,
     DATETIME_FORMAT_MILLIS,
-    DEFAULT_CUSTOM_ID,
     DEFAULT_MAX_WORKERS,
     DP_KEY_VALUE,
     DUMMY_SERIAL,
@@ -81,6 +80,7 @@ from aiohomematic.const import (
     ForcedDeviceAvailability,
     Interface,
     InterfaceEventType,
+    InternalCustomID,
     Operations,
     ParameterData,
     ParameterType,
@@ -1815,7 +1815,9 @@ async def _track_single_data_point_state_change_or_timeout(
             )
             return
         if (
-            unsub := dp.register_data_point_updated_callback(cb=_async_event_changed, custom_id=DEFAULT_CUSTOM_ID)
+            unsub := dp.register_data_point_updated_callback(
+                cb=_async_event_changed, custom_id=InternalCustomID.DEFAULT
+            )
         ) is None:
             return
 

aiohomematic/client/json_rpc.py

@@ -368,8 +368,8 @@ class AioJsonRpcAioHttpClient(LogContextMixin):
         _LOGGER.debug("POST_SCRIPT: method: %s [%s]", method, script_name)
 
         try:
-            if not response[_JsonKey.ERROR]:
-                response[_JsonKey.RESULT] = orjson.loads(response[_JsonKey.RESULT])
+            if not response[_JsonKey.ERROR] and (resp := response[_JsonKey.RESULT]) and isinstance(resp, str):
+                response[_JsonKey.RESULT] = orjson.loads(resp)
         finally:
             if not keep_session:
                 await self._do_logout(session_id=session_id)

aiohomematic/const.py

@@ -19,7 +19,7 @@ import sys
 from types import MappingProxyType
 from typing import Any, Final, NamedTuple, Required, TypeAlias, TypedDict
 
-VERSION: Final = "2025.10.9"
+VERSION: Final = "2025.10.11"
 
 # Detect test speedup mode via environment
 _TEST_SPEEDUP: Final = (
@@ -27,8 +27,6 @@ _TEST_SPEEDUP: Final = (
 )
 
 # default
-DEFAULT_STORAGE_DIRECTORY: Final = "aiohomematic_storage"
-DEFAULT_CUSTOM_ID: Final = "custom_id"
 DEFAULT_DELAY_NEW_DEVICE_CREATION: Final = False
 DEFAULT_ENABLE_DEVICE_FIRMWARE_CHECK: Final = False
 DEFAULT_ENABLE_PROGRAM_SCAN: Final = True
@@ -40,8 +38,11 @@ DEFAULT_INCLUDE_INTERNAL_SYSVARS: Final = True
 DEFAULT_MAX_READ_WORKERS: Final = 1
 DEFAULT_MAX_WORKERS: Final = 1
 DEFAULT_MULTIPLIER: Final = 1.0
+DEFAULT_OPTIONAL_SETTINGS: Final[tuple[OptionalSettings | str, ...]] = ()
 DEFAULT_PERIODIC_REFRESH_INTERVAL: Final = 15
 DEFAULT_PROGRAM_MARKERS: Final[tuple[DescriptionMarker | str, ...]] = ()
+DEFAULT_SESSION_RECORDER_START_FOR_SECONDS: Final = 180
+DEFAULT_STORAGE_DIRECTORY: Final = "aiohomematic_storage"
 DEFAULT_SYSVAR_MARKERS: Final[tuple[DescriptionMarker | str, ...]] = ()
 DEFAULT_SYS_SCAN_INTERVAL: Final = 30
 DEFAULT_TLS: Final = False
@@ -49,12 +50,6 @@ DEFAULT_UN_IGNORES: Final[frozenset[str]] = frozenset()
 DEFAULT_USE_GROUP_CHANNEL_FOR_COVER_STATE: Final = True
 DEFAULT_VERIFY_TLS: Final = False
 
-MANU_TEMP_CUSTOM_ID: Final = "manu_temp"
-INTERNAL_CUSTOM_IDS: Final[tuple[str, ...]] = (
-    DEFAULT_CUSTOM_ID,
-    MANU_TEMP_CUSTOM_ID,
-)
-
 # Default encoding for json service calls, persistent cache
 UTF_8: Final = "utf-8"
 # Default encoding for xmlrpc service calls and script files
@@ -214,6 +209,13 @@ class CommandRxMode(StrEnum):
     WAKEUP = "WAKEUP"
 
 
+class InternalCustomID(StrEnum):
+    """Enum for Homematic internal custom IDs."""
+
+    DEFAULT = "cid_default"
+    MANU_TEMP = "cid_manu_temp"
+
+
 class DataOperationResult(Enum):
     """Enum with data operation results."""
 
@@ -352,6 +354,13 @@ class Operations(IntEnum):
     EVENT = 4
 
 
+class OptionalSettings(StrEnum):
+    """Enum with aiohomematic optional settings."""
+
+    SR_DISABLE_RANDOMIZE_OUTPUT = "SR_DISABLE_RANDOMIZED_OUTPUT"
+    SR_RECORD_SYSTEM_INIT = "SR_RECORD_SYSTEM_INIT"
+
+
 class Parameter(StrEnum):
     """Enum with Homematic parameters."""
 

aiohomematic/model/custom/climate.py

@@ -12,10 +12,10 @@ import logging
 from typing import Any, Final, cast
 
 from aiohomematic.const import (
-    MANU_TEMP_CUSTOM_ID,
     SCHEDULER_PROFILE_PATTERN,
     SCHEDULER_TIME_PATTERN,
     DataPointCategory,
+    InternalCustomID,
     Parameter,
     ParamsetKey,
     ProductGroup,
@@ -235,7 +235,7 @@ class BaseCustomDpClimate(CustomDataPoint):
         )
         self._unregister_callbacks.append(
             self._dp_setpoint.register_data_point_updated_callback(
-                cb=self._manu_temp_changed, custom_id=MANU_TEMP_CUSTOM_ID
+                cb=self._manu_temp_changed, custom_id=InternalCustomID.MANU_TEMP
             )
         )
 
@@ -802,7 +802,7 @@ class CustomDpRfThermostat(BaseCustomDpClimate):
 
         self._unregister_callbacks.append(
             self._dp_control_mode.register_data_point_updated_callback(
-                cb=self._manu_temp_changed, custom_id=MANU_TEMP_CUSTOM_ID
+                cb=self._manu_temp_changed, custom_id=InternalCustomID.MANU_TEMP
             )
         )
 
@@ -1047,7 +1047,7 @@ class CustomDpIpThermostat(BaseCustomDpClimate):
 
         self._unregister_callbacks.append(
             self._dp_set_point_mode.register_data_point_updated_callback(
-                cb=self._manu_temp_changed, custom_id=MANU_TEMP_CUSTOM_ID
+                cb=self._manu_temp_changed, custom_id=InternalCustomID.MANU_TEMP
             )
         )
 

aiohomematic/model/data_point.py

@@ -39,11 +39,9 @@ from aiohomematic import central as hmcu, client as hmcl, support as hms, valida
 from aiohomematic.async_support import loop_check
 from aiohomematic.const import (
     CALLBACK_TYPE,
-    DEFAULT_CUSTOM_ID,
     DEFAULT_MULTIPLIER,
     DP_KEY_VALUE,
     INIT_DATETIME,
-    INTERNAL_CUSTOM_IDS,
     KEY_CHANNEL_OPERATION_MODE_VISIBILITY,
     KWARGS_ARG_CUSTOM_ID,
     KWARGS_ARG_DATA_POINT,
@@ -55,6 +53,7 @@ from aiohomematic.const import (
     DataPointUsage,
     EventKey,
     Flag,
+    InternalCustomID,
     Operations,
     Parameter,
     ParameterData,
@@ -309,11 +308,11 @@ class CallbackDataPoint(ABC, LogContextMixin):
 
     def register_internal_data_point_updated_callback(self, *, cb: Callable) -> CALLBACK_TYPE:
         """Register internal data_point updated callback."""
-        return self.register_data_point_updated_callback(cb=cb, custom_id=DEFAULT_CUSTOM_ID)
+        return self.register_data_point_updated_callback(cb=cb, custom_id=InternalCustomID.DEFAULT)
 
     def register_data_point_updated_callback(self, *, cb: Callable, custom_id: str) -> CALLBACK_TYPE:
         """Register data_point updated callback."""
-        if custom_id not in INTERNAL_CUSTOM_IDS:
+        if custom_id not in InternalCustomID:
             if self._custom_id is not None and self._custom_id != custom_id:
                 raise AioHomematicException(
                     f"REGISTER_data_point_updated_CALLBACK failed: hm_data_point: {self.full_name} is already registered by {self._custom_id}"

aiohomematic/model/device.py

@@ -1293,7 +1293,7 @@ class _DefinitionExporter:
             str, dict[ParamsetKey, dict[str, ParameterData]]
         ] = await self._client.get_all_paramset_descriptions(device_descriptions=tuple(device_descriptions.values()))
         model = device_descriptions[self._device_address]["TYPE"]
-        filename = f"{model}.json"
+        file_name = f"{model}.json"
 
         # anonymize device_descriptions
         anonymize_device_descriptions: list[DeviceDescription] = []
@@ -1316,14 +1316,14 @@ class _DefinitionExporter:
         # Save device_descriptions for device to file.
         await self._save(
             directory=f"{self._storage_directory}/{DEVICE_DESCRIPTIONS_DIR}",
-            filename=filename,
+            file_name=file_name,
             data=anonymize_device_descriptions,
         )
 
         # Save device_descriptions for device to file.
         await self._save(
             directory=f"{self._storage_directory}/{PARAMSET_DESCRIPTIONS_DIR}",
-            filename=filename,
+            file_name=file_name,
             data=anonymize_paramset_descriptions,
         )
 
@@ -1332,13 +1332,13 @@ class _DefinitionExporter:
         address_parts[0] = self._random_id
         return ADDRESS_SEPARATOR.join(address_parts)
 
-    async def _save(self, *, directory: str, filename: str, data: Any) -> DataOperationResult:
+    async def _save(self, *, directory: str, file_name: str, data: Any) -> DataOperationResult:
         """Save file to disk."""
 
         def perform_save() -> DataOperationResult:
             if not check_or_create_directory(directory=directory):
                 return DataOperationResult.NO_SAVE  # pragma: no cover
-            with open(file=os.path.join(directory, filename), mode="wb") as fptr:
+            with open(file=os.path.join(directory, file_name), mode="wb") as fptr:
                 fptr.write(orjson.dumps(data, option=orjson.OPT_INDENT_2 | orjson.OPT_NON_STR_KEYS))
             return DataOperationResult.SAVE_SUCCESS
 

aiohomematic/model/update.py

@@ -11,11 +11,11 @@ from typing import Final
 
 from aiohomematic.const import (
     CALLBACK_TYPE,
-    DEFAULT_CUSTOM_ID,
     HMIP_FIRMWARE_UPDATE_IN_PROGRESS_STATES,
     HMIP_FIRMWARE_UPDATE_READY_STATES,
     DataPointCategory,
     Interface,
+    InternalCustomID,
 )
 from aiohomematic.decorators import inspector
 from aiohomematic.exceptions import AioHomematicException
@@ -114,7 +114,7 @@ class DpUpdate(CallbackDataPoint, PayloadMixin):
 
     def register_data_point_updated_callback(self, *, cb: Callable, custom_id: str) -> CALLBACK_TYPE:
         """Register update callback."""
-        if custom_id != DEFAULT_CUSTOM_ID:
+        if custom_id != InternalCustomID.DEFAULT:
             if self._custom_id is not None:
                 raise AioHomematicException(
                     f"REGISTER_UPDATE_CALLBACK failed: hm_data_point: {self.full_name} is already registered by {self._custom_id}"