/risco-mqtt-local

Provide Risco alarm system integration to Home assistant using local TCP communication (no cloud required) and MQTT

Primary LanguageTypeScriptMIT LicenseMIT

license badge Docker Pulls Maintenance buy me a coffee

Add to Home Assistant

Risco MQTT Local integration

Provide Risco alarm panels integration to Home Assistant using Local TCP communication with Panel (no cloud access required)

This project is a fork of Johann Vanackere. In turn this forks risco-mqtt-home-assistant by Alessandro Mancini, using local APIs instead of RiscoCloud APIs. Local APIs are based on TJForc local RISCO communication library

Requirements

  • Node.js (currently tested with >=ver. 10.x)
  • Mqtt Server - e.g. Mosquitto, HiveMQ, etc.
  • Home Assistant

Features

  • Interaction with RISCO alarm control panel using local APIs.
  • Interaction with MQTT Alarm Control Panel integration in Home Assistant: maps away, home and disarmed.
  • Interaction with MQTT Binary Sensor integration in Home Assistant: sensors for each alarm state and additional alarm triggered sensor.
  • Home Assistant MQTT Auto Discovery.
  • RISCO multipartitions.
  • Bypass zones in Home Assistant (additional switch created for each zone).
  • Multiple systems with configurable alarm topic for each.
  • Outputs supported. Non-user-usable outputs represented as binary sensors (system outputs in configuration). User-usable outputs represented as switches or button. Note that pulsed switches are represented as buttons. Refer to https://www.home-assistant.io/integrations/button/ and https://www.home-assistant.io/integrations/binary_sensor/ for acceptable device classes.
  • Supports mapping of group arming via config file.
  • Wireless zones now show battery status as additional binary sensors (this is the only information the panel gives).
  • Separate binary sensors are provided that are only triggered in an alarm state. This permits automations based only on alarm-triggers.
  • Cloud proxy status sensor supported.
  • Configurable reconnection delay after dropping of Cloud connection.
  • Buttons to republish status, autodiscovery and reinitiate communications.

Installation

npm install @markxroberts/risco-mqtt-local

Or

docker run -v $(pwd)/config.json:/data/config.json markxroberts/risco-mqtt-local:latest

Or install as HA add-on.

Configuration

Create a file config.json in your project directory. I suggest using config-sample.json in this folder rather than copying the commented version below.

{
  "log": "info", // Optional, default to "info"
  "panel": {
    "panelIp": "192.168.1.150",
    "panelPort": 1000,
    "panelPassword": "1234",
    "panelId": 1,
    "watchDogInterval": 10000,
    "socketMode": "direct" // Optional
    "commandsLog": false // If enabled, dump all commands in a file named risco-commands-${date}.csv
  },
  "ha_discovery_prefix_topic": "homeassistant" //Optional
  "risco_mqtt_topic": "risco-alarm-panel", //Optional - topic to which state changes are published for multiple instances
  "filter_bypass_zones": true, // Optional - system filters out non-functional bypasses (usually entry and exit zones)
  "alarm_system_name": "Risco Alarm", // Optional - Device name and therefore prefix for HA sensor name
  "ha_state_publishing_delay": 30, // Option - delay between autodiscovery and publishing states.  Without this delay HA may well show unknown state for sensors
  "comms_restart_delay": 30, // Optional - delay before restarting comms after interrupt
  "socket_retry_delay": 600, // Optional - delay retrying socket after socket disconnected

  "mqtt": {
    "url": "mqtt://192.168.1.10:1883",
    "username": "MQTT_USERNAME",
    "password": "MQTT_PASSWORD"
  },
  "zones": {
    "default": { // Default zones configuration
      "off_delay": 30, // Optional auto off configuration for detectors. 0 to disable (default value: disabled)
      "name_prefix": "Sensor - " // A common prefix, added before all zone name
    },
    "GARAGE": { // Override config for an individual zone (based on zone label)
      "off_delay": 0, // Disable off_delay for this zone.
      "device_class": "garage_door", // override device class for binary sensor. default to "motion". see HA documentation for available values
      "name": "Garage Door", // Override default name for this zone. Default to zone label
      "name_prefix": "" // Force zone name prefix to empty for this zone
    },
  }
  "partitions": {
    "default": {
      "name_prefix": ""
    },
    "1": {
      "name": "House"
    },
    "2": {
      "name": "Garage"
    }
  },
  "user_outputs": {
    "default": {
      "name_prefix": ""
    },
    "Up/over Trigger": { 
      "device_class": "none", 
      "name": "Garage door trigger RISCO", 
      "name_prefix": "" 
    }
  },
  "system_outputs": {
    "default": {
      "name_prefix": ""
    },
    "Bell": { 
      "device_class": "sound", 
      "name": "Alarm Bell", 
      "name_prefix": "" 
    },
    "Strobe": { 
      "device_class": "light", 
      "name": "Alarm Strobe", 
      "name_prefix": "" 
    }
  }
  "arming_modes": {
    "House": { // Name of partition to remap
      "armed_away": "armed_away",  //optional - default shown
      "armed_home": "armed_home",  //optional - default shown
      "armed_night": "armed_home",  //optional - default shown
      "armed_vacation": "armed_away",  //optional - default shown
      "armed_custom_bypass: "armed_group_A" // Optional.  Example of group arming (takes A/B/C/D).  Default here is "armed_away"
  }
}

The panel full configuration options are described here : https://github.com/markxroberts/risco-lan-bridge#configuration

NB Ensure that zone description matches label stored in panel exactly (including case) to ensure that config is correctly represented.

Subscribe Topics

risco-mqtt-local subscribes at startup one topic for every partition in your risco alarm panel configuration.

Topic format is <risco_node_id>/alarm/<partition_id>/set where partition_id is the id of the partition

Payload could be : disarmed if risco panel is in disarmed mode,armed_home if risco panel is in armed at home mode and armed_away if risco panel is in armed away mode.

Publish Topics

risco-mqtt-local publishes one topic for every partition and for every zones in your risco alarm panel configuration.

Partition topicsformat is <risco_node_id>/alarm/<partition_id>/status where partition_id is the id of the partition

Payload could be : disarmed if risco panel is in disarmed mode,armed_home if risco panel is in armed at home mode and armed_away if risco panel is in armed away mode.

Zones topics format is <risco_node_id>/alarm/<partition_id>/<zone_id>/status where partition_id is the id of the partition and zone_id is the id of the zone.

Payload could be : triggered if zone is curently triggered, and idle if zone is currently idle.

In addition to every zone status, risco-mqtt-local publishes a topic for every zone with all the info of the zone in the payload in json format. Topics format is <risco_node_id>/alarm/<partition_id>/<zone_id> where partition_id is the id of the partition and zone_id is the id of the zone.

Zones that may be bypassed are published as switches at: <risco_alarm_panel>/alarm/<partition_id>/switch/<zone_id>-bypass. Entry/exit zones may not be bypassed and so are not published.

Battery-powered zones have separate sensors for the battery. These are published at: <risco_node_id>/alarm/<partition_id>/<zone_id>/battery. These only have a binary state.

Outputs are published as <risco_node_id/alarm>/<output_id>/status for sensor outputs. For outputs where interaction is possible, these are published as <risco_node_id>/alarm/<output_id>/status unless buttons, which are stateless. Switches are published to <risco_node_id>/alarm/<output_id>/set as subscribed topics.

The cloud proxy status is published at <risco_node_id>/alarm/cloudstatus if the cloud proxy is enabled.

Arming modes are shown in the configuration example above. All of these are optional. Defaults are shown. The syntax shown here must be used for mappings to work.

Home Assistant Auto Discovery

risco-mqtt-local supports mqtt auto discovery feature.

Default <discovery_prefix> is homeassistant. You can change it by overwriting the value within ha_discovery_prefix_topic config.

Home assistant auto discovery is republished on Home Assistant restart.

For multiple partitions, change risco_node_id in each installation.

Usage

First, create the config.json file. Only the first part of the file with system settings is mandatory. It's not necessary to describe all of the zones/partitions/sensors as these can be customized from the Home Assistant front end. I suggest using config-sample.json as a template. The bind mount location is /data in the container.

It needs to be strictly in json format.

Support

Bug reports

Please use the bug issue template and fill all requested informations, including debug logs and commands logs.

Credits

The bulk of this work was completed by vanackej. I've adapted this and updated it, mainly for my purposes. Thanks to pergolafabio for the proxy testing.

Thanks to TJForc for the local communication library and Alessandro Mancini for his initial work.