| Name | qolsys JSON |
| Version |
1.6.0
JSON |
| download |
| home_page | None |
| Summary | Qolsys IQ Panel 2+ gateway API |
| upload_time | 2024-09-09 03:34:41 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2021 Raphaël Beamonte <raphael.beamonte@gmail.com>
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. |
| keywords |
api
gateway
iq panel
qolsys
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Qolsys Gateway - `qolsysgw`
[](https://github.com/XaF/qolsysgw/releases)
Qolsys Gateway (`qolsysgw`) is an [AppDaemon][appdaemon]
automation that serves as a gateway between a Qolsys IQ Panel
([2][qolsys-panel-2], [2+][qolsys-panel-2-plus] or [4][qolsys-panel-4])
and [Home Assistant][hass]. Qolsys Gateway works by establishing a connection
to your Qolsys Panel and uses the [MQTT integration of Home Assistant][hass-mqtt].
It takes advantages of the [MQTT discovery][hass-mqtt-discovery]
feature (automatically enabled when you setup the integration) to declare the
device, alarm control panels (for each partition) and different sensors, and
keep them up to date with the information coming from the panel, while
providing you with the means to arm, disarm or trigger your alarm directly
from Home Assistant, manually or through automations.
- [How It Works](#how-it-works)
- [Requirements](#requirements)
- [Installation](#installation)
- [Installing Home Assistant](#installing-home-assistant)
- [Installing an MQTT Broker](#installing-an-mqtt-broker)
- [Installing AppDaemon](#installing-appdaemon)
- [Installing HACS (optional, recommended)](#installing-hacs-optional-recommended)
- [Installing Qolsys Gateway](#installing-qolsys-gateway)
- [With HACS (recommended)](#with-hacs-recommended)
- [Manually](#manually)
- [Configuration](#configuration)
- [Configuring the MQTT integration in Home Assistant](#configuring-the-mqtt-integration-in-home-assistant)
- [Configuring your Qolsys IQ Panel](#configuring-your-qolsys-iq-panel)
- [Configuring Qolsys Gateway](#configuring-qolsys-gateway)
- [Required configuration](#required-configuration)
- [Optional configuration related to the Qolsys Panel itself](#optional-configuration-related-to-the-qolsys-panel-itself)
- [Optional configuration related to the representation of the panel in Home Assistant](#optional-configuration-related-to-the-representation-of-the-panel-in-home-assistant)
- [Optional configuration related to MQTT & AppDaemon](#optional-configuration-related-to-mqtt--appdaemon)
- [Other documentation](#other-documentation)
- [Acknowledgements and thanks](#acknowledgements-and-thanks)
## How It Works
Qolsys Gateway is an [async application][asyncio] and has a few parallel
workflows:
1. The communication with the Qolsys Panel
1. Qolsys Gateway connects to your Qolsys Panel using the configured
information (hostname, token, port), thanks to a Control4 interface
2. As soon as the connection is established, Qolsys Gateway requests
from the panel the information on the current state of the panel,
its partitions and sensors
3. Qolsys Gateway listens for messages from the panel, and calls a
callback method everytime a message can be parsed to an executable
action; the callback will push that message in an MQTT thread _(that
step is not mandatory but doing that loop allows to debug the
application from Home Assistant by sending events directly in MQTT)_
4. Every 4 minutes, a keep-alive message is sent to the connection,
in order to avoid the panel from disconnecting Qolsys Gateway
2. The communications with MQTT
1. Qolsys Gateway listens to an `event` topic, when a message is received,
we update the state of the panel according to the event (it can be
updating the sensors, the partitions or the panel itself). Messages in
that topic are the messages that come from the Qolsys Panel, and that
we intepret as change to the state of the panel. In general, with the
update, we will trigger a few MQTT messages to be sent to update the
status of the element at the source of the event in Home Assistant.
2. Qolsys Gateway also listens to a `control` topic, when a message is
received, we communicate the action to perform to the Qolsys Panel.
Messages in that topic are coming from Home Assistant as reactions
to service calls on the `alarm_control_panel` entities, or of manually
configured actions. They can be used to arm or disarm the system,
or even to trigger the alarm on the device.
## Requirements
- A Qolsys IQ Panel 2 or 2+ (software version 2.5.3 or greater), or 4
(software version 4.1 or greater),
for which you have the **dealer code** (defaults to `2222`). In some cases,
the _installer code_ (defaults to `1111`) might be sufficient, but in my
experience, it was not, as the required menus were not visible.
- Understanding that this automation is not part of the core of Home Assistant
and is thus not officially supported by Home Assistant. By using it, you
agree that neither Home Assistant nor myself are responsible for any issues
with your Home Assistant configuration, loss of data, or whatever could be
caused by using Qolsys Gateway. Setting up Qolsys Gateway requires enabling
the Control4 protocol on your Qolsys Panel, which may open to security issues
and someone taking over control of your alarm system, so please be aware of
what you are doing, and only do it if you are ready to take those risks.
## Installation
Installing Qolsys Gateway requires the following steps.
### Installing Home Assistant
You can get to the [Home Assistant documentation for installation][hass-install]
page in order to setup Home Assistant for your needs.
### Installing an MQTT Broker
You will require a working MQTT broker alongside your Home Assistant
installation. Home Assistant provides [documentation on how to install
and configure an MQTT broker][hass-mqtt-broker].
If you wish to use MQTT through a docker deployment, you can use the
[`eclipse-mosquitto` docker image][mqtt-docker].
If you can, setup a username and password to secure your broker even more.
### Installing AppDaemon
Qolsys Gateway is an AppDaemon automation, which means it depends on a
working and running version of AppDaemon, connected to your Home Assistant.
You can find all the resources necessary in AppDaemon's documentation about
how to [install AppDaemon][appdaemon-install] and how to
[configure it with the HASS plugin][appdaemon-hass-plugin] for communicating
with Home Assistant, and [with the MQTT plugin][appdaemon-mqtt-plugin]
for communicating with your MQTT broker.
If you wish to use AppDaemon through a docker deployment, you can use the
[`acockburn/appdaemon` docker image][appdaemon-docker].
<details><summary>See an example of <code>appdaemon.yaml</code></summary>
```yaml
appdaemon:
time_zone: "America/New_York" # Adapt this to your actual timezone
# All three of those might be already filled for you, or you set the
# values here, or use the secrets.yaml file to setup the values
latitude: !secret latitude
longitude: !secret longitude
elevation: !secret elevation
plugins:
# If using the add-on in Home Assistant, that plugin will already be
# enabled; when using the docker container, you will have to add it here
HASS:
type: hass
ha_url: "http://homeassistant:8123"
token: !secret ha_token # The token you get from home assistant
# And we need to add the MQTT plugin
MQTT:
type: mqtt
namespace: mqtt # We will need that same value in the apps.yaml configuration
client_host: mosquitto # The IP address or hostname of the MQTT broker
client_port: 1883 # The port of the MQTT broker, generally 1883
# Only if you have setup an authenticated connection, otherwise skip those:
client_user: appdaemon # The username
client_password: !secret mqtt_password # The password
```
</details>
### Installing HACS (optional, recommended)
HACS is the Home Assistant Community Store and allows for community integrations and
automations to be updated cleanly and easily from the Home Assistant web user interface.
If it is simple to install Qolsys Gateway without HACS, keeping up to date requires
manual steps that HACS will handle for you: you will be notified of updates, and they
can be installed by a click on a button.
If you want to use HACS, you will have to follow [their documentation on how to install HACS][hacs-install].
### Installing Qolsys Gateway
Installing Qolsys Gateway is pretty simple once all the applications above
are setup. You can either follow the path using HACS (a bit more steps initially,
easier on the longer run) or use the manual setup approach.
#### With HACS (recommended)
To install Qolsys Gateway with HACS, you will need to make sure that you enabled
AppDaemon automations in HACS, as these are not enabled by default:
1. Click on `Configuration` on the left menu bar in Home Assistant Web UI
2. Select `Devices & Services`
3. Select `Integrations`
4. Find `HACS` and click on `Configure`
5. In the window that opens, make sure that `Enable AppDaemon apps discovery & tracking`
is checked, or check it and click `Submit`
6. If you just enabled this (or just installed HACS), you might have to wait a few minutes
as all repositories are being fetched; you might hit a GitHub rate limit, which might
then require you to wait a few hours for HACS to be fully configured. In this case,
you won't be able to proceed to the next steps until HACS is ready.
Now, to install Qolsys Gateway with HACS, follow these steps:
1. Click on `HACS` on the left menu bar in Home Assistant Web UI
2. Click on `Automations` in the right panel
3. Click on `Explore & download repositories` in the bottom right corner
4. Search for `qolsysgw`, and click on `Qolsys Gateway` in the list that appears
5. In the bottom right corner of the panel that appears, click on
`Download this repository with HACS`
6. A confirmation panel will appear, click on `Download`, and wait for HACS to
proceed with the download
6. Qolsys Gateway is now installed, and HACS will inform you when updates are available
#### Manually
Installing Qolsys Gateway manually can be summarized by putting the content of the
`apps/` directory of this repository (the `qolsysgw/` directory) into the `apps/`
directory of your AppDaemon installation.
For instance, if your Home Assistant configuration directory is in `/hass/config/`,
you most likely have AppDaemon setup in `/hass/config/appdaemon/`, and you can thus
put `qolsysgw/` into `/hass/config/appdaemon/apps/`.
## Configuration
### Configuring the MQTT integration in Home Assistant
The MQTT integration of Home Assistant needs to be configured with your
MQTT broker in order for Qolsys Gateway to work. If you haven't setup the
MQTT integration yet, you can do so with the following steps:
1. Click on `Configuration` on the left menu bar in Home Assistant Web UI
2. Select `Devices & Services`
3. Select `Integrations`
4. Click on `Add Integration` in the bottom right corner
5. Search for `MQTT`, and click on the MQTT integration
6. Fill in the information as configured for your MQTT broker (hostname,
port, and username and password if setting things up with an
authenticated connection)
7. Click on `Submit`, Home Assistant will try and connect to the MQTT broker,
and the integration will be setup upon success.
### Configuring your Qolsys IQ Panel
If you already have the Control4 token for your Qolsys IQ Panel, you can
skip that step. If you do not understand what that sentence is about, you
definitely need to go through that step.
Qolsys Gateway communicates with your Qolsys Panel using a protocol that
exists for communications with Control4 automation. That protocol is not
enabled on your Qolsys Panel by default, so we will need to enable it and
note the token that will be provided to us.
To enable the feature and get your secure token, you will need to:
1. <details><summary>Connect your Qolsys Panel to your WiFi network (if not already done)</summary>
1. Swipe down from the top menu bar and select `Settings`.
2. Touch `Advanced Settings` and use either the _installer_ code or
the _dealer_ code (you might have access with the main user code, too).
3. Touch `Wi-Fi`.
4. Check the `Enable Wi-Fi` box if not already active.
5. Available networks will appear in a list.
6. Touch the desired network and use the keyboard to type the password (if required).
<p></p>
<p align="center">
<img src="./docs/images/qolsys-connecting-to-wifi.png"
alt="Qolsys documentation to connect to WiFi" width="738" />
</p>
</details>
1. <details><summary>Enable 3rd party connections</summary>
1. Swipe down from the top menu bar and select `Settings`.
2. Touch `Advanced Settings` and use the _dealer_ code (you **might** have
access with the _installer_ code, too).
3. Touch `Installation`.
4. Touch `Devices`.
5. Touch `Wi-Fi Devices`.
6. Touch `3rd Party Connections`.
7. Check the `Control4` box to enable 3rd Party Connections.
8. The panel will reboot in order to apply the change.
9. Come back to the same menu once the reboot is done.
10. Touch `Reveal secure token` and note the token that the panel is
providing you, we will need it to configure Qolsys Gateway.
11. If you ever leak that token, come back to this menu and touch
`Regenerate secure token` in order to make sure that nobody can
get access to control your alarm system.
<p></p>
<p align="center">
<img src="./docs/images/qolsys-3rd-party-connections.png"
alt="Qolsys documentation for 3rd party connections" width="738">
</p>
</details>
### Configuring Qolsys Gateway
Qolsys Gateway needs to be configured in the `apps.yaml` file of AppDaemon.
If your Home Assistant configuration directory is in `/hass/config/`, and
AppDaemon in `/hass/config/appdaemon/`, you will find this file in
`/hass/config/appdaemon/apps/apps.yaml` (next to the `qolsysgw/` directory
we moved here previously).
#### Required configuration
The minimum configuration to use Qolsys Gateway is the following:
```yaml
qolsys_panel:
module: gateway
class: QolsysGateway
panel_host: <qolsys_panel_host_or_ip>
panel_token: <qolsys_secure_token>
```
With:
- **qolsys_panel:** the name of the application for AppDaemon. You can run
multiple instances of Qolsys Gateway, each with a different Qolsys Panel,
if you ever need so. See the configuration options below, specifically
`panel_unique_id`, to be able to configure multiple devices.
- **module**: the main module from which QolsysGateway will be loaded.
This parameter is mandatory and **cannot be changed** as it references
the `qolsysgw/gateway.py` file.
- **class**: the name of the class that will be loaded by AppDaemon for
that automation. This parameter is mandatory and **cannot be changed** as
it references the `QolsysGateway` class in the `qolsysgw/gateway.py` file.
- **panel_host:** the hostname or IP address of your Qolsys Panel, as
connected to your network. That hostname or IP address must, of course, be
accessible from the server running AppDaemon.
- **panel_token:** the secure token we got from enabling Control4 on the
Qolsys Panel.
#### Optional configuration related to the Qolsys Panel itself
- <details><summary><strong>panel_port:</strong> the port to use to connect to your Qolsys Panel with the
Control4 protocol. This is not really configurable on the panel itself,
but available as an option if needed (for instance, for NAT needs).
Defaults to <code>12345</code>.</summary>
```yaml
qolsys_panel:
# ...
panel_port: 4242 # use the port 4242
# ...
```
</details>
- <details><summary><strong>panel_mac:</strong> the mac address of your Qolsys Panel.
This is something you can find from your router, and might allow you to link the
device created in Home Assistant by Qolsys Gateway to other entries related to your
Panel. Not used by default, and Qolsys Gateway will try to resolve the mac address
using ARP - which does not work when using appdaemon in docker, except if using the
host network mode -, or ignore it entirely if not possible.</summary>
```yaml
qolsys_panel:
# ...
panel_mac: aa:bb:cc:dd:11:22
# ...
```
</details>
- <details><summary><strong>panel_user_code:</strong> the code to send to your
Qolsys Panel to disarm your system (and arm when in secure arm mode). This needs
to be a valid user code added to your Qolsys Panel. It is recommended to use a
distinct user code if setup, so you have the ability to roll it as needed.
If unset (or <code>null</code>), you will not be able to disarm your alarm system
without providing a code in Home Assistant.
Defaults to <code>null</code>.</summary>
```yaml
qolsys_panel:
# ...
panel_user_code: 1234 # there is a code '1234' allowing me to disarm my Qolsys Panel
# ...
```
</details>
- <details><summary><strong>arm_away_exit_delay:</strong> the delay to set
when arming away through Qolsys Gateway. Setting the value to
<code>0</code> will instantly arm the alarm system. Setting to
<code>null</code> will let the panel use its default value. Setting
to any other positive value will set that delay. This will not change
the default behavior of the panel when handled manually, simply what
will happen when arming away from Home Assistant through Qolsys Gateway.
<em>Note that if "Auto Stay" is enabled (may be the default in some cases),
an exit delay is configured, and no door is opened or closed
during the delay, the panel will be set to "Arm Stay" instead.</em>
Defaults to <code>null</code>.</summary>
```yaml
qolsys_panel:
# ...
arm_away_exit_delay: 0 # arming instantly when triggered from Home Assistant, since related to automations
# ...
```
</details>
- <details><summary><strong>arm_stay_exit_delay:</strong> the delay to set
when arming stay through Qolsys Gateway. Setting the value to
<code>0</code> will instantly arm the alarm system. Setting to
<code>null</code> will let the panel use its default value. Setting
to any other positive value will set that delay. This will not change
the default behavior of the panel when handled manually, simply what
will happen when arming stay from Home Assistant through Qolsys Gateway.
Defaults to <code>null</code>.</summary>
```yaml
qolsys_panel:
# ...
arm_stay_exit_delay: 10 # arming in 10 seconds when triggered from Home Assistant
# ...
```
</details>
- <details><summary><strong>arm_away_bypass:</strong> whether or not to
bypass sensors that are "open" when arming away through Qolsys Gateway.
Bypassed sensors are then ignored until the next time the panel will
be armed (this means that closing and reopening those sensors after
arming with the bypass will not trigger an alarm).
Setting the value to <code>true</code> will always bypass open sensors
when arming away, while setting it to <code>false</code> will always
disable the bypass. If you have a default behavior for this defined in
your panel, this parameter will override it. Leaving the parameter
unset will leave the panel decide what to do.
Defaults to <code>null</code>.</summary>
```yaml
qolsys_panel:
# ...
arm_away_bypass: true # will bypass the open sensors if any
# ...
```
</details>
- <details><summary><strong>arm_stay_bypass:</strong> whether or not to
bypass sensors that are "open" when arming stay through Qolsys Gateway.
Bypassed sensors are then ignored until the next time the panel will
be armed (this means that closing and reopening those sensors after
arming with the bypass will not trigger an alarm).
Setting the value to <code>true</code> will always bypass open sensors
when arming stay, while setting it to <code>false</code> will always
disable the bypass. If you have a default behavior for this defined in
your panel, this parameter will override it. Leaving the parameter
unset will leave the panel decide what to do.
Defaults to <code>null</code>.</summary>
```yaml
qolsys_panel:
# ...
arm_stay_bypass: false # will NOT bypass the open sensors if any
# ...
```
</details>
- <details><summary><strong>arm_type_custom_bypass:</strong> the type of
arming to use when using <code>ARM_CUSTOM_BYPASS</code> from Home Assistant. This
arming type will automatically enable bypassing the open sensors.
Setting the value to <code>arm_away</code> will lead to the panel being
armed in away mode with bypass enabled when <code>ARM_CUSTOM_BYPASS</code> is used.
Setting the value to <code>arm_stay</code> will lead to the panel being
armed in stay mode.
Defaults to <code>arm_away</code>.</summary>
```yaml
qolsys_panel:
# ...
arm_type_custom_bypass: arm_stay # to arm the panel in stay mode when using the custom bypass arming type
# ...
```
</details>
#### Optional configuration related to the representation of the panel in Home Assistant
- <details><summary><strong>panel_unique_id:</strong> the unique ID of the device
that will be created for the panel in Home Assistant. All the partitions and
sensors unique IDs will be based on that unique ID to, in order to separate cleanly
the potential multiple panels you would setup with Qolsys Gateway.
Defaults to <code>qolsys_panel</code>.</summary>
```yaml
qolsys_panel:
# ...
panel_unique_id: meerkat # there cannot be another device with 'meerkat' as ID, it can help if you want to use Qolsys Gateway for two+ panels
# ...
```
</details>
- <details><summary><strong>panel_device_name:</strong> the name of the device as it
will appear in Home Assistant. Because Qolsys Gateway provides a unique ID for all
its elements, you will be able to change the name in the user interface of Home
Assistant. Even though, this is the name that Qolsys Gateway will advertise for
your panel.
Defaults to <code>Qolsys Panel</code>.</summary>
```yaml
qolsys_panel:
# ...
panel_device_name: Steve # hey, Steve!
# ...
```
</details>
- <details><summary><strong>ha_check_user_code:</strong> whether or not
the check of the user code should be done in the Home Assistant user
interface. If set to <code>false</code>, the code will never be checked
in home assistant even if required for arming, disarming or triggering
the alarm, and will always be sent to Qolsys Gateway for checking. If
set to <code>true</code> and the code is required for one of the actions,
if will be checked by the Home Assistant user interface, and never
sent through the network to Qolsys Gateway (a session token is shared
to Home Assistant by Qolsys Gateway to make sure it is receiving control
messages from the right instance). Note that in case of issues of checking
a code in Qolsys Gateway, things will simply fail silently.
<em>Requires <code>panel_user_code</code> to be set, will silently
revert to <code>false</code> otherwise.</em>
Defaults to <code>true</code>.</summary>
```yaml
qolsys_panel:
# ...
ha_check_user_code: false # we want Qolsys Gateway to receive the code and perform the check
# ...
```
</details>
- <details><summary><strong>ha_user_code:</strong> if you want to use a
different disarm code in Home Assistant than the actual disarm code that
Qolsys Gateway will use with the panel, you can define it here. You can
use numeric codes (will show a numeric pad in Home Assistant's user
interface) or any characters (will show a text box).
If <code>ha_check_user_code</code> is set to <code>true</code>, then
the verification of that code will be done in Home Assistant directly. If
set to <code>false</code>, Qolsys Gateway will use that code to compare
against what Home Assistant will send in the control topic.
<em>Requires <code>panel_user_code</code> to be set, will raise an
error otherwise.</em>
Defaults to <code>null</code>.</summary>
```yaml
qolsys_panel:
# ...
ha_user_code: $up3r$ecre7!! # this will be the code expected from the user
# ...
```
</details>
- <details><summary><strong>code_arm_required:</strong> whether or not
we require to type-in the code to arm the alarm system.
<em>Requires <code>panel_user_code</code> to be set, will raise an
error otherwise as the Qolsys Panel does not require any code to arm
the alarm system, and Qolsys Gateway cannot do that check without a
configured code.</em>
Defaults to <code>false</code>.</summary>
```yaml
qolsys_panel:
# ...
code_arm_required: true
# ...
```
</details>
- <details><summary><strong>code_disarm_required:</strong> whether or not
we require to type-in the code to arm the alarm system.
<em>Will silently be forced to <code>true</code> if
<code>panel_user_code</code> is not set, as Qolsys Gateway will not be
able to disarm the alarm system without a code.</em>
Defaults to <code>false</code>.</summary>
```yaml
qolsys_panel:
# ...
code_disarm_required: true
# ...
```
</details>
- <details><summary><strong>code_trigger_required:</strong> whether or not
we require to type-in the code to trigger the alarm system.
<em>Requires <code>panel_user_code</code> to be set, will raise an
error otherwise as the Qolsys Panel does not require any code to trigger
the alarm system, and Qolsys Gateway cannot do that check without a
configured code.</em>
Defaults to <code>false</code>.</summary>
```yaml
qolsys_panel:
# ...
code_trigger_required: true
# ...
```
</details>
- <details><summary><strong>default_trigger_command:</strong> the trigger
command to use among the <a href="./docs/qolsysgw-control-commands.md">valid
control commands that Qolsys Gateway support</a>.
Defaults to <code>TRIGGER</code>.</summary>
```yaml
qolsys_panel:
# ...
default_trigger_command: TRIGGER_FIRE # if we want to trigger the fire alarm by default
# ...
```
</details>
- <details><summary><strong>default_sensor_device_class:</strong> the sensor
device class to use by default if a Qolsys sensor type is not directly
mapped to a device class in Qolsys Gateway, but is still part of the
identified sensors.
Defaults to <code>safety</code>.</summary>
```yaml
qolsys_panel:
# ...
default_sensor_device_class: null # if we do not want to get a sensor if the device class is not directly mapped
# ...
```
</details>
- <details><summary><strong>enable_static_sensors_by_default:</strong>
whether or not sensors that will not be updated by the panel (e.g. Bluetooth)
should be enabled by default in Home Assistant. Even if setting this to
<code>false</code>, you will have the ability to enable them on a
sensor-by-sensor basis in Home Assistant. If setting it to <code>true</code>,
you will also be able to disable them on a sensor-by-sensor basis in
Home Assistant.
Defaults to <code>false</code>.</summary>
```yaml
qolsys_panel:
# ...
enable_static_sensors_by_default: true
# ...
```
</details>
#### Optional configuration related to MQTT & AppDaemon
- <details><summary><strong>mqtt_namespace:</strong> the MQTT namespace to use to
read and send messages in MQTT. This should be the same as configured in
<code>appdaemon.yaml</code>, so if you did not use <code>mqtt</code>, you will
need to use that option for Qolsys Gateway to work properly.
Defaults to <code>mqtt</code>.</summary>
```yaml
qolsys_panel:
# ...
mqtt_namespace: mqtt-homeassistant # if we used that namespace in appdaemon.yaml
# ...
```
</details>
- <details><summary><strong>mqtt_retain:</strong> whether or not we should set
the retain flag on availability and states messages of the partitions and sensors.
This is interesting as if Home Assistant starts listening to MQTT right after we
sent our status messages and we do not use <code>retain</code>, then Home Assistant
will not know the state. However, using <code>retain</code> means that we need to
handle the cases where AppDaemon is killed, this means that for this option to be
considered, we need the <code>birth_topic</code> and <code>will_topic</code> of
AppDaemon to be the same, so we can consider AppDaemon's availability as an
information of the availability of our partitions and sensors.
Defaults to <code>true</code>.</summary>
```yaml
qolsys_panel:
# ...
mqtt_retain: false # if we do not want to use MQTT retain
# ...
```
</details>
- <details><summary><strong>discovery_topic:</strong> The topic base that Home
Assistant listens to for MQTT discovery. This needs to be the same as the
<code>discovery_prefix</code> configured for the MQTT module in the Home
Assistant configuration, which is <code>homeassistant</code> by default.
Defaults to <code>homeassistant</code>.</summary>
```yaml
qolsys_panel:
# ...
discovery_topic: hass-discovery # if the discovery_prefix was changed to hass-discovery in Home Assistant
# ...
```
</details>
- <details><summary><strong>control_topic:</strong> the topic to use to
receive control commands from Home Assistant. If using <code>{panel_unique_id}</code>
as part of the value, it will be converted to the value as defined by
the <code>panel_unique_id</code> parameter, allowing to automatically
handle multiple instances of Qolsys Gateway for multiple panels, since
you will have to define different unique IDs for each.
Defaults to <code>{discovery_topic}/alarm_control_panel/{panel_unique_id}/set</code>.</summary>
```yaml
qolsys_panel:
# ...
control_topic: panel_{panel_unique_id}/control
# ...
```
</details>
- <details><summary><strong>event_topic:</strong> the topic to use to
write (and also read) the Qolsys Panel events. If using <code>{panel_unique_id}</code>
as part of the value, it will be converted to the value as defined by
the <code>panel_unique_id</code> parameter, allowing to automatically
handle multiple instances of Qolsys Gateway for multiple panels, since
you will have to define different unique IDs for each.
Defaults to <code>qolsys/{panel_unique_id}/event</code>.</summary>
```yaml
qolsys_panel:
# ...
event_topic: panel_{panel_unique_id}/event
# ...
```
</details>
- <details><summary><strong>user_control_token:</strong> a fixed control
token that can be used as an alternative to the session token for control
commands sent to Qolsys Gateway, if you want to trigger control commands
that are not supported by an Home Assistant service. When set to <code>null</code>,
this is simply disabled (only the session token will be considered valid).
Defaults to <code>null</code>.</summary>
```yaml
qolsys_panel:
# ...
user_control_token: My$ecr3tT0k3n!
# ...
```
</details>
## Other documentation
- [The known Qolsys Panel interactions](./docs/qolsys-panel-interactions.md)
- [Qolsys Gateway's control commands](./docs/qolsysgw-control-commands.md)
- [Qolsys Gateway's entities](./docs/qolsysgw-entities.md)
## Acknowledgements and thanks
The initial findings that made this project possible are discussed
[in the community forum of Home Assistant][hass-community-thread], where the
Control4 interface was initially mentioned, as well as a number of the events
and actions that could be used once the connection initiated with the Qolsys
Panel.
The [<code>ad-qolsys</code>][ad-qolsys] project by [@roopesh][roopesh], which I
used before deciding to rewrite the automation from scratch with different
features and a different way to handle events and actions. This project is not
using a line of code of <code>ad-qolsys</code>, but was initially inspired
by it.
<!--
List of links used in that page, sorted alphabetically by tag
-->
[ad-qolsys]: https://github.com/roopesh/ad-qolsys
[appdaemon-docker]: https://hub.docker.com/r/acockburn/appdaemon/
[appdaemon-hass-plugin]: https://appdaemon.readthedocs.io/en/latest/CONFIGURE.html#configuration-of-the-hass-plugin
[appdaemon-install]: https://appdaemon.readthedocs.io/en/latest/INSTALL.html
[appdaemon-mqtt-plugin]: https://appdaemon.readthedocs.io/en/latest/CONFIGURE.html#configuration-of-the-mqtt-plugin
[appdaemon]: https://github.com/AppDaemon/appdaemon
[asyncio]: https://docs.python.org/3/library/asyncio.html
[hacs-install]: https://hacs.xyz/docs/setup/download
[hacs-pr]: https://github.com/hacs/default/pull/1173
[hass-community-thread]: https://community.home-assistant.io/t/qolsys-iq-panel-2-and-3rd-party-integration/231405
[hass-install]: https://www.home-assistant.io/installation/
[hass-mqtt-broker]: https://www.home-assistant.io/docs/mqtt/broker
[hass-mqtt-discovery]: https://www.home-assistant.io/docs/mqtt/discovery/
[hass-mqtt]: https://www.home-assistant.io/integrations/mqtt/
[hass]: https://www.home-assistant.io/
[mqtt-docker]: https://hub.docker.com/_/eclipse-mosquitto
[qolsys-panel-2]: https://qolsys.com/iq-panel-2/
[qolsys-panel-2-plus]: https://qolsys.com/iq-panel-2-plus/
[qolsys-panel-4]: https://qolsys.com/iq-panel-4/
[roopesh]: https://github.com/roopesh
Raw data
{
"_id": null,
"home_page": null,
"name": "qolsys",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "api, gateway, iq panel, qolsys",
"author": null,
"author_email": "Rapha\u00ebl Beamonte <raphael.beamonte@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e9/4c/4b337f036e1cb9e80263ba1cd4e940901ca805c076c963b8693fe0238152/qolsys-1.6.0.tar.gz",
"platform": null,
"description": "# Qolsys Gateway - `qolsysgw`\n\n\n\n[](https://github.com/XaF/qolsysgw/releases)\n\nQolsys Gateway (`qolsysgw`) is an [AppDaemon][appdaemon]\nautomation that serves as a gateway between a Qolsys IQ Panel\n([2][qolsys-panel-2], [2+][qolsys-panel-2-plus] or [4][qolsys-panel-4])\nand [Home Assistant][hass]. Qolsys Gateway works by establishing a connection\nto your Qolsys Panel and uses the [MQTT integration of Home Assistant][hass-mqtt].\nIt takes advantages of the [MQTT discovery][hass-mqtt-discovery]\nfeature (automatically enabled when you setup the integration) to declare the\ndevice, alarm control panels (for each partition) and different sensors, and\nkeep them up to date with the information coming from the panel, while\nproviding you with the means to arm, disarm or trigger your alarm directly\nfrom Home Assistant, manually or through automations.\n\n\n- [How It Works](#how-it-works)\n- [Requirements](#requirements)\n- [Installation](#installation)\n - [Installing Home Assistant](#installing-home-assistant)\n - [Installing an MQTT Broker](#installing-an-mqtt-broker)\n - [Installing AppDaemon](#installing-appdaemon)\n - [Installing HACS (optional, recommended)](#installing-hacs-optional-recommended)\n - [Installing Qolsys Gateway](#installing-qolsys-gateway)\n - [With HACS (recommended)](#with-hacs-recommended)\n - [Manually](#manually)\n- [Configuration](#configuration)\n - [Configuring the MQTT integration in Home Assistant](#configuring-the-mqtt-integration-in-home-assistant)\n - [Configuring your Qolsys IQ Panel](#configuring-your-qolsys-iq-panel)\n - [Configuring Qolsys Gateway](#configuring-qolsys-gateway)\n - [Required configuration](#required-configuration)\n - [Optional configuration related to the Qolsys Panel itself](#optional-configuration-related-to-the-qolsys-panel-itself)\n - [Optional configuration related to the representation of the panel in Home Assistant](#optional-configuration-related-to-the-representation-of-the-panel-in-home-assistant)\n - [Optional configuration related to MQTT & AppDaemon](#optional-configuration-related-to-mqtt--appdaemon)\n- [Other documentation](#other-documentation)\n- [Acknowledgements and thanks](#acknowledgements-and-thanks)\n\n\n## How It Works\n\nQolsys Gateway is an [async application][asyncio] and has a few parallel\nworkflows:\n\n1. The communication with the Qolsys Panel\n\n 1. Qolsys Gateway connects to your Qolsys Panel using the configured\n information (hostname, token, port), thanks to a Control4 interface\n\n 2. As soon as the connection is established, Qolsys Gateway requests\n from the panel the information on the current state of the panel,\n its partitions and sensors\n\n 3. Qolsys Gateway listens for messages from the panel, and calls a\n callback method everytime a message can be parsed to an executable\n action; the callback will push that message in an MQTT thread _(that\n step is not mandatory but doing that loop allows to debug the\n application from Home Assistant by sending events directly in MQTT)_\n\n 4. Every 4 minutes, a keep-alive message is sent to the connection,\n in order to avoid the panel from disconnecting Qolsys Gateway\n\n2. The communications with MQTT\n\n 1. Qolsys Gateway listens to an `event` topic, when a message is received,\n we update the state of the panel according to the event (it can be\n updating the sensors, the partitions or the panel itself). Messages in\n that topic are the messages that come from the Qolsys Panel, and that\n we intepret as change to the state of the panel. In general, with the\n update, we will trigger a few MQTT messages to be sent to update the\n status of the element at the source of the event in Home Assistant.\n\n 2. Qolsys Gateway also listens to a `control` topic, when a message is\n received, we communicate the action to perform to the Qolsys Panel.\n Messages in that topic are coming from Home Assistant as reactions\n to service calls on the `alarm_control_panel` entities, or of manually\n configured actions. They can be used to arm or disarm the system,\n or even to trigger the alarm on the device.\n\n\n## Requirements\n\n- A Qolsys IQ Panel 2 or 2+ (software version 2.5.3 or greater), or 4\n (software version 4.1 or greater),\n for which you have the **dealer code** (defaults to `2222`). In some cases,\n the _installer code_ (defaults to `1111`) might be sufficient, but in my\n experience, it was not, as the required menus were not visible.\n\n- Understanding that this automation is not part of the core of Home Assistant\n and is thus not officially supported by Home Assistant. By using it, you\n agree that neither Home Assistant nor myself are responsible for any issues\n with your Home Assistant configuration, loss of data, or whatever could be\n caused by using Qolsys Gateway. Setting up Qolsys Gateway requires enabling\n the Control4 protocol on your Qolsys Panel, which may open to security issues\n and someone taking over control of your alarm system, so please be aware of\n what you are doing, and only do it if you are ready to take those risks.\n\n\n## Installation\n\nInstalling Qolsys Gateway requires the following steps.\n\n\n### Installing Home Assistant\n\nYou can get to the [Home Assistant documentation for installation][hass-install]\npage in order to setup Home Assistant for your needs.\n\n\n### Installing an MQTT Broker\n\nYou will require a working MQTT broker alongside your Home Assistant\ninstallation. Home Assistant provides [documentation on how to install\nand configure an MQTT broker][hass-mqtt-broker].\nIf you wish to use MQTT through a docker deployment, you can use the\n[`eclipse-mosquitto` docker image][mqtt-docker].\nIf you can, setup a username and password to secure your broker even more.\n\n\n### Installing AppDaemon\n\nQolsys Gateway is an AppDaemon automation, which means it depends on a\nworking and running version of AppDaemon, connected to your Home Assistant.\nYou can find all the resources necessary in AppDaemon's documentation about\nhow to [install AppDaemon][appdaemon-install] and how to\n[configure it with the HASS plugin][appdaemon-hass-plugin] for communicating\nwith Home Assistant, and [with the MQTT plugin][appdaemon-mqtt-plugin]\nfor communicating with your MQTT broker.\n\nIf you wish to use AppDaemon through a docker deployment, you can use the\n[`acockburn/appdaemon` docker image][appdaemon-docker].\n\n<details><summary>See an example of <code>appdaemon.yaml</code></summary>\n\n```yaml\nappdaemon:\n time_zone: \"America/New_York\" # Adapt this to your actual timezone\n\n # All three of those might be already filled for you, or you set the\n # values here, or use the secrets.yaml file to setup the values\n latitude: !secret latitude\n longitude: !secret longitude\n elevation: !secret elevation\n\n plugins:\n # If using the add-on in Home Assistant, that plugin will already be\n # enabled; when using the docker container, you will have to add it here\n HASS:\n type: hass\n ha_url: \"http://homeassistant:8123\"\n token: !secret ha_token # The token you get from home assistant\n\n # And we need to add the MQTT plugin\n MQTT:\n type: mqtt\n namespace: mqtt # We will need that same value in the apps.yaml configuration\n client_host: mosquitto # The IP address or hostname of the MQTT broker\n client_port: 1883 # The port of the MQTT broker, generally 1883\n\n # Only if you have setup an authenticated connection, otherwise skip those:\n client_user: appdaemon # The username\n client_password: !secret mqtt_password # The password\n```\n</details>\n\n\n### Installing HACS (optional, recommended)\n\nHACS is the Home Assistant Community Store and allows for community integrations and\nautomations to be updated cleanly and easily from the Home Assistant web user interface.\nIf it is simple to install Qolsys Gateway without HACS, keeping up to date requires\nmanual steps that HACS will handle for you: you will be notified of updates, and they\ncan be installed by a click on a button.\n\nIf you want to use HACS, you will have to follow [their documentation on how to install HACS][hacs-install].\n\n\n### Installing Qolsys Gateway\n\nInstalling Qolsys Gateway is pretty simple once all the applications above\nare setup. You can either follow the path using HACS (a bit more steps initially,\neasier on the longer run) or use the manual setup approach.\n\n#### With HACS (recommended)\n\nTo install Qolsys Gateway with HACS, you will need to make sure that you enabled\nAppDaemon automations in HACS, as these are not enabled by default:\n\n1. Click on `Configuration` on the left menu bar in Home Assistant Web UI\n2. Select `Devices & Services`\n3. Select `Integrations`\n4. Find `HACS` and click on `Configure`\n5. In the window that opens, make sure that `Enable AppDaemon apps discovery & tracking`\n is checked, or check it and click `Submit`\n6. If you just enabled this (or just installed HACS), you might have to wait a few minutes\n as all repositories are being fetched; you might hit a GitHub rate limit, which might\n then require you to wait a few hours for HACS to be fully configured. In this case,\n you won't be able to proceed to the next steps until HACS is ready.\n\nNow, to install Qolsys Gateway with HACS, follow these steps:\n\n1. Click on `HACS` on the left menu bar in Home Assistant Web UI\n2. Click on `Automations` in the right panel\n3. Click on `Explore & download repositories` in the bottom right corner\n4. Search for `qolsysgw`, and click on `Qolsys Gateway` in the list that appears\n5. In the bottom right corner of the panel that appears, click on\n `Download this repository with HACS`\n6. A confirmation panel will appear, click on `Download`, and wait for HACS to\n proceed with the download\n6. Qolsys Gateway is now installed, and HACS will inform you when updates are available\n\n\n#### Manually\n\nInstalling Qolsys Gateway manually can be summarized by putting the content of the\n`apps/` directory of this repository (the `qolsysgw/` directory) into the `apps/`\ndirectory of your AppDaemon installation.\n\nFor instance, if your Home Assistant configuration directory is in `/hass/config/`,\nyou most likely have AppDaemon setup in `/hass/config/appdaemon/`, and you can thus\nput `qolsysgw/` into `/hass/config/appdaemon/apps/`.\n\n\n## Configuration\n\n### Configuring the MQTT integration in Home Assistant\n\nThe MQTT integration of Home Assistant needs to be configured with your\nMQTT broker in order for Qolsys Gateway to work. If you haven't setup the\nMQTT integration yet, you can do so with the following steps:\n\n1. Click on `Configuration` on the left menu bar in Home Assistant Web UI\n2. Select `Devices & Services`\n3. Select `Integrations`\n4. Click on `Add Integration` in the bottom right corner\n5. Search for `MQTT`, and click on the MQTT integration\n6. Fill in the information as configured for your MQTT broker (hostname,\n port, and username and password if setting things up with an\n authenticated connection)\n7. Click on `Submit`, Home Assistant will try and connect to the MQTT broker,\n and the integration will be setup upon success.\n\n\n### Configuring your Qolsys IQ Panel\n\nIf you already have the Control4 token for your Qolsys IQ Panel, you can\nskip that step. If you do not understand what that sentence is about, you\ndefinitely need to go through that step.\n\nQolsys Gateway communicates with your Qolsys Panel using a protocol that\nexists for communications with Control4 automation. That protocol is not\nenabled on your Qolsys Panel by default, so we will need to enable it and\nnote the token that will be provided to us.\n\nTo enable the feature and get your secure token, you will need to:\n\n1. <details><summary>Connect your Qolsys Panel to your WiFi network (if not already done)</summary>\n\n 1. Swipe down from the top menu bar and select `Settings`.\n 2. Touch `Advanced Settings` and use either the _installer_ code or\n the _dealer_ code (you might have access with the main user code, too).\n 3. Touch `Wi-Fi`.\n 4. Check the `Enable Wi-Fi` box if not already active.\n 5. Available networks will appear in a list.\n 6. Touch the desired network and use the keyboard to type the password (if required).\n\n <p></p>\n\n <p align=\"center\">\n <img src=\"./docs/images/qolsys-connecting-to-wifi.png\"\n alt=\"Qolsys documentation to connect to WiFi\" width=\"738\" />\n </p>\n\n </details>\n\n1. <details><summary>Enable 3rd party connections</summary>\n\n 1. Swipe down from the top menu bar and select `Settings`.\n 2. Touch `Advanced Settings` and use the _dealer_ code (you **might** have\n access with the _installer_ code, too).\n 3. Touch `Installation`.\n 4. Touch `Devices`.\n 5. Touch `Wi-Fi Devices`.\n 6. Touch `3rd Party Connections`.\n 7. Check the `Control4` box to enable 3rd Party Connections.\n 8. The panel will reboot in order to apply the change.\n 9. Come back to the same menu once the reboot is done.\n 10. Touch `Reveal secure token` and note the token that the panel is\n providing you, we will need it to configure Qolsys Gateway.\n 11. If you ever leak that token, come back to this menu and touch\n `Regenerate secure token` in order to make sure that nobody can\n get access to control your alarm system.\n\n <p></p>\n\n <p align=\"center\">\n <img src=\"./docs/images/qolsys-3rd-party-connections.png\"\n alt=\"Qolsys documentation for 3rd party connections\" width=\"738\">\n </p>\n\n </details>\n\n\n### Configuring Qolsys Gateway\n\nQolsys Gateway needs to be configured in the `apps.yaml` file of AppDaemon.\nIf your Home Assistant configuration directory is in `/hass/config/`, and\nAppDaemon in `/hass/config/appdaemon/`, you will find this file in\n`/hass/config/appdaemon/apps/apps.yaml` (next to the `qolsysgw/` directory\nwe moved here previously).\n\n\n#### Required configuration\n\nThe minimum configuration to use Qolsys Gateway is the following:\n\n```yaml\nqolsys_panel:\n module: gateway\n class: QolsysGateway\n panel_host: <qolsys_panel_host_or_ip>\n panel_token: <qolsys_secure_token>\n```\n\nWith:\n\n- **qolsys_panel:** the name of the application for AppDaemon. You can run\n multiple instances of Qolsys Gateway, each with a different Qolsys Panel,\n if you ever need so. See the configuration options below, specifically\n `panel_unique_id`, to be able to configure multiple devices.\n- **module**: the main module from which QolsysGateway will be loaded.\n This parameter is mandatory and **cannot be changed** as it references\n the `qolsysgw/gateway.py` file.\n- **class**: the name of the class that will be loaded by AppDaemon for\n that automation. This parameter is mandatory and **cannot be changed** as\n it references the `QolsysGateway` class in the `qolsysgw/gateway.py` file.\n- **panel_host:** the hostname or IP address of your Qolsys Panel, as\n connected to your network. That hostname or IP address must, of course, be\n accessible from the server running AppDaemon.\n- **panel_token:** the secure token we got from enabling Control4 on the\n Qolsys Panel.\n\n\n#### Optional configuration related to the Qolsys Panel itself\n\n- <details><summary><strong>panel_port:</strong> the port to use to connect to your Qolsys Panel with the\n Control4 protocol. This is not really configurable on the panel itself,\n but available as an option if needed (for instance, for NAT needs).\n Defaults to <code>12345</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n panel_port: 4242 # use the port 4242\n # ...\n ```\n </details>\n\n- <details><summary><strong>panel_mac:</strong> the mac address of your Qolsys Panel.\n This is something you can find from your router, and might allow you to link the\n device created in Home Assistant by Qolsys Gateway to other entries related to your\n Panel. Not used by default, and Qolsys Gateway will try to resolve the mac address\n using ARP - which does not work when using appdaemon in docker, except if using the\n host network mode -, or ignore it entirely if not possible.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n panel_mac: aa:bb:cc:dd:11:22\n # ...\n ```\n </details>\n\n- <details><summary><strong>panel_user_code:</strong> the code to send to your\n Qolsys Panel to disarm your system (and arm when in secure arm mode). This needs\n to be a valid user code added to your Qolsys Panel. It is recommended to use a\n distinct user code if setup, so you have the ability to roll it as needed.\n If unset (or <code>null</code>), you will not be able to disarm your alarm system\n without providing a code in Home Assistant.\n Defaults to <code>null</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n panel_user_code: 1234 # there is a code '1234' allowing me to disarm my Qolsys Panel\n # ...\n ```\n </details>\n\n- <details><summary><strong>arm_away_exit_delay:</strong> the delay to set\n when arming away through Qolsys Gateway. Setting the value to\n <code>0</code> will instantly arm the alarm system. Setting to\n <code>null</code> will let the panel use its default value. Setting\n to any other positive value will set that delay. This will not change\n the default behavior of the panel when handled manually, simply what\n will happen when arming away from Home Assistant through Qolsys Gateway.\n <em>Note that if \"Auto Stay\" is enabled (may be the default in some cases),\n an exit delay is configured, and no door is opened or closed\n during the delay, the panel will be set to \"Arm Stay\" instead.</em>\n Defaults to <code>null</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n arm_away_exit_delay: 0 # arming instantly when triggered from Home Assistant, since related to automations\n # ...\n ```\n </details>\n\n- <details><summary><strong>arm_stay_exit_delay:</strong> the delay to set\n when arming stay through Qolsys Gateway. Setting the value to\n <code>0</code> will instantly arm the alarm system. Setting to\n <code>null</code> will let the panel use its default value. Setting\n to any other positive value will set that delay. This will not change\n the default behavior of the panel when handled manually, simply what\n will happen when arming stay from Home Assistant through Qolsys Gateway.\n Defaults to <code>null</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n arm_stay_exit_delay: 10 # arming in 10 seconds when triggered from Home Assistant\n # ...\n ```\n </details>\n\n- <details><summary><strong>arm_away_bypass:</strong> whether or not to\n bypass sensors that are \"open\" when arming away through Qolsys Gateway.\n Bypassed sensors are then ignored until the next time the panel will\n be armed (this means that closing and reopening those sensors after\n arming with the bypass will not trigger an alarm).\n Setting the value to <code>true</code> will always bypass open sensors\n when arming away, while setting it to <code>false</code> will always\n disable the bypass. If you have a default behavior for this defined in\n your panel, this parameter will override it. Leaving the parameter\n unset will leave the panel decide what to do.\n Defaults to <code>null</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n arm_away_bypass: true # will bypass the open sensors if any\n # ...\n ```\n </details>\n\n- <details><summary><strong>arm_stay_bypass:</strong> whether or not to\n bypass sensors that are \"open\" when arming stay through Qolsys Gateway.\n Bypassed sensors are then ignored until the next time the panel will\n be armed (this means that closing and reopening those sensors after\n arming with the bypass will not trigger an alarm).\n Setting the value to <code>true</code> will always bypass open sensors\n when arming stay, while setting it to <code>false</code> will always\n disable the bypass. If you have a default behavior for this defined in\n your panel, this parameter will override it. Leaving the parameter\n unset will leave the panel decide what to do.\n Defaults to <code>null</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n arm_stay_bypass: false # will NOT bypass the open sensors if any\n # ...\n ```\n </details>\n\n- <details><summary><strong>arm_type_custom_bypass:</strong> the type of\n arming to use when using <code>ARM_CUSTOM_BYPASS</code> from Home Assistant. This\n arming type will automatically enable bypassing the open sensors.\n Setting the value to <code>arm_away</code> will lead to the panel being\n armed in away mode with bypass enabled when <code>ARM_CUSTOM_BYPASS</code> is used.\n Setting the value to <code>arm_stay</code> will lead to the panel being\n armed in stay mode.\n Defaults to <code>arm_away</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n arm_type_custom_bypass: arm_stay # to arm the panel in stay mode when using the custom bypass arming type\n # ...\n ```\n </details>\n\n\n#### Optional configuration related to the representation of the panel in Home Assistant\n\n- <details><summary><strong>panel_unique_id:</strong> the unique ID of the device\n that will be created for the panel in Home Assistant. All the partitions and\n sensors unique IDs will be based on that unique ID to, in order to separate cleanly\n the potential multiple panels you would setup with Qolsys Gateway.\n Defaults to <code>qolsys_panel</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n panel_unique_id: meerkat # there cannot be another device with 'meerkat' as ID, it can help if you want to use Qolsys Gateway for two+ panels\n # ...\n ```\n </details>\n\n- <details><summary><strong>panel_device_name:</strong> the name of the device as it\n will appear in Home Assistant. Because Qolsys Gateway provides a unique ID for all\n its elements, you will be able to change the name in the user interface of Home\n Assistant. Even though, this is the name that Qolsys Gateway will advertise for\n your panel.\n Defaults to <code>Qolsys Panel</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n panel_device_name: Steve # hey, Steve!\n # ...\n ```\n </details>\n\n- <details><summary><strong>ha_check_user_code:</strong> whether or not\n the check of the user code should be done in the Home Assistant user\n interface. If set to <code>false</code>, the code will never be checked\n in home assistant even if required for arming, disarming or triggering\n the alarm, and will always be sent to Qolsys Gateway for checking. If\n set to <code>true</code> and the code is required for one of the actions,\n if will be checked by the Home Assistant user interface, and never\n sent through the network to Qolsys Gateway (a session token is shared\n to Home Assistant by Qolsys Gateway to make sure it is receiving control\n messages from the right instance). Note that in case of issues of checking\n a code in Qolsys Gateway, things will simply fail silently.\n <em>Requires <code>panel_user_code</code> to be set, will silently\n revert to <code>false</code> otherwise.</em>\n Defaults to <code>true</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n ha_check_user_code: false # we want Qolsys Gateway to receive the code and perform the check\n # ...\n ```\n </details>\n\n- <details><summary><strong>ha_user_code:</strong> if you want to use a\n different disarm code in Home Assistant than the actual disarm code that\n Qolsys Gateway will use with the panel, you can define it here. You can\n use numeric codes (will show a numeric pad in Home Assistant's user\n interface) or any characters (will show a text box).\n If <code>ha_check_user_code</code> is set to <code>true</code>, then\n the verification of that code will be done in Home Assistant directly. If\n set to <code>false</code>, Qolsys Gateway will use that code to compare\n against what Home Assistant will send in the control topic.\n <em>Requires <code>panel_user_code</code> to be set, will raise an\n error otherwise.</em>\n Defaults to <code>null</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n ha_user_code: $up3r$ecre7!! # this will be the code expected from the user\n # ...\n ```\n </details>\n\n- <details><summary><strong>code_arm_required:</strong> whether or not\n we require to type-in the code to arm the alarm system.\n <em>Requires <code>panel_user_code</code> to be set, will raise an\n error otherwise as the Qolsys Panel does not require any code to arm\n the alarm system, and Qolsys Gateway cannot do that check without a\n configured code.</em>\n Defaults to <code>false</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n code_arm_required: true\n # ...\n ```\n </details>\n\n- <details><summary><strong>code_disarm_required:</strong> whether or not\n we require to type-in the code to arm the alarm system.\n <em>Will silently be forced to <code>true</code> if\n <code>panel_user_code</code> is not set, as Qolsys Gateway will not be\n able to disarm the alarm system without a code.</em>\n Defaults to <code>false</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n code_disarm_required: true\n # ...\n ```\n </details>\n\n- <details><summary><strong>code_trigger_required:</strong> whether or not\n we require to type-in the code to trigger the alarm system.\n <em>Requires <code>panel_user_code</code> to be set, will raise an\n error otherwise as the Qolsys Panel does not require any code to trigger\n the alarm system, and Qolsys Gateway cannot do that check without a\n configured code.</em>\n Defaults to <code>false</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n code_trigger_required: true\n # ...\n ```\n </details>\n\n- <details><summary><strong>default_trigger_command:</strong> the trigger\n command to use among the <a href=\"./docs/qolsysgw-control-commands.md\">valid\n control commands that Qolsys Gateway support</a>.\n Defaults to <code>TRIGGER</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n default_trigger_command: TRIGGER_FIRE # if we want to trigger the fire alarm by default\n # ...\n ```\n </details>\n\n- <details><summary><strong>default_sensor_device_class:</strong> the sensor\n device class to use by default if a Qolsys sensor type is not directly\n mapped to a device class in Qolsys Gateway, but is still part of the\n identified sensors.\n Defaults to <code>safety</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n default_sensor_device_class: null # if we do not want to get a sensor if the device class is not directly mapped\n # ...\n ```\n </details>\n\n- <details><summary><strong>enable_static_sensors_by_default:</strong>\n whether or not sensors that will not be updated by the panel (e.g. Bluetooth)\n should be enabled by default in Home Assistant. Even if setting this to\n <code>false</code>, you will have the ability to enable them on a\n sensor-by-sensor basis in Home Assistant. If setting it to <code>true</code>,\n you will also be able to disable them on a sensor-by-sensor basis in\n Home Assistant.\n Defaults to <code>false</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n enable_static_sensors_by_default: true\n # ...\n ```\n </details>\n\n\n#### Optional configuration related to MQTT & AppDaemon\n\n- <details><summary><strong>mqtt_namespace:</strong> the MQTT namespace to use to\n read and send messages in MQTT. This should be the same as configured in\n <code>appdaemon.yaml</code>, so if you did not use <code>mqtt</code>, you will\n need to use that option for Qolsys Gateway to work properly.\n Defaults to <code>mqtt</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n mqtt_namespace: mqtt-homeassistant # if we used that namespace in appdaemon.yaml\n # ...\n ```\n </details>\n\n- <details><summary><strong>mqtt_retain:</strong> whether or not we should set\n the retain flag on availability and states messages of the partitions and sensors.\n This is interesting as if Home Assistant starts listening to MQTT right after we\n sent our status messages and we do not use <code>retain</code>, then Home Assistant\n will not know the state. However, using <code>retain</code> means that we need to\n handle the cases where AppDaemon is killed, this means that for this option to be\n considered, we need the <code>birth_topic</code> and <code>will_topic</code> of\n AppDaemon to be the same, so we can consider AppDaemon's availability as an\n information of the availability of our partitions and sensors.\n Defaults to <code>true</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n mqtt_retain: false # if we do not want to use MQTT retain\n # ...\n ```\n </details>\n\n- <details><summary><strong>discovery_topic:</strong> The topic base that Home\n Assistant listens to for MQTT discovery. This needs to be the same as the\n <code>discovery_prefix</code> configured for the MQTT module in the Home\n Assistant configuration, which is <code>homeassistant</code> by default.\n Defaults to <code>homeassistant</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n discovery_topic: hass-discovery # if the discovery_prefix was changed to hass-discovery in Home Assistant\n # ...\n ```\n </details>\n\n- <details><summary><strong>control_topic:</strong> the topic to use to\n receive control commands from Home Assistant. If using <code>{panel_unique_id}</code>\n as part of the value, it will be converted to the value as defined by\n the <code>panel_unique_id</code> parameter, allowing to automatically\n handle multiple instances of Qolsys Gateway for multiple panels, since\n you will have to define different unique IDs for each.\n Defaults to <code>{discovery_topic}/alarm_control_panel/{panel_unique_id}/set</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n control_topic: panel_{panel_unique_id}/control\n # ...\n ```\n </details>\n\n- <details><summary><strong>event_topic:</strong> the topic to use to\n write (and also read) the Qolsys Panel events. If using <code>{panel_unique_id}</code>\n as part of the value, it will be converted to the value as defined by\n the <code>panel_unique_id</code> parameter, allowing to automatically\n handle multiple instances of Qolsys Gateway for multiple panels, since\n you will have to define different unique IDs for each.\n Defaults to <code>qolsys/{panel_unique_id}/event</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n event_topic: panel_{panel_unique_id}/event\n # ...\n ```\n </details>\n\n- <details><summary><strong>user_control_token:</strong> a fixed control\n token that can be used as an alternative to the session token for control\n commands sent to Qolsys Gateway, if you want to trigger control commands\n that are not supported by an Home Assistant service. When set to <code>null</code>,\n this is simply disabled (only the session token will be considered valid).\n Defaults to <code>null</code>.</summary>\n\n ```yaml\n qolsys_panel:\n # ...\n user_control_token: My$ecr3tT0k3n!\n # ...\n ```\n </details>\n\n\n## Other documentation\n\n- [The known Qolsys Panel interactions](./docs/qolsys-panel-interactions.md)\n- [Qolsys Gateway's control commands](./docs/qolsysgw-control-commands.md)\n- [Qolsys Gateway's entities](./docs/qolsysgw-entities.md)\n\n\n## Acknowledgements and thanks\n\nThe initial findings that made this project possible are discussed\n[in the community forum of Home Assistant][hass-community-thread], where the\nControl4 interface was initially mentioned, as well as a number of the events\nand actions that could be used once the connection initiated with the Qolsys\nPanel.\n\nThe [<code>ad-qolsys</code>][ad-qolsys] project by [@roopesh][roopesh], which I\nused before deciding to rewrite the automation from scratch with different\nfeatures and a different way to handle events and actions. This project is not\nusing a line of code of <code>ad-qolsys</code>, but was initially inspired\nby it.\n\n\n<!--\nList of links used in that page, sorted alphabetically by tag\n-->\n[ad-qolsys]: https://github.com/roopesh/ad-qolsys\n[appdaemon-docker]: https://hub.docker.com/r/acockburn/appdaemon/\n[appdaemon-hass-plugin]: https://appdaemon.readthedocs.io/en/latest/CONFIGURE.html#configuration-of-the-hass-plugin\n[appdaemon-install]: https://appdaemon.readthedocs.io/en/latest/INSTALL.html\n[appdaemon-mqtt-plugin]: https://appdaemon.readthedocs.io/en/latest/CONFIGURE.html#configuration-of-the-mqtt-plugin\n[appdaemon]: https://github.com/AppDaemon/appdaemon\n[asyncio]: https://docs.python.org/3/library/asyncio.html\n[hacs-install]: https://hacs.xyz/docs/setup/download\n[hacs-pr]: https://github.com/hacs/default/pull/1173\n[hass-community-thread]: https://community.home-assistant.io/t/qolsys-iq-panel-2-and-3rd-party-integration/231405\n[hass-install]: https://www.home-assistant.io/installation/\n[hass-mqtt-broker]: https://www.home-assistant.io/docs/mqtt/broker\n[hass-mqtt-discovery]: https://www.home-assistant.io/docs/mqtt/discovery/\n[hass-mqtt]: https://www.home-assistant.io/integrations/mqtt/\n[hass]: https://www.home-assistant.io/\n[mqtt-docker]: https://hub.docker.com/_/eclipse-mosquitto\n[qolsys-panel-2]: https://qolsys.com/iq-panel-2/\n[qolsys-panel-2-plus]: https://qolsys.com/iq-panel-2-plus/\n[qolsys-panel-4]: https://qolsys.com/iq-panel-4/\n[roopesh]: https://github.com/roopesh\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2021 Rapha\u00ebl Beamonte <raphael.beamonte@gmail.com>\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Qolsys IQ Panel 2+ gateway API",
"version": "1.6.0",
"project_urls": {
"Changelog": "https://github.com/xaf/qolsysgw/commits/main/",
"Documentation": "https://github.com/xaf/qolsysgw",
"Homepage": "https://github.com/xaf/qolsysgw",
"Issues": "https://github.com/xaf/qolsysgw/issues",
"Repository": "https://github.com/xaf/qolsysgw.git"
},
"split_keywords": [
"api",
" gateway",
" iq panel",
" qolsys"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ddc5da8ba1c496792401020199b61f587d3a044536474686c61564a337122d6b",
"md5": "f99c15670be40acb15e81651c8032995",
"sha256": "528d95d5a826e1eaf2c049e396d87759252796147815060db156f37f7c2d1cf6"
},
"downloads": -1,
"filename": "qolsys-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f99c15670be40acb15e81651c8032995",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27491,
"upload_time": "2024-09-09T03:34:42",
"upload_time_iso_8601": "2024-09-09T03:34:42.480118Z",
"url": "https://files.pythonhosted.org/packages/dd/c5/da8ba1c496792401020199b61f587d3a044536474686c61564a337122d6b/qolsys-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e94c4b337f036e1cb9e80263ba1cd4e940901ca805c076c963b8693fe0238152",
"md5": "ed3d2a093921669290ead7d2c210f6c4",
"sha256": "8cd2ad36038c8545dcd575f3899ec6d50b42299c182d77d1e27b4fab801ff6e8"
},
"downloads": -1,
"filename": "qolsys-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "ed3d2a093921669290ead7d2c210f6c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 31542,
"upload_time": "2024-09-09T03:34:41",
"upload_time_iso_8601": "2024-09-09T03:34:41.170263Z",
"url": "https://files.pythonhosted.org/packages/e9/4c/4b337f036e1cb9e80263ba1cd4e940901ca805c076c963b8693fe0238152/qolsys-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-09 03:34:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xaf",
"github_project": "qolsysgw",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "qolsys"
}
