.. image:: https://github.com/hostcc/pyg90alarm/actions/workflows/main.yml/badge.svg?branch=master
:target: https://github.com/hostcc/pyg90alarm/tree/master
:alt: Github workflow status
.. image:: https://readthedocs.org/projects/pyg90alarm/badge/?version=stable
:target: https://pyg90alarm.readthedocs.io/en/stable
:alt: ReadTheDocs status
.. image:: https://img.shields.io/github/v/release/hostcc/pyg90alarm
:target: https://github.com/hostcc/pyg90alarm/releases/latest
:alt: Latest GitHub release
.. image:: https://img.shields.io/pypi/v/pyg90alarm
:target: https://pypi.org/project/pyg90alarm/
:alt: Latest PyPI version
Description
===========
Python package to control G90-based alarm systems.
Many manufacturers sell such systems under different brands - Golden Security,
PST, Kerui and others. Those are cheap low-end systems, typically equipped with
WiFi and possible GSM interfaces for connectivity, and support different range
of peripherals:
* Wired and wireless sensors
* Relays (switches)
... and probably others
The package implements asynchronous I/O over most of code paths using
`asyncio <https://docs.python.org/3/library/asyncio.html>`_.
Disclaimer
==========
The author has no affiliation or any relationship to any of the hardware
vendors in question. The code has been created upon many trial and error
iterations.
Motivation
==========
The primary motivation creating the code is the comfort of using the security
system - the mobile applications provided by the vendor, called "Carener", is
slow and crashes sometimes. Instead, it would be awesome to have the system
integrated into larger ecosystems, like Home Assistant, HomeKit and such.
Hence, the code has been created to interact with the security system using
Python, and it opens up a way for further integrations.
Supported hardware
==================
It mightn't possible to list every system supported by the package due to
manufacturers name the products differently. Here is the list of hardware
known to work with the package:
* `PST G90B Plus <http://www.cameralarms.com/products/auto_dial_alarm_system/185.html>`_
And the list of sensors, actual set of device should be notable larger as many
of other manufacturers produce similar items. The names in parenthesis are
taken from the alarm system documentation, for example, `Home Alarm GB90-Plus <https://archive.org/details/HomeAlarmGB90-Plus/G90B%20plus%20WIFIGSMGPRS%20alarm%20system%20user%20manual/page/n7/mode/2up>`_.
* Wired PIR sensors
* Wireless PIR sensors (WPD01, WMS08)
* Door/window sensors (WDS07, WRDS01)
* Water leak sensors (LSTC01)
* Smoke sensors (WSD02)
* Gas sensors (WGD01)
* Switches/relays (JDQ)
Basically, the alarm system uses 433 MHz communications for the wireless
devices using EV1527, PT2262 protocols. The mobile application also mentions
some devices using 2.4GHz, although details of the protocols haven't been
identified as no such hardware has been available for experimentation.
Known caveats
=============
* Wireless shutter sensor (WRDS01) doesn't send anything on sensor closed, only
when opened. In contrast, WDS07 wireless door sensor does both.
* Wireless relays (at least JDQ) use same RF code for switching on and off,
when configured in toggle mode. That means a RF signal repeater will make
controlling such relays unpredictable, since the code will be sent more than
once.
* Low battery notifications for wireless sensors (at least for WDS07 and WSD02)
are often missing, either due to the sensors not sending them or the device
doesn't receive those.
* Wired sensors toggle on line state change, i.e. those aren't limited to have
normal closed (NC) or normal open (NO) contacts only. Best used with NC
contact sensors though, since an intruder cutting the line will trigger the
alarm.
Enabling 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.
Please see
`protocol documentation <https://pyg90alarm.readthedocs.io/en/stable/protocol.html>`_
for further details on the device notifications.
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
reservation. Please check the documentation of your networking gear on how to
set the IP address allocation up.
.. note:: Since the IP address trick above isn't something the device exposes
to the user, the functionality might change or even cease functioning upon a
firmware upgrade!
.. note:: The device notifications in question are fully local with no
dependency on the cloud or Internet connection on the device.
.. note:: If IP address trick doesn't work for you by a reason, the package
will still be able to perform the key functions - for example, arming or
disarming the panel, or reading the list of sensors. However, the sensor
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
===========
.. code:: shell
pip install pyg90alarm
Documentation
=============
Please see `online documentation <https://pyg90alarm.readthedocs.io>`_ for
details on the protocol, its security, supported commands and the API package
provides.
Raw data
{
"_id": null,
"home_page": "https://github.com/hostcc/pyg90alarm",
"name": "pyg90alarm",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "g90, alarm, protocol",
"author": "Ilia Sotnikov",
"author_email": "hostcc@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a6/d4/a091626db8214ef5c6958b819a6d5d5be55c4848cbac0b6fd0e20c620ac7/pyg90alarm-1.17.1.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/hostcc/pyg90alarm/actions/workflows/main.yml/badge.svg?branch=master\n :target: https://github.com/hostcc/pyg90alarm/tree/master\n :alt: Github workflow status\n.. image:: https://readthedocs.org/projects/pyg90alarm/badge/?version=stable\n :target: https://pyg90alarm.readthedocs.io/en/stable\n :alt: ReadTheDocs status\n.. image:: https://img.shields.io/github/v/release/hostcc/pyg90alarm\n :target: https://github.com/hostcc/pyg90alarm/releases/latest\n :alt: Latest GitHub release\n.. image:: https://img.shields.io/pypi/v/pyg90alarm\n :target: https://pypi.org/project/pyg90alarm/\n :alt: Latest PyPI version\n\nDescription\n===========\n\nPython package to control G90-based alarm systems.\n\nMany manufacturers sell such systems under different brands - Golden Security,\nPST, Kerui and others. Those are cheap low-end systems, typically equipped with\nWiFi and possible GSM interfaces for connectivity, and support different range\nof peripherals:\n\n* Wired and wireless sensors\n* Relays (switches)\n\n... and probably others\n\nThe package implements asynchronous I/O over most of code paths using\n`asyncio <https://docs.python.org/3/library/asyncio.html>`_.\n\nDisclaimer\n==========\n\nThe author has no affiliation or any relationship to any of the hardware\nvendors in question. The code has been created upon many trial and error\niterations.\n\nMotivation\n==========\n\nThe primary motivation creating the code is the comfort of using the security\nsystem - the mobile applications provided by the vendor, called \"Carener\", is\nslow and crashes sometimes. Instead, it would be awesome to have the system\nintegrated into larger ecosystems, like Home Assistant, HomeKit and such.\nHence, the code has been created to interact with the security system using\nPython, and it opens up a way for further integrations.\n\nSupported hardware\n==================\n\nIt mightn't possible to list every system supported by the package due to\nmanufacturers name the products differently. Here is the list of hardware\nknown to work with the package:\n\n* `PST G90B Plus <http://www.cameralarms.com/products/auto_dial_alarm_system/185.html>`_\n\nAnd the list of sensors, actual set of device should be notable larger as many\nof other manufacturers produce similar items. The names in parenthesis are\ntaken from the alarm system documentation, for example, `Home Alarm GB90-Plus <https://archive.org/details/HomeAlarmGB90-Plus/G90B%20plus%20WIFIGSMGPRS%20alarm%20system%20user%20manual/page/n7/mode/2up>`_.\n\n* Wired PIR sensors\n* Wireless PIR sensors (WPD01, WMS08)\n* Door/window sensors (WDS07, WRDS01)\n* Water leak sensors (LSTC01)\n* Smoke sensors (WSD02)\n* Gas sensors (WGD01)\n* Switches/relays (JDQ)\n\nBasically, the alarm system uses 433 MHz communications for the wireless\ndevices using EV1527, PT2262 protocols. The mobile application also mentions\nsome devices using 2.4GHz, although details of the protocols haven't been\nidentified as no such hardware has been available for experimentation.\n\nKnown caveats\n=============\n\n* Wireless shutter sensor (WRDS01) doesn't send anything on sensor closed, only\n when opened. In contrast, WDS07 wireless door sensor does both.\n* Wireless relays (at least JDQ) use same RF code for switching on and off,\n when configured in toggle mode. That means a RF signal repeater will make\n controlling such relays unpredictable, since the code will be sent more than\n once.\n* Low battery notifications for wireless sensors (at least for WDS07 and WSD02)\n are often missing, either due to the sensors not sending them or the device\n doesn't receive those.\n* Wired sensors toggle on line state change, i.e. those aren't limited to have\n normal closed (NC) or normal open (NO) contacts only. Best used with NC\n contact sensors though, since an intruder cutting the line will trigger the\n alarm.\n\nEnabling device notifications\n=============================\n\nThere is a hidden device capability to send protocol notifications over the\nWiFi interface. The notifications are done using broadcast UDP packets with\nsource/destination ports being ``45000:12901`` (non-configurable), and sent when\nthe device has IP address of its WiFi interface set to ``10.10.10.250``. That is\nthe same IP the device will allocate to the WiFi interface when AP (access\npoint is enabled). Please note enabling the AP *is not* required for the\nnotifications to be sent, only the IP address matters. Likely the firmware does\na check internally and enables those when corresponding IP address is found on\nthe WiFi interface.\n\nPlease see\n`protocol documentation <https://pyg90alarm.readthedocs.io/en/stable/protocol.html>`_\nfor further details on the device notifications.\n\nDepending on your network setup, ensuring the `10.10.10.250` IP address is\nallocated to the WiFi interface of the device might be as simple as DHCP\nreservation. Please check the documentation of your networking gear on how to\nset the IP address allocation up.\n\n.. note:: Since the IP address trick above isn't something the device exposes\n to the user, the functionality might change or even cease functioning upon a\n firmware upgrade!\n\n.. note:: The device notifications in question are fully local with no\n dependency on the cloud or Internet connection on the device.\n\n.. note:: If IP address trick doesn't work for you by a reason, the package\n will still be able to perform the key functions - for example, arming or\n disarming the panel, or reading the list of sensors. However, the sensor\n status will not be reflected and those will always be reported as inactive,\n since there is no way to read their state in a polled manner.\n\n To work that limitation around the package now supports simulating device\n notifications from periodically polling the history it records - the\n simulation works only for the alerts, not notifications (e.g. notifications\n include low battery events and alike). This also requires the particular\n alert to be enabled in the mobile application, otherwise it won't be\n recorded in the history.\n\nQuick start\n===========\n\n.. code:: shell\n\n pip install pyg90alarm\n\nDocumentation\n=============\n\nPlease see `online documentation <https://pyg90alarm.readthedocs.io>`_ for\ndetails on the protocol, its security, supported commands and the API package\nprovides.\n",
"bugtrack_url": null,
"license": null,
"summary": "G90 Alarm system protocol",
"version": "1.17.1",
"project_urls": {
"Bug Reports": "https://github.com/hostcc/pyg90alarm/issues",
"Homepage": "https://github.com/hostcc/pyg90alarm",
"Source": "https://github.com/hostcc/pyg90alarm/"
},
"split_keywords": [
"g90",
" alarm",
" protocol"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4d3a64b80a57574d9c432ac0da50e19b157343f83b38fcefc33a4c740d6997e8",
"md5": "ef384e40ce3b4cb96b7fe2842c32973d",
"sha256": "dc5b9fbba96b708452ae739f754add366dddb3d7577e789307d98f705211943b"
},
"downloads": -1,
"filename": "pyg90alarm-1.17.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ef384e40ce3b4cb96b7fe2842c32973d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 53558,
"upload_time": "2024-12-17T19:41:22",
"upload_time_iso_8601": "2024-12-17T19:41:22.217171Z",
"url": "https://files.pythonhosted.org/packages/4d/3a/64b80a57574d9c432ac0da50e19b157343f83b38fcefc33a4c740d6997e8/pyg90alarm-1.17.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a6d4a091626db8214ef5c6958b819a6d5d5be55c4848cbac0b6fd0e20c620ac7",
"md5": "c761e07d6b5274262c7a366bfe867d06",
"sha256": "ca9b55316e76c09150ad98bb778c23fade98731900d86951dcce7038fdd4b176"
},
"downloads": -1,
"filename": "pyg90alarm-1.17.1.tar.gz",
"has_sig": false,
"md5_digest": "c761e07d6b5274262c7a366bfe867d06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 58297,
"upload_time": "2024-12-17T19:41:23",
"upload_time_iso_8601": "2024-12-17T19:41:23.584525Z",
"url": "https://files.pythonhosted.org/packages/a6/d4/a091626db8214ef5c6958b819a6d5d5be55c4848cbac0b6fd0e20c620ac7/pyg90alarm-1.17.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 19:41:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hostcc",
"github_project": "pyg90alarm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pyg90alarm"
}
JSON
