pyg90alarm 1.20.0__py3-none-any.whl → 2.0.1__py3-none-any.whl

pyg90alarm/notifications/protocol.py

@@ -0,0 +1,116 @@
+# 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.
+
+"""
+Defines notification protocol for `NotificationBase` class.
+"""
+
+from ..const import (
+    G90ArmDisarmTypes,
+    G90RemoteButtonStates,
+)
+
+
+class G90NotificationProtocol:
+    """
+    Protocol for notification handling.
+    """
+    async def on_armdisarm(self, state: G90ArmDisarmTypes) -> None:
+        """
+        Invoked when device is armed or disarmed.
+
+        :param state: State of the device
+        """
+
+    async def on_sensor_activity(self, idx: int, name: str) -> None:
+        """
+        Invoked on sensor activity.
+
+        :param idx: Index of the sensor.
+        :param name: Name of the sensor.
+        """
+
+    async def on_door_open_when_arming(
+        self, event_id: int, zone_name: str
+    ) -> None:
+        """
+        Invoked when door open is detected when panel is armed.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the sensor that reports door open.
+        """
+
+    async def on_door_open_close(
+        self, event_id: int, zone_name: str, is_open: bool
+    ) -> None:
+        """
+        Invoked when door sensor reports it opened or closed.
+
+        :param event_id: Index of the sensor reporting the event.
+        :param zone_name: Name of the sensor that reports door open/close.
+        :param is_open: Indicates if the door is open.
+        """
+
+    async def on_low_battery(self, event_id: int, zone_name: str) -> None:
+        """
+        Invoked when a sensor reports it is low on battery.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the sensor that reports low battery.
+        """
+
+    async def on_alarm(
+        self, event_id: int, zone_name: str, is_tampered: bool
+    ) -> None:
+        """
+        Invoked when device triggers the alarm.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the zone that triggered the alarm.
+        """
+
+    async def on_remote_button_press(
+        self, event_id: int, zone_name: str, button: G90RemoteButtonStates
+    ) -> None:
+        """
+        Invoked when a remote button is pressed.
+
+        Please note there will only be call to the method w/o invoking
+        :meth:`G90DeviceNotifications.on_sensor_activity`.
+
+        :param event_id: Index of the sensor associated with the remote.
+        :param zone_name: Name of the sensor that reports remote button press.
+        :param button: The button pressed on the remote
+        """
+
+    async def on_sos(
+        self, event_id: int, zone_name: str, is_host_sos: bool
+    ) -> None:
+        """
+        Invoked when SOS is triggered.
+
+        Please note that the panel might not set its status to alarm
+        internally, so that :meth:`G90DeviceNotifications` might need an
+        explicit call in the derived class to simulate that.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the sensor that reports SOS.
+        :param is_host_sos: Indicates if the SOS is host-initiated.
+        """

{pyg90alarm-1.20.0.dist-info → pyg90alarm-2.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: pyg90alarm
-Version: 1.20.0
+Version: 2.0.1
 Summary: G90 Alarm system protocol
 Home-page: https://github.com/hostcc/pyg90alarm
 Author: Ilia Sotnikov
@@ -15,14 +15,13 @@ Classifier: Topic :: Home Automation
 Classifier: Topic :: System :: Hardware
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3 :: Only
-Requires-Python: >=3.8, <4
+Requires-Python: >=3.9, <4
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Provides-Extra: dev
@@ -40,6 +39,7 @@ Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: keywords
+Dynamic: license-file
 Dynamic: project-url
 Dynamic: provides-extra
 Dynamic: requires-python
@@ -136,22 +136,14 @@ Known caveats
   contact sensors though, since an intruder cutting the line will trigger the
   alarm.
 
-Enabling device notifications
-=============================
+Device notifications
+====================
 
-There is a hidden device capability to send protocol notifications over the
-WiFi interface. The notifications are done using broadcast UDP packets with
-source/destination ports being ``45000:12901`` (non-configurable), and sent when
-the device has IP address of its WiFi interface set to ``10.10.10.250``. That is
-the same IP the device will allocate to the WiFi interface when AP (access
-point is enabled). Please note enabling the AP *is not* required for the
-notifications to be sent, only the IP address matters. Likely the firmware does
-a check internally and enables those when corresponding IP address is found on
-the WiFi interface.
+Local notifications
+-------------------
 
-Please see
-`protocol documentation <https://pyg90alarm.readthedocs.io/en/stable/protocol.html>`_
-for further details on the device notifications.
+There is a hidden device capability to send protocol notifications over the
+WiFi interface, thus called local. The notifications are done using broadcast UDP packets with source/destination ports being ``45000:12901`` (non-configurable), and sent when the device has IP address of its WiFi interface set to ``10.10.10.250``. That is the same IP the device will allocate to the WiFi interface when AP (access point is enabled). Please note enabling the AP *is not* required for the notifications to be sent, only the IP address matters. Likely the firmware does a check internally and enables those when corresponding IP address is found on the WiFi interface.
 
 Depending on your network setup, ensuring the `10.10.10.250` IP address is
 allocated to the WiFi interface of the device might be as simple as DHCP
@@ -178,6 +170,97 @@ set the IP address allocation up.
    alert to be enabled in the mobile application, otherwise it won't be
    recorded in the history.
 
+For the local notifications to be enabled the ```G90Alarm.use_local_notifications()``` needs to be called upon contstucting an instance of ``G90Alarm`` class, then ```G90Alarm.listen_notifications()`z to start processing those coming from the panel - the code fragment below demonstrate that though being incomplete since callbacks (e.g. ``G90Alarm.on_armdisarm()``) should be set for the actual processing of the notifications.
+
+.. code:: python
+
+   from pyg90alarm import G90Alarm
+
+   # Create an instance of the alarm panel
+   alarm = G90Alarm(host='10.10.10.250')
+   # Enable local notifications
+   await alarm.use_local_notifications()
+   # Start listening for notifications
+   await alarm.listen_notifications()
+
+Cloud notifications
+-------------------
+
+The cloud protocol is native to the panel and is used to interact with mobile application. The package can mimic the cloud server and interpret the messages the panel sends to the cloud, allowing to receive the notifications and alerts.
+While the protocol also allows to send commands to the panel, it is not implemented and local protocol is used for that - i.e. when cloud notifications are in use the local protocol still utilized for sending commands to the panel.
+
+The cloud protocol is TCP based and typically interacts with cloud service at known IP address and port (not customizeable at panel side). To process the cloud notifications all the traffic from panel towards the cloud (IP address ``47.88.7.61`` and TCP port ``5678`` as of writing) needs to be diverted to the node where the package is running - depending on your network equipment it could be port forwarding, DNAT or other means. It is unclear whether the panel utilizes DNS to resolve the cloud service IP address, hence the documentation only mentions IP-based traffic redirection.
+
+Please see
+`cloud-protocol.rst <docs/cloud-protocol.rst>`_ for further details on the protocol.
+
+The benefit of the cloud notifications is that the panel no longer required to have ``10.10.10.250`` IP address.
+
+The package could act as:
+
+- Standalone cloud server with no Internet connectivity or cloud service
+  required at all - good if you'd like to avoid having a vendor service involved. Please note the mobile application will show panel as offline in this mode
+- Chained cloud server, where in addition to intepreting the notifications it
+  will also forward all packets received from the panel to the cloud server, and pass its responses back to the panel. This allows to have notificaitons processed by the package and the mobile application working as well.
+
+  .. note:: Sending packets upstream to the known IP address and port of the cloud server might result in those looped back (since traffic from panel to cloud service has to be redirected to the host where package runs), if your network equipment can't account for source address in redirection rules (i.e. limiting the port redirection to the panel's IP address). In that case you'll need another redirection, from the host where the package runs to the cloud service using an IP from your network. That way those two redirection rules will coexist correctly. To illustate:
+
+   Port forwarding rule 1:
+
+   - Source: panel IP address
+   - Destination: 47.88.7.61
+   - Port: 5678
+   - Redirect to host: host where package runs
+   - Redirect to port: 5678 (or other port if you want to use it)
+
+   Port forwarding rule 2 (optional):
+
+   - Source: host where package runs
+   - Destination: an IP address from your network
+   - Port: 5678 (or other port if you want to use it)
+   - Redirect to : 47.88.7.61
+   - Redirect to port: 5678
+
+The code fragments below demonstrate how to utilize both modes - please note those are incomplete, since no callbacks are set to process the notifications.
+
+**Standalone mode**
+
+.. code:: python
+
+   from pyg90alarm import G90Alarm
+
+   # Create an instance of the alarm panel
+   alarm = G90Alarm(host='<panel IP address>')
+   # Enable cloud notifications
+   await alarm.use_cloud_notifications(
+      # Optional, see note above redirecting cloud traffic from panel
+      local_port=5678,
+      upstream_host=None
+   )
+   # Start listening for notifications
+   await alarm.listen_notifications()
+
+
+**Chained mode**
+
+.. code:: python
+
+   from pyg90alarm import G90Alarm
+
+   # Create an instance of the alarm panel
+   alarm = G90Alarm(host='<panel IP address>')
+   # Enable cloud notifications
+   await alarm.use_cloud_notifications(
+      # Optional, see note above redirecting cloud traffic from panel
+      local_port=5678,
+      # See note above re: cloud service and sending packets to it
+      upstream_host='47.88.7.61',
+      upstream_port=5678
+   )
+   # Start listening for notifications
+   await alarm.listen_notifications()
+
+
 Quick start
 ===========
 

pyg90alarm-2.0.1.dist-info/RECORD

@@ -0,0 +1,40 @@
+pyg90alarm/__init__.py,sha256=Gpl_3jd5Ye_O8rVG2GJg7FvgFEqcp-qNj5UBK9GBLwM,2258
+pyg90alarm/alarm.py,sha256=7j0rLBDaX1LFaM2WS_ZCVekqu-zoeNvsCVuD8bLJscM,41249
+pyg90alarm/callback.py,sha256=3JsD_JChmZD24OyjaCP-PxxuBDBX7myGYhkM4RN7bk4,3742
+pyg90alarm/const.py,sha256=F1qqwZFZeLLhb2AFv22dIIc6Ri0NPcHjmIsYXK7RYAI,6775
+pyg90alarm/exceptions.py,sha256=eiOcRe7D18EIPyPFDNU9DdFgbnkwPmkiLl8lGPOhBNw,1475
+pyg90alarm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyg90alarm/cloud/__init__.py,sha256=u7ZzrIwCsdgmBmgtpCe6c_Kipdo8nG8PEOEcaAHXCxI,1407
+pyg90alarm/cloud/const.py,sha256=FYUxkj0DSI7nnXZHsJMfv8RNQiXKV3TYKGHSdfHdMjg,2113
+pyg90alarm/cloud/messages.py,sha256=iH8PZ77Dz-ksTQpIMRFFKQI3gmIjKBTsfLeou8SyjIA,18003
+pyg90alarm/cloud/notifications.py,sha256=4n0pIpv_TH_9EXZQyqTjNc_AOJPT8DmxlpiPAGz0D1o,15598
+pyg90alarm/cloud/protocol.py,sha256=82l2IXSM12tv_iWkTrAQZ-aw5UR4tmWFQJKVcgBfIww,16159
+pyg90alarm/definitions/__init__.py,sha256=s0NZnkW_gMH718DJbgez28z9WA231CyszUf1O_ojUiI,68
+pyg90alarm/definitions/sensors.py,sha256=rKOu21ZpI44xk6aMh_vBjniFqnsNTc1CKwAvnv4PYLQ,19904
+pyg90alarm/entities/__init__.py,sha256=hHb6AOiC4Tz--rOWiiICMdLaZDs1Tf_xpWk_HeS_gO4,66
+pyg90alarm/entities/base_entity.py,sha256=Ea1r1aP7FMnOiEPhBhkrndmcr5Iy8jcfQuuXCNHajrU,2473
+pyg90alarm/entities/base_list.py,sha256=76DUtdXTwd26vv6HIw_qdtBNd1FqMfoRf0VI9KxV5aA,5703
+pyg90alarm/entities/device.py,sha256=f_LHvKCAqTEebZ4mrRh3CpPUI7o-OvpvOfyTRCbftJs,2818
+pyg90alarm/entities/device_list.py,sha256=FrsfzP1BgwCKOn6bzVUpQHdatB6MUcWhPeuaJ3c5mqg,2154
+pyg90alarm/entities/sensor.py,sha256=ax-6ttps7sCWfuP6CcnS00Zy5WZVKleO8vAsdhU3KQc,21986
+pyg90alarm/entities/sensor_list.py,sha256=qLNbLZXrPlcdZLoyZw3Mzf1PwX4BiW3z6SKi_NqhVnM,1806
+pyg90alarm/local/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyg90alarm/local/base_cmd.py,sha256=NNaSXqNWEuxtxrz3l7gLwVodpuzESWvt0mYQC9pIBTY,9812
+pyg90alarm/local/config.py,sha256=2YtIgdT7clQXmYvkdn_fhIdS05CY8E1Yc90R8_tAmRI,1961
+pyg90alarm/local/discovery.py,sha256=8YVIXuNe57lhas0VSRf7QXZH83pEDGNj9oehNY4Kh2U,3576
+pyg90alarm/local/history.py,sha256=v_deRl62tHeysydyeLRvyHJwcBMnKonsEbXXSXb8XP8,9138
+pyg90alarm/local/host_info.py,sha256=4lFIaFEpYd3EvgNrDJmKijTrzX9i29nFISLLlXGnkmE,2759
+pyg90alarm/local/host_status.py,sha256=WHGtw-A0wHILqVWP4DnZhXj8DPRGyS26AV0bL1isTz4,1863
+pyg90alarm/local/notifications.py,sha256=TGNaRxI2BL2wWhT2YbDIyRn5iwGA0lXjwdMD8go2eRE,4555
+pyg90alarm/local/paginated_cmd.py,sha256=bUCtuCYec2pWkufY43sx3gCYE0prysbFY7seegUtkRw,4441
+pyg90alarm/local/paginated_result.py,sha256=knvFKtpswtVnC-1Av5vbVYhL5bue60qKmo4p6FCv0_k,5448
+pyg90alarm/local/targeted_discovery.py,sha256=Ik2C2VBtVLurf3-RKko4O2R3B6MrmFdOskd457uyASU,5516
+pyg90alarm/local/user_data_crc.py,sha256=JQBOPY3RlOgVtvR55R-rM8OuKjYW-BPXQ0W4pi6CEH0,1689
+pyg90alarm/notifications/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyg90alarm/notifications/base.py,sha256=KXZkhFLO-cNcGOLIItxoZr0FaI8ohzlD3njcWVqkOb0,15218
+pyg90alarm/notifications/protocol.py,sha256=1d9rLIX_EwLpH36rXTm6xYS00TNVGCZi88n86VDcQX0,4076
+pyg90alarm-2.0.1.dist-info/licenses/LICENSE,sha256=f884inRbeNv-O-hbwz62Ro_1J8xiHRTnJ2cCx6A0WvU,1070
+pyg90alarm-2.0.1.dist-info/METADATA,sha256=tbZP_20tfCk_MdtUY_rA-cIaeCnbhzTQhP4_MQgSFbI,12569
+pyg90alarm-2.0.1.dist-info/WHEEL,sha256=ck4Vq1_RXyvS4Jt6SI0Vz6fyVs4GWg7AINwpsaGEgPE,91
+pyg90alarm-2.0.1.dist-info/top_level.txt,sha256=czHiGxYMyTk5QEDTDb0EpPiKqUMRa8zI4zx58Ii409M,11
+pyg90alarm-2.0.1.dist-info/RECORD,,

{pyg90alarm-1.20.0.dist-info → pyg90alarm-2.0.1.dist-info}/WHEEL

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

pyg90alarm-1.20.0.dist-info/RECORD

@@ -1,31 +0,0 @@
-pyg90alarm/__init__.py,sha256=5AITRm5jZSzuQaL7PS8fZZMZb4-IuGRhSqyAdfTt0Cs,2236
-pyg90alarm/alarm.py,sha256=YMqf5nyoqQVZPJJB2vRXzWcHNcRjfVGojN7KDBM-KS8,38093
-pyg90alarm/base_cmd.py,sha256=Bz7yoZ0RpkcjWARya664DKAPo3goD6BeaKtuW-hA804,9902
-pyg90alarm/callback.py,sha256=3JsD_JChmZD24OyjaCP-PxxuBDBX7myGYhkM4RN7bk4,3742
-pyg90alarm/config.py,sha256=2YtIgdT7clQXmYvkdn_fhIdS05CY8E1Yc90R8_tAmRI,1961
-pyg90alarm/const.py,sha256=uBzDUSlVO3FZxLI11bzfCm6JTI2_ciageyf43JLSehg,6632
-pyg90alarm/device_notifications.py,sha256=pqkeKYORUUZUEovUKajuu8JHCtXD0ulAZIKelNfn2Eg,17602
-pyg90alarm/discovery.py,sha256=fwyBHDCKGej06OwhpbVCHYTRU9WWkeYysAFgv3FiwqI,3575
-pyg90alarm/exceptions.py,sha256=eiOcRe7D18EIPyPFDNU9DdFgbnkwPmkiLl8lGPOhBNw,1475
-pyg90alarm/history.py,sha256=5NfgB0V-7TZlMNHEjtRbOA0ZtJfQTgh2ysZIg5RM7ck,9080
-pyg90alarm/host_info.py,sha256=4lFIaFEpYd3EvgNrDJmKijTrzX9i29nFISLLlXGnkmE,2759
-pyg90alarm/host_status.py,sha256=4XhuilBzB8XsXkpeWj3PAVpmDPcTnBBOYunO21Flabo,1862
-pyg90alarm/paginated_cmd.py,sha256=vJ8slMS7aNLpkAxnIe25EHstusYy1bYTl1j306ps-MQ,4439
-pyg90alarm/paginated_result.py,sha256=Zs_yB9UW6VlHRBPIzOwHy8ZJ0FqCUPMB-rmfPG2BdnU,5447
-pyg90alarm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pyg90alarm/targeted_discovery.py,sha256=h0SijMpPQ12iBZtfh4xsaP_HIbiQRNBnXsd0-K9rjHA,5514
-pyg90alarm/user_data_crc.py,sha256=JQBOPY3RlOgVtvR55R-rM8OuKjYW-BPXQ0W4pi6CEH0,1689
-pyg90alarm/definitions/__init__.py,sha256=s0NZnkW_gMH718DJbgez28z9WA231CyszUf1O_ojUiI,68
-pyg90alarm/definitions/sensors.py,sha256=rKOu21ZpI44xk6aMh_vBjniFqnsNTc1CKwAvnv4PYLQ,19904
-pyg90alarm/entities/__init__.py,sha256=hHb6AOiC4Tz--rOWiiICMdLaZDs1Tf_xpWk_HeS_gO4,66
-pyg90alarm/entities/base_entity.py,sha256=Ea1r1aP7FMnOiEPhBhkrndmcr5Iy8jcfQuuXCNHajrU,2473
-pyg90alarm/entities/base_list.py,sha256=76DUtdXTwd26vv6HIw_qdtBNd1FqMfoRf0VI9KxV5aA,5703
-pyg90alarm/entities/device.py,sha256=f_LHvKCAqTEebZ4mrRh3CpPUI7o-OvpvOfyTRCbftJs,2818
-pyg90alarm/entities/device_list.py,sha256=FrsfzP1BgwCKOn6bzVUpQHdatB6MUcWhPeuaJ3c5mqg,2154
-pyg90alarm/entities/sensor.py,sha256=ax-6ttps7sCWfuP6CcnS00Zy5WZVKleO8vAsdhU3KQc,21986
-pyg90alarm/entities/sensor_list.py,sha256=qLNbLZXrPlcdZLoyZw3Mzf1PwX4BiW3z6SKi_NqhVnM,1806
-pyg90alarm-1.20.0.dist-info/LICENSE,sha256=f884inRbeNv-O-hbwz62Ro_1J8xiHRTnJ2cCx6A0WvU,1070
-pyg90alarm-1.20.0.dist-info/METADATA,sha256=UDwmoHFOiwFFQiq0yVLsV0Pl1YV2D09H8AwNtw8zESQ,7951
-pyg90alarm-1.20.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-pyg90alarm-1.20.0.dist-info/top_level.txt,sha256=czHiGxYMyTk5QEDTDb0EpPiKqUMRa8zI4zx58Ii409M,11
-pyg90alarm-1.20.0.dist-info/RECORD,,