# UltraSync Python Tool
This tool is designed to allow 'API' access through a CLI wrapper to several types of alarm system IP modules that utilise the UltraSync+ mobile app. These modules are generally found in or can be added to systems produced by the below vendors:
- Hills Ltd (Business defunct in 2023, now operating as Aritech (a division of Kidde Global Solutions))
- United Technologies Corporation (Alarm division defunct in 2021)
The tool can be leveraged by other scripts/integrations such as [HA UltraSync](https://github.com/caronc/ha-ultrasync) for integration into Home Automation systems.
# Compatibility
The tool is written to be compatible with the [Hills/Aritech](https://aritech.com.au/) NX-595E ComNav, [Interlogix](https://www.interlogix.com/index.html) xGen/xGen8 (such as NXG-8-Z-BO), and [ZeroWire](https://www.interlogix.com/index.html) UltraSync-based alarm solutions. It is possible that more systems are supported that utilise the UltraSync+ app and share similar code structure, however any not explicitly listed here are untested by the code author/contributors.
**Note**:
ComNav modules runinng firmware version P004000-12 and above disable access to programming menus for cybersecurity reasons. To enable programming menus permanently, turn on Feature Location 19 Option 6. With programming menus disabled, users will only be allowed access through remote/online login (over the internet). Compatibility for remote login cannot be added to this tool due to there being no public API available, and no official vendor support for this method outside of the UltraSync+ mobile app. Later model Aritech Reliance XR series alarm systems include a built-in IP module that allows local network access as it is not affected by the same vulnerabilities.
[**ComNav Product Security Advisory**](https://www.corporate.carrier.com/Images/CARR-PSA-Hills-ComNav-002-1121_tcm558-149392.pdf)
As the original manufacturer(s) are mostly defunct, new software development is generally not expected at the vendor level. Newer Aritech ATS alarm systems utilise the Advisor Advanced Pro mobile app instead of UltraSync+ and are unlikely to be supported by this tool.
*UltraSync Hub*
[](https://paypal.me/lead2gold?locale.x=en_US)
[](https://twitter.com/l2gnux/)<br/>
[](https://pypi.org/project/ultrasync/)
[](https://github.com/caronc/ultrasync/actions/workflows/tests.yml)
[](https://codecov.io/github/caronc/ultrasync)
[](https://pypi.org/project/ultrasync/)
## How Does It Work?
1. First you need to install it; this part is easy:
```bash
# Install ultrasync onto your system
pip install ultrasync
```
2. Create a configuration file that identifies:
1. The hostname or IP address of the alarm system on your local network.
1. Your alarm system login User ID (case-sensitive)
1. Your alarm system login pin.
**Note**: You can generally only be logged into the alarm system with the same user *once*; a subsequent login with the same user logs out the other. Since this tool actively polls and maintains a login session to your system, it can prevent you from being able to log into at the same time elsewhere (via it's website). **It is strongly recommended that you create a second user account on your system dedicated to just this service.**
```yaml
# An example of what would be found in your configuration file:
# Use hashtags/pound symbols (#) to optionally add comments
# Syntax is simply <key>: <value>
#
# For local network login you must specify an ip/hostname, user, and pin
#
host: 192.168.0.30
user: My Username (case-sensitive)
pin: 1234
```
3. Use the **--scene** (**-s**) to set your security system's alarm scene. The possible options are: `disarm`, `away`, `stay`, `fire`, `medical`, and `panic`. The latter 3 are only available for NX-595E currently.
```bash
# By default if no --config= (-c) is specified, one will be automatically
# loaded from the following location (if present):
# ~/.ultrasync
# ~/.config/ultrasync
# Windows users can store their default configuration files here:
# %APPDATA%/UltraSync/config
# %LOCALAPPDATA%/UltraSync/config
# Disarm your security system
ultrasync --scene disarm
# Arm your security system and activate all of your sensors when setting the
# away mode macro
ultrasync --scene away
# Arm your security system and only activate your perimeter sensors:
ultrasync --scene stay
# Trigger the fire alarm (ComNav Only):
ultrasync --scene fire
# Trigger the medical alarm (ComNav Only):
ultrasync --scene medical
# Trigger the panic alarm (ComNav Only):
ultrasync --scene panic
```
## What Else Can It Do?
- You can put up a live monitor of your device by typing the following:
```bash
# A live monitoring of your home security system:
ultrasync --watch
```
- You can generate a snapshot (in JSON format) that greatly details everything taking place through your security home setup. It provides MUCH greater detail than the `--watch` which allows it to also be integrated with [Home Assistant](https://www.home-assistant.io/integrations/ultrasync/).
```bash
# Print a JSON formatted snapshot of all home security details
ultrasync --details
```
- You can perform a dump of all of the web based files (*that I've found to be useful so far*) to disk. This makes troubleshooting much easier.
```bash
# Extracts information from your system that can be
# incredibly useful in debugging and/or adding enhancements
# later on:
ultrasync --debug-dump
```
The debug content gets written to a zip file (residing in the same folder you ran this command from) in the form of: `YYYYmmddHHMMSS.ultrasync-dump.zip`.
## Reverse Proxy
If you've exposed your panel to the internet, you can access it by setting your `host` to the full URL to it (instead of just the hosthame/ip). For example:
```yaml
# A sample UltraSync configuration that requires you to pass through
# a proxy in order to get to your destination:
host: https://your.security.panel/
user: My Username
pin: 1234
```
If you've also protected your panel behind an additional user/pass combo using *Basic Auth* at the reverse proxy level, you can pass through it like so:
```yaml
# A sample ultrasync configuration that requires you to pass through
# a proxy expecting authentication in order to get to your destination:
host: https://user:pass@your.security.panel/
user: My Username
pin: 1234
# You can also optionally turn off the secure hostname verification
# by using the verify switch. But default this is set to yes if not
# specified:
verify: no
```
## Global Variables
You can also (optionally) set the following global variables to provide the equivalent of what the configuration file could have. If a configuration file is also loaded, it's settings will always prevail. If an entry is missing, then the environment variable is used instead (if it's defined):
| Global Variable | Description |
| --- | --- |
| **ULTRASYNC_PIN** | Provides the `pin` variable to the library
| **ULTRASYNC_USER** | Provides the `user` variable to the library
| **ULTRASYNC_HOST** | Provides the `host` variable to the library
| **ULTRASYNC_SSL_VERIFY** | Provides the `verify` variable to the library (optional, defaults to yes if not set)
## Disclaimer
This tool was created through reverse engineering and has been expanded through crowdsourced data. All of this code was generated through trial and error since there is no official documentation available that explains the registers. If you can help out by filling in some of the blanks throughout the code base, I would be greatly appreciative of it! Alternatively [buying me a coffee](https://paypal.me/lead2gold?locale.x=en_US) greatly inspires me to continue improving the application.
Raw data
{
"_id": null,
"home_page": "https://github.com/caronc/ultrasync",
"name": "ultrasync",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "XGen XGen8 Hills Aritech ComNav Interlogix UltraSync NX-595E ZeroWire Security Panel",
"author": "Chris Caron",
"author_email": "lead2gold@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9a/53/6d217aab4ab68ab7c63bee97cc9a7fcb32625dc669731d79ce2ce13dcd79/ultrasync-1.0.3.tar.gz",
"platform": null,
"description": "# UltraSync Python Tool\n\nThis tool is designed to allow 'API' access through a CLI wrapper to several types of alarm system IP modules that utilise the UltraSync+ mobile app. These modules are generally found in or can be added to systems produced by the below vendors:\n - Hills Ltd (Business defunct in 2023, now operating as Aritech (a division of Kidde Global Solutions))\n - United Technologies Corporation (Alarm division defunct in 2021)\n\nThe tool can be leveraged by other scripts/integrations such as [HA UltraSync](https://github.com/caronc/ha-ultrasync) for integration into Home Automation systems.\n\n# Compatibility\n\nThe tool is written to be compatible with the [Hills/Aritech](https://aritech.com.au/) NX-595E ComNav, [Interlogix](https://www.interlogix.com/index.html) xGen/xGen8 (such as NXG-8-Z-BO), and [ZeroWire](https://www.interlogix.com/index.html) UltraSync-based alarm solutions. It is possible that more systems are supported that utilise the UltraSync+ app and share similar code structure, however any not explicitly listed here are untested by the code author/contributors.\n\n**Note**:\nComNav modules runinng firmware version P004000-12 and above disable access to programming menus for cybersecurity reasons. To enable programming menus permanently, turn on Feature Location 19 Option 6. With programming menus disabled, users will only be allowed access through remote/online login (over the internet). Compatibility for remote login cannot be added to this tool due to there being no public API available, and no official vendor support for this method outside of the UltraSync+ mobile app. Later model Aritech Reliance XR series alarm systems include a built-in IP module that allows local network access as it is not affected by the same vulnerabilities.\n\n[**ComNav Product Security Advisory**](https://www.corporate.carrier.com/Images/CARR-PSA-Hills-ComNav-002-1121_tcm558-149392.pdf)\n\nAs the original manufacturer(s) are mostly defunct, new software development is generally not expected at the vendor level. Newer Aritech ATS alarm systems utilise the Advisor Advanced Pro mobile app instead of UltraSync+ and are unlikely to be supported by this tool.\n\n*UltraSync Hub*\n![ZeroWire Hub Image](https://raw.githubusercontent.com/caronc/ultrasync/master/static/zerowire_hub.jpeg \"UltraSync Hub\")\n\n[](https://paypal.me/lead2gold?locale.x=en_US)\n[](https://twitter.com/l2gnux/)<br/>\n[](https://pypi.org/project/ultrasync/)\n[](https://github.com/caronc/ultrasync/actions/workflows/tests.yml)\n[](https://codecov.io/github/caronc/ultrasync)\n[](https://pypi.org/project/ultrasync/)\n\n## How Does It Work?\n\n1. First you need to install it; this part is easy:\n\n ```bash\n # Install ultrasync onto your system\n pip install ultrasync\n ```\n\n2. Create a configuration file that identifies:\n 1. The hostname or IP address of the alarm system on your local network.\n 1. Your alarm system login User ID (case-sensitive)\n 1. Your alarm system login pin.\n\n **Note**: You can generally only be logged into the alarm system with the same user *once*; a subsequent login with the same user logs out the other. Since this tool actively polls and maintains a login session to your system, it can prevent you from being able to log into at the same time elsewhere (via it's website). **It is strongly recommended that you create a second user account on your system dedicated to just this service.**\n\n ```yaml\n # An example of what would be found in your configuration file:\n # Use hashtags/pound symbols (#) to optionally add comments\n # Syntax is simply <key>: <value>\n #\n # For local network login you must specify an ip/hostname, user, and pin\n #\n host: 192.168.0.30\n user: My Username (case-sensitive)\n pin: 1234\n ```\n\n3. Use the **--scene** (**-s**) to set your security system's alarm scene. The possible options are: `disarm`, `away`, `stay`, `fire`, `medical`, and `panic`. The latter 3 are only available for NX-595E currently.\n\n ```bash\n # By default if no --config= (-c) is specified, one will be automatically\n # loaded from the following location (if present):\n # ~/.ultrasync\n # ~/.config/ultrasync\n\n # Windows users can store their default configuration files here:\n # %APPDATA%/UltraSync/config\n # %LOCALAPPDATA%/UltraSync/config\n\n # Disarm your security system\n ultrasync --scene disarm\n\n # Arm your security system and activate all of your sensors when setting the\n # away mode macro\n ultrasync --scene away\n\n # Arm your security system and only activate your perimeter sensors:\n ultrasync --scene stay\n \n # Trigger the fire alarm (ComNav Only):\n ultrasync --scene fire\n \n # Trigger the medical alarm (ComNav Only):\n ultrasync --scene medical\n \n # Trigger the panic alarm (ComNav Only):\n ultrasync --scene panic\n ```\n\n## What Else Can It Do?\n\n- You can put up a live monitor of your device by typing the following:\n\n ```bash\n # A live monitoring of your home security system:\n ultrasync --watch\n ```\n\n\n- You can generate a snapshot (in JSON format) that greatly details everything taking place through your security home setup. It provides MUCH greater detail than the `--watch` which allows it to also be integrated with [Home Assistant](https://www.home-assistant.io/integrations/ultrasync/).\n\n ```bash\n # Print a JSON formatted snapshot of all home security details\n ultrasync --details\n ```\n\n- You can perform a dump of all of the web based files (*that I've found to be useful so far*) to disk. This makes troubleshooting much easier.\n\n ```bash\n # Extracts information from your system that can be\n # incredibly useful in debugging and/or adding enhancements\n # later on:\n ultrasync --debug-dump\n ```\n\n The debug content gets written to a zip file (residing in the same folder you ran this command from) in the form of: `YYYYmmddHHMMSS.ultrasync-dump.zip`.\n\n## Reverse Proxy\n\nIf you've exposed your panel to the internet, you can access it by setting your `host` to the full URL to it (instead of just the hosthame/ip). For example:\n\n```yaml\n# A sample UltraSync configuration that requires you to pass through\n# a proxy in order to get to your destination:\nhost: https://your.security.panel/\nuser: My Username\npin: 1234\n```\n\nIf you've also protected your panel behind an additional user/pass combo using *Basic Auth* at the reverse proxy level, you can pass through it like so:\n\n```yaml\n# A sample ultrasync configuration that requires you to pass through\n# a proxy expecting authentication in order to get to your destination:\nhost: https://user:pass@your.security.panel/\nuser: My Username\npin: 1234\n# You can also optionally turn off the secure hostname verification\n# by using the verify switch. But default this is set to yes if not\n# specified:\nverify: no\n```\n\n## Global Variables\n\nYou can also (optionally) set the following global variables to provide the equivalent of what the configuration file could have. If a configuration file is also loaded, it's settings will always prevail. If an entry is missing, then the environment variable is used instead (if it's defined):\n\n| Global Variable | Description |\n| --- | --- |\n| **ULTRASYNC_PIN** | Provides the `pin` variable to the library\n| **ULTRASYNC_USER** | Provides the `user` variable to the library\n| **ULTRASYNC_HOST** | Provides the `host` variable to the library\n| **ULTRASYNC_SSL_VERIFY** | Provides the `verify` variable to the library (optional, defaults to yes if not set)\n\n## Disclaimer\n\nThis tool was created through reverse engineering and has been expanded through crowdsourced data. All of this code was generated through trial and error since there is no official documentation available that explains the registers. If you can help out by filling in some of the blanks throughout the code base, I would be greatly appreciative of it! Alternatively [buying me a coffee](https://paypal.me/lead2gold?locale.x=en_US) greatly inspires me to continue improving the application.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Wrapper to XGen/XGen8/ComNav/Hills/Interlogix NX-595E/UltraSync ZeroWire",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/caronc/ultrasync"
},
"split_keywords": [
"xgen",
"xgen8",
"hills",
"aritech",
"comnav",
"interlogix",
"ultrasync",
"nx-595e",
"zerowire",
"security",
"panel"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3363af8a89d0748f8fd78ca3a62f7506a20abeef51f846d7a33bf179b593d624",
"md5": "033f218687246918d6d57ee9783917b9",
"sha256": "23e7825b74ad4b0036c26bf3d55b89e0a4c8bed78683a59205a80a0de7b1a6f4"
},
"downloads": -1,
"filename": "ultrasync-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "033f218687246918d6d57ee9783917b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 31725,
"upload_time": "2025-09-06T19:10:51",
"upload_time_iso_8601": "2025-09-06T19:10:51.536560Z",
"url": "https://files.pythonhosted.org/packages/33/63/af8a89d0748f8fd78ca3a62f7506a20abeef51f846d7a33bf179b593d624/ultrasync-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9a536d217aab4ab68ab7c63bee97cc9a7fcb32625dc669731d79ce2ce13dcd79",
"md5": "1aebf3b9a07813a375fd50d1a415d89f",
"sha256": "d32ddc798fda99a1db569a903a1f378f4efcd770af4488d4784841871f6eaf26"
},
"downloads": -1,
"filename": "ultrasync-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "1aebf3b9a07813a375fd50d1a415d89f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 85972,
"upload_time": "2025-09-06T19:10:52",
"upload_time_iso_8601": "2025-09-06T19:10:52.879289Z",
"url": "https://files.pythonhosted.org/packages/9a/53/6d217aab4ab68ab7c63bee97cc9a7fcb32625dc669731d79ce2ce13dcd79/ultrasync-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 19:10:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caronc",
"github_project": "ultrasync",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": []
},
{
"name": "requests",
"specs": []
}
],
"tox": true,
"lcname": "ultrasync"
}
JSON
