pyg90alarm 2.3.0__py3-none-any.whl

pyg90alarm/local/paginated_cmd.py

@@ -0,0 +1,132 @@
+# 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.
+
+"""
+Implements paginated command for G90 alarm panel protocol.
+"""
+from __future__ import annotations
+import logging
+from typing import Any, cast
+from dataclasses import dataclass
+from .base_cmd import G90BaseCommand, G90BaseCommandData
+from ..exceptions import G90Error
+from ..const import G90Commands
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class G90PaginationFields:
+    """
+    Represents structure of the pagination fields used by alarm panel.
+
+    :meta private:
+    """
+    total: int
+    start: int
+    nelems: int
+
+
+class G90PaginatedCommand(G90BaseCommand):
+    """
+    Implements paginated command for alarm panel protocol.
+    """
+    # pylint: disable=too-many-positional-arguments,too-many-arguments
+    def __init__(
+        self, host: str, port: int, code: G90Commands, start: int, end: int,
+        **kwargs: Any
+    ) -> None:
+        self._start = start
+        self._end = end
+        self._expected_nelems = end - start + 1
+        self._nelems = 0
+        self._total = 0
+        super().__init__(host, port, code, [self._start, self._end],
+                         **kwargs)
+
+    @property
+    def total(self) -> int:
+        """
+        Total number of records available.
+        """
+        return self._total
+
+    @property
+    def start(self) -> int:
+        """
+        Index of the first record in the response.
+        """
+        return self._start
+
+    @property
+    def count(self) -> int:
+        """
+        Number of records in the response.
+        """
+        return self._nelems
+
+    def _parse(self, data: str) -> None:
+        """
+        Parses the response from the alarm panel.
+        """
+        super()._parse(data)
+        resp_data: G90BaseCommandData = self._resp.data or []
+        try:
+            page_data = resp_data.pop(0)
+            page_info = G90PaginationFields(*page_data)
+        except TypeError as exc:
+            raise G90Error(f'Wrong pagination data {page_data} - {str(exc)}'
+                           ) from exc
+        except IndexError as exc:
+            raise G90Error(f"Missing pagination in response '{self._resp}'"
+                           ) from exc
+
+        self._total = page_info.total
+        self._start = page_info.start
+        self._nelems = page_info.nelems
+
+        errors = []
+        if self._nelems != len(resp_data):
+            qualifier = (
+                "Truncated" if self._nelems > len(resp_data) else "Extra"
+            )
+            errors.append(
+                f'{qualifier} data provided in paginated response -'
+                f' expected {self._nelems} entities as per response,'
+                f' received {len(resp_data)}')
+
+        if self._expected_nelems < len(resp_data):
+            errors.append(
+                f'Extra data provided in paginated response -'
+                f' expected {self._expected_nelems} entities as per request,'
+                f' received {len(resp_data)}')
+
+        if errors:
+            raise G90Error('. '.join(errors))
+
+        _LOGGER.debug('Paginated command response: '
+                      'total records %s, start record %s, record count %s',
+                      page_info.total, page_info.start, page_info.nelems)
+
+    async def process(self) -> G90PaginatedCommand:
+        """
+        Initiates the command processing.
+        """
+        return cast(G90PaginatedCommand, await super().process())

pyg90alarm/local/paginated_result.py

@@ -0,0 +1,135 @@
+# 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.
+
+"""
+Extends paginated command for G90 alarm panel providing convenience interface
+to work with results of paginated commands.
+"""
+
+import logging
+from typing import Any, Optional, AsyncGenerator, Iterable, cast
+from dataclasses import dataclass
+from .paginated_cmd import G90PaginatedCommand
+from ..const import (
+    G90Commands,
+    CMD_PAGE_SIZE,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class G90PaginatedResponse:
+    """
+    Response yielded from the :meth:`.G90PaginatedResult.process` method
+    """
+    proto_idx: int
+    data: str
+
+
+class G90PaginatedResult:
+    """
+    Processes paginated response from G90 corresponding panel commands.
+    """
+    # pylint: disable=too-few-public-methods
+    # pylint: disable=too-many-positional-arguments,too-many-arguments
+    def __init__(
+        self, host: str, port: int, code: G90Commands, start: int = 1,
+        end: Optional[int] = None, **kwargs: Any
+    ):
+        self._host = host
+        self._port = port
+        self._code = code
+        self._start = start
+        self._end = end
+        self._kwargs = kwargs
+
+    async def process(self) -> AsyncGenerator[G90PaginatedResponse, None]:
+        """
+        Process paginated response yielding :class:`.G90PaginatedResponse`
+        instance for each element.
+        """
+        page = CMD_PAGE_SIZE
+        start = self._start
+        count = 0
+        while True:
+            # The start record number is one-based, so subtract one when
+            # calculating the number of the end record for the current
+            # iteration
+            end = start + page - 1
+            # Use the smallest of requested end record number and calculated
+            # one (based of page size), allows for number of records less than
+            # in page
+            if self._end:
+                end = min(end, self._end)
+
+            _LOGGER.debug('Invoking paginated command for %s..%s range',
+                          start, end)
+            cmd = await G90PaginatedCommand(
+                host=self._host, port=self._port, code=self._code,
+                start=start, end=end,
+                **self._kwargs
+            ).process()
+
+            # The caller didn't supply the end record number, use the records
+            # total since it is now known
+            if not self._end:
+                self._end = cmd.total
+            # The supplied end record number is higher than total records
+            # available, reset to the latter
+            if self._end > cmd.total:
+                _LOGGER.warning('Requested record range (%i) exceeds number of'
+                                ' available records (%i), setting to the'
+                                ' latter', self._end, cmd.total)
+                self._end = cmd.total
+
+            _LOGGER.debug('Retrieved %i records in the iteration,'
+                          ' %i available in total, target end'
+                          ' record number is %i',
+                          cmd.count, cmd.total, self._end)
+
+            # Produce the resulting records for the consumer
+            for idx, data in enumerate(cast(Iterable[str], cmd.result)):
+                # Protocol uses one-based indexes, `start` implies that so no
+                # further additions to resulting value is needed.
+                # Note the index provided here is running one across multiple
+                # pages hence use of `start` variable
+                yield G90PaginatedResponse(start + idx, data)
+
+            # Count the number of processed records
+            count += cmd.count
+
+            # End the loop if we processed same number of sensors as in the
+            # pagination header (or attempted to process more than that by
+            # an error), or no records have been received
+            if not cmd.count:
+                break
+            if cmd.start + cmd.count - 1 >= self._end:
+                break
+            # Move to the next page for another iteration
+            start = start + page
+
+        _LOGGER.debug('Total number of paginated entries:'
+                      ' processed %s, expected %s',
+                      count,
+                      # Again, both end and start record numbers are one-based,
+                      # so need to add one to calculate how many records have
+                      # been requested
+                      self._end - self._start + 1)

pyg90alarm/local/targeted_discovery.py

@@ -0,0 +1,162 @@
+# 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.
+
+"""
+Discovers G90 alarm panel devices with specific ID.
+"""
+from __future__ import annotations
+import logging
+from typing import Tuple, Any, Optional, Dict, List
+from dataclasses import dataclass, asdict
+import asyncio
+from asyncio.transports import BaseTransport
+from .base_cmd import G90BaseCommand
+from ..const import G90Commands
+from ..exceptions import G90Error
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+# pylint: disable=too-many-instance-attributes
+class G90TargetedDiscoveryInfo:
+    """
+    Wire representation of the information about discovered device.
+    """
+    message: str
+    product_name: str
+    wifi_protocol_version: str
+    cloud_protocol_version: str
+    mcu_hw_version: str
+    fw_version: str
+    gsm_status: str
+    wifi_status: str
+    server_status: str
+    reserved1: str
+    reserved2: str
+    gsm_signal_level: str
+    wifi_signal_level: str
+
+    def _asdict(self) -> Dict[str, Any]:
+        """
+        Returns the information about discovered device as dictionary.
+        """
+        return asdict(self)
+
+
+@dataclass
+class G90DiscoveredDeviceTargeted(G90TargetedDiscoveryInfo):
+    """
+    Discovered device with specific ID.
+    """
+    host: str
+    port: int
+    guid: str
+
+
+class G90TargetedDiscovery(G90BaseCommand):
+    """
+    Discovers alarm panel devices with specific ID.
+    """
+    # pylint: disable=too-few-public-methods
+    def __init__(self, device_id: str, **kwargs: Any):
+        super().__init__(
+            # No actual command will be processed by base class, `NONE` is used
+            # for proper typing only
+            code=G90Commands.NONE, **kwargs
+        )
+        self._device_id = device_id
+        self._discovered_devices: List[G90DiscoveredDeviceTargeted] = []
+
+    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.
+        """
+
+    # Implementation of datagram protocol,
+    # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
+    def datagram_received(self, data: bytes, addr: Tuple[str, int]) -> None:
+        """
+        Invoked when datagram is received.
+        """
+        try:
+            _LOGGER.debug('Received from %s:%s: %s', addr[0], addr[1], data)
+            try:
+                decoded = data.decode('utf-8')
+            except UnicodeDecodeError as exc:
+                raise G90Error(
+                    'Unable to decode discovery response from UTF-8'
+                ) from exc
+            if not decoded.endswith('\0'):
+                raise G90Error('Invalid discovery response')
+            host_info = G90TargetedDiscoveryInfo(*decoded[:-1].split(','))
+            if host_info.message != 'IWTAC_PROBE_DEVICE_ACK':
+                raise G90Error('Invalid discovery response')
+            res = G90DiscoveredDeviceTargeted(
+                host=addr[0],
+                port=addr[1],
+                guid=self._device_id,
+                **host_info._asdict()
+            )
+            _LOGGER.debug('Discovered device: %s', res)
+            self.add_device(res)
+        except Exception as exc:  # pylint: disable=broad-except
+            _LOGGER.warning('Got exception, ignoring: %s', exc)
+
+    def error_received(self, exc: Exception) -> None:
+        """
+        Invoked when error is received.
+        """
+
+    def to_wire(self) -> bytes:
+        """
+        Converts the command to wire representation.
+        """
+        return bytes(f'IWTAC_PROBE_DEVICE,{self._device_id}\0', 'ascii')
+
+    async def process(self) -> G90TargetedDiscovery:
+        """
+        Initiates the device discovery process.
+        """
+        _LOGGER.debug('Attempting device discovery...')
+        transport, _ = await self._create_connection()
+        transport.sendto(self.to_wire())
+        await asyncio.sleep(self._timeout)
+        transport.close()
+        _LOGGER.debug('Discovered %s devices', len(self.devices))
+        return self
+
+    @property
+    def devices(self) -> List[G90DiscoveredDeviceTargeted]:
+        """
+        The list of discovered devices.
+        """
+        return self._discovered_devices
+
+    def add_device(self, value: G90DiscoveredDeviceTargeted) -> None:
+        """
+        Adds discovered device to the list.
+        """
+        self._discovered_devices.append(value)

pyg90alarm/local/user_data_crc.py

@@ -0,0 +1,46 @@
+# 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.
+
+"""
+Protocol entity for G90 alarm panel that provides checksums of different
+on-device databases.
+"""
+from __future__ import annotations
+from typing import Any, Dict
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class G90UserDataCRC:
+    """
+    Represents structure of GETUSERDATACRC command response.
+    """
+    sensor_list: str
+    device_list: str
+    history_list: str
+    scene_list: str
+    ifttt_list: str
+    fingerprint_list: str
+
+    def _asdict(self) -> Dict[str, Any]:
+        """
+        Returns the host information as dictionary.
+        """
+        return asdict(self)