pyg90alarm 1.10.0__py3-none-any.whl → 1.12.1__py3-none-any.whl

pyg90alarm/alarm.py

@@ -48,12 +48,13 @@ G90HostInfo(host_guid='<...>',
             wifi_signal_level=100)
 
 """
-
+import asyncio
 import logging
 from .const import (
     G90Commands, REMOTE_PORT,
     REMOTE_TARGETED_DISCOVERY_PORT,
     LOCAL_TARGETED_DISCOVERY_PORT,
+    NOTIFICATIONS_PORT,
     G90ArmDisarmTypes,
 )
 from .base_cmd import G90BaseCommand
@@ -71,11 +72,14 @@ from .config import (G90AlertConfig, G90AlertConfigFlags)
 from .history import G90History
 from .user_data_crc import G90UserDataCRC
 from .callback import G90Callback
+from .exceptions import G90Error, G90TimeoutError
 
 _LOGGER = logging.getLogger(__name__)
 
 
-class G90Alarm:  # pylint: disable=too-many-public-methods
+# pylint: disable=too-many-public-methods
+class G90Alarm(G90DeviceNotifications):
+
     """
     Allows to interact with G90 alarm panel.
 
@@ -87,30 +91,31 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
      protocol commands on WiFi interface, currently the devices don't allow it
      to be customized
     :type port: int, optional
-    :param sock: The existing socket to operate on, instead of
-     creating one internally. Primarily used by the tests to mock the network
-     traffic
-    :type sock: socket.socket or None, optional
     :param reset_occupancy_interval: The interval upon that the sensors are
      simulated to go into inactive state.
     :type reset_occupancy_interval: int, optional
     """
-    # pylint: disable=too-many-instance-attributes
-    def __init__(self, host, port=REMOTE_PORT, sock=None,
-                 reset_occupancy_interval=3):
+    # pylint: disable=too-many-instance-attributes,too-many-arguments
+    def __init__(self, host, port=REMOTE_PORT,
+                 reset_occupancy_interval=3,
+                 notifications_host='0.0.0.0',
+                 notifications_port=NOTIFICATIONS_PORT):
+        super().__init__(host=notifications_host, port=notifications_port)
         self._host = host
         self._port = port
         self._sensors = []
         self._devices = []
         self._notifications = None
-        self._sock = sock
         self._sensor_cb = None
         self._armdisarm_cb = None
         self._door_open_close_cb = None
         self._alarm_cb = None
+        self._low_battery_cb = None
         self._reset_occupancy_interval = reset_occupancy_interval
         self._alert_config = None
         self._sms_alert_when_armed = False
+        self._alert_simulation_task = None
+        self._alert_simulation_start_listener_back = False
 
     async def command(self, code, data=None):
         """
@@ -124,7 +129,7 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
          command invocation
         """
         cmd = await G90BaseCommand(
-            self._host, self._port, code, data, sock=self._sock).process()
+            self._host, self._port, code, data).process()
         return cmd.result
 
     def paginated_result(self, code, start=1, end=None):
@@ -141,7 +146,7 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
           yields :class:`.G90PaginatedResponse` instance
         """
         return G90PaginatedResult(
-            self._host, self._port, code, start, end, sock=self._sock
+            self._host, self._port, code, start, end
         ).process()
 
     @classmethod
@@ -404,10 +409,15 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
         """
         res = self.paginated_result(G90Commands.GETHISTORY,
                                     start, count)
-        history = [G90History(*x.data) async for x in res]
-        return history
 
-    async def _internal_sensor_cb(self, idx, name, occupancy=True):
+        # Sort the history entries from older to newer - device typically does
+        # that, but apparently that is not guaranteed
+        return sorted(
+            [G90History(*x.data) async for x in res],
+            key=lambda x: x.datetime, reverse=True
+        )
+
+    async def on_sensor_activity(self, idx, name, occupancy=True):
         """
         Callback that invoked both for sensor notifications and door open/close
         alerts, since the logic for both is same and could be reused. Please
@@ -424,6 +434,7 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
          alerts (only for `door` type sensors, if door open/close alerts are
          enabled)
         """
+        _LOGGER.debug('on_sensor_acitvity: %s %s %s', idx, name, occupancy)
         sensor = await self.find_sensor(idx, name)
         if sensor:
             _LOGGER.debug('Setting occupancy to %s (previously %s)',
@@ -481,19 +492,21 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     def sensor_callback(self, value):
         self._sensor_cb = value
 
-    async def _internal_door_open_close_cb(self, idx, name, is_open):
+    async def on_door_open_close(self, event_id, zone_name, is_open):
         """
         Callback that invoked when door open/close alert comes from the alarm
         panel. Please note the callback is for internal use by the class.
 
-        .. seealso:: `method`:_internal_sensor_cb for arguments
+        .. seealso:: `method`:on_sensor_activity for arguments
         """
         # Same internal callback is reused both for door open/close alerts and
         # sensor notifications. The former adds reporting when a door is
         # closed, since the notifications aren't sent for such events
-        await self._internal_sensor_cb(idx, name, is_open)
+        await self.on_sensor_activity(event_id, zone_name, is_open)
         # Invoke user specified callback if any
-        G90Callback.invoke(self._door_open_close_cb, idx, name, is_open)
+        G90Callback.invoke(
+            self._door_open_close_cb, event_id, zone_name, is_open
+        )
 
     @property
     def door_open_close_callback(self):
@@ -513,7 +526,7 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
         """
         self._door_open_close_cb = value
 
-    async def _internal_armdisarm_cb(self, state):
+    async def on_armdisarm(self, state):
         """
         Callback that invoked when the device is armed or disarmed. Please note
         the callback is for internal use by the class.
@@ -549,7 +562,7 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     def armdisarm_callback(self, value):
         self._armdisarm_cb = value
 
-    async def _internal_alarm_cb(self, sensor_idx, sensor_name):
+    async def on_alarm(self, event_id, zone_name):
         """
         Callback that invoked when alarm is triggered. Fires alarm callback if
         set by the user with `:property:G90Alarm.alarm_callback`.
@@ -558,14 +571,14 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
         :param int: Index of the sensor triggered alarm
         :param str: Sensor name
         """
-        sensor = await self.find_sensor(sensor_idx, sensor_name)
+        sensor = await self.find_sensor(event_id, zone_name)
         # The callback is still delivered to the caller even if the sensor
         # isn't found, only `extra_data` is skipped. That is to ensur the
         # important callback isn't filtered
         extra_data = sensor.extra_data if sensor else None
 
         G90Callback.invoke(
-            self._alarm_cb, sensor_idx, sensor_name, extra_data
+            self._alarm_cb, event_id, zone_name, extra_data
         )
 
     @property
@@ -585,27 +598,49 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     def alarm_callback(self, value):
         self._alarm_cb = value
 
-    async def listen_device_notifications(self, sock=None):
+    async def on_low_battery(self, event_id, zone_name):
+        """
+        Callback that invoked when the sensor reports on low battery. Fires
+        corresponding callback if set by the user with
+        `:property:G90Alarm.on_low_battery_callback`.
+        Please note the callback is for internal use by the class.
+
+        :param int: Index of the sensor triggered alarm
+        :param str: Sensor name
+        """
+        sensor = await self.find_sensor(event_id, zone_name)
+        if sensor:
+            # Invoke per-sensor callback if provided
+            G90Callback.invoke(sensor.low_battery_callback)
+
+        G90Callback.invoke(self._low_battery_cb, event_id, zone_name)
+
+    @property
+    def low_battery_callback(self):
+        """
+        Get or set low battery callback, the callback is invoked when sensor
+        the condition is reported by a sensor.
+
+        :type: .. py:function:: ()(idx, name)
+        """
+        return self._low_battery_cb
+
+    @low_battery_callback.setter
+    def low_battery_callback(self, value):
+        self._low_battery_cb = value
+
+    async def listen_device_notifications(self):
         """
         Starts internal listener for device notifications/alerts.
 
-        :param sock: socket instance to listen on, mostly used by tests
-        :type: socket.socket
         """
-        self._notifications = G90DeviceNotifications(
-            sensor_cb=self._internal_sensor_cb,
-            door_open_close_cb=self._internal_door_open_close_cb,
-            armdisarm_cb=self._internal_armdisarm_cb,
-            alarm_cb=self._internal_alarm_cb,
-            sock=sock)
-        await self._notifications.listen()
+        await self.listen()
 
     def close_device_notifications(self):
         """
         Closes the listener for device notifications/alerts.
         """
-        if self._notifications:
-            self._notifications.close()
+        self.close()
 
     async def arm_away(self):
         """
@@ -642,3 +677,125 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     @sms_alert_when_armed.setter
     def sms_alert_when_armed(self, value):
         self._sms_alert_when_armed = value
+
+    async def start_simulating_alerts_from_history(
+        self, interval=5, history_depth=5
+    ):
+        """
+        Starts the separate task to simulate device alerts from history
+        entries.
+
+        The listener for device notifications will be stopped, so device
+        notifications will not be processed thus resulting in possible
+        duplicated if those could be received from the network.
+
+        :param int interval: Interval (in seconds) between polling for newer
+          history entities
+        :param int history_depth: Amount of history entries to fetch during
+          each polling cycle
+        """
+        # Remember if device notifications listener has been started already
+        self._alert_simulation_start_listener_back = self.listener_started
+        # And then stop it
+        self.close()
+
+        # Start the task
+        self._alert_simulation_task = asyncio.create_task(
+            self._simulate_alerts_from_history(interval, history_depth)
+        )
+
+    async def stop_simulating_alerts_from_history(self):
+        """
+        Stops the task simulating device alerts from history entries.
+
+        The listener for device notifications will be started back, if it was
+        running when simulation has been started.
+        """
+        # Stop the task simulating the device alerts from history if it was
+        # running
+        if self._alert_simulation_task:
+            self._alert_simulation_task.cancel()
+            self._alert_simulation_task = None
+
+        # Start device notifications listener back if it was running when
+        # simulated alerts have been enabled
+        if self._alert_simulation_start_listener_back:
+            await self.listen()
+
+    async def _simulate_alerts_from_history(self, interval, history_depth):
+        """
+        Periodically fetches history entries from the device and simulates
+        device alerts off of those.
+
+        Only the history entries occur after the process is started are
+        handled, to avoid triggering callbacks retrospectively.
+
+        See :method:`start_simulating_alerts_from_history` for the parameters.
+        """
+        last_history_ts = None
+
+        _LOGGER.debug(
+            'Simulating device alerts from history:'
+            ' interval %s, history depth %s',
+            interval, history_depth
+        )
+        while True:
+            try:
+                # Retrieve the history entries of the specified amount - full
+                # history retrieval might be an unnecessary long operation
+                history = await self.history(count=history_depth)
+
+                # Initial iteration where no timestamp of most recent history
+                # entry is recorded - do that and skip to next iteration, since
+                # it isn't yet known what entries would be considered as new
+                # ones.
+                # Empty history will skip recording the timestamp and the
+                # looping over entries below, effectively skipping to next
+                # iteration
+                if not last_history_ts and history:
+                    # First entry in the list is assumed to be the most recent
+                    # one
+                    last_history_ts = history[0].datetime
+                    _LOGGER.debug(
+                        'Initial time stamp of last history entry: %s',
+                        last_history_ts
+                    )
+                    continue
+
+                # Process history entries from older to newer to preserve the
+                # order of happenings
+                for item in reversed(history):
+                    # Process only the entries newer than one been recorded as
+                    # most recent one
+                    if item.datetime > last_history_ts:
+                        _LOGGER.debug(
+                            'Found newer history entry: %s, simulating alert',
+                            repr(item)
+                        )
+                        # Send the history entry down the device notification
+                        # code as alert, as if it came from the device and its
+                        # notifications port
+                        self._handle_alert(
+                            (self._host, self._notifications_port),
+                            item.as_device_alert()
+                        )
+
+                        # Record the entry as most recent one
+                        last_history_ts = item.datetime
+                        _LOGGER.debug(
+                            'Time stamp of last history entry: %s',
+                            last_history_ts
+                        )
+            except (G90Error, G90TimeoutError) as exc:
+                _LOGGER.debug(
+                    'Error interacting with device, ignoring %s', repr(exc)
+                )
+            except Exception as exc:
+                _LOGGER.error(
+                    'Exception simulating device alerts from history: %s',
+                    repr(exc)
+                )
+                raise exc
+
+            # Sleep to next iteration
+            await asyncio.sleep(interval)

pyg90alarm/base_cmd.py

@@ -44,62 +44,6 @@ class G90Header(NamedTuple):
     data: Optional[str] = None
 
 
-class G90DeviceProtocol:
-    """
-    tbd
-
-    :meta private:
-    """
-    def __init__(self):
-        """
-        tbd
-        """
-        self._data = None
-
-    @property
-    def future_data(self):
-        """
-        tbd
-        """
-        return self._data
-
-    @future_data.setter
-    def future_data(self, value):
-        """
-        tbd
-        """
-        self._data = value
-
-    def connection_made(self, transport):
-        """
-        tbd
-        """
-
-    def connection_lost(self, exc):
-        """
-        tbd
-        """
-
-    def datagram_received(self, data, addr):
-        """
-        tbd
-        """
-        if asyncio.isfuture(self._data):
-            if self._data.done():
-                _LOGGER.warning('Excessive packet received'
-                                ' from %s:%s: %s',
-                                addr[0], addr[1], data)
-                return
-            self._data.set_result((*addr, data))
-
-    def error_received(self, exc):
-        """
-        tbd
-        """
-        if asyncio.isfuture(self._data) and not self._data.done():
-            self._data.set_exception(exc)
-
-
 class G90BaseCommand:
     """
     tbd
@@ -110,7 +54,7 @@ class G90BaseCommand:
 
     def __init__(self, host, port, code,
                  data=None, local_port=None,
-                 timeout=3.0, retries=3, sock=None):
+                 timeout=3.0, retries=3):
         """
         tbd
         """
@@ -123,6 +67,7 @@ class G90BaseCommand:
         self._retries = retries
         self._data = '""'
         self._result = None
+        self._connection_result = None
         if data:
             self._data = json.dumps([code, data],
                                     # No newlines to be inserted
@@ -130,13 +75,40 @@ class G90BaseCommand:
                                     # No whitespace around entities
                                     separators=(',', ':'))
         self._resp = G90Header()
-        self._sock = sock
 
-    def _proto_factory(self):  # pylint: disable=no-self-use
+    # Implementation of datagram protocol,
+    # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
+    def connection_made(self, transport):
+        """
+        tbd
+        """
+
+    def connection_lost(self, exc):
+        """
+        tbd
+        """
+
+    def datagram_received(self, data, addr):
+        """
+        tbd
+        """
+        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):
         """
         tbd
         """
-        return G90DeviceProtocol()
+        if (
+            asyncio.isfuture(self._connection_result) and not
+            self._connection_result.done()
+        ):
+            self._connection_result.set_exception(exc)
 
     async def _create_connection(self):
         """
@@ -147,23 +119,17 @@ class G90BaseCommand:
         except AttributeError:
             loop = asyncio.get_event_loop()
 
-        if self._sock:
-            _LOGGER.debug('Using provided socket %s', self._sock)
-            transport, protocol = await loop.create_datagram_endpoint(
-                self._proto_factory,
-                sock=self._sock)
-        else:
-            _LOGGER.debug('Creating UDP endpoint for %s:%s',
-                          self.host, self.port)
-            extra_kwargs = {}
-            if self._local_port:
-                extra_kwargs['local_addr'] = ('0.0.0.0', self._local_port)
-
-            transport, protocol = await loop.create_datagram_endpoint(
-                self._proto_factory,
-                remote_addr=(self.host, self.port),
-                **extra_kwargs,
-                allow_broadcast=True)
+        _LOGGER.debug('Creating UDP endpoint for %s:%s',
+                      self.host, self.port)
+        extra_kwargs = {}
+        if self._local_port:
+            extra_kwargs['local_addr'] = ('0.0.0.0', self._local_port)
+
+        transport, protocol = await loop.create_datagram_endpoint(
+            lambda: self,
+            remote_addr=(self.host, self.port),
+            **extra_kwargs,
+            allow_broadcast=True)
 
         return transport, protocol
 
@@ -248,7 +214,7 @@ class G90BaseCommand:
         tbd
         """
 
-        transport, protocol = await self._create_connection()
+        transport, _ = await self._create_connection()
         attempts = self._retries
         while True:
             attempts = attempts - 1
@@ -256,24 +222,24 @@ class G90BaseCommand:
                 loop = asyncio.get_running_loop()
             except AttributeError:
                 loop = asyncio.get_event_loop()
-            protocol.future_data = loop.create_future()
+            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([protocol.future_data],
+                done, _ = await asyncio.wait([self._connection_result],
                                              timeout=self._timeout)
-            if protocol.future_data in done:
+            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
-            protocol.future_data.cancel()
+            self._connection_result.cancel()
             if not attempts:
                 transport.close()
                 raise G90TimeoutError()
             _LOGGER.debug('Timed out, retrying')
         transport.close()
-        (host, port, data) = protocol.future_data.result()
+        (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':

pyg90alarm/const.py

@@ -27,6 +27,7 @@ from enum import IntEnum
 REMOTE_PORT = 12368
 REMOTE_TARGETED_DISCOVERY_PORT = 12900
 LOCAL_TARGETED_DISCOVERY_PORT = 12901
+NOTIFICATIONS_PORT = 12901
 
 CMD_PAGE_SIZE = 10
 
@@ -184,10 +185,21 @@ class G90AlertSources(IntEnum):
     """
     Defines possible sources of the alert sent by the panel.
     """
+    DEVICE = 0
     SENSOR = 1
     DOORBELL = 12
 
 
+class G90AlertStates(IntEnum):
+    """
+    Defines possible states of the alert sent by the panel.
+    """
+    DOOR_CLOSE = 0
+    DOOR_OPEN = 1
+    TAMPER = 3
+    LOW_BATTERY = 4
+
+
 class G90AlertStateChangeTypes(IntEnum):
     """
     Defines types of alert for device state changes.
@@ -200,3 +212,21 @@ class G90AlertStateChangeTypes(IntEnum):
     LOW_BATTERY = 6
     WIFI_CONNECTED = 7
     WIFI_DISCONNECTED = 8
+
+
+class G90HistoryStates(IntEnum):
+    """
+    Defines possible states for history entities.
+    """
+    DOOR_CLOSE = 1
+    DOOR_OPEN = 2
+    TAMPER = 3
+    ALARM = 4
+    AC_POWER_FAILURE = 5
+    AC_POWER_RECOVER = 6
+    DISARM = 7
+    ARM_AWAY = 8
+    ARM_HOME = 9
+    LOW_BATTERY = 10
+    WIFI_CONNECTED = 11
+    WIFI_DISCONNECTED = 12