pyg90alarm 2.3.0__py3-none-any.whl

pyg90alarm/entities/sensor_list.py

@@ -0,0 +1,183 @@
+# 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.
+"""
+Sensor list.
+"""
+from __future__ import annotations
+from typing import AsyncGenerator, Optional, TYPE_CHECKING
+import logging
+import asyncio
+
+from .sensor import G90Sensor
+from .base_list import G90BaseList
+from ..const import G90Commands
+from ..exceptions import G90EntityRegistrationError, G90Error
+from ..definitions.sensors import G90SensorDefinitions
+from ..entities.sensor import G90SensorUserFlags
+
+if TYPE_CHECKING:
+    from ..alarm import G90Alarm
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class G90SensorList(G90BaseList[G90Sensor]):
+    """
+    Sensor list class.
+    """
+    def __init__(self, parent: G90Alarm) -> None:
+        super().__init__(parent)
+        self._sensor_change_future: Optional[asyncio.Future[G90Sensor]] = None
+
+    async def _fetch(self) -> AsyncGenerator[G90Sensor, None]:
+        """
+        Fetch the list of sensors from the panel.
+
+        :yields: G90Sensor: Sensor entity.
+        """
+        entities = self._parent.paginated_result(
+            G90Commands.GETSENSORLIST
+        )
+
+        async for entity in entities:
+            yield G90Sensor(
+                *entity.data, parent=self._parent, subindex=0,
+                proto_idx=entity.proto_idx
+            )
+
+    async def sensor_change_callback(
+        self, idx: int, name: str, added: bool
+    ) -> None:
+        """
+        Sensor change callback.
+
+        Should be invoked from corresponding panel's notification handler to
+        finish the registration process.
+
+        :param idx: Sensor index.
+        :param name: Sensor name.
+        :param added: True if the sensor was added, False if removed.
+        """
+        _LOGGER.debug(
+            "Sensor change callback: name='%s', index=%d, added=%s",
+            name, idx, added
+        )
+        # The method depends on the future to be created before it is called
+        if not self._sensor_change_future:
+            raise G90EntityRegistrationError(
+                "Sensor change callback called without a future"
+            )
+
+        # Update the sensor list to get the latest data, unfortunately there is
+        # no panel command to get just a single sensor
+        try:
+            await self.update()
+        except G90Error as err:
+            _LOGGER.debug(
+                "Failed to update the sensor list: %s", err
+            )
+            # Indicate the error to the caller
+            self._sensor_change_future.set_exception(err)
+            return
+
+        # Attempt to find the sensor just changed by its index
+        if not (found := await self.find_by_idx(
+            idx, exclude_unavailable=False
+        )):
+            msg = (
+                f"Failed to find the added sensor '{name}'"
+                f' at index {idx}'
+            )
+            _LOGGER.debug(msg)
+            # Indicate the error to the caller
+            self._sensor_change_future.set_exception(
+                G90EntityRegistrationError(msg)
+            )
+            return
+
+        # Provide the found sensor as the future result so that the caller
+        # can use it
+        self._sensor_change_future.set_result(found)
+
+    async def register(
+        self, definition_name: str,
+        room_id: int, timeout: float, name: Optional[str] = None,
+    ) -> G90Sensor:
+        """
+        Registers sensor to the panel.
+
+        :param definition_name: Sensor definition name.
+        :param room_id: Room ID to assign the sensor to.
+        :param timeout: Timeout for the registration process.
+        :param name: Optional name for the sensor, if not provided, the
+         definition name will be used.
+        :raises G90EntityRegistrationError: If the registration fails.
+        :return: G90Sensor: The registered sensor entity.
+        """
+        sensor_definition = G90SensorDefinitions.get_by_name(definition_name)
+        dev_name = name or sensor_definition.name
+
+        # Future is needed to coordinate the registration process with panel
+        # notifications (see `sensor_change_callback()` method)
+        self._sensor_change_future = asyncio.get_running_loop().create_future()
+
+        # Register the sensor with the panel
+        await self._parent.command(
+            G90Commands.ADDSENSOR, [
+                dev_name,
+                # Registering sensor requires to provide a free index from
+                # panel point of view
+                await self.find_free_idx(),
+                room_id,
+                sensor_definition.type,
+                sensor_definition.subtype,
+                sensor_definition.timeout,
+                # Newly registered sensors are enabled by default and set to
+                # alarm in away and home modes
+                G90SensorUserFlags.ENABLED
+                | G90SensorUserFlags.ALERT_WHEN_AWAY_AND_HOME,
+                sensor_definition.baudrate,
+                sensor_definition.protocol,
+                sensor_definition.reserved_data,
+                sensor_definition.node_count,
+                sensor_definition.rx,
+                sensor_definition.tx,
+                sensor_definition.private_data
+            ]
+        )
+
+        # Waiting for the registration to finish, where panel will send
+        # corresponding notification processed by `sensor_change_callback()`
+        # method, which manipulates the future created above.
+        done, _ = await asyncio.wait(
+            [self._sensor_change_future], timeout=timeout
+        )
+
+        if self._sensor_change_future not in done:
+            msg = f"Failed to learn the device '{dev_name}', timed out"
+            _LOGGER.debug(msg)
+            raise G90EntityRegistrationError(msg)
+
+        # Propagate any exception that might have occurred in
+        # `sensor_change_callback()` method during the registration process
+        self._sensor_change_future.exception()
+
+        # Return the registered sensor entity
+        return self._sensor_change_future.result()

pyg90alarm/exceptions.py

@@ -0,0 +1,63 @@
+# 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.
+
+
+"""
+Exceptions specific to G90-based alarm systems.
+"""
+
+import asyncio
+
+
+class G90Error(Exception):
+    """
+    Represents a generic exception raised by many package classes.
+    """
+
+
+class G90TimeoutError(asyncio.TimeoutError):  # pylint:disable=R0903
+    """
+    Raised when particular package class to report an operation (typically
+    device command) has timed out.
+    """
+
+
+class G90CommandFailure(G90Error):
+    """
+    Raised when a command to the alarm panel reports failure.
+    """
+
+
+class G90CommandError(G90Error):
+    """
+    Raised when a command to the alarm panel reports an error.
+    """
+
+
+class G90EntityRegistrationError(G90Error):
+    """
+    Raised when registering an entity to the alarm panel fails.
+    """
+
+
+class G90PeripheralDefinitionNotFound(G90Error):
+    """
+    Raised when a peripheral definition is not found.
+    """

pyg90alarm/local/base_cmd.py

@@ -0,0 +1,293 @@
+# 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 support for basic commands of G90 alarm panel.
+"""
+from __future__ import annotations
+import logging
+import json
+import asyncio
+from asyncio import Future
+from asyncio.protocols import DatagramProtocol
+from asyncio.transports import DatagramTransport, BaseTransport
+from typing import Optional, Tuple, List, Any
+from dataclasses import dataclass
+from ..exceptions import (
+    G90Error, G90TimeoutError, G90CommandFailure, G90CommandError
+)
+from ..const import G90Commands
+
+
+_LOGGER = logging.getLogger(__name__)
+G90BaseCommandData = List[Any]
+
+
+@dataclass
+class G90Header:
+    """
+    Represents JSON structure of the header used in alarm panel commands.
+
+    :meta private:
+    """
+    code: Optional[int] = None
+    data: Optional[G90BaseCommandData] = None
+
+
+class G90BaseCommand(DatagramProtocol):
+    """
+    Implements basic command handling for alarm panel protocol.
+    """
+    # pylint: disable=too-many-instance-attributes
+    # Lock need to be shared across all of the class instances
+    _sk_lock = asyncio.Lock()
+
+    # pylint: disable=too-many-positional-arguments,too-many-arguments
+    def __init__(self, host: str, port: int, code: G90Commands,
+                 data: Optional[G90BaseCommandData] = None,
+                 local_port: Optional[int] = None,
+                 timeout: float = 3.0, retries: int = 3) -> None:
+        self._remote_host = host
+        self._remote_port = port
+        self._local_port = local_port
+        self._code = code
+        self._timeout = timeout
+        self._retries = retries
+        self._data = '""'
+        self._result: G90BaseCommandData = []
+        self._connection_result: Optional[
+            Future[Tuple[str, int, bytes]]
+        ] = None
+        if data:
+            self._data = json.dumps([code, data],
+                                    # No newlines to be inserted
+                                    indent=None,
+                                    # No whitespace around entities
+                                    separators=(',', ':'))
+        self._resp = G90Header()
+
+    # Implementation of datagram protocol,
+    # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
+    def connection_made(self, transport: BaseTransport) -> None:
+        """
+        Invoked when connection is established.
+        """
+
+    def connection_lost(self, exc: Optional[Exception]) -> None:
+        """
+        Invoked when connection is lost.
+        """
+
+    def datagram_received(self, data: bytes, addr: Tuple[str, int]) -> None:
+        """
+        Invoked when datagram is received.
+        """
+        if asyncio.isfuture(self._connection_result):
+            if self._connection_result.done():
+                _LOGGER.warning('Excessive packet received'
+                                ' from %s:%s: %s',
+                                addr[0], addr[1], data)
+                return
+            self._connection_result.set_result((*addr, data))
+
+    def error_received(self, exc: Exception) -> None:
+        """
+        Invoked when error is received.
+        """
+        if (
+            asyncio.isfuture(self._connection_result) and not
+            self._connection_result.done()
+        ):
+            self._connection_result.set_exception(exc)
+
+    async def _create_connection(self) -> (
+        Tuple[DatagramTransport, DatagramProtocol]
+    ):
+        """
+        Creates UDP connection to the alarm panel.
+        """
+        loop = asyncio.get_running_loop()
+
+        _LOGGER.debug('Creating UDP endpoint for %s:%s',
+                      self.host, self.port)
+        local_addr = None
+        if self._local_port:
+            local_addr = ('0.0.0.0', self._local_port)
+
+        transport, protocol = await loop.create_datagram_endpoint(
+            lambda: self,
+            remote_addr=(self.host, self.port),
+            allow_broadcast=True,
+            local_addr=local_addr)
+
+        return (transport, protocol)
+
+    def to_wire(self) -> bytes:
+        """
+        Returns the command in wire format.
+        """
+        wire = bytes(f'ISTART[{self._code},{self._code},{self._data}]IEND\0',
+                     'utf-8')
+        _LOGGER.debug('Encoded to wire format %s', wire)
+        return wire
+
+    def from_wire(self, data: bytes) -> G90BaseCommandData:
+        """
+        Parses the response from the alarm panel.
+        """
+        _LOGGER.debug('To be decoded from wire format %s', data)
+        try:
+            self._parse(data.decode('utf-8'))
+        except UnicodeDecodeError as exc:
+            raise G90Error(
+                'Unable to decode response from UTF-8'
+            ) from exc
+        return self._resp.data or []
+
+    def _parse(self, data: str) -> None:
+        """
+        Processes the response from the alarm panel.
+        """
+        if not data.startswith('ISTART'):
+            raise G90Error('Missing start marker in data')
+        if not data.endswith('IEND\0'):
+            raise G90Error('Missing end marker in data')
+        payload = data[6:-5]
+        _LOGGER.debug("Decoded from wire: string '%s'", payload)
+
+        if not payload:
+            return
+
+        # Panel may report the last command has failed
+        if payload == 'fail':
+            raise G90CommandFailure(
+                f"Command {self._code.name}"
+                f" (code={self._code.value}) failed"
+            )
+
+        # Also, panel may report an error supplying specific reason, e.g.
+        # command and its arguments that have failed
+        if payload.startswith('error'):
+            error = payload[5:]
+            raise G90CommandError(
+                f"Command {self._code.name}"
+                f" (code={self._code.value}) failed"
+                f" with error: '{error}'")
+
+        resp = None
+        try:
+            resp = json.loads(payload, strict=False)
+        except json.JSONDecodeError as exc:
+            raise G90Error(
+                f"Unable to parse response as JSON: '{payload}'"
+            ) from exc
+
+        if not isinstance(resp, list):
+            raise G90Error(
+                f"Malformed response, 'list' expected: '{payload}'"
+            )
+
+        if resp is not None:
+            self._resp = G90Header(*resp)
+            _LOGGER.debug('Parsed from wire: %s', self._resp)
+
+            if not self._resp.code:
+                raise G90Error(f"Missing code in response: '{payload}'")
+            # Check there is data if the response is non-empty
+            if not self._resp.data:
+                raise G90Error(f"Missing data in response: '{payload}'")
+
+            if self._resp.code != self._code:
+                raise G90Error(
+                    'Wrong response - received code '
+                    f"{self._resp.code}, expected code {self._code}")
+
+    @property
+    def result(self) -> G90BaseCommandData:
+        """
+        The result of the command.
+        """
+        return self._result
+
+    @property
+    def host(self) -> str:
+        """
+        The hostname/IP address of the alarm panel.
+        """
+        return self._remote_host
+
+    @property
+    def port(self) -> int:
+        """
+        The port of the alarm panel.
+        """
+        return self._remote_port
+
+    async def process(self) -> G90BaseCommand:
+        """
+        Processes the command.
+        """
+        # Disallow using `NONE` command, which is intended to use by inheriting
+        # classes overriding `process()` method
+        if self._code == G90Commands.NONE:
+            raise G90Error("'NONE' command code is disallowed")
+
+        transport, _ = await self._create_connection()
+        attempts = self._retries
+        while True:
+            attempts = attempts - 1
+            loop = asyncio.get_running_loop()
+            self._connection_result = loop.create_future()
+            async with self._sk_lock:
+                _LOGGER.debug('(code %s) Sending request to %s:%s',
+                              self._code, self.host, self.port)
+                transport.sendto(self.to_wire())
+                done, _ = await asyncio.wait([self._connection_result],
+                                             timeout=self._timeout)
+            if self._connection_result in done:
+                break
+            # Cancel the future to signal protocol handler it is no longer
+            # valid, the future will be re-created on next retry
+            self._connection_result.cancel()
+            if not attempts:
+                transport.close()
+                raise G90TimeoutError()
+            _LOGGER.debug('Timed out, retrying')
+        transport.close()
+        (host, port, data) = self._connection_result.result()
+        _LOGGER.debug('Received response from %s:%s', host, port)
+        if self.host != '255.255.255.255':
+            if self.host != host or host == '255.255.255.255':
+                raise G90Error(f'Received response from wrong host {host},'
+                               f' expected from {self.host}')
+        if self.port != port:
+            raise G90Error(f'Received response from wrong port {port},'
+                           f' expected from {self.port}')
+
+        ret = self.from_wire(data)
+        self._result = ret
+        return self
+
+    def __repr__(self) -> str:
+        """
+        Returns string representation of the command.
+        """
+        return f'Command: {self._code}, request: {self._data},' \
+            f' response: {self._resp.data}'

pyg90alarm/local/config.py

@@ -0,0 +1,157 @@
+# 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.
+
+"""
+Represents various configuration aspects of the alarm panel.
+"""
+from __future__ import annotations
+from typing import TYPE_CHECKING
+import logging
+from dataclasses import dataclass
+from enum import IntFlag
+from ..const import G90Commands
+if TYPE_CHECKING:
+    from ..alarm import G90Alarm
+
+
+class G90AlertConfigFlags(IntFlag):
+    """
+    Alert configuration flags, used bitwise
+    """
+    AC_POWER_FAILURE = 1
+    AC_POWER_RECOVER = 2
+    ARM_DISARM = 4
+    HOST_LOW_VOLTAGE = 8
+    SENSOR_LOW_VOLTAGE = 16
+    WIFI_AVAILABLE = 32
+    WIFI_UNAVAILABLE = 64
+    DOOR_OPEN = 128
+    DOOR_CLOSE = 256
+    SMS_PUSH = 512
+    UNKNOWN1 = 2048
+    UNKNOWN2 = 8192
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class G90AlertConfigData:
+    """
+    Represents alert configuration data as received from the alarm panel.
+    """
+    flags_data: int
+
+    @property
+    def flags(self) -> G90AlertConfigFlags:
+        """
+        :return: The alert configuration flags
+        """
+        return G90AlertConfigFlags(self.flags_data)
+
+    @flags.setter
+    def flags(self, value: G90AlertConfigFlags) -> None:
+        """
+        :param value: The alert configuration flags
+        """
+        self.flags_data = value.value
+
+
+class G90AlertConfig:
+    """
+    Represents alert configuration as received from the alarm panel.
+    """
+    def __init__(self, parent: G90Alarm) -> None:
+        self.parent = parent
+
+    async def _get(self) -> G90AlertConfigData:
+        """
+        Retrieves the alert configuration flags directly from the device.
+
+        :return: The alerts configured
+        """
+        _LOGGER.debug('Retrieving alert configuration from the device')
+        res = await self.parent.command(G90Commands.GETNOTICEFLAG)
+        data = G90AlertConfigData(*res)
+        _LOGGER.debug(
+            'Alert configuration: %s, flags: %s', data,
+            repr(data.flags)
+        )
+        return data
+
+    async def set(self, flags: G90AlertConfigFlags) -> None:
+        """
+        .. deprecated:: 2.3.0
+
+        This method is deprecated and will always raise a RuntimeError.
+        Please use :meth:`set_flag` to set individual flags.
+        """
+        raise RuntimeError(
+            'The set() method is deprecated. Please use set_flag() to set'
+            ' individual flags instead.'
+        )
+
+    async def _set(self, flags: G90AlertConfigFlags) -> None:
+        """
+        Sets the alert configuration flags on the device.
+        """
+        _LOGGER.debug('Setting alert configuration to %s', repr(flags))
+        await self.parent.command(G90Commands.SETNOTICEFLAG, [flags.value])
+
+    async def get_flag(self, flag: G90AlertConfigFlags) -> bool:
+        """
+        :param flag: The flag to check
+        """
+        return flag in await self.flags
+
+    async def set_flag(self, flag: G90AlertConfigFlags, value: bool) -> None:
+        """
+        Sets the given flag to the desired value.
+
+        Uses read-modify-write approach.
+
+        :param flag: The flag to set
+        :param value: The value to set
+        """
+        # Retrieve current flags
+        current_flags = await self.flags
+        # Skip updating the flag if it has the desired value
+        if (flag in current_flags) == value:
+            _LOGGER.debug(
+                'Flag %s already set to %s, skipping update',
+                repr(flag), value
+            )
+            return
+
+        # Set or reset corresponding user flag depending on desired value
+        if value:
+            current_flags |= flag
+        else:
+            current_flags &= ~flag
+
+        # Set the updated flags
+        await self._set(current_flags)
+
+    @property
+    async def flags(self) -> G90AlertConfigFlags:
+        """
+        :return: Symbolic names for corresponding flag bits
+        """
+        return (await self._get()).flags