### Configure appdaemon.yaml for Qolsys Gateway

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Example configuration for the appdaemon.yaml file, including the HASS and MQTT plugin settings required for Qolsys Gateway.

```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
```

--------------------------------

### ARM_AWAY control command JSON

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

Example of the ARM_AWAY command payload. Includes optional bypass and delay fields to override panel defaults.

```json
{
  "action": "ARM_AWAY",
  "code": "4242",
  "bypass": false,
  "delay": 0,
  "partition_id": 0,
  "session_token": "<session_token>"
}
```

--------------------------------

### DISARM control command JSON

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

Example of the DISARM command payload. The code field is required if code_disarm_required is true or if panel_user_code is missing.

```json
{
  "action": "DISARM",
  "code": "4242",
  "partition_id": 0,
  "session_token": "<session_token>"
}
```

--------------------------------

### Set code_disarm_required to true in qolsys_panel YAML

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Configures whether a code is required to disarm the alarm system. The example sets code_disarm_required to true.

```yaml
qolsys_panel:
  # ...
  code_disarm_required: true
  # ...
```

--------------------------------

### Configure discovery_topic

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Defines the topic base for Home Assistant MQTT discovery. Must match the discovery_prefix in Home Assistant configuration.

```yaml
qolsys_panel:
  # ...
  discovery_topic: hass-discovery # if the discovery_prefix was changed to hass-discovery in Home Assistant
  # ...
```

--------------------------------

### INFO Action

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsys-panel-interactions.md

Queries the summary of the panel state, including partitions and sensors. The panel responds with an INFO event.

```APIDOC
## INFO Action

### Description
Queries the summary of the panel state, including partitions and sensors. The panel responds with an INFO event.

### Action Type
INFO

### Parameters
- **action** (string) - Required - Must be "INFO".
- **info_type** (string) - Required - Must be "SUMMARY".
- **token** (string) - Required - Token provided by the Qolsys Panel.
- **nonce** (string) - Required - Must be "qolsys".
- **source** (string) - Required - Must be "C4".
- **version** (integer) - Required - Must be 0.

### Request Example
{
  "action": "INFO",
  "info_type": "SUMMARY",
  "token": "<token>",
  "nonce": "qolsys",
  "source": "C4",
  "version": 0
}
```

--------------------------------

### INFO Action Request

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsys-panel-interactions.md

Used to query the current state of the panel, including partitions and sensors. This action is typically followed by an INFO event response.

```json
{
  "action": "INFO",
  "info_type": "SUMMARY",
  "token": "<token>",
  "nonce": "qolsys",
  "source": "C4",
  "version": 0
}
```

--------------------------------

### Configure arm_stay_exit_delay

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the exit delay when arming stay through Qolsys Gateway. Setting to 0 arms instantly, while null uses the panel default.

```yaml
qolsys_panel:
    # ...
    arm_stay_exit_delay: 10 # arming in 10 seconds when triggered from Home Assistant
    # ...
```

--------------------------------

### Configure mqtt_namespace

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the MQTT namespace for reading and sending messages. This must match the configuration in appdaemon.yaml.

```yaml
qolsys_panel:
  # ...
  mqtt_namespace: mqtt-homeassistant # if we used that namespace in appdaemon.yaml
  # ...
```

--------------------------------

### Configure arm_away_exit_delay

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the exit delay when arming away through Qolsys Gateway. Setting to 0 arms instantly, while null uses the panel default.

```yaml
qolsys_panel:
    # ...
    arm_away_exit_delay: 0 # arming instantly when triggered from Home Assistant, since related to automations
    # ...
```

--------------------------------

### Configure panel_device_name

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the display name for the panel in Home Assistant. Defaults to Qolsys Panel.

```yaml
qolsys_panel:
  # ...
  panel_device_name: Steve # hey, Steve!
  # ...
```

--------------------------------

### Create a Template Sensor for Gateway Errors

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-entities.md

Use this YAML configuration in Home Assistant to create a sensor that tracks the 'desc' attribute of the 'qolsys_panel_last_error' sensor.

```yaml
template:
  - sensor:
      - name: qolsys_panel_last_error_desc
        state: "{{state_attr('sensor.qolsys_panel_last_error', 'desc')}}"
```

--------------------------------

### ARM_NIGHT

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

This control command is an alias of ARM_HOME. It is sent as a JSON object to the Qolsys Gateway to arm the partition in stay mode.

```APIDOC
## ARM_NIGHT

### Description
This control command is an alias of ARM_HOME. It is sent as a JSON object to the Qolsys Gateway to arm the partition in stay mode.

### Request Body
- **action** (string) - Required - The action to perform, set to "ARM_NIGHT".
- **code** (string) - Optional - The panel user code, required if panel_user_code is not defined in configuration or if code_arm_required is true and the code is not checked in Home Assistant directly.
- **bypass** (boolean) - Optional - Whether to bypass currently open sensors.
- **delay** (integer) - Optional - The exit delay in seconds before the panel is armed.
- **partition_id** (integer) - Optional - The partition to arm.
- **session_token** (string) - Optional - The session token for authentication.

### Request Example
{
  "action": "ARM_NIGHT",
  "code": "4242",
  "bypass": false,
  "delay": 0,
  "partition_id": 0,
  "session_token": "<session_token>"
}
```

--------------------------------

### Configure event_topic

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the topic for reading and writing Qolsys Panel events. Supports {panel_unique_id} placeholder.

```yaml
qolsys_panel:
  # ...
  event_topic: panel_{panel_unique_id}/event
  # ...
```

--------------------------------

### Configure control_topic

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the topic for receiving control commands from Home Assistant. Supports {panel_unique_id} placeholder.

```yaml
qolsys_panel:
  # ...
  control_topic: panel_{panel_unique_id}/control
  # ...
```

--------------------------------

### Configure Qolsys Gateway in apps.yaml

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

The minimum required configuration for the Qolsys Gateway within the AppDaemon apps.yaml file, specifying the module, class, panel host, and secure token.

```yaml
qolsys_panel:
  module: gateway
  class: QolsysGateway
  panel_host: <qolsys_panel_host_or_ip>
  panel_token: <qolsys_secure_token>
```

--------------------------------

### Set enable_static_sensors_by_default to true in qolsys_panel YAML

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Enables static sensors (e.g., Bluetooth) by default in Home Assistant. Even when false, they can be enabled per sensor; when true, they can also be disabled per sensor. Defaults to false.

```yaml
qolsys_panel:
  # ...
  enable_static_sensors_by_default: true
  # ...
```

--------------------------------

### ARM_HOME

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

This control command asks the Qolsys Gateway to arm the partition in stay mode, where only door and window sensors are active. It includes optional fields for code, bypass, and delay.

```APIDOC
## ARM_HOME

### Description
This control command asks the Qolsys Gateway to arm the partition in stay mode, where only door and window sensors are active and trigger the alarm. The code field is required if panel_user_code is not defined in the configuration or if code_arm_required is true and the code is not checked in Home Assistant directly. The bypass field indicates whether to bypass currently open sensors, and the delay field sets the exit delay in seconds before arming.

### Request Body
- **action** (string) - Required - The action to perform, set to "ARM_HOME".
- **code** (string) - Optional - The panel user code, required if panel_user_code is not defined in configuration or if code_arm_required is true and the code is not checked in Home Assistant directly.
- **bypass** (boolean) - Optional - Whether to bypass currently open sensors; overrides panel default configuration.
- **delay** (integer) - Optional - The exit delay in seconds before the panel is armed; overrides panel default configuration.
- **partition_id** (integer) - Optional - The partition to arm.
- **session_token** (string) - Optional - The session token for authentication.

### Request Example
{
  "action": "ARM_HOME",
  "code": "4242",
  "bypass": false,
  "delay": 0,
  "partition_id": 0,
  "session_token": "<session_token>"
}
```

--------------------------------

### ARMING Action - ARM_STAY

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsys-panel-interactions.md

Arms the panel in stay mode. No extra parameters are required beyond the common ones.

```APIDOC
## ARMING Action - ARM_STAY

### Description
Arms the panel in stay mode. No extra parameters are required beyond the common ones.

### Action Type
ARMING

### Parameters
- **action** (string) - Required - Must be "ARMING".
- **arming_type** (string) - Required - Must be "ARM_STAY".
- **partition_id** (integer) - Required - ID of the partition to arm.
- **token** (string) - Required - Token provided by the Qolsys Panel.
- **nonce** (string) - Required - Must be "qolsys".
- **source** (string) - Required - Must be "C4".
- **version** (integer) - Required - Must be 0.

### Request Example
{
  "action": "ARMING",
  "arming_type": "ARM_STAY",
  "partition_id": 0,
  "token": "<token>",
  "nonce": "qolsys",
  "source": "C4",
  "version": 0
}
```

--------------------------------

### Configure panel_mac

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Specifies the MAC address of the Qolsys Panel. This is used to link the device in Home Assistant and is resolved via ARP if not provided.

```yaml
qolsys_panel:
    # ...
    panel_mac: aa:bb:cc:dd:11:22
    # ...
```

--------------------------------

### ARM_VACATION

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

This control command is an alias of ARM_AWAY. It is sent as a JSON object to the Qolsys Gateway to arm the partition in away mode.

```APIDOC
## ARM_VACATION

### Description
This control command is an alias of ARM_AWAY. It is sent as a JSON object to the Qolsys Gateway to arm the partition in away mode.

### Request Body
- **action** (string) - Required - The action to perform, set to "ARM_VACATION".
- **code** (string) - Optional - The panel user code, required if panel_user_code is not defined in configuration or if code_arm_required is true and the code is not checked in Home Assistant directly.
- **bypass** (boolean) - Optional - Whether to bypass currently open sensors.
- **delay** (integer) - Optional - The exit delay in seconds before the panel is armed.
- **partition_id** (integer) - Optional - The partition to arm.
- **session_token** (string) - Optional - The session token for authentication.

### Request Example
{
  "action": "ARM_VACATION",
  "code": "4242",
  "bypass": false,
  "delay": 0,
  "partition_id": 0,
  "session_token": "<session_token>"
}
```

--------------------------------

### Configure panel_unique_id

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the unique ID for the panel device in Home Assistant. Defaults to qolsys_panel.

```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
  # ...
```

--------------------------------

### ARMING Action - ARM_AWAY

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsys-panel-interactions.md

Arms the panel in away mode. Supports optional delay and bypass parameters.

```APIDOC
## ARMING Action - ARM_AWAY

### Description
Arms the panel in away mode. Supports optional delay and bypass parameters.

### Action Type
ARMING

### Parameters
- **action** (string) - Required - Must be "ARMING".
- **arming_type** (string) - Required - Must be "ARM_AWAY".
- **partition_id** (integer) - Required - ID of the partition to arm.
- **delay** (integer) - Optional - Exit delay in seconds. If 0, the panel arms immediately. If omitted, uses the panel's default.
- **bypass** (string) - Optional - "true" to bypass open sensors, "false" to prevent arming if any sensor is open.
- **token** (string) - Required - Token provided by the Qolsys Panel.
- **nonce** (string) - Required - Must be "qolsys".
- **source** (string) - Required - Must be "C4".
- **version** (integer) - Required - Must be 0.

### Request Example
{
  "action": "ARMING",
  "arming_type": "ARM_AWAY",
  "partition_id": 0,
  "delay": 10,
  "bypass": "false",
  "token": "<token>",
  "nonce": "qolsys",
  "source": "C4",
  "version": 0
}
```

--------------------------------

### Configure ha_check_user_code

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Determines if user code verification occurs in Home Assistant or via Qolsys Gateway. Requires panel_user_code to be set.

```yaml
qolsys_panel:
  # ...
  ha_check_user_code: false # we want Qolsys Gateway to receive the code and perform the check
  # ...
```

--------------------------------

### Configure panel_user_code

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Defines the user code required to disarm the system or arm in secure mode. Defaults to null, which prevents disarming without a code provided in Home Assistant.

```yaml
qolsys_panel:
    # ...
    panel_user_code: 1234 # there is a code '1234' allowing me to disarm my Qolsys Panel
    # ...
```

--------------------------------

### ARM_STAY Action Request

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsys-panel-interactions.md

Arms the panel in stay mode for the specified partition ID. No extra parameters are required.

```json
{
  "action": "ARMING",
  "arming_type": "ARM_STAY",
  "partition_id": 0,
  "token": "<token>",
  "nonce": "qolsys",
  "source": "C4",
  "version": 0
}
```

--------------------------------

### Configure ha_user_code

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets a custom disarm code for Home Assistant. Requires panel_user_code to be set.

```yaml
qolsys_panel:
  # ...
  ha_user_code: $up3r$ecre7!! # this will be the code expected from the user
  # ...
```

--------------------------------

### Configure mqtt_retain

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Determines whether to set the retain flag on availability and state messages. Defaults to true.

```yaml
qolsys_panel:
  # ...
  mqtt_retain: false # if we do not want to use MQTT retain
  # ...
```

--------------------------------

### ARM_AWAY

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

Sends a command to arm the specified partition in away mode. Includes optional fields for code, bypass, and delay.

```APIDOC
## ARM_AWAY

### Description
Sends a command to arm the specified partition in away mode. The `code` field is required if `panel_user_code` is not defined or if `code_arm_required` is true and the code is not checked in Home Assistant.

### Parameters
#### Message Fields
- **action** (string) - Required - Must be "ARM_AWAY"
- **code** (string) - Optional - The user code to verify or send to the panel
- **bypass** (boolean) - Optional - Whether to bypass currently open sensors
- **delay** (integer) - Optional - Exit delay in seconds before arming
- **partition_id** (integer) - Required - The partition to arm
- **session_token** (string) - Required - Token to verify the command source

### Request Example
{
  "action": "ARM_AWAY",
  "code": "4242",
  "bypass": false,
  "delay": 0,
  "partition_id": 0,
  "session_token": "<session_token>"
}
```

--------------------------------

### Configure arm_type_custom_bypass

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Defines the arming type used when ARM_CUSTOM_BYPASS is triggered in Home Assistant. Defaults to arm_away.

```yaml
qolsys_panel:
  # ...
  arm_type_custom_bypass: arm_stay # to arm the panel in stay mode when using the custom bypass arming type
  # ...
```

--------------------------------

### Configure panel_port

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the port used to connect to the Qolsys Panel via the Control4 protocol. Defaults to 12345.

```yaml
qolsys_panel:
    # ...
    panel_port: 4242 # use the port 4242
    # ...
```

--------------------------------

### Configure code_arm_required

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets whether a code is required to arm the system. Requires panel_user_code to be set.

```yaml
qolsys_panel:
  # ...
  code_arm_required: true
  # ...
```

--------------------------------

### ARM_CUSTOM_BYPASS

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

This control command asks the Qolsys Gateway to arm the partition in away or stay mode, depending on configuration, while bypassing all open sensors. It includes optional fields for code and delay.

```APIDOC
## ARM_CUSTOM_BYPASS

### Description
This control command asks the Qolsys Gateway to arm the partition in away (default) or stay mode, depending on the configuration. When using this control to arm the partition, all open sensors will be bypassed, meaning that even after closing those sensors, subsequent opens will not trigger the alarm. The code field is required if panel_user_code is not defined in the configuration or if code_arm_required is true and the code is not checked in Home Assistant directly. The delay field sets the exit delay in seconds before arming.

### Request Body
- **action** (string) - Required - The action to perform, set to "ARM_CUSTOM_BYPASS".
- **code** (string) - Optional - The panel user code, required if panel_user_code is not defined in configuration or if code_arm_required is true and the code is not checked in Home Assistant directly.
- **delay** (integer) - Optional - The exit delay in seconds before the panel is armed; overrides panel default configuration.
- **partition_id** (integer) - Optional - The partition to arm.
- **session_token** (string) - Optional - The session token for authentication.

### Request Example
{
  "action": "ARM_CUSTOM_BYPASS",
  "code": "4242",
  "delay": 0,
  "partition_id": 0,
  "session_token": "<session_token>"
}
```

--------------------------------

### Configure user_control_token

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets a fixed control token as an alternative to the session token for control commands. Defaults to null.

```yaml
qolsys_panel:
  # ...
  user_control_token: My$ecr3tT0k3n!
  # ...
```

--------------------------------

### ARM_AWAY Action Request

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsys-panel-interactions.md

Arms the panel in away mode. Supports optional delay and bypass parameters for handling open sensors.

```json
{
  "action": "ARMING",
  "arming_type": "ARM_AWAY",
  "partition_id": 0,
  "delay": 10,
  "bypass": "false",
  "token": "<token>",
  "nonce": "qolsys",
  "source": "C4",
  "version": 0
}
```

--------------------------------

### Configure arm_away_bypass

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Determines whether to bypass open sensors when arming away. Setting to true forces a bypass, while false disables it.

```yaml
qolsys_panel:
    # ...
    arm_away_bypass: true # will bypass the open sensors if any
    # ...
```

--------------------------------

### DISARM Action Request

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsys-panel-interactions.md

Disarms the panel for the specified partition. Requires a valid usercode.

```json
{
  "action": "ARMING",
  "arming_type": "DISARM",
  "partition_id": 0,
  "usercode": "4242",
  "token": "<token>",
  "nonce": "qolsys",
  "source": "C4",
  "version": 0
}
```

--------------------------------

### Configure arm_stay_bypass

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets whether the panel will bypass open sensors when arming in stay mode.

```yaml
qolsys_panel:
  # ...
  arm_stay_bypass: false # will NOT bypass the open sensors if any
  # ...
```

--------------------------------

### ARMING Action - DISARM

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsys-panel-interactions.md

Disarms the panel. Requires a valid usercode.

```APIDOC
## ARMING Action - DISARM

### Description
Disarms the panel. Requires a valid usercode.

### Action Type
ARMING

### Parameters
- **action** (string) - Required - Must be "ARMING".
- **arming_type** (string) - Required - Must be "DISARM".
- **partition_id** (integer) - Required - ID of the partition to disarm.
- **usercode** (string) - Required - Valid disarm code for the panel.
- **token** (string) - Required - Token provided by the Qolsys Panel.
- **nonce** (string) - Required - Must be "qolsys".
- **source** (string) - Required - Must be "C4".
- **version** (integer) - Required - Must be 0.

### Request Example
{
  "action": "ARMING",
  "arming_type": "DISARM",
  "partition_id": 0,
  "usercode": "4242",
  "token": "<token>",
  "nonce": "qolsys",
  "source": "C4",
  "version": 0
}
```

--------------------------------

### DISARM

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

Sends a command to disarm a specified partition. The code field is required if code verification is enabled or if the panel_user_code is not configured.

```APIDOC
## DISARM

### Description
Sends a command to disarm the specified partition. The `code` field is required if `code_disarm_required` is true and `ha_check_user_code` is false, or if `panel_user_code` is not provided in the configuration.

### Parameters
#### Message Fields
- **action** (string) - Required - Must be "DISARM"
- **code** (string) - Optional - The user code to verify or send to the panel
- **partition_id** (integer) - Required - The partition to disarm
- **session_token** (string) - Required - Token to verify the command source

### Request Example
{
  "action": "DISARM",
  "code": "4242",
  "partition_id": 0,
  "session_token": "<session_token>"
}
```

--------------------------------

### Set default_sensor_device_class to null in qolsys_panel YAML

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the default sensor device class to null, meaning no sensor is created if the device class is not directly mapped. The default value is safety.

```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
  # ...
```

--------------------------------

### Set default_trigger_command to TRIGGER_FIRE in qolsys_panel YAML

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Sets the default trigger command to TRIGGER_FIRE, which triggers the fire alarm by default. The valid commands are those supported by Qolsys Gateway; the default is TRIGGER.

```yaml
qolsys_panel:
  # ...
  default_trigger_command: TRIGGER_FIRE # if we want to trigger the fire alarm by default
  # ...
```

--------------------------------

### Set code_trigger_required to true in qolsys_panel YAML

Source: https://github.com/xaf/qolsysgw/blob/main/README.md

Configures whether a code is required to trigger the alarm system. Requires panel_user_code to be set; otherwise an error is raised. Defaults to false.

```yaml
qolsys_panel:
  # ...
  code_trigger_required: true
  # ...
```

--------------------------------

### TRIGGER command

Source: https://github.com/xaf/qolsysgw/blob/main/docs/qolsysgw-control-commands.md

Triggers the default POLICE alarm. Include the code field if code_trigger_required is set to true.

```json
{
  "action": "TRIGGER",
  "code": "4242",
  "partition_id": 0,
  "session_token": "<session_token>"
}
```