pyg90alarm 1.11.0__py3-none-any.whl → 1.12.0__py3-none-any.whl

pyg90alarm/alarm.py

@@ -48,7 +48,7 @@ G90HostInfo(host_guid='<...>',
             wifi_signal_level=100)
 
 """
-
+import asyncio
 import logging
 from .const import (
     G90Commands, REMOTE_PORT,
@@ -76,7 +76,9 @@ from .callback import G90Callback
 _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.
 
@@ -92,9 +94,12 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
      simulated to go into inactive state.
     :type reset_occupancy_interval: int, optional
     """
-    # pylint: disable=too-many-instance-attributes
+    # pylint: disable=too-many-instance-attributes,too-many-arguments
     def __init__(self, host, port=REMOTE_PORT,
-                 reset_occupancy_interval=3):
+                 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 = []
@@ -104,9 +109,12 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
         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):
         """
@@ -400,10 +408,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
@@ -420,6 +433,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)',
@@ -477,19 +491,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):
@@ -509,7 +525,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.
@@ -545,7 +561,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`.
@@ -554,14 +570,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
@@ -581,27 +597,49 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     def alarm_callback(self, value):
         self._alarm_cb = value
 
-    async def listen_device_notifications(
-        self, host='0.0.0.0', port=NOTIFICATIONS_PORT
-    ):
+    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.
 
         """
-        self._notifications = G90DeviceNotifications(
-            host=host, port=port,
-            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)
-        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):
         """
@@ -638,3 +676,108 @@ 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:
+            # 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
+            if not last_history_ts:
+                # 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
+                    )
+
+            # 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
@@ -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
@@ -131,11 +76,39 @@ class G90BaseCommand:
                                     separators=(',', ':'))
         self._resp = G90Header()
 
-    def _proto_factory(self):
+    # 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):
         """
@@ -153,7 +126,7 @@ class G90BaseCommand:
             extra_kwargs['local_addr'] = ('0.0.0.0', self._local_port)
 
         transport, protocol = await loop.create_datagram_endpoint(
-            self._proto_factory,
+            lambda: self,
             remote_addr=(self.host, self.port),
             **extra_kwargs,
             allow_broadcast=True)
@@ -241,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
@@ -249,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

@@ -185,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.
@@ -201,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

pyg90alarm/device_notifications.py

@@ -21,7 +21,6 @@
 """
 Implements support for notifications/alerts sent by G90 alarm panel.
 """
-
 import json
 import logging
 from collections import namedtuple
@@ -34,6 +33,7 @@ from .const import (
     G90AlertStateChangeTypes,
     G90ArmDisarmTypes,
     G90AlertSources,
+    G90AlertStates,
 )
 
 
@@ -43,7 +43,7 @@ _LOGGER = logging.getLogger(__name__)
 class G90Message(namedtuple('G90Message',
                             ['code', 'data'])):
     """
-    tbd
+    Represents the message received from the device.
 
     :meta private:
     """
@@ -52,7 +52,7 @@ class G90Message(namedtuple('G90Message',
 class G90Notification(namedtuple('G90Notification',
                                  ['kind', 'data'])):
     """
-    tbd
+    Represents the notification received from the device.
 
     :meta private:
     """
@@ -61,7 +61,7 @@ class G90Notification(namedtuple('G90Notification',
 class G90ZoneInfo(namedtuple('G90ZoneInfo',
                              ['idx', 'name'])):
     """
-    tbd
+    Represents zone details received from the device.
 
     :meta private:
     """
@@ -70,7 +70,7 @@ class G90ZoneInfo(namedtuple('G90ZoneInfo',
 class G90ArmDisarmInfo(namedtuple('G90ArmDisarmInfo',
                                   ['state'])):
     """
-    tbd
+    Represents the arm/disarm state received from the device.
 
     :meta private:
     """
@@ -81,46 +81,31 @@ class G90DeviceAlert(namedtuple('G90DeviceAlert',
                                  'zone_name', 'device_id', 'unix_time',
                                  'resv4', 'other'])):
     """
-    tbd
+    Represents alert received from the device.
 
     :meta private:
     """
 
 
-class G90DeviceNotificationProtocol:
+class G90DeviceNotifications:
     """
     tbd
-
-    :meta private:
     """
-    def __init__(self, armdisarm_cb=None, sensor_cb=None,
-                 door_open_close_cb=None, alarm_cb=None):
-        """
-        tbd
-        """
-        self._armdisarm_cb = armdisarm_cb
-        self._sensor_cb = sensor_cb
-        self._door_open_close_cb = door_open_close_cb
-        self._alarm_cb = alarm_cb
-
-    def connection_made(self, transport):
-        """
-        tbd
-        """
-
-    def connection_lost(self, exc):
-        """
-        tbd
-        """
+    def __init__(self, port, host):
+        # pylint: disable=too-many-arguments
+        self._notification_transport = None
+        self._notifications_host = host
+        self._notifications_port = port
 
     def _handle_notification(self, addr, notification):
         # Sensor activity notification
         if notification.kind == G90NotificationTypes.SENSOR_ACTIVITY:
             g90_zone_info = G90ZoneInfo(*notification.data)
             _LOGGER.debug('Sensor notification: %s', g90_zone_info)
-            G90Callback.invoke(self._sensor_cb,
-                               g90_zone_info.idx,
-                               g90_zone_info.name)
+            G90Callback.invoke(
+                self.on_sensor_activity,
+                g90_zone_info.idx, g90_zone_info.name
+            )
             return
 
         # Arm/disarm notification
@@ -131,8 +116,7 @@ class G90DeviceNotificationProtocol:
             state = G90ArmDisarmTypes(g90_armdisarm_info.state)
             _LOGGER.debug('Arm/disarm notification: %s',
                           state)
-            G90Callback.invoke(self._armdisarm_cb,
-                               state)
+            G90Callback.invoke(self.on_armdisarm, state)
             return
 
         _LOGGER.warning('Unknown notification received from %s:%s:'
@@ -141,14 +125,30 @@ class G90DeviceNotificationProtocol:
 
     def _handle_alert(self, addr, alert):
         if alert.type == G90AlertTypes.DOOR_OPEN_CLOSE:
-            is_open = (
-                alert.source == G90AlertSources.SENSOR and alert.state == 1
-            ) or alert.source == G90AlertSources.DOORBELL
-            _LOGGER.debug('Door open_close alert: %s', alert)
-            G90Callback.invoke(self._door_open_close_cb,
-                               alert.event_id, alert.zone_name,
-                               is_open)
-            return
+            if alert.state in (
+                G90AlertStates.DOOR_OPEN, G90AlertStates.DOOR_CLOSE
+            ):
+                is_open = (
+                    alert.source == G90AlertSources.SENSOR
+                    and alert.state == G90AlertStates.DOOR_OPEN  # noqa: W503
+                ) or alert.source == G90AlertSources.DOORBELL
+                _LOGGER.debug('Door open_close alert: %s', alert)
+                G90Callback.invoke(
+                    self.on_door_open_close,
+                    alert.event_id, alert.zone_name, is_open
+                )
+                return
+
+            if (
+                alert.source == G90AlertSources.SENSOR
+                and alert.state == G90AlertStates.LOW_BATTERY  # noqa: W503
+            ):
+                _LOGGER.debug('Low battery alert: %s', alert)
+                G90Callback.invoke(
+                    self.on_low_battery,
+                    alert.event_id, alert.zone_name
+                )
+                return
 
         if alert.type == G90AlertTypes.STATE_CHANGE:
             # Define the mapping between device state received in the alert, to
@@ -168,21 +168,36 @@ class G90DeviceNotificationProtocol:
                 # We received the device state change related to arm/disarm,
                 # invoke the corresponding callback
                 _LOGGER.debug('Arm/disarm state change: %s', state)
-                G90Callback.invoke(self._armdisarm_cb, state)
+                G90Callback.invoke(self.on_armdisarm, state)
                 return
 
         if alert.type == G90AlertTypes.ALARM:
             _LOGGER.debug('Alarm: %s', alert.zone_name)
-            G90Callback.invoke(self._alarm_cb, alert.event_id, alert.zone_name)
+            G90Callback.invoke(
+                self.on_alarm,
+                alert.event_id, alert.zone_name
+            )
             return
 
         _LOGGER.warning('Unknown alert received from %s:%s:'
                         ' type %s, data %s',
                         addr[0], addr[1], alert.type, alert)
 
+    # Implementation of datagram protocol,
+    # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
+    def connection_made(self, transport):
+        """
+        Invoked when connection from the device is made.
+        """
+
+    def connection_lost(self, exc):
+        """
+        Same but when the connection is lost.
+        """
+
     def datagram_received(self, data, addr):  # pylint:disable=R0911
         """
-        tbd
+        Invoked from datagram is received from the device.
         """
         s_data = data.decode('utf-8')
         if not s_data.endswith('\0'):
@@ -228,37 +243,34 @@ class G90DeviceNotificationProtocol:
         _LOGGER.warning('Unknown message received from %s:%s: %s',
                         addr[0], addr[1], message)
 
+    async def on_armdisarm(self, state):
+        """
+        Invoked when device is armed or disarmed.
+        """
 
-class G90DeviceNotifications:
-    """
-    tbd
-    """
-    def __init__(self, port, host,
-                 armdisarm_cb=None, sensor_cb=None,
-                 door_open_close_cb=None, alarm_cb=None):
-        # pylint: disable=too-many-arguments
-        self._notification_transport = None
-        self._host = host
-        self._port = port
-        self._armdisarm_cb = armdisarm_cb
-        self._sensor_cb = sensor_cb
-        self._door_open_close_cb = door_open_close_cb
-        self._alarm_cb = alarm_cb
-
-    def proto_factory(self):
+    async def on_sensor_activity(self, idx, name):
         """
-        tbd
+        Invoked on sensor activity.
+        """
+
+    async def on_door_open_close(self, event_id, zone_name, is_open):
+        """
+        Invoked when door sensor reports it opened or closed.
+        """
+
+    async def on_low_battery(self, event_id, zone_name):
+        """
+        Invoked when a sensor reports it is low on battery.
+        """
+
+    async def on_alarm(self, event_id, zone_name):
+        """
+        Invoked when device triggers the alarm.
         """
-        return G90DeviceNotificationProtocol(
-            armdisarm_cb=self._armdisarm_cb,
-            sensor_cb=self._sensor_cb,
-            door_open_close_cb=self._door_open_close_cb,
-            alarm_cb=self._alarm_cb
-        )
 
     async def listen(self):
         """
-        tbd
+        Listens for notifications/alers from the device.
         """
         try:
             loop = asyncio.get_running_loop()
@@ -266,15 +278,29 @@ class G90DeviceNotifications:
             loop = asyncio.get_event_loop()
 
         _LOGGER.debug('Creating UDP endpoint for %s:%s',
-                      self._host, self._port)
+                      self._notifications_host,
+                      self._notifications_port)
         (self._notification_transport,
          _protocol) = await loop.create_datagram_endpoint(
-            self.proto_factory,
-            local_addr=(self._host, self._port))
+            lambda: self,
+            local_addr=(
+                self._notifications_host, self._notifications_port
+            ))
+
+    @property
+    def listener_started(self):
+        """
+        Indicates if the listener of the device notifications has been started.
+
+        :rtype: bool
+        """
+        return self._notification_transport is not None
 
     def close(self):
         """
-        tbd
+        Closes the listener.
         """
         if self._notification_transport:
+            _LOGGER.debug('No longer listening for device notifications')
             self._notification_transport.close()
+            self._notification_transport = None

pyg90alarm/discovery.py

@@ -32,34 +32,28 @@ from .const import G90Commands
 _LOGGER = logging.getLogger(__name__)
 
 
-class G90DiscoveryProtocol:
+class G90Discovery(G90BaseCommand):
     """
     tbd
-
-    :meta private:
     """
-    def __init__(self, parent):
-        """
-        tbd
-        """
-        self._parent = parent
-
-    def connection_made(self, transport):
-        """
-        tbd
-        """
-
-    def connection_lost(self, exc):
+    # pylint: disable=too-few-public-methods
+    def __init__(self, timeout=10, **kwargs):
         """
         tbd
         """
+        # pylint: disable=too-many-arguments
+        super().__init__(code=G90Commands.GETHOSTINFO, timeout=timeout,
+                         **kwargs)
+        self._discovered_devices = []
 
+    # Implementation of datagram protocol,
+    # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
     def datagram_received(self, data, addr):
         """
         tbd
         """
         try:
-            ret = self._parent.from_wire(data)
+            ret = self.from_wire(data)
             host_info = G90HostInfo(*ret)
             _LOGGER.debug('Received from %s:%s: %s', addr[0], addr[1], ret)
             res = {
@@ -69,31 +63,11 @@ class G90DiscoveryProtocol:
             }
             res.update(host_info._asdict())
             _LOGGER.debug('Discovered device: %s', res)
-            self._parent.add_device(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):
-        """
-        tbd
-        """
-
-
-class G90Discovery(G90BaseCommand):
-    """
-    tbd
-    """
-    # pylint: disable=too-few-public-methods
-    def __init__(self, timeout=10, **kwargs):
-        """
-        tbd
-        """
-        # pylint: disable=too-many-arguments
-        super().__init__(code=G90Commands.GETHOSTINFO, timeout=timeout,
-                         **kwargs)
-        self._discovered_devices = []
-
     async def process(self):
         """
         tbd
@@ -118,9 +92,3 @@ class G90Discovery(G90BaseCommand):
         tbd
         """
         self._discovered_devices.append(value)
-
-    def _proto_factory(self):
-        """
-        tbd
-        """
-        return G90DiscoveryProtocol(self)

pyg90alarm/entities/sensor.py

@@ -172,6 +172,7 @@ class G90Sensor:  # pylint:disable=too-many-instance-attributes
         self._subindex = subindex
         self._occupancy = False
         self._state_callback = None
+        self._low_battery_callback = None
         self._proto_idx = proto_idx
         self._extra_data = None
 
@@ -217,6 +218,25 @@ class G90Sensor:  # pylint:disable=too-many-instance-attributes
         """
         self._state_callback = value
 
+    @property
+    def low_battery_callback(self):
+        """
+        Returns callback the sensor might have set for low battery condition.
+
+        :return: Sensor's low battery callback
+        :rtype: object
+        """
+        return self._low_battery_callback
+
+    @low_battery_callback.setter
+    def low_battery_callback(self, value):
+        """
+        Sets callback for the low battery condition reported by the sensor.
+
+        :param object value: Sensor's low battery callback
+        """
+        self._low_battery_callback = value
+
     @property
     def occupancy(self):
         """

pyg90alarm/history.py

@@ -22,35 +22,197 @@
 History protocol entity.
 """
 
-import time
+from datetime import datetime, timezone
 from collections import namedtuple
+from .const import (
+    G90AlertTypes,
+    G90AlertSources,
+    G90AlertStates,
+    G90AlertStateChangeTypes,
+    G90HistoryStates,
+)
+from .device_notifications import G90DeviceAlert
+
+
+# The state of the incoming history entries are mixed of `G90AlertStates` and
+# `G90AlertStateChangeTypes`, depending on entry type - the mapping
+# consilidates them into unified `G90HistoryStates`. The latter enum can't be
+# just an union of former two, since those have conflicting values
+states_mapping = {
+    G90AlertStates.DOOR_CLOSE:
+        G90HistoryStates.DOOR_CLOSE,
+    G90AlertStates.DOOR_OPEN:
+        G90HistoryStates.DOOR_OPEN,
+    G90AlertStates.TAMPER:
+        G90HistoryStates.TAMPER,
+    G90AlertStates.LOW_BATTERY:
+        G90HistoryStates.LOW_BATTERY,
+    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,
+}
 
 INCOMING_FIELDS = [
-    'log_type',  # (1 or 3 - alarm, 2 or 4 - notification)
-    'param1',    # (type 1: 1 - SOS, 2 - tamper alarm; type 3 - device ID; type
-                 #  2 - 5 stayarm, 3 - disarm, 4 - awayarm )
-    'param2',    # (type 3: device type)
-    'param3',
+    'type',
+    'event_id',
+    'source',
+    'state',
     'sensor_name',
     'unix_time',
-    'rest',
+    'other',
 ]
+# Class representing the data incoming from the device
+ProtocolData = namedtuple('ProtocolData', INCOMING_FIELDS)
 
 
-class G90History(namedtuple('G90History', INCOMING_FIELDS)):
+class G90History:
     """
     tbd
     """
+    def __init__(self, *args, **kwargs):
+        self._protocol_data = ProtocolData(*args, **kwargs)
 
     @property
     def datetime(self):
         """
-        tbd
+        Date/time of the history entry.
+
+        :rtype: :class:`datetime.datetime`
+        """
+        return datetime.fromtimestamp(
+            self._protocol_data.unix_time, tz=timezone.utc
+        )
+
+    @property
+    def type(self):
+        """
+        Type of the history entry.
+
+        :rtype: :class:`.G90AlertTypes`
+        """
+        return G90AlertTypes(self._protocol_data.type)
+
+    @property
+    def state(self):
+        """
+        State for the history entry.
+
+        :rtype: :class:`.G90HistoryStates`
+        """
+        # Door open/close type, mapped against `G90AlertStates` using `state`
+        # incoming field
+        if self.type == G90AlertTypes.DOOR_OPEN_CLOSE:
+            return G90HistoryStates(
+                states_mapping[G90AlertStates(self._protocol_data.state)]
+            )
+
+        # Device state change, mapped against `G90AlertStateChangeTypes` using
+        # `event_id` incoming field
+        if self.type == G90AlertTypes.STATE_CHANGE:
+            return G90HistoryStates(
+                states_mapping[
+                    G90AlertStateChangeTypes(self._protocol_data.event_id)
+                ]
+            )
+
+        # Alarm gets mapped to its counterpart in `G90HistoryStates`
+        if self.type == G90AlertTypes.ALARM:
+            return G90HistoryStates.ALARM
+
+        # Other types are mapped against `G90AlertStateChangeTypes`
+        return G90HistoryStates(
+            states_mapping[
+                G90AlertStateChangeTypes(self._protocol_data.event_id)
+            ]
+        )
+
+    @property
+    def source(self):
         """
-        return time.ctime(self.unix_time)
+        Source of the history entry.
+
+        :rtype: :class:`.G90AlertSources`
+        """
+        # Device state changes or open/close events are mapped against
+        # `G90AlertSources` using `source` incoming field
+        if self.type in [
+            G90AlertTypes.STATE_CHANGE, G90AlertTypes.DOOR_OPEN_CLOSE
+        ]:
+            return G90AlertSources(self._protocol_data.source)
+
+        # Alarm will have `SENSOR` as the source, since that is likely what
+        # triggered it
+        if self.type == G90AlertTypes.ALARM:
+            return G90AlertSources.SENSOR
+
+        # Other sources are assumed to be initiated by device itself
+        return G90AlertSources.DEVICE
+
+    @property
+    def sensor_name(self):
+        """
+        Name of the sensor related to the history entry, might be empty if none
+        associated.
+
+        :rtype: str|None
+        """
+        return self._protocol_data.sensor_name or None
+
+    @property
+    def sensor_idx(self):
+        """
+        ID of the sensor related to the history entry, might be empty if none
+        associated.
+
+        :rtype: str|None
+        """
+        # 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):
+        """
+        Returns the history entry represented as device alert structure,
+        suitable for :meth:`G90DeviceNotifications._handle_alert`.
+
+        :rtype: :class:`.G90DeviceAlert`
+        """
+        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=None,
+            unix_time=self._protocol_data.unix_time,
+            resv4=None,
+            other=self._protocol_data.other
+        )
 
     def __repr__(self):
         """
-        tbd
+        Textural representation of the history entry.
+
+        :rtype: str
         """
-        return super().__repr__() + f'(datetime={str(self.datetime)})'
+        return f'type={repr(self.type)}' \
+            + f' source={repr(self.source)}' \
+            + f' state={repr(self.state)}' \
+            + f' sensor_name={self.sensor_name}' \
+            + f' sensor_idx={self.sensor_idx}' \
+            + f' datetime={repr(self.datetime)}'

pyg90alarm/targeted_discovery.py

@@ -55,29 +55,21 @@ class G90TargetedDiscoveryInfo(namedtuple('G90TargetedDiscoveryInfo',
     """
 
 
-class G90TargetedDiscoveryProtocol:
+class G90TargetedDiscovery(G90Discovery):
     """
     tbd
-
-    :meta private:
     """
-    def __init__(self, device_id, parent):
-        """
-        tbd
-        """
-        self._parent = parent
-        self._device_id = device_id
 
-    def connection_made(self, transport):
-        """
-        tbd
-        """
-
-    def connection_lost(self, exc):
+    # pylint: disable=too-few-public-methods
+    def __init__(self, device_id, **kwargs):
         """
         tbd
         """
+        super().__init__(**kwargs)
+        self._device_id = device_id
 
+    # Implementation of datagram protocol,
+    # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
     def datagram_received(self, data, addr):
         """
         tbd
@@ -95,39 +87,12 @@ class G90TargetedDiscoveryProtocol:
                    'port': addr[1]}
             res.update(host_info._asdict())
             _LOGGER.debug('Discovered device: %s', res)
-            self._parent.add_device(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):
-        """
-        tbd
-        """
-
-
-class G90TargetedDiscovery(G90Discovery):
-    """
-    tbd
-    """
-
-    # pylint: disable=too-few-public-methods
-    def __init__(self, device_id, **kwargs):
-        """
-        tbd
-        """
-
-        super().__init__(**kwargs)
-        self._device_id = device_id
-
     def to_wire(self):
         """
         tbd
         """
         return bytes(f'IWTAC_PROBE_DEVICE,{self._device_id}\0', 'ascii')
-
-    def _proto_factory(self):
-        """
-        tbd
-        """
-        return G90TargetedDiscoveryProtocol(self._device_id,
-                                            self)

{pyg90alarm-1.11.0.dist-info → pyg90alarm-1.12.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyg90alarm
-Version: 1.11.0
+Version: 1.12.0
 Summary: G90 Alarm system protocol
 Home-page: https://github.com/hostcc/pyg90alarm
 Author: Ilia Sotnikov
@@ -24,13 +24,13 @@ Requires-Python: >=3.7, <4
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Provides-Extra: dev
-Requires-Dist: check-manifest ; extra == 'dev'
+Requires-Dist: check-manifest; extra == "dev"
 Provides-Extra: docs
-Requires-Dist: sphinx ; extra == 'docs'
-Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
 Provides-Extra: test
-Requires-Dist: coverage ; extra == 'test'
-Requires-Dist: asynctest ; extra == 'test'
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: asynctest; extra == "test"
 
 .. image::  https://github.com/hostcc/pyg90alarm/actions/workflows/main.yml/badge.svg?branch=master
    :target: https://github.com/hostcc/pyg90alarm/tree/master
@@ -158,6 +158,13 @@ set the IP address allocation up.
    status will not be reflected and those will always be reported as inactive,
    since there is no way to read their state in a polled manner.
 
+   To work that limitation around the package now supports simulating device
+   notifications from periodically polling the history it records - the
+   simulation works only for the alerts, not notifications (e.g. notifications
+   include low battery events and alike). This also requires the particular
+   alert to be enabled in the mobile application, otherwise it won't be
+   recorded in the history.
+
 Quick start
 ===========
 

{pyg90alarm-1.11.0.dist-info → pyg90alarm-1.12.0.dist-info}/RECORD

@@ -1,26 +1,26 @@
 pyg90alarm/__init__.py,sha256=zidYApReScSFZCpC9Tk7pdsBNPMql6XiUtt-O7l3D5M,1381
-pyg90alarm/alarm.py,sha256=0SMGPe9J1550j_Yq-KxoFlKPjzVIZ5Z-RhsjUusUS9U,23528
-pyg90alarm/base_cmd.py,sha256=xuW-jjuScag1kAVPKNa2GUmL99UYeyu2n-C9ppLmOMo,8768
+pyg90alarm/alarm.py,sha256=IsNpnPyBh90lTP9L03R1GJ608Ld6ZgUsJ7D5nS3WpCk,29157
+pyg90alarm/base_cmd.py,sha256=rjpjIzEgtI5mUvmurBasrt9psYKdbIEsivnx8QboivY,8561
 pyg90alarm/callback.py,sha256=zg698TCjjYhjAMk770J9CZp8-dDbX0Zj5wtoC6axq6w,4033
 pyg90alarm/config.py,sha256=FiYjiz_WrDH2OEqHyUJXZDDK7v1fLAUpZcQ3JRMmmX0,1974
-pyg90alarm/const.py,sha256=nhqrP9GqsU4VeEYHSW4NJTh6QO20L7uDea2reqDnqO4,5226
-pyg90alarm/device_notifications.py,sha256=wxDf0m_LOt6Sj_jG8cfTFZM3LNry2xrPwkFPa4lVscI,9315
-pyg90alarm/discovery.py,sha256=07TZIIGgPsRcW_iYpS-82lG18rotuykYqfGV-cE2eHc,3474
+pyg90alarm/const.py,sha256=XP_x5w6quiKQceOJDpExXI86L5KbQLdTed4lbjlNth0,5760
+pyg90alarm/device_notifications.py,sha256=JLdOIIwyoxQdqvIjuLj6_5Rz_W6slYeM8HBPzPIa1ew,10628
+pyg90alarm/discovery.py,sha256=sPk2mRhc0IgpOIlC9kRlKCnlAfdXsT7TyWfHAc1bfqQ,3077
 pyg90alarm/exceptions.py,sha256=eiOcRe7D18EIPyPFDNU9DdFgbnkwPmkiLl8lGPOhBNw,1475
-pyg90alarm/history.py,sha256=E8c8ucy5cscPSawIz4nXxV4HKdyhsoJda4Akvvt3k6I,1836
+pyg90alarm/history.py,sha256=Ln3-v8hvagIXTmj_2iURE3oOsVLeQb8OMczUy-SKSRs,7039
 pyg90alarm/host_info.py,sha256=fGGI2ZH6GVD0WhYT72rIELTbiIAmmPiT31eZkyVugwY,2571
 pyg90alarm/host_status.py,sha256=PEPgpkfGNkUzKUgRpfPKldz5qq3_9lqBwX86Ld613vk,1406
 pyg90alarm/paginated_cmd.py,sha256=7pXLAgFQHheByBpwRV-I1yEdZnm8hk6j2OMPZ_Wn-vE,3768
 pyg90alarm/paginated_result.py,sha256=xweFfPLn1a2yYm5h0AxGoDCyDIoy0JkUC_tI80vsrLc,5246
-pyg90alarm/targeted_discovery.py,sha256=_SR_pBZxDkLNL5WA8LfGboQw2AH09G65ASn9EEtxlDs,3735
+pyg90alarm/targeted_discovery.py,sha256=DPxNvs8qJfyIOq6KLBYBpqkHPCpHbMW70_gfNyvNAoY,3221
 pyg90alarm/user_data_crc.py,sha256=RsQlbuXC4baD88hX4y0XdysmxEMtQkqkNVX_FhTLSmw,1467
 pyg90alarm/definitions/__init__.py,sha256=s0NZnkW_gMH718DJbgez28z9WA231CyszUf1O_ojUiI,68
 pyg90alarm/definitions/sensors.py,sha256=2Liap0stTT5qNmvsbP_7UscA21IYXQcSAKQLLm7YfHQ,19921
 pyg90alarm/entities/__init__.py,sha256=hHb6AOiC4Tz--rOWiiICMdLaZDs1Tf_xpWk_HeS_gO4,66
 pyg90alarm/entities/device.py,sha256=QbsQyIq2wFLjIH389zyD3d0CyME_rpG_ciD3srAdqXQ,2772
-pyg90alarm/entities/sensor.py,sha256=2d_671Kefx7wM6mWRQR79XyScEkkp3bk7HsA1Qnx75I,13354
-pyg90alarm-1.11.0.dist-info/LICENSE,sha256=f884inRbeNv-O-hbwz62Ro_1J8xiHRTnJ2cCx6A0WvU,1070
-pyg90alarm-1.11.0.dist-info/METADATA,sha256=4TEvcDDcPQcq7E0bHPGZ83NWBxl56gDL7I98goAmHvU,7211
-pyg90alarm-1.11.0.dist-info/WHEEL,sha256=cpQTJ5IWu9CdaPViMhC9YzF8gZuS5-vlfoFihTBC86A,91
-pyg90alarm-1.11.0.dist-info/top_level.txt,sha256=czHiGxYMyTk5QEDTDb0EpPiKqUMRa8zI4zx58Ii409M,11
-pyg90alarm-1.11.0.dist-info/RECORD,,
+pyg90alarm/entities/sensor.py,sha256=AkVj_qrK35K5SwSlAHXU9UXdBKVaJzV4TBcoeZUevn4,13942
+pyg90alarm-1.12.0.dist-info/LICENSE,sha256=f884inRbeNv-O-hbwz62Ro_1J8xiHRTnJ2cCx6A0WvU,1070
+pyg90alarm-1.12.0.dist-info/METADATA,sha256=8zrPZpzJVGK7UZ-It72WrJEpQst6S5BWVGjatOaLr_M,7611
+pyg90alarm-1.12.0.dist-info/WHEEL,sha256=HiCZjzuy6Dw0hdX5R3LCFPDmFS4BWl8H-8W39XfmgX4,91
+pyg90alarm-1.12.0.dist-info/top_level.txt,sha256=czHiGxYMyTk5QEDTDb0EpPiKqUMRa8zI4zx58Ii409M,11
+pyg90alarm-1.12.0.dist-info/RECORD,,

{pyg90alarm-1.11.0.dist-info → pyg90alarm-1.12.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (70.1.0)
+Generator: setuptools (72.2.0)
 Root-Is-Purelib: true
 Tag: py3-none-any