pyg90alarm 1.20.0__tar.gz → 2.0.0__tar.gz

{pyg90alarm-1.20.0 → pyg90alarm-2.0.0}/.github/workflows/main.yml

@@ -16,9 +16,6 @@ jobs:
     strategy:
       matrix:
         include:
-          - os: ubuntu-latest
-            python: '3.8'
-            toxenv: py
           - os: ubuntu-latest
             python: '3.9'
             toxenv: py

{pyg90alarm-1.20.0 → pyg90alarm-2.0.0}/MANIFEST.in

@@ -9,6 +9,6 @@ include LICENSE
 # Include setup.py
 include setup.py
 
-recursive-include src py.typed
+recursive-include src *.py py.typed
 
 exclude requirements_dev.txt

{pyg90alarm-1.20.0 → pyg90alarm-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: pyg90alarm
-Version: 1.20.0
+Version: 2.0.0
 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-1.20.0 → pyg90alarm-2.0.0}/README.rst

@@ -89,22 +89,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
@@ -131,6 +123,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.0/docs/cloud-protocol.rst

@@ -0,0 +1,85 @@
+Cloud protocol
+=============================================
+
+.. contents::
+
+Version
+-------
+
+The cloud protocol version: 1.1 (presumably, as seen in response to ``GETHOSTINFO`` local command).
+
+Description
+-----------
+
+The cloud protocol is TCP based, using ``47.88.7.61`` as destination IP address and port ``5678`` (both as seen towards cloud service side). The connection is always initiated by the alarm panel.
+
+The protocol is binary with header (basic or versioned) and command-specific payload. All data is sent in host order (little-endian, LSB first). See below for their wire format.
+
+Security
+--------
+
+.. warning:: The cloud protocol *does not* provide any authorization or encryption. Presumably, the device ID (GUID) is what identifies the panel to the cloud service.
+
+Packet format
+-------------
+
+The G90 cloud protocol packets consist of a header followed by command-specific payload:
+
+::
+
+    +----------------+------------------------+
+    |     Header     |        Payload         |
+    | (8 or 12 bytes)|  (variable length)     |
+    +----------------+------------------------+
+
+Header format
+-------------
+
+The protocol uses two types of headers:
+
+1. Basic Header (8 bytes):
+
+::
+
+    0                   1                   2                   3
+    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |    Command    |     Source    |     Flag1     | Destination   |
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |                       Message Length                          |
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+2. Versioned Header (12 bytes):
+
+::
+
+    0                   1                   2                   3
+    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |    Command    |     Source    |     Flag1     | Destination   |
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |                       Message Length                          |
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |            Version            |           Sequence            |
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+Where:
+
+- **Command**: The command type (see :py:class:`.G90CloudCommand`)
+- **Source**: The source direction of the message (see :py:class:`.G90CloudDirection`)
+- **Flag1**: A flag of unknown purpose (typically 0x00)
+- **Destination**: The destination direction of the message (see :py:class:`.G90CloudDirection`)
+- **Message Length**: Total length of the message including header and payload
+- **Version**: Protocol version (0x01 for protocol version 1.1)
+- **Sequence**: Sequence number, either 0 for single message in the packet or starting from 1 for multiple ones
+
+Payload format
+--------------
+
+The payload format is command-specific and follows the header. The payload length can be calculated as:
+
+::
+
+    Payload Length = Message Length - Header Size
+
+All messages are defined in the :py:mod:`.cloud.messages` module for the headeres and the command-specific payload.

{pyg90alarm-1.20.0 → pyg90alarm-2.0.0}/docs/index.rst

@@ -3,7 +3,8 @@
    :hidden:
 
    Introduction <self>
-   protocol
+   local-protocol
+   cloud-protocol
    api-docs
 
 .. contents::

pyg90alarm-1.20.0/docs/protocol.rst → pyg90alarm-2.0.0/docs/local-protocol.rst

@@ -1,17 +1,15 @@
-G90 alarm panel protocol
-========================
+Local protocol
+=============================================
 
 .. contents::
 
-There are two protocols a G90 alarm system uses: one towards its own cloud and
-another for the clients on local network over WiFi connection.
-
-By the time of writing the following protocol versions are in use:
+Version
+-------
 
-* Cloud: version 1.1
-* Local: version 1.2
+The local protocol version: 1.2 (presumably, as seen in response to ``GETHOSTINFO`` local command).
 
-.. note:: The rest of the document describes only the local protocol, version 1.2
+Description
+-----------
 
 The local protocol is UDP based, using destination port (alarm panel side) of
 ``12368``. It has been noticed the vendor provided applications (at least, on iOS)
@@ -37,7 +35,7 @@ That translates to:
 You should consider implementing network controls to, at least, limit on what
 clients could interact with the alarm control panel. The implementation might
 consider firewall rules, VLANs and other measures available in the network
-equipment you user
+equipment you use.
 
 Request
 -------
@@ -148,7 +146,7 @@ notifications are send unconditionally, that is you cannot disable them, while
 alerts are only sent if enabled in the device.
 
 To receive the notifications from the device you need to follow the steps
-outlined in :ref:`Enabling device notifications`.
+outlined in :ref:`Local notifications`.
 
 The device uses UDP protocol and ``12901`` target port, each notification is
 sent in separate packets having the following structure:
@@ -159,4 +157,4 @@ All messages are terminated with binary zero (shown below as ``\0``), and text
 uses ``utf-8`` encoding.
 
 Data varies across different notification and alert types, see
-`pyg90alarm/device_notifications.py <../../src/pyg90alarm/device_notifications.py>`_. 
+`src/pyg90alarm/local/notifications.py <../../src/pyg90alarm/local/notifications.py>`_.

{pyg90alarm-1.20.0 → pyg90alarm-2.0.0}/setup.py

@@ -36,7 +36,6 @@ setup(
         'Topic :: System :: Hardware',
         'License :: OSI Approved :: MIT License',
         'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.8',
         'Programming Language :: Python :: 3.9',
         'Programming Language :: Python :: 3.10',
         'Programming Language :: Python :: 3.11',
@@ -48,7 +47,7 @@ setup(
     keywords='g90, alarm, protocol',
     package_dir={'': 'src'},
     packages=find_packages(where='src'),
-    python_requires='>=3.8, <4',
+    python_requires='>=3.9, <4',
     install_requires=[],
 
     extras_require={

{pyg90alarm-1.20.0 → pyg90alarm-2.0.0}/sonar-project.properties

@@ -1,4 +1,4 @@
-sonar.python.version=3.7, 3.8, 3.9, 3.10
+sonar.python.version=3.9, 3.10, 3.11, 3.12, 3.13
 sonar.python.coverage.reportPaths=coverage.xml
 sonar.python.pylint.reportPaths=pylint.txt
 sonar.python.flake8.reportPaths=flake8.txt

{pyg90alarm-1.20.0 → pyg90alarm-2.0.0}/src/pyg90alarm/__init__.py

@@ -23,17 +23,17 @@ Python package to control G90-based alarm systems.
 """
 
 from .alarm import G90Alarm
-from .base_cmd import G90BaseCommand
-from .paginated_result import G90PaginatedResult
-from .device_notifications import (
+from .local.base_cmd import G90BaseCommand
+from .local.paginated_result import G90PaginatedResult
+from .notifications.base import (
     G90DeviceAlert,
 )
 from .entities.sensor import G90Sensor, G90SensorTypes
 from .entities.device import G90Device
-from .host_info import (
+from .local.host_info import (
     G90HostInfo, G90HostInfoWifiStatus, G90HostInfoGsmStatus
 )
-from .host_status import G90HostStatus
+from .local.host_status import G90HostStatus
 from .const import (
     G90MessageTypes,
     G90NotificationTypes,