Ring MQTT: Do more with your Ring Products

What is Ring MQTT?

Ring MQTT also recently known as Ring Alarm MQTT, (but now greatly expanded beyond just alarm functions) integrates with the Ring app API and exposes the controls to a series of MQTT topics. If you’re new to MQTT check out some of our previous articles.

• What is MQTT?
• MQTT.fx: A Messaging Swiss Army Knife

So you’ve got some shiny new Ring products and the ability to control them all from an app is nice.  But what if you want to do more. For instance, what if you want to schedule overnight automatic arming/disarming or you want to monitor status from Node-Red or Home Assistant. Or if you’re like me and you want to use RFID cards to disarm and unlock your home. Well, thanks to a GitHub project from tisghtler called Ring-MQTT you can.

Supports the following devices:

Note the released version as of this writing is 3.0.1 and does not support Ring lighting. It is in development and may be available very soon. 3rd party sensors are also not supported at this time.

• Ring Branded Alarm Devices
  • Contact and Motion Sensors
  • Flood/Freeze Sensor
  • Smoke/CO Listener
  • Ring Retro Kit
• 3rd Party Alarm Devices
  • First Alert Z-Wave Smoke/CO Detector
  • Integrated door locks (status and lock control)
• 3rd party Z-Wave lights, switches, dimmers, and fans
• Ring Cameras
  • Motion Events
  • Doorbell (Ding) Events
  • Lights (for devices with lights)
  • Siren (for devices with siren support)

Installation

These instructions assume a Debian based operating system using the APT package manager. e.g. Debian, Ubuntu or Raspbian. They also assume a clean install of the OS so we will go through installing the pre-requisite packages.

Install Node.js

In order to avoid confusion and editing of most Node applications. I tend to install from nodesource.com as the built-in APT versions sometimes use a different executable name of nodejs rather than the default of node

Configure Repo

curl -sL https://deb.nodesource.com/setup_10.x | sudo bash -

The command above adds the key for NodeSource to your system. It also creates a source for APT, installs all the pre-requisites, and refreshes the APT cache.

Install node.js & npm

sudo apt-get install -y nodejs

Verify Install

node -v
 This will output something like ---  v10.19.0
npm -v
 Will output something like ---  6.13.4

Install git

If git is not installed you will need to first install it

sudo apt-get install -y git

Install Ring MQTT

This will install the package in a subdirectory of whatever directory you run the command from.  I generally install in my home directory but can you choose wherever you like. The example system service will need to be updated to reflect whatever path you chose.

git clone https://github.com/tsightler/ring-mqtt.git
cd ring-mqtt
chmod +x ring-mqtt.js
npm install

Configuration

Authentication

As of February 18, 2020 Ring requires two-factor authentication (2FA) for all logins. This script provides a utility for generating a long-lived token as a workaround. This token is needed to complete the config file so we will generate it first. From the directory where you installed Ring MQTT run:

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

It will generate output similar to this

In a browser go to http://<ip_of_server>:55123 and you will be presented with a login screen. Enter the username and password of a ring account associated with your devices. I recommend creating a separate account so that you can tell the difference between actions taken by your personal login and MQTT commands.

Upon successful username/password authentication, you will be presented with a screen to enter your 2FA code. Depending on how your Ring account is configured you will either receive an e-mail or a text message containing the code. Enter the code to continue.

On the next screen, you will be presented with a really long string of alphanumeric characters and symbols. Choose copy to clipboard and save it to a safe place for the next step.

You can now kill the debug session with a control-c key sequence.

Editing the config file

Now edit config.json with appropriate info for your environment

nano config.json

Edit the file with your info. It should look something like. Fill ring_token with the long string we generated in the previous step.

{
  "host": "192.168.1.4",
  "port": 1883,
  "ring_topic": "ring",
  "hass_topic": "hass/status",
  "mqtt_user": "mqttuser",
  "mqtt_pass": "mqttpass",
  "ring_token": "454354354359435ltjrlkgrenjglkjdfdgjglrkjg;lkfdjgdlkfjdlk;jg;lkdjg;lkfjlkfdhjfdlkgjdslkgjdflkgjfd;lkgjfdslkgjfdgfrdklgjdflkgjfdlkgjfdlkgjkjgdflkgjsdlkgjfdslkgjfdslkgjdflkgdjfg;lkfdjg;lkfdjg;lkfdjfd;lkjfdlkgjflkgjdfslkg9t8509w49tlkeds94tslkfsk",
  "enable_cameras": false,
  "location_ids": [""]
}

If you have cameras make sure to change enable_cameras to true. Otherwise, only alarm devices will be displayed.

Testing

At this point, we should be able to run the debug command again and get the output of our MQTT topics. Similar to below:

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

This will be followed by the publishing of many topics for each of your devices.

Configuring a systemd service to autostart Ring MQTT

A service file is included in this project. If you have installed it in the same location as me then it would look like.

#!/bin/sh -
[Unit]
Description=ring-mqtt

[Service]
ExecStart=/home/pi/ring-mqtt/ring-mqtt.js
Restart=always
Environment=PATH=/usr/bin/
Environment=NODE_ENV=production
WorkingDirectory=/usr/bin/

[Install]
WantedBy=multi-user.target
Alias=ring-mqtt.service

The primary difference between the version above and the included file is on the ExecStart line. The path to nodejs has been removed as it is in the path and the location of the script has been updated to reflect where I installed it.

Additionally, the User and Group lines have been removed as that user does not exist on my system and is un-needed for the function of this script.

You can now enable the service by running the following command from the install directory.

sudo cp ring-mqtt.service /lib/systemd/system/ring-mqtt.service
sudo systemctl daemon-reload
sudo systemctl enable ring-mqtt
sudo systemctl start ring-mqtt

Now check that the service started successfully with the command.

sudo systemctl status ring-mqtt

Successful output will show something like
● ring-mqtt.service – ring-mqtt
Loaded: loaded (/lib/systemd/system/ring-mqtt.service; enabled; vendor preset: enabled)
Active: active (running)

Ring MQTT is now installed and working.

Integrations and Interactions

Getting this project up and running is all well and good. But unless you interact with it in some way we’ve wasted our time. As should be clear from the name of the project. We are now able to interact with any tool that talks MQTT like Node-Red, but we’ll look at that in a minute. But one nice addition is the ability to automatically populate all the devices into Home Assistant with MQTT autodiscovery. As that will be the use case for the majority of users we’ll focus on that first.

Home Assistant Integration

Home Assistant auto-discovery topics are sent automatically by Ring MQTT. The only necessary configuration item is defining hass_topic in config.json. By default, it is defined as hass/status. Consequently, the majority of the configuration is done within Home Assistant’s configuration.yaml. There a few key items configured to make it work.

1. MQTT must be configured with the discovery option set to true.
2. A birth_message must be set with the topic matching hass_topic as defined in config.json
3. The payload of the topic must be online.

Using the example values we defined in config.json during the installation. A corresponding configuration.yaml setting would look like below.

mqtt:
   broker: 192.168.1.1
   username: mqttuser
   password: mqttpass
   discovery: true
   discovery_prefix: homeassistant
   birth_message:
     topic: 'hass/status'
     payload: 'online'
     qos: 0
     retain: false

So consequently, this configuration will now trigger a flow of actions causing Ring MQTT to send the device discovery information to Home Assistant.

1. First Home Assistant starts up and publishes online to the topic hass/status
2. Ring MQTT is subscribed to hass/status. As a result of seeing the payload online.
   1. It publishes the MQTT autodiscovery topics for each device
   2. In addition, it will do this multiple times to ensure all devices show up
3. Home Assistant’s autodiscovery services see all these topics and consequently adds the devices as entities in Home Assistant

As a result, you are now able to add these new entities to Lovelace or automation. For example, I use a simple glance card like this.

Discovering Control Topics for use with MQTT

What if you don’t use Home Assistant and just want to leverage the capabilities of MQTT in Node-Red or maybe even your own DIY projects?  Well unfortunately because the ring-alarm-mqtt bases the topics on your unique Ring location and device ID’s there’s no simple thing like a list of all the topics you can just view.

As noted previously Ring MQTT is publishing config topics with all the info you need. In a previous article, we talked about a powerful MQTT interaction tool called MQTT.fx. Here we can leverage an excellent feature called Topics Collector.  You can start the topics collector scan and wait for the Home Assistant config topics to show up. Or if you want to get them all right away you can publish a payload of online to the hass/status topic. In any case, you should get a batch of topics that look similar to below.

The topics follow a pattern of homeassistant/<device_type>/<location_id>/<device_id>/config

Double-clicking on a topic name will subscribe you to it. Different device types have different options available to them. Once a payload comes in you will get an output similar to below.

All devices have availability, state and attributes topics. Controllable devices like Locks, lights and the alarm panel also have command topics. The topics follow a pattern of

ring/<location_id>/alarm/<device_type>/<device_id>/<prefix>_state
ring/<location_id>/alarm/<device_type>/<device_id>/<prefix>_command

For example, a dimmer switch has the following topics available.

Current on/off state
     ring/<location_id>/alarm/switch/<device_id>/switch_state
 Current brightness level
     ring/<location_id>/alarm/switch/<device_id>/switch_brightness_state
 Turn on/off
     ring/<location_id>/alarm/switch/<device_id>/switch_command
 Set brightness level
     ring/<location_id>/alarm/switch/<device_id>/switch_brightness_command

Command Payloads

Lock: LOCK, UNLOCK

Alarm Panel: DISARM, ARM_AWAY & ARM_HOME

Light, Dimmer, Switch, Fan: ON, OFF

Dimmer Brightness: Numerics values 1-100

Fan Speed: high, medium and low

Command Examples

• To unlock a deadbolt
  • I would send a payload of UNLOCK
  • To ring/aac6dd5b-ad24/alarm/lock/01ed2464-cb80-4bed/lock_command
• To turn a fan on high
  • First I would send a payload of ON
  • To ring/aac6dd5b-ad24/alarm/fan/01ed2464-cb80-4bed/fan_command
  • Second I would send a payload of high
  • To ring/aac6dd5b-ad24/alarm/fan/01ed2464-cb80-4bed/fan_speed_command

Conclusion

So, to sum up, you can see that this bit of software can be a powerful extension to your Ring Alarm and Camera products. As a result, with its built-in integration with Home Assistant and the use of the common MQTT protocol. Ring MQTT allows endless integration options with tools like Node-Red or even your own DIY projects.

This article was produced as part of our ongoing series on MQTT and as part of a connected series on https://iotrant.com/