-
Notifications
You must be signed in to change notification settings - Fork 101
Frequently Asked Questions (FAQ)
Q) Why is this a Home Assistant addon and not part of the official Home Assistant intregration
A) The ring-mqtt project is not Home Assistant specific and really has nothing to do with Home Assistant overall. When I started this project I was not even using Home Assistant and many users of ring-mqtt continue to leverage other tools, like Node-RED or OpenHAB or any other tool that can leverage MQTT. Someone else initially packaged ring-mqtt as a Home Assistant addon but then didn't maintain it and I eventually, although somewhat begrudgingly, agreed it was easier to maintain a semi-official ring-mqtt addon for Home Assistant vs having people using a poorly maintained 3rd-party addon and constantly opening issues about that addon here. While I have made efforts to make ring-mqtt integrate as easily as possible with Home Assistant, this project will never be an official part of Home Assistant, nor is that a goal, it does not even use the same programming language as Home Assistant.
Q) I want to be able to <insert random request not possible in the Ring app>
A) The goal of this project is to facilitate integration of devices in Ring's proprietary ecosystem with external systems via industry standard protocols, but it cannot fundamentally change how these Ring devices work. This project uses the same API which is leveraged by Ring's own apps so, if you can't perform a given function via the Ring app, it is unlikely to be possible with ring-mqtt.
Q) I want to be able to be able to control my devices locally rather than via the cloud
A) Then I suggest you sell your Ring devices and buy something else. Ring devices are, quite simply, designed as cloud powered devices, but there are plenty of devices from other manufacturers if you prefer local control. It is possible to use Ring Alarm sensors, which are mostly just generic Z-wave sensors, directly with other Z-wave controllers/sticks, but the base Ring devices all require the cloud and ring-mqtt does not change this, actually, quite the opposite, as ring-mqtt connects to the Ring Cloud API just like the Ring apps do. The Ring Alarm Pro does provide some local recording, which is supported by ring-mqtt, but it is still largely a cloud powered device.
Q) Why do I see high memory usage?
A) The ring-mqtt code is written in Javascript and runs in NodeJS, which isn't the most memory efficient environment to start with. The code depends on several other libraries which themselves have large dependencies. All of this code is parsed and loaded into process memory at startup so memory usage of the main process is generally around 250-350MB, depending on the number of devices, etc. During device discovery, an additional worker thread is started for each camera, which is typically another 20-30MB per device. For reference, I have tested with 8 cameras, and around 25 alarm devices and the ring-mqtt process hovers around 450MB of usage. When actively streaming there's typically another 15-25MB of usage per-stream.
When running as an addon it is highly recommended that your HA system have at least 2GB of RAM (this is a general recommendation of the HA community anyway). For systems with only 1GB of RAM, it might work if you have only alarm and smart lighting devices, or just a small number of cameras (1-3). If the addon fails to start on such a system you might be able to increase the default swap size to get it to work, but memory will be very tight, and you might see unpredictable behavior such as slower than expected stream startup, or not being able to stream at all. ..
Q) I want to able to trigger the alarm into pending or active state
A) This isn't possible via ring-mqtt just like it isn't possible with the Ring app. The ring-mqtt project uses the same API used by the Ring apps, if you can't perform a function in the app then it's unlikely to be possible via the API. When Ring Alarm is armed it triggers pending/alarm state based on the connected sensors, not based on some call to the API. The only exception to this is the panic sliders which are available in the Ring app, these can be optionally exposed via the ring-mqtt enable_panic config option but be aware that, as the name suggests, toggling these switches is considered a panic and will trigger immediate alarm and police/fire response and thus should be used with extreme care. As far as I know these switches require a Ring monitoring subscription to function.
Q) Why am I not receiving notifications that worked previously
A) Versions of ring-mqtt prior to 5.x used a polling method to detect events. While this method was somewhat slow and heavy handed, it was reliable and would detect all motion/ding events even if notifications for those events were disabled in the Ring app (although it would not detect if motion detection was completely disabled). The 5.x and later versions of ring-mqtt use ring-client-api v11.x which has removed the old polling interface and now relies on push notifications. Push notifications are much faster and very reliable, but if you use Ring app features such as Smart Notifications to restrict which notifications are received, this will also limit the events which get sent to ring-mqtt as well. If you want ring-mqtt to receive all notifications they must be fully enabled in the Ring app.
Q) What are "low-power" vs "high-power" cameras
A) This is more difficult to answer than it would at first appear. Ring cameras can operate in either "low-power" mode, which is commonly used for battery powered devices, or "high-power" mode, which is mostly for line or PoE powered devices. Some cameras can operate in either mode, for example, a stick-up Cam may support battery or line powered mode, or even have supplemental solar power. In general, if a device is powered by battery or a non-fixed power source (solar, for example) it is considered a low-power device. Doorbells which have a battery but "trickle charge" are low power, as is the low-end Video Doorbell Wired, even though it doesn't actually have a battery. The Video Doorbell Pro models are "high-power" devices, as are cameras powered by mains/house wiring such as Floodlight cams or powered via PoE, such as the Stick-up Cam Elite.
Q) What are the functional differences between "low-power" and "high-power" cameras
A) The primary difference is in capability to take snapshots. While "high-power" devices can take a snapshot at any time and will generally respond to a snapshot request in a few milliseconds, the "low-power" devices can take significantly longer to wake from low-power mode and to take a snapshot and, more importantly, cannot take a snapshot at all when they are recording/live streaming meaning that it's not possible to get a snapshot of motion events from these "low-power" device without a Ring subscription and enabling rich notificaitons. Taking snapshots on an interval with a "low-power" camera will use significantly more battery due to the constant wakeup from power-save mode, thus you should not use quick intervals for snapshots with low-power cameras that are exclusively on battery unless you are OK with more frequent battery swaps.
Q) Why am I unable to get motion snapshots from my camera
A) The most likely cause of this behavior is use with a "low-power" mode camera. These cameras cannot take a snapshot while recording and, since a motion event generally starts a recording, it's not possible to retrieve a snapshot after the motion event has been detected. Because of this, ring-mqtt attempts to use the image UUID included in the push notification to retrieve the notification snapshot (the same snapshot used in rich notifications on the Ring app) for motion events, however, this feature requires at least the basic Ring Protect Plan subscription. If the account has no subscription, or Rich Notifications have not been enabled for the device, then ring-mqtt will not be able to retrieve a snapshot image on motion.
Q) My streams were working fine but now fail with an error that says something about "Legacy Video Mode", what gives?
A) Ring has recently started, seemingly randomly, enabling HEVC/H.265 video codec for their cameras. Even more, when it does this, it doesn't even offer the older AVC/H.264 codec as part of the negotiation. Currently, ring-mqtt does not support codecs other than H.264 and, while it would be possible to add this support, it causes lots of issues as many downstream devices still don't support H.265 due mostly to licensing issues. That means that devices which work now would stop working, which would be confusing to users, or ring-mqtt would need to transcode the video, which requires high CPU usage and is less than ideal for many of the lower power devices ring-mqtt is run on. While some type of support for H.265 is likely in the coming months, for now the best option is to simply enable the Legacy Video Mode as documented on the Ring website. Note that ring-mqtt is not the only system which has this issue as the Ring forums are full of threads with various issues on devices like the Echo Show integration, just as an example.
Q) Why do streams keep running for ~5 minutes after viewing them in Home Assistant?
A) The Home Assistant stream component is not optimized for on-demand streaming. When you view a stream in the UI the stream component will keep the stream active for 5 minutes, even if you manually stop the stream it will just wait 10 seconds and reconnect. The best solution for this is to implement the RTSPtoWebRTC integration along with the Go2RTC addon which can provide fast startup and low-latency viewing and will generally stop the livestream within a few seconds.
Q) Streams keep starting all the time even when I'm not viewing anything
A) In Home Assistant, do not use the "Preload Stream" option and make sure the Camera View setting in the Picture Glance card is set to "auto" instead of "live". If you use the "live" setting, the card will attempt to start streams in the background for faster startup when you bring up the card. This is fine for local cameras but, because Ring cameras do not send motion events during streams, having streams running all the time will cause motion events to be missed and, since all streaming goes through Ring servers on the Internet, you will use a lot of bandwidth as well.
There have also been reports of certain components connecting to live streams with when no password is set on the RTSP server, I've not personally seen this behavior but multiple users have sent log examples showing "something" connecting to the RTSP server which triggers the stream to start. The simplest way to solve this is to set a livestream username/password so that services which automatically discover RTSP endpoints cannot connect and start streams.
Q) Why does the live stream stop after ~10 minutes even if I'm still viewing?
A) Ring enforces a time limit on active live streams and terminates them, typically after approximately 10 minutes, although sometimes significantly less and sometimes a little more. Currently, you'll need to refresh to manually restart the stream but it is NOT recommended to attempt to stream continuously as Ring cameras just aren't engineered for this use case and are subject to overheating and even premature failure.
Q) Why is the stream delayed/lagged?
A) The code path for streaming is highly optimized and typically adds only a few hundred millisoncds of total latency to the stream, however, Home Assistant uses the LL-HLS protocol for streaming in the web browser which splits the existing stream into segments for delivery over HTTP/HTTPS. While HLS streaming is extremely reliable and widely compatible with various web browsers and network setups, it typically adds 3-5 seconds of delay which is serviceable for live viewing in many cases, but not really ideal. Unfortunately, because of the way LL-HLS segments the stream for delivery over HTTP/HTTPS, it can lead to an increase in artifacts and video stuttering, see the question below on video artifact/stuttering for more details on possible mitigations for this behavior.
For the lowest latency viewing possible, the best solution for Home Assistant is to use the RTSPtoWebRTC integration in concert with the Go2RTC addon. This integration overrides the Home Assistant default use of LL-HLS and instead uses WebRTC, which leverages the native streaming capability available in modern web browsers. Testing has shown the RTSPtoWebRTC integration in concert with the Go2RTC addon gives the best front-end streaming experience with fast startup, low latency (<1 second) and relatively smooth display.
Other options that offer low-latency viewing are the use an external media player capable of RTSP playback. VLC works well, but note that by default it buffers 1 second of video, although on fast networks you can tweak this to as low as 0 milliseconds to reduce the delay even further.
Q) Why do I have video artifacts and/or stuttering in the stream?
A) There are three likely sources of artifacts/stuttering and I'll outline each of these below:
The first and most common issue is that Ring streams include a significant number of minor encoding anomalies, especially in the first 5-10 seconds of the stream. I initially thought this was a bug in stream handling pipeline but further investigation showed that the same anomalies exist in the video recording files downloaded directly from Ring servers, so it clearly indicates the error is in the initial stream encoding from the camera. These anomalies are overall minor and go largely unnoticed in media players that decode the H264 stream directly, however, they are amplified by the Home Assistant stream component which uses specific markers to split the RTP stream into the required HLS segments and this is even more troublesome for LL-HLS, which further chunks the streams into even smaller parts. The following settings have been found to minimize (not eliminate) the artifacts while keeping most of the benefit of the LL-HLS protocol (only a small increase in latency over the defaults):
stream:
ll_hls: true
segment_duration: 2.9
part_duration: 1.45
The second issue mostly impacts the live stream which uses WebRTC to stream encrypted RTP over UDP. WebRTC is normally handled natively by the web browser, however, ring-mqtt and ring-client-api (the API layer that makes ring-mqtt possible) is written in Javascript and runs in NodeJS, which, unfortunately, has no native WebRTC implementation. Instead, ring-client-api uses WeRIFT (WebRTC Implementation for TypeScript) which means that the entire RTP stream is processed in Javascript code before being piped via FFmpeg to the RTSP server. While NodeJS is quite fast for running an interpreted language like JavaScript, it's still not exactly the most efficient for real-time stream processing that requires per-packet decryption meaning significant amount of CPU is used per-stream.
While Intel CPUs seem to be able to keep up fairly easily, the story is not as good for low-power ARM CPUs, like those in devices such as the Raspberry Pi, which generally run NodeJS at 25% of the speed of even decade old Intel CPUs. Because of this, these systems sometimes struggle to process the stream without dropping packets, especially during initial stream startup. While I have put significant effort into optimizing the processing pipeline, including implementation for worker threads for the live stream itself, it's still very difficult for these lower end CPUs to keep up with the data rates.
Having a good CPU and a solid networking setup that does not drop UDP packets is critical to reliable and artifact free function of the live stream. If you have multiple cameras, or a system with limited CPU/RAM (RPi3 for example) then it will be difficult to support more than a handful of streams concurrently. Testing shows that an RPi3 struggles to support more than 2-3 concurrent streams without significant artifacts while an RPi4 can handle 4-5 concurrent streams before artifacts become a major issue. Intel based machines can handle ~3-4 live streams per-core, although this can vary significantly based on the processor type. These numbers assume that the load on the CPU from other components is minimal. Another way to look at it, once CPU load approaches 70%, artifacts begin to appear more frequently.
A third issue, which really is part of the second issue, is the limited size of the default UDP buffers in Linux which are usually only about 200KB. Even if WeRIFT can mostly keep up with the stream, small bursts of CPU activity can cause a delay in processing and, due to the small buffer size, packets end up being dropped before they are processed into the WeRIFT media pipeline. On lower end processors increasing the buffer size to something more reasonable like 2-4MB can make dramatic difference in stream reliability, especially with multiple concurrent streams. Unfortunately, since ring-mqtt is commonly run inside a container, it's not possible for the code to automatically increase these buffers as they must be increased on the host OS.
When running a Docker or manual install you can simply increase net.core.rmem_max/rmem_default values on the host OS using sysctl.conf or other supported methods for the given Linux distribution. This is more complex for those using the addon with Home Assistant OS, which doesn't even allow SSH access to the actual host OS by default. However, if you want to improve your video quality in this case it is possible to follow [these instructions] (https://developers.home-assistant.io/docs/operating-system/debugging/) to enable full SSH access to the host. Once rool level ssh to the host OS is possible (must be the real debug/developer console root, not the SSH console provided by some addons) you can then perform the following steps:
# cd /etc/udev/rules.d
# vi 99-local.rules
Copy and paste the following:
ACTION=="add", SUBSYSTEM=="net", RUN+="/bin/sh -c 'sysctl -w net.core.rmem_max=2097152'"
ACTION=="add", SUBSYSTEM=="net", RUN+="/bin/sh -c 'sysctl -w net.core.rmem_default=2097152'"
Save the file (:wq) and reboot the host, log back in and verify that /proc/sys/net/core/rmem_max/default are set to 2097152 (2MB) instead of the default (~200KB). This implements the update of UDP buffers as a UDEV rule because /etc/udev/rules.d is one of the few mount points that is persistent within Home Assistant OS and thus the changes made this way should survive reboots and future OS updates.
Q) Why are there no motion events while live streaming?
A) This is a limitation of Ring cameras as they do not detect/send motion events while a stream/recording is active. The code itself has no limitations in this regard.
Q) Why do I have so many recordings on my Ring App?
A) If you have a Ring Protect subscription then all "live streams" are actually recording sessions as well, so every time you start a live view of your camera you will see a recording in the Ring app.