pyg90alarm 2.3.0__py3-none-any.whl

pyg90alarm/local/discovery.py

@@ -0,0 +1,103 @@
+# 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 panels.
+"""
+from __future__ import annotations
+import asyncio
+from typing import Any, List, Tuple
+from dataclasses import dataclass
+import logging
+
+from .base_cmd import G90BaseCommand
+from .host_info import G90HostInfo
+from ..const import G90Commands
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class G90DiscoveredDevice(G90HostInfo):
+    """
+    Represents discovered alarm panel.
+    """
+    host: str
+    port: int
+    guid: str
+
+
+class G90Discovery(G90BaseCommand):
+    """
+    Discovers alarm panels.
+    """
+    # pylint: disable=too-few-public-methods
+    def __init__(self, timeout: float = 10, **kwargs: Any):
+        # pylint: disable=too-many-arguments
+        super().__init__(code=G90Commands.GETHOSTINFO, timeout=timeout,
+                         **kwargs)
+        self._discovered_devices: List[G90DiscoveredDevice] = []
+
+    # 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 some data is received.
+        """
+        try:
+            ret = self.from_wire(data)
+            host_info = G90HostInfo(*ret)
+            _LOGGER.debug('Received from %s:%s: %s', addr[0], addr[1], ret)
+            res = G90DiscoveredDevice(
+                host=addr[0],
+                port=addr[1],
+                guid=host_info.host_guid,
+                **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)
+
+    async def process(self) -> G90Discovery:
+        """
+        Initiates device discovery.
+        """
+        _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[G90DiscoveredDevice]:
+        """
+        The list of discovered devices.
+        """
+        return self._discovered_devices
+
+    def add_device(self, value: G90DiscoveredDevice) -> None:
+        """
+        Adds discovered device to the list.
+        """
+        self._discovered_devices.append(value)

pyg90alarm/local/history.py

@@ -0,0 +1,272 @@
+# 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.
+
+"""
+History protocol entity.
+"""
+import logging
+
+from typing import Any, Optional, Dict
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from ..const import (
+    G90AlertTypes,
+    G90AlertSources,
+    G90AlertStates,
+    G90AlertStateChangeTypes,
+    G90HistoryStates,
+    G90RemoteButtonStates,
+)
+from ..notifications.base import G90DeviceAlert
+
+_LOGGER = logging.getLogger(__name__)
+
+
+# The state of the incoming history entries are mixed of `G90AlertStates`,
+# `G90AlertStateChangeTypes` and `G90RemoteButtonStates`, depending on entry
+# type - hence separate dictionaries, since enums used for keys have
+# conflicting values
+states_mapping_alerts = {
+    G90AlertStates.DOOR_CLOSE:
+        G90HistoryStates.DOOR_CLOSE,
+    G90AlertStates.DOOR_OPEN:
+        G90HistoryStates.DOOR_OPEN,
+    G90AlertStates.TAMPER:
+        G90HistoryStates.TAMPER,
+    G90AlertStates.LOW_BATTERY:
+        G90HistoryStates.LOW_BATTERY,
+    G90AlertStates.ALARM:
+        G90HistoryStates.ALARM,
+}
+
+states_mapping_state_changes = {
+    G90AlertStateChangeTypes.AC_POWER_FAILURE:
+        G90HistoryStates.AC_POWER_FAILURE,
+    G90AlertStateChangeTypes.AC_POWER_RECOVER:
+        G90HistoryStates.AC_POWER_RECOVER,
+    G90AlertStateChangeTypes.DISARM:
+        G90HistoryStates.DISARM,
+    G90AlertStateChangeTypes.ARM_AWAY:
+        G90HistoryStates.ARM_AWAY,
+    G90AlertStateChangeTypes.ARM_HOME:
+        G90HistoryStates.ARM_HOME,
+    G90AlertStateChangeTypes.LOW_BATTERY:
+        G90HistoryStates.LOW_BATTERY,
+    G90AlertStateChangeTypes.WIFI_CONNECTED:
+        G90HistoryStates.WIFI_CONNECTED,
+    G90AlertStateChangeTypes.WIFI_DISCONNECTED:
+        G90HistoryStates.WIFI_DISCONNECTED,
+}
+
+states_mapping_remote_buttons = {
+    G90RemoteButtonStates.ARM_AWAY:
+        G90HistoryStates.REMOTE_BUTTON_ARM_AWAY,
+    G90RemoteButtonStates.ARM_HOME:
+        G90HistoryStates.REMOTE_BUTTON_ARM_HOME,
+    G90RemoteButtonStates.DISARM:
+        G90HistoryStates.REMOTE_BUTTON_DISARM,
+    G90RemoteButtonStates.SOS:
+        G90HistoryStates.REMOTE_BUTTON_SOS,
+}
+
+
+@dataclass
+class ProtocolData:
+    """
+    Class representing the data incoming from the device
+
+    :meta private:
+    """
+    type: G90AlertTypes
+    event_id: G90AlertStateChangeTypes
+    source: G90AlertSources
+    state: int
+    sensor_name: str
+    unix_time: int
+    other: str
+
+
+class G90History:
+    """
+    Represents a history entry from the alarm panel.
+    """
+    def __init__(self, *args: Any, **kwargs: Any):
+        self._raw_data = args
+        self._protocol_data = ProtocolData(*args, **kwargs)
+
+    @property
+    def datetime(self) -> datetime:
+        """
+        Date/time of the history entry.
+        """
+        return datetime.fromtimestamp(
+            self._protocol_data.unix_time, tz=timezone.utc
+        )
+
+    @property
+    def type(self) -> Optional[G90AlertTypes]:
+        """
+        Type of the history entry.
+        """
+        try:
+            return G90AlertTypes(self._protocol_data.type)
+        except (ValueError, KeyError):
+            _LOGGER.warning(
+                "Can't interpret '%s' as alert type (decoded protocol"
+                " data '%s', raw data '%s')",
+                self._protocol_data.type, self._protocol_data, self._raw_data
+            )
+            return None
+
+    @property
+    def state(self) -> Optional[G90HistoryStates]:
+        """
+        State for the history entry.
+        """
+        # No meaningful state for SOS alerts initiated by the panel itself
+        # (host)
+        if self.type == G90AlertTypes.HOST_SOS:
+            return None
+
+        try:
+            # State of the remote indicate which button has been pressed
+            if (
+                self.type in [
+                    G90AlertTypes.SENSOR_ACTIVITY, G90AlertTypes.ALARM
+                ] and self.source == G90AlertSources.REMOTE
+            ):
+                return states_mapping_remote_buttons[
+                    G90RemoteButtonStates(self._protocol_data.state)
+                ]
+
+            # Door open/close or alert types, mapped against `G90AlertStates`
+            # using `state` incoming field
+            if self.type in [
+                G90AlertTypes.SENSOR_ACTIVITY, G90AlertTypes.ALARM
+            ]:
+                return G90HistoryStates(
+                    states_mapping_alerts[
+                        G90AlertStates(self._protocol_data.state)
+                    ]
+                )
+        except (ValueError, KeyError):
+            _LOGGER.warning(
+                "Can't interpret '%s' as alert state (decoded protocol"
+                " data '%s', raw data '%s')",
+                self._protocol_data.state, self._protocol_data, self._raw_data
+            )
+            return None
+
+        try:
+            # Other types are mapped against `G90AlertStateChangeTypes`
+            return G90HistoryStates(
+                states_mapping_state_changes[
+                    G90AlertStateChangeTypes(self._protocol_data.event_id)
+                ]
+            )
+        except (ValueError, KeyError):
+            _LOGGER.warning(
+                "Can't interpret '%s' as state change (decoded protocol"
+                " data '%s', raw data '%s')",
+                self._protocol_data.event_id, self._protocol_data,
+                self._raw_data
+            )
+            return None
+
+    @property
+    def source(self) -> Optional[G90AlertSources]:
+        """
+        Source of the history entry.
+        """
+        try:
+            # Device state changes, open/close or alarm events are mapped
+            # against `G90AlertSources` using `source` incoming field
+            if self.type in [
+                G90AlertTypes.STATE_CHANGE, G90AlertTypes.SENSOR_ACTIVITY,
+                G90AlertTypes.ALARM
+            ]:
+                return G90AlertSources(self._protocol_data.source)
+        except (ValueError, KeyError):
+            _LOGGER.warning(
+                "Can't interpret '%s' as alert source (decoded protocol"
+                " data '%s', raw data '%s')",
+                self._protocol_data.source, self._protocol_data, self._raw_data
+            )
+            return None
+
+        # Other sources are assumed to be initiated by device itself
+        return G90AlertSources.DEVICE
+
+    @property
+    def sensor_name(self) -> Optional[str]:
+        """
+        Name of the sensor related to the history entry, might be empty if none
+        associated.
+        """
+        return self._protocol_data.sensor_name or None
+
+    @property
+    def sensor_idx(self) -> Optional[int]:
+        """
+        ID of the sensor related to the history entry, might be empty if none
+        associated.
+        """
+        # Sensor ID will only be available if entry source is a sensor
+        if self.source == G90AlertSources.SENSOR:
+            return self._protocol_data.event_id
+
+        return None
+
+    def as_device_alert(self) -> G90DeviceAlert:
+        """
+        Returns the history entry represented as device alert structure,
+        suitable for :meth:`G90DeviceNotifications._handle_alert`.
+        """
+
+        return G90DeviceAlert(
+            type=self._protocol_data.type,
+            event_id=self._protocol_data.event_id,
+            source=self._protocol_data.source,
+            state=self._protocol_data.state,
+            zone_name=self._protocol_data.sensor_name,
+            device_id='',
+            unix_time=self._protocol_data.unix_time,
+            resv4=0,
+            other=self._protocol_data.other
+        )
+
+    def _asdict(self) -> Dict[str, Any]:
+        """
+        Returns the history entry as dictionary.
+        """
+        return {
+            'type': self.type,
+            'source': self.source,
+            'state': self.state,
+            'sensor_name': self.sensor_name,
+            'sensor_idx': self.sensor_idx,
+            'datetime': self.datetime,
+        }
+
+    def __repr__(self) -> str:
+        """
+        Textural representation of the history entry.
+        """
+        return super().__repr__() + f'({repr(self._asdict())})'

pyg90alarm/local/host_info.py

@@ -0,0 +1,89 @@
+# 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 information.
+"""
+from __future__ import annotations
+from typing import Any, Dict
+from dataclasses import dataclass, asdict
+from enum import IntEnum
+
+
+class G90HostInfoGsmStatus(IntEnum):
+    """
+    Defines possible values of GSM module status.
+    """
+    POWERED_OFF = 0
+    SIM_ABSENT = 1
+    NO_SIGNAL = 2
+    OPERATIONAL = 3
+
+
+class G90HostInfoWifiStatus(IntEnum):
+    """
+    Defines possible values of Wifi module status.
+    """
+    POWERED_OFF = 0
+    NOT_CONNECTED = 1
+    NO_SIGNAL = 2
+    OPERATIONAL = 3
+
+
+@dataclass
+class G90HostInfo:  # pylint: disable=too-many-instance-attributes
+    """
+    Interprets data fields of GETHOSTINFO command.
+    """
+    host_guid: str
+    product_name: str
+    wifi_protocol_version: str
+    cloud_protocol_version: str
+    mcu_hw_version: str
+    wifi_hw_version: str
+    gsm_status_data: int
+    wifi_status_data: int
+    reserved1: int
+    reserved2: int
+    band_frequency: str
+    gsm_signal_level: int
+    wifi_signal_level: int
+
+    @property
+    def gsm_status(self) -> G90HostInfoGsmStatus:
+        """
+        Translates the GSM module status received from the device into
+        corresponding enum.
+        """
+        return G90HostInfoGsmStatus(self.gsm_status_data)
+
+    @property
+    def wifi_status(self) -> G90HostInfoWifiStatus:
+        """
+        Translates the Wifi module status received from the device into
+        corresponding enum.
+        """
+        return G90HostInfoWifiStatus(self.wifi_status_data)
+
+    def _asdict(self) -> Dict[str, Any]:
+        """
+        Returns the host information as dictionary.
+        """
+        return asdict(self)

pyg90alarm/local/host_status.py

@@ -0,0 +1,52 @@
+# 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 status.
+"""
+from __future__ import annotations
+from typing import Any, Dict
+from dataclasses import dataclass, asdict
+from ..const import G90ArmDisarmTypes
+
+
+@dataclass
+class G90HostStatus:
+    """
+    Interprets data fields of GETHOSTSTATUS command.
+    """
+    host_status_data: int
+    host_phone_number: str
+    product_name: str
+    mcu_hw_version: str
+    wifi_hw_version: str
+
+    @property
+    def host_status(self) -> G90ArmDisarmTypes:
+        """
+        Translates host status data to G90ArmDisarmTypes.
+        """
+        return G90ArmDisarmTypes(self.host_status_data)
+
+    def _asdict(self) -> Dict[str, Any]:
+        """
+        Returns the host information as dictionary.
+        """
+        return asdict(self)

pyg90alarm/local/notifications.py

@@ -0,0 +1,117 @@
+# 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 support for notifications/alerts sent by G90 alarm panel.
+"""
+import logging
+from typing import (
+    Optional, Tuple, Callable
+)
+import asyncio
+from asyncio.transports import BaseTransport
+from asyncio.protocols import DatagramProtocol
+
+from ..notifications.base import G90NotificationsBase
+from ..notifications.protocol import G90NotificationProtocol
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class G90LocalNotifications(G90NotificationsBase, DatagramProtocol):
+    """
+    Implements support for notifications/alerts sent by alarm panel.
+
+    There is a basic check to ensure only notifications/alerts from the correct
+    device are processed - the check uses the host and port of the device, and
+    the device ID (GUID) that is set by the ancestor class that implements the
+    commands (e.g. :class:`.G90Alarm`). The latter to work correctly needs a
+    command to be performed first, one that fetches device GUID and then stores
+    it using :attr:`.device_id` (e.g. :meth:`.G90Alarm.get_host_info`).
+
+    :param protocol_factory: A callable that returns a new instance of the
+     :class:`.G90NotificationProtocol` class.
+    :param port: The port on which the device is listening for notifications.
+    :param host: The host on which the device is listening for notifications.
+    :param local_port: The port on which the local host is listening for
+     notifications.
+    :param local_host: The host on which the local host is listening for
+     notifications.
+    """
+    # pylint:disable=too-many-positional-arguments,too-many-arguments
+    def __init__(
+        self, protocol_factory: Callable[[], G90NotificationProtocol],
+        port: int, host: str, local_port: int, local_host: str,
+    ):
+        super().__init__(protocol_factory)
+
+        self._host = host
+        self._port = port
+        self._notifications_local_host = local_host
+        self._notifications_local_port = local_port
+
+    # 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 from the device is made.
+        """
+
+    def connection_lost(self, exc: Optional[Exception]) -> None:
+        """
+        Same but when the connection is lost.
+        """
+
+    def datagram_received(
+        self, data: bytes, addr: Tuple[str, int]
+    ) -> None:
+        """
+        Invoked when datagram is received from the device.
+        """
+        if self._host and self._host != addr[0]:
+            _LOGGER.error(
+                "Received notification/alert from wrong host '%s',"
+                " expected from '%s'",
+                addr[0], self._host
+            )
+            return
+
+        self.set_last_device_packet_time()
+
+        _LOGGER.debug('Received device message from %s:%s: %s',
+                      addr[0], addr[1], data)
+
+        self.handle(data)
+
+    async def listen(self) -> None:
+        """
+        Listens for notifications/alerts from the device.
+        """
+        loop = asyncio.get_running_loop()
+
+        _LOGGER.debug('Creating UDP endpoint for %s:%s',
+                      self._notifications_local_host,
+                      self._notifications_local_port)
+        (self._transport,
+         _protocol) = await loop.create_datagram_endpoint(
+            lambda: self,
+            local_addr=(
+                self._notifications_local_host, self._notifications_local_port
+            ))