pyg90alarm 2.1.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

pyg90alarm/entities/base_entity.py

@@ -20,6 +20,7 @@
 """
 Base entity.
 """
+from __future__ import annotations
 from abc import ABC, abstractmethod
 # `Self` has been introduced in Python 3.11, need to use `typing_extensions`
 # for earlier versions
@@ -81,3 +82,12 @@ class G90BaseEntity(ABC):
 
         :return: Index of the entity.
         """
+
+    @property
+    @abstractmethod
+    def subindex(self) -> int:
+        """
+        Get the subindex of the entity.
+
+        :return: Subindex of the entity.
+        """

pyg90alarm/entities/base_list.py

@@ -24,11 +24,21 @@ Base entity list.
 from abc import ABC, abstractmethod
 from typing import (
     List, AsyncGenerator, Optional, TypeVar, Generic, cast, TYPE_CHECKING,
+    Callable, Coroutine, Union
 )
 import asyncio
 import logging
 
+from ..exceptions import G90Error
 from .base_entity import G90BaseEntity
+from ..callback import G90Callback
+
+T = TypeVar('T', bound=G90BaseEntity)
+ListChangeCallback = Union[
+    Callable[[T, bool], None],
+    Callable[[T, bool], Coroutine[None, None, None]]
+]
+
 if TYPE_CHECKING:
     from ..alarm import G90Alarm
 else:
@@ -36,7 +46,6 @@ else:
     # (`G90Alarm` -> `G90SensorList` -> `G90BaseList` -> `G90Alarm`)
     G90Alarm = object
 
-T = TypeVar('T', bound=G90BaseEntity)
 _LOGGER = logging.getLogger(__name__)
 
 
@@ -50,6 +59,7 @@ class G90BaseList(Generic[T], ABC):
         self._entities: List[T] = []
         self._lock = asyncio.Lock()
         self._parent = parent
+        self._list_change_cb: Optional[ListChangeCallback[T]] = None
 
     @abstractmethod
     async def _fetch(self) -> AsyncGenerator[T, None]:
@@ -91,26 +101,41 @@ class G90BaseList(Generic[T], ABC):
             entities = self._fetch()
 
             non_existing_entities = self._entities.copy()
-            async for entity in entities:
-                try:
-                    existing_entity_idx = self._entities.index(entity)
-                except ValueError:
-                    existing_entity_idx = None
-
-                if existing_entity_idx is not None:
-                    existing_entity = self._entities[existing_entity_idx]
-                    # Update the existing entity with the new data
-                    _LOGGER.debug(
-                        "Updating existing entity '%s' from protocol"
-                        " data '%s'", existing_entity, entity
-                    )
-
-                    self._entities[existing_entity_idx].update(entity)
-                    non_existing_entities.remove(entity)
-                else:
-                    # Add the new entity to the list
-                    _LOGGER.debug('Adding new entity: %s', entity)
-                    self._entities.append(entity)
+            try:
+                async for entity in entities:
+                    try:
+                        existing_entity = next(
+                            x for x in self._entities if x == entity
+                        )
+                    except StopIteration:
+                        existing_entity = None
+
+                    if existing_entity is not None:
+                        # Update the existing entity with the new data
+                        _LOGGER.debug(
+                            "Updating existing entity '%s' from protocol"
+                            " data '%s'", existing_entity, entity
+                        )
+
+                        existing_entity.update(entity)
+                        non_existing_entities.remove(existing_entity)
+
+                        # Invoke the list change callback for the existing
+                        # entity to notify about the update
+                        G90Callback.invoke(
+                            self._list_change_cb, existing_entity, False
+                        )
+                    else:
+                        # Add the new entity to the list
+                        _LOGGER.debug('Adding new entity: %s', entity)
+                        self._entities.append(entity)
+                        # Invoke the list change callback for the new entity
+                        G90Callback.invoke(self._list_change_cb, entity, True)
+            except TypeError as err:
+                _LOGGER.error(
+                    'Failed to fetch entities: %s', err
+                )
+                raise G90Error(err) from err
 
             # Mark the entities that are no longer in the list
             for unavailable_entity in non_existing_entities:
@@ -126,30 +151,30 @@ class G90BaseList(Generic[T], ABC):
 
             return self._entities
 
-    async def find(
-        self, idx: int, name: str, exclude_unavailable: bool
+    async def find_by_idx(
+        self, idx: int, exclude_unavailable: bool, subindex: int = 0
     ) -> Optional[T]:
         """
-        Finds entity by index and name.
+        Finds entity by index.
 
         :param idx: Entity index
-        :param name: Entity name
         :param exclude_unavailable: Exclude unavailable entities
-        :return: Entity instance
+        :param subindex: Entity subindex
+        :return: Entity instance or None if not found
         """
         entities = await self.entities
 
         found = None
-        # Fast lookup by direct index
-        if idx < len(entities) and entities[idx].name == name:
+        if idx < len(entities):
             entity = entities[idx]
-            _LOGGER.debug('Found entity via fast lookup: %s', entity)
-            found = entity
+            if entity.index == idx and entity.subindex == subindex:
+                # Fast lookup by direct index
+                _LOGGER.debug('Found entity via fast lookup: %s', entity)
+                found = entity
 
-        # Fast lookup failed, perform slow one over the whole entities list
         if not found:
             for entity in entities:
-                if entity.index == idx and entity.name == name:
+                if entity.index == idx and entity.subindex == subindex:
                     _LOGGER.debug('Found entity: %s', entity)
                     found = entity
 
@@ -161,5 +186,83 @@ class G90BaseList(Generic[T], ABC):
                 'Entity is found but unavailable, will result in none returned'
             )
 
-        _LOGGER.error('Entity not found: idx=%s, name=%s', idx, name)
+        _LOGGER.error(
+            'Entity not found by index=%s and subindex=%s', idx, subindex
+        )
         return None
+
+    async def find(
+        self, idx: int, name: str, exclude_unavailable: bool, subindex: int = 0
+    ) -> Optional[T]:
+        """
+        Finds entity by index, subindex and name.
+
+        :param idx: Entity index
+        :param name: Entity name
+        :param exclude_unavailable: Exclude unavailable entities
+        :param subindex: Entity subindex
+        :return: Entity instance or None if not found
+        """
+        found = await self.find_by_idx(idx, exclude_unavailable, subindex)
+        if not found:
+            return None
+
+        if found.name == name:
+            return found
+
+        _LOGGER.error(
+            'Entity not found: index=%s, subindex=%s, name=%s',
+            idx, subindex, name
+        )
+        return None
+
+    async def find_free_idx(self) -> int:
+        """
+        Finds the first free index in the list.
+
+        The index is from protocol point of view (`.index` attribute of the
+        protocol data), not the index in the list. The index is required when
+        registering a new entity on the panel.
+
+        :return: Free index
+        """
+        entities = await self.entities
+
+        # Collect indexes in use by the existing entities
+        occupied_indexes = set(x.index for x in entities)
+        # Generate a set of possible indexes from 0 to the maximum index in
+        # use
+        possible_indexes = set(range(0, max(occupied_indexes)))
+
+        try:
+            # Find the first free index by taking difference between
+            # possible indexes and occupied ones, and then taking the minimum
+            # value off the difference
+            free_idx = min(
+                set(possible_indexes).difference(occupied_indexes)
+            )
+            _LOGGER.debug(
+                'Found free index: %s out of occupied indexes: %s',
+                free_idx, occupied_indexes
+            )
+            return free_idx
+        except ValueError:
+            # If no gaps in existing indexes, then return the index next to
+            # the last existing entity
+            return len(entities)
+
+    @property
+    def list_change_callback(self) -> Optional[ListChangeCallback[T]]:
+        """
+        List change callback.
+
+        Invoked when the list of entities is changed, i.e. when a new entity is
+        added or an existing one is updated.
+
+        :return: Callback
+        """
+        return self._list_change_cb
+
+    @list_change_callback.setter
+    def list_change_callback(self, value: ListChangeCallback[T]) -> None:
+        self._list_change_cb = value

pyg90alarm/entities/device.py

@@ -22,10 +22,13 @@
 Provides interface to devices (switches) of G90 alarm panel.
 """
 from __future__ import annotations
+from typing import Optional
 import logging
 from .sensor import G90Sensor
 from ..const import G90Commands
-
+from ..definitions.base import G90PeripheralDefinition
+from ..definitions.devices import G90DeviceDefinitions
+from ..exceptions import G90PeripheralDefinitionNotFound
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -34,6 +37,25 @@ class G90Device(G90Sensor):
     """
     Interacts with device (relay) on G90 alarm panel.
     """
+    @property
+    def definition(self) -> Optional[G90PeripheralDefinition]:
+        """
+        Returns the definition for the device.
+
+        :return: Device definition
+        """
+        if not self._definition:
+            # No definition has been cached, try to find it by type, subtype
+            # and protocol
+            try:
+                self._definition = (
+                    G90DeviceDefinitions.get_by_id(
+                        self.type, self.subtype, self.protocol
+                    )
+                )
+            except G90PeripheralDefinitionNotFound:
+                return None
+        return self._definition
 
     async def turn_on(self) -> None:
         """

pyg90alarm/entities/device_list.py

@@ -20,10 +20,17 @@
 """
 Device list.
 """
-from typing import AsyncGenerator
+from typing import AsyncGenerator, Optional
+import logging
+import asyncio
 from .device import G90Device
 from .base_list import G90BaseList
 from ..const import G90Commands
+from ..definitions.devices import G90DeviceDefinitions
+from ..entities.sensor import G90SensorUserFlags
+from ..exceptions import G90EntityRegistrationError
+
+_LOGGER = logging.getLogger(__name__)
 
 
 class G90DeviceList(G90BaseList[G90Device]):
@@ -56,3 +63,94 @@ class G90DeviceList(G90BaseList[G90Device]):
                     subindex=node, proto_idx=device.proto_idx
                 )
                 yield obj
+
+    async def register(
+        self, definition_name: str,
+        room_id: int, timeout: float, name: Optional[str] = None,
+    ) -> G90Device:
+        """
+        Register the devices (switches) to the panel.
+
+        Contrary to registering the sensors, the registration of devices does
+        not have an associated notification from the panel, hence the list of
+        devices is polled to determine when new device is added.
+
+        :param definition_name: Name of the device definition to register.
+        :param room_id: ID of the room to assign the device to.
+        :param timeout: Timeout in seconds to wait for the device to be added.
+        :param name: Optional name for the device, if not provided, the
+         name from the definition will be used.
+        :raises G90EntityRegistrationError: If the device could not be
+         registered or found after the registration.
+        :return: G90Device: The registered device entity.
+        """
+        device_definition = G90DeviceDefinitions.get_by_name(definition_name)
+        dev_name = name or device_definition.name
+
+        # Register the device with the panel
+        await self._parent.command(
+            G90Commands.ADDDEVICE, [
+                dev_name,
+                # Registering device requires to provide a free index from
+                # panel point of view
+                await self.find_free_idx(),
+                room_id,
+                device_definition.type,
+                device_definition.subtype,
+                device_definition.timeout,
+                # Newly registered devices are enabled by default
+                G90SensorUserFlags.ENABLED,
+                device_definition.baudrate,
+                device_definition.protocol,
+                device_definition.reserved_data,
+                device_definition.node_count,
+                device_definition.rx,
+                device_definition.tx,
+                device_definition.private_data
+            ]
+        )
+
+        # Confirm the registration of the device to the panel
+        res = await self._parent.command(
+            G90Commands.SENDREGDEVICERESULT,
+            # 1 = register, 0 = cancel
+            [1]
+        )
+
+        # The command above returns the index of the added device in the
+        # device list from panel point of view
+        try:
+            added_at = next(iter(res))
+            _LOGGER.debug('Device added at index=%s', added_at)
+        except StopIteration:
+            msg = (
+                f"Failed to register device '{dev_name}' - response does not"
+                ' contain the index in the device list'
+            )
+            _LOGGER.debug(msg)
+            # pylint: disable=raise-missing-from
+            raise G90EntityRegistrationError(msg)
+
+        # Update the list of devices polling for the new entity
+        # to appear in the list - it takes some time for the panel
+        # to process the registration and add the device to the list
+        found = None
+        for _ in range(int(timeout)):
+            # Update the list of devices from the panel
+            await self.update()
+            # Try to find the device by the index it was added at
+            if found := await self.find_by_idx(
+                added_at, exclude_unavailable=False
+            ):
+                break
+            await asyncio.sleep(1)
+
+        if found:
+            return found
+
+        msg = (
+            f"Failed to find the added device '{dev_name}'"
+            f' at index {added_at}'
+        )
+        _LOGGER.debug(msg)
+        raise G90EntityRegistrationError(msg)