Qolsys Gateway - qolsysgw

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
• Requirements
• Installation
  • Installing Home Assistant
  • Installing an MQTT Broker
  • Installing AppDaemon
  • Installing HACS (optional, recommended)
  • Installing Qolsys Gateway
    • With HACS (recommended)
    • Manually
• Configuration
  • Configuring the MQTT integration in Home Assistant
  • Configuring your Qolsys IQ Panel
  • Configuring Qolsys Gateway
    • Required configuration
    • Optional configuration related to the Qolsys Panel itself
    • Optional configuration related to the representation of the panel in Home Assistant
    • Optional configuration related to MQTT & AppDaemon
• Other documentation
• 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>

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