Skip to content
tsightler edited this page May 10, 2022 · 45 revisions

ring-mqtt-logo

Overview

The ring-mqtt project acts as a bridge between alarm, smart lighting and camera devices sold by Ring LLC and an MQTT broker thus allowing any automation tools that can leverage the open standards based MQTT protocol to monitor and control these devices. The project also supports video streaming by providing an RTSP gateway service that allows any media client supporting the RTSP protocol to connect to a Ring camera livestream or to play back recorded events (Ring Protect subscription required for event recording playback). Please review the full list of supported devices and features for more information on current capabilities.

The code is written primarily in JavaScript and leverages the excellent ring-client-api for communicating with the same REST API used by the official Ring apps. For video streaming ring-client-api establishes the RTP steam via a SIP session and forwards the packets to an FFmpeg which publishes the stream via RTSP to rtsp-simple-server.

Home Assistant style MQTT discovery is supported which allows for easy integration with minimal configuration (requires the Home Assistant Mosquitto/MQTT integration to be enabled). For those using Home Assistant OS, or other supervised Home Assistant installations, there is a sister project providing a Home Assistant Addon which allows installing Ring-MQTT directly via the native add-on store capabilities (not HACS).

Installation

Docker is the recommended installation method. While it's completely possible to install this code manually as a service on Linux, it requires manually satisfying pre-requisites, copying systemd unit files and registering the service, etc. I do not test the standard install method so if you go with this method you are mostly on your own to solve problems with versions and dependencies. Note that this project supports only Linux platforms and will not run properly on Windows. Please read the documentation for your preferred install method below for details on the require installation steps and configuration:

Addon Install <-- For users running Home Assistant OS or Home Assistant Supervised

Docker Install <-- Fully supported and highly preferred

Advanced/Manual Install <-- Possible, but you will be largely on your own

Camera configuration

Please read the detailed video streaming documentation for more information on configuring cameras for streaming of live and recorded events.

!!!! Important note regarding camera support !!!!
The ring-mqtt project does not turn Ring cameras into 24x7/continuous streaming CCTV cameras. Ring cameras are designed to work with Ring cloud servers for on-demand streaming based on detected events (motion/ding) or interactive viewing. Even when using ring-mqtt, all streaming still goes through Ring cloud servers and is not local. Attempting to leverage this project for continuous streaming is not a supported use case and attempts to do so will almost certainly end in disappointment, this includes use with NVR tools like Frigate, Zoneminder or motionEye as well as others.

MQTT Topics

MQTT topics are built consistently during each startup. The easiest way to determine the device topics is to run the script with debug output. More details about the topic format for all devices is available in Device MQTT Topics.

Supported Devices and Features

  • Full support for 2FA including embedded web based authentication app (addon and standalone installs only, Docker includes a simple CLI)
  • Supports the following devices and features:
    • Alarm Devices
      • Alarm Control Panel
        • Arm/Disarm actions
        • Arm/Disarm commands are monitored for success and retried automatically
        • Automatic and manual sensor bypass when arming
        • Alarm states:
          • Disarmed
          • Armed Home
          • Armed Away
          • Arming (exit delay)
          • Pending (entry delay)
          • Triggered
        • Disarm code support for Home Assistant (optional)
      • Base Station
        • Volume Control (only when using Ring primary account)
        • Panic Switches (same as panic sliders in Ring app, Ring Protect Plan is required)
        • Siren Switch
      • Keypad
      • Ring Contact and Motion Sensors
      • Ring Flood/Freeze Sensor
      • Ring Smoke/CO Listener
      • First Alert Z-Wave Smoke/CO Detector
      • Ring Retro Kit Zones
      • Ring Range Extender
      • Ring External Siren
      • 3rd party Z-Wave door locks (Wi-Fi based locks integrated via Amazon Key are NOT supported as they use a completely different API)
      • 3rd party Z-Wave switches, dimmers, and fans
      • 3rd party Z-Wave motion/contact/tilt sensors (basic support)
      • 3rd party Z-Wave thermostats and temperature sensors
      • 3rd party Z-Wave sirens
      • Battery Level (for devices that support battery, detailed data in entity attributes)
      • Tamper Status (for devices that support tamper)
      • Device info sensor with detailed state information such as (exact info varies by device):
        • Communication status
        • Z-Wave Link Quality
        • Serial Number
        • Firmware status
        • Device volume
    • Ring Camera Devices
      • Motion Events
      • Doorbell (Ding) Events
      • Lights (for capable devices)
      • Siren (for capable device)
      • Snapshots (images refresh on motion events or scheduled refresh interval).
      • Live video streams via RTSP (streams start on-demand or can also be started via MQTT, for example to record based on events from other devices)
      • Recorded event streams via RTSP (playback of last 5 motion/ding recorded events selected via MQTT)
      • Battery Level (detailed battery data such as charging status and aux battery state in attributes)
      • Wireless Signal in dBm (Wireless network in attributes)
      • Device info sensor with detailed state information such as (exact info varies by device):
        • Wireless Signal
        • Wired Network Name
        • Firmware Status
        • Last Update Status
    • Ring Chimes (requires using Ring primary account)
      • Volume Control
      • Play ding/motion sounds
      • Enter/Exit Snooze Mode
      • Set Snooze Minute (must be set prior to entering snooze state)
      • Wireless Signal in dBm (Wireless network in attributes)
      • Device info sensor with detailed state information such as (exact info varies by device):
        • Wireless Signal
        • Wired Network Name
        • Firmware Status
        • Last Update Status
    • Smart Lighting
      • Lighting and motion sensor devices
      • Light groups (requires using Ring primary account)
      • Light duration (set per-device)
      • Device info sensor with detailed state information (exact info varies by device)
    • Location Modes
      • For locations without a Ring Alarm, can add a security panel style device for controlling camera settings via Ring Location Modes feature
      • Displays as an Alarm Panel in Home Assistant for setting modes and displaying mode state
      • Must be explicitly enabled using "enable_modes" config or ENABLEMODES environment variable
  • Full Home Assistant MQTT discovery and device registry support - devices appear automatically
  • Consistent topic creation based on location/device ID - easy to use with MQTT tools like Node-RED or other home automation platforms with MQTT support
  • Support for multiple locations
  • Monitors WebSocket connection to each alarm and sets reachability status if socket is unavailable (Home Assistant UI reports "unknown" status for unreachable devices), automatically resends device state when connection is established
  • Monitors MQTT connection to trigger automatic resend of configuration and state data after restart/disconnect
  • Monitors Home Assistant MQTT birth messages to trigger automatic resend of configuration and state data after Home Assistant restart
  • Does not require MQTT retain and can work well with brokers that provide no persistent storage

Additional Feature Details

Snapshot Options

Ring-mqtt has the ability to take still image snapshots based on motion events or at specific intervals. These images can be automatically displayed in many home automation platforms, such as Home Assistant, via a camera entity/device. Please note that these are not live action as MQTT is limited in this regard, however, even these snapshots can be quite useful. The snapshot mode can be set per-camera and will be remembered as part of the device state, the following modes are available:

Mode Description
auto This is the default behavior and is designed to optimize based on high vs low-power Ring devices. For high-powered devices (most line-powered devices) this enables both interval and motion snapshots. For low-powered devices (generally battery powered devices, but also some lower-end wired doorbells) this mode defaults to only motion snapshots to avoid any additional power drain by default.
motion Snapshots are refreshed only on detected motion events
interval Snapshots are refreshed on scheduled interval only.
all Snapshots are refreshed on both scheduled and motion events. Interval snapshots are paused during active motions events.
disabled No snapshots are taken for this camera in any case.

When snapshot support is enabled, the script always attempts to grab a snapshot on initial startup.

When any mode includes interval snapshots the default interval is selected as follows:

  • For high-powered devices (most line-powered cameras and higher end wired doorbells) snapshots default to every 30 seconds
  • For low-powered devices (battery/solar powered and some lower end wired doorbells) the code attempts to detect the snapshot interval configured for the Snapshot Capture feature in the Ring app and uses that interval or, if this value cannot be determined, default to 600 seconds.

The snapshot interval can be set manually per-camera and these setting will be persisted in the state file to be used during future startups.

Note that low-power mode cameras have significant limitations with regard to their snapshot capabilities and these limitations impact the ability to acquire snapshots in all cases. These cameras are unable to take snapshots while they are recording or live streaming and thus rely on a special image UUID which is part of the push notification. This feature requires a Ring Protect plan and rich notifications must be enabled. Also, if any smart notifications are enabled to reduce notifications to the Ring app, then ring-mqtt will also be unable to get those notifications as it depends on the same notification settings. You can potentially work around this by using a separate account on the phone vs ring-mqtt with different notification settings.

Sensor Bypass

Each alarm sensor includes a bypass mode selector that allows the bypass behavior to be set for each sensor individually. The three possible modes are as follows:

Mode Description
never The sensor will never be bypassed, if sensor is faulted it will prevent arming. This is the default behavior.
faulted The sensor will be automatically bypassed if it is faulted during an arming attempt.
always The sensor will be bypassed during an arming attempt, regardless of its existing state.

The contact, zone and tilt sensors support all three modes, while motion and glassbreak sensors support only the Never and Always modes.

Limiting Locations

By default, this script will discover and monitor enabled devices across all locations to which the specified account has access, even shared locations. During startup all locations must be initially online or the script will wait forever until those locations are reachable. To limit monitored locations it's possible to create a separate account and assign only the desired resources to it, or to pass the specific location IDs using the appropriate config option. To get the location id from the Ring website simply login to Ring.com and look at the address bar in the browser. It will look similar to https://account.ring.com/account/dashboard?l=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with the last path element being the location id (the id is after "?l=").

Volume Control

Volume Control is supported for Ring Keypads and Base Stations. Note that Ring shared users do not have access to control the Base Station volume so, if you want to control the Base Station volume using this integration, you must generate the refresh token using the primary Ring account. During startup the system attempts to detect if the account can control the base station volume and only shows the volume control if it determines the account has access. This is a limitation of the Ring API as even the official Ring App does not offer volume control to shared users.

Debugging

Debug output is controlled using the DEBUG environment variable and leverages the terrific debug package. To get debug output simply set the DEBUG environment variable as appropriate. The debug message categories and the corresponding output are described below:

Category Description
ring-mqtt Startup messages and MQTT topic/state messages only for simple text based entity topics
ring-attr MQTT topic/state message for JSON attribute topics
ring-disc Full MQTT Home Assistant discovery messages (for large environments can be quite wordy during startup)
ring-rtsp Messages from RTSP streaming server the video stream on-demand scripts

The default debug output for the Docker image, as well as the Home Assistant addon, is all categories (DEBUG=ring-*) but it is possible to override this by explicitly setting the DEBUG environment variable. For the standard installation, debug output is disabled by default. Multiple debug categories can be selected by combining them with a comma or by using wildcards. Below are some examples:

Debug messages from both simple topics and attributes topics
DEBUG=ring-mqtt,ring-attr

Enable all ring-mqtt specific debug messages (this is the most useful for debugging issues)
This option can also be useful when using the script with external MQTT tools as it dumps all discovered sensors and their topics and allows you to monitor sensor states in real-time on the console.
DEBUG=ring-*

Debug messages from ring-mqtt and all sub-modules (Warning, this extremely verbose and rarely needed!)
DEBUG=*

Example for Docker

docker run -it --rm --mount type=bind,source=/etc/ring-mqtt,target=/data -e "DEBUG=ring-*" tsightler/ring-mqtt

Example for Standard Install
DEBUG=ring-mqtt ./ring-mqtt

Thanks

Many thanks to @dgreif and his excellent ring-client-api API as well as his homebridge plugin, from which I've learned a lot. Without his work it would have taken far more effort and time, probably more time than I had, to get this working.

Also, thanks to acolytec3 on the Home Assistant community forums for the 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.