ring-alarm-mqtt

This is a simple script that leverages the ring alarm API available at dgreif/ring-alarm and provides access to the alarm control panel and sensors via MQTT. It provides support for Home Assistant style MQTT discovery which allows for very easy integration with Home Assistant with near zero configuration (assuming MQTT is already configured). It can also be used with any other tool capable of working with MQTT as it provides consistent topic naming based on location/device ID.

Installation

Make sure Node.js (tested with 8.x and higher) is installed on your system and then clone this repo:

git clone https://github.com/tsightler/ring-alarm-mqtt.git

Change to the ring-alarm-mqtt directory and run:

chmod +x ring-alarm-mqtt.js
npm install

This should install all required dependencies. Edit the config.js and enter your Ring account user/password and MQTT broker connection information. You can also change the top level topic used for creating ring device topics and also configre the Home Assistant state topic, but most people should leave these as default.

Now you should just execute the script and devices should show up automatically in Home Assistant within a few seconds.

Starting the service automatically during boot

I've included a sample service file which you can use to automaticlly start the script during system boot as long as your system uses systemd (most modern Linux distros). The service file assumes you've installed the script in /opt/ring-alarm-mqtt and that you want to run the process as the homeassistant user, but you can easily modify this to any path and user you'd like. Just edit the file as required and drop it in /etc/systemd/system then run the following:

systemctl enable ring-alarm-mqtt

Optional Home Assistant Configuration (Highly Recommended)

If you'd like to take full advantage of the Home Assistant specific features (auto MQTT discovery and server state monitorting) you need to make sure Home Assistant MQTT is configured with discovery and birth message options, here's an example:

mqtt:
  broker: 127.0.0.1
  discovery: true
  discovery_prefix: homeassistant
  birth_message:
    topic: 'hass/status'
    payload: 'online'
    qos: 0
    retain: false

Current Features

• Simple configuration via config file, most cases just need Ring user/password and that's it
• Supports the following devices:
  • Ring Contact and Motion Sensors
  • Ring Flood/Freeze Sensor
  • Ring Smoke/CO Listener
  • First Alert Z-Wave Smoke/CO Detector (experimental - testing needed)
  • Ring Alarm integrated door locks (status and lock control)
• Provides battery and tamper status for supported devices via JSON attribute topic (visible in Home Assistant UI)
• Full Home Assistant MQTT Discovery - devices appear automatically (also tested with OpenHAB 2.4 MQTT)
• Consistent topic creation based on location/device ID - easy to use with MQTT tools like Node-RED
• Arm/Disarm via alarm control panel MQTT object
• Arm/Disarm commands are monitored for success and retried (default up to 12x with 10 second interval)
• Support for mulitple alarms
• Monitors websocket connection to each alarm and sets reachability status if socket is unavailable (Home Assistant UI reports "unknown" status for unreachable), automatically resends device state when connection is established
• Can monitor Home Assistant MQTT birth message to trigger automatic resend of configuration data after restart. The script will automatically resend device config/state 60 seconds after receiving online message from Home Assistant. This keeps you from having to restart the script after a Home Assistant restart.
• Monitors MQTT connection and automatically resends device state after any disconnect/reconnect event
• Does not require MQTT retain and can work well with brokers that provide no persistent storage

Possible future features

• Additional Devices (base station, keypad - at least for tamper/battery status)
• Base station settings (volume, chime)
• Arm/Disarm with code
• Arm/Disarm with sensor bypass
• Dynamic add/remove of alarms/devices (i.e. no service restart required)
• Support for non-alarm devices (doorbell/camera motion/lights/siren)

Debugging

By default the script should produce no console output, however, the script does leverage the terriffic debug package. To get debug output, simply run the script like this:

Debug messages from all modules

DEBUG=* ./ring-alarm-mqtt.js

Debug messages from ring-alarm-mqtt only

DEBUG=ring-alarm-mqtt ./ring-alarm-mqtt.js

This option is also useful when using script with external MQTT tools as it dumps all discovered sensors and their topics. Also allows you to monitor sensor states in real-time on the console.

Thanks

Much thanks must go to dgrief and his excellent ring-alarm API as well as his homebridge plugin. Without his work it would have taken far more effort and time, probably more time than I had, to get this working.

I also have to give much credit to acolytec3 on the Home Assistant community forums for his original Ring Alarm MQTT script. Having an already functioning script with support for MQTT discovery saved me quite a bit of time in developing this script.