Home
The ring-mqtt project acts as a bridge to allow Ring alarm, camera, and smart lighting devices to be monitored and controlled via simple MQTT messages thus enabling integration with automation tools that can leverage the open standards based MQTT protocol. Video streaming is also supported by providing an RTSP gateway service that allows any media client supporting the RTSP protocol to connect to a Ring camera live stream 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 which communicates with Ring devices via the same API used by the official Ring apps. For video streaming ring-client-api establishes at WebRTC session and makes the stream available locally via go2rtc and will automatically start and stop the stream on-demand when any RTSP client is connected.
Home Assistant style MQTT device discovery is supported which allows for easy integration with minimal configuration (requires the Home Assistant Mosquitto/MQTT integration to be enabled and working properly). For those using Home Assistant OS, or other supervised Home Assistant installations, the sister Home Assistant Addon project allows easy installation of the official ring-mqtt Docker image via the native add-on store capabilities (not HACS).
For users of Home Assistant OS or Home Assistant Supervised, it's recommended to use the Home Assistant Addon installation method. For all other users, the Docker installation method is highly recommended. While it is possible to install this code locally on any Linux system, this requires manually satisfying pre-requisites, configuring systemd unit files, registering the service, etc. While the manual installation method covers these steps at a high level, this method is no longer regularly tested so leveraging this method will mostly leave users to solve problems with versions and dependencies on their own.
Home Assistant Addon Install <-- For users running Home Assistant OS or Home Assistant Supervised
Docker Install <-- Fully supported and highly preferred
Manual Install <-- Possible, but largely self-supported
Note: This project supports only Linux platforms and will not run properly on Windows!
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 others and there are significant functional side effects to doing so, most notably loss of motion/ding events while streaming (Ring cameras only send alerts when they are not actively streaming/recording). While you are of course welcome to use this project however you like, questions about use of such tools, or issues opened about these tools, will be locked and deleted.
- 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
- Volume Control
- Battery level
- AC/Charging state
- Proximity sensor as motion sensor (requires keypad LED Settings of "Keep Mode Button Lit" or "Motion Turns on Lights")
- 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
- Alarm Control Panel
- Ring Camera Devices (must set "enable_cameras" config option to "true")
- 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, must set "enable_cameras" config option to "true")
- 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
- Ring Intercom (must set "enable_cameras" config option to "true")
- Ding state
- Lock state
- Unlock door
- Device info sensor with detailed state information such as (exact info varies by device):
- Battery level
- 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 option
- Alarm Devices
- 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
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-mqttExample for Standard Install
DEBUG=ring-mqtt ./ring-mqtt
Many thanks to @dgreif and his excellent ring-client-api API without which this project would not be possible as well as the excellent homebridge plugin from which I learned a ton, especially in the early days of this project. 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 the initial development of this script.