pyg90alarm 2.3.0__py3-none-any.whl

pyg90alarm/entities/__init__.py

@@ -0,0 +1,3 @@
+"""
+Implements various protocol entities for G90 alarm panel.
+"""

pyg90alarm/entities/base_entity.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2025 Ilia Sotnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""
+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
+try:
+    from typing import Self  # type: ignore[attr-defined,unused-ignore]
+except ImportError:
+    from typing_extensions import Self
+
+
+class G90BaseEntity(ABC):
+    """
+    Base entity class.
+
+    Contains minimal set of method for :class:`.G90BaseList` class
+    """
+    @abstractmethod
+    def update(
+        self,
+        obj: Self  # pylint: disable=used-before-assignment
+    ) -> None:
+        """
+        Update the entity from another one.
+
+        :param obj: Object to update from.
+        """
+
+    @property
+    @abstractmethod
+    def is_unavailable(self) -> bool:
+        """
+        Check if the entity is unavailable.
+
+        :return: True if the entity is unavailable.
+        """
+
+    @is_unavailable.setter
+    @abstractmethod
+    def is_unavailable(self, value: bool) -> None:
+        """
+        Set the entity as unavailable.
+
+        :param value: Value to set.
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Get the name of the entity.
+
+        :return: Name of the entity.
+        """
+
+    @property
+    @abstractmethod
+    def index(self) -> int:
+        """
+        Get the index of the entity.
+
+        :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

@@ -0,0 +1,268 @@
+# Copyright (c) 2025 Ilia Sotnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+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:
+    # Alias G90Alarm to object avoid circular imports
+    # (`G90Alarm` -> `G90SensorList` -> `G90BaseList` -> `G90Alarm`)
+    G90Alarm = object
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class G90BaseList(Generic[T], ABC):
+    """
+    Base entity list class.
+
+    :param parent: Parent alarm panel instance.
+    """
+    def __init__(self, parent: G90Alarm) -> None:
+        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]:
+        """
+        Fetch the list of entities from the panel.
+
+        :return: Async generator of entities
+        """
+        yield cast(T, None)
+
+    @property
+    async def entities(self) -> List[T]:
+        """
+        Return the list of entities.
+
+        :meth:`update` is called if the list is empty.
+
+        :return: List of entities
+        """
+        # Please see below for the explanation of the lock usage
+        async with self._lock:
+            entities = self._entities
+
+        if not entities:
+            return await self.update()
+
+        return entities
+
+    async def update(self) -> List[T]:
+        """
+        Update the list of entities from the panel.
+
+        :return: List of entities
+        """
+        # Use lock around the operation, to ensure no duplicated entries in the
+        # resulting list or redundant exchanges with panel are made when the
+        # method is called concurrently
+        async with self._lock:
+            entities = self._fetch()
+
+            non_existing_entities = self._entities.copy()
+            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:
+                _LOGGER.debug(
+                    'Marking entity as unavailable: %s', unavailable_entity
+                )
+                unavailable_entity.is_unavailable = True
+
+            _LOGGER.debug(
+                'Total number of entities: %s, unavailable: %s',
+                len(self._entities), len(non_existing_entities)
+            )
+
+            return self._entities
+
+    async def find_by_idx(
+        self, idx: int, exclude_unavailable: bool, subindex: int = 0
+    ) -> Optional[T]:
+        """
+        Finds entity by index.
+
+        :param idx: Entity index
+        :param exclude_unavailable: Exclude unavailable entities
+        :param subindex: Entity subindex
+        :return: Entity instance or None if not found
+        """
+        entities = await self.entities
+
+        found = None
+        if idx < len(entities):
+            entity = entities[idx]
+            if entity.index == idx and entity.subindex == subindex:
+                # Fast lookup by direct index
+                _LOGGER.debug('Found entity via fast lookup: %s', entity)
+                found = entity
+
+        if not found:
+            for entity in entities:
+                if entity.index == idx and entity.subindex == subindex:
+                    _LOGGER.debug('Found entity: %s', entity)
+                    found = entity
+
+        if found:
+            if not exclude_unavailable or not found.is_unavailable:
+                return found
+
+            _LOGGER.debug(
+                'Entity is found but unavailable, will result in none returned'
+            )
+
+        _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

@@ -0,0 +1,97 @@
+# Copyright (c) 2021 Ilia Sotnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+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__)
+
+
+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:
+        """
+        Turns on the device (relay)
+        """
+        await self.parent.command(G90Commands.CONTROLDEVICE,
+                                  [self.index, 0, self.subindex])
+
+    async def turn_off(self) -> None:
+        """
+        Turns off the device (relay)
+        """
+        await self.parent.command(G90Commands.CONTROLDEVICE,
+                                  [self.index, 1, self.subindex])
+
+    @property
+    def supports_updates(self) -> bool:
+        """
+        Indicates if disabling/enabling the device (relay) is supported.
+
+        :return: Support for enabling/disabling the device
+        """
+        # No support for manipulating of disable/enabled for the device, since
+        # single protocol entity read from the G90 alarm panel results in
+        # multiple `G90Device` instances and changing the state would
+        # subsequently require a design change to allow multiple entities to
+        # reflect that. Multiple device entities are for multi-channel relays
+        # mostly.
+        return False
+
+    async def delete(self) -> None:
+        """
+        Deletes the device (relay) from the G90 alarm panel.
+        """
+        _LOGGER.debug("Deleting device: %s", self)
+        # Mark the device as unavailable
+        self.is_unavailable = True
+        # Delete the device from the alarm panel
+        await self.parent.command(G90Commands.DELDEVICE, [self.index])

pyg90alarm/entities/device_list.py

@@ -0,0 +1,156 @@
+# Copyright (c) 2025 Ilia Sotnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""
+Device list.
+"""
+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]):
+    """
+    Device list class.
+    """
+    async def _fetch(self) -> AsyncGenerator[G90Device, None]:
+        """
+        Fetch the list of devices from the panel.
+
+        :yields: G90Device: Device entity.
+        """
+        devices = self._parent.paginated_result(
+            G90Commands.GETDEVICELIST
+        )
+
+        async for device in devices:
+            obj = G90Device(
+                *device.data, parent=self._parent, subindex=0,
+                proto_idx=device.proto_idx
+            )
+
+            yield obj
+
+            # Multi-node devices (first node has already been handled
+            # above)
+            for node in range(1, obj.node_count):
+                obj = G90Device(
+                    *device.data, parent=self._parent,
+                    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)