HomeSeer HS4 Ring Plug In System User Guide
- June 1, 2024
- HomeSeer
Table of Contents
HomeSeer HS4 Ring Plug In System
Specifications
- Product Name: Ring Plug-In for HS4
- Compatibility: HS4
- Support Forum:
Online Forum Support
Getting Started
- Acknowledge the UELA by clicking on Plugins->Ring->Accept and reading the information before acceptance.
- Authenticate with your Ring service by entering your username, password, and any 2FA code if applicable.
- The plugin will retrieve your Ring account information and populate devices and features.
- On Windows, allow network access approval if prompted.
Important Notes
- Ensure that you do not post any proprietary information when sharing logs.
- If you encounter issues with live views, check browser] compatibility and codec support.
- For 2-way audio during live view, ensure an HTTPS connection or use MyHS for access.
Risk and Refunds
Understand that the plugin author has no relationship with Ring and changes in
Ring’s API may affect plugin functionality. Consider this risk before
purchasing as refunds may not be available.
Frequently Asked Questions (FAQ):
Q: What should I do if the plugin does not start automatically?
A: Acknowledge the UELA by clicking on Plugins->Ring->Accept and reading
the information before acceptance.
Ring Plug-In for HS4.
Go to https://forums.homeseer.com/forum/hs4-products/hs4-plugins/camera-plug- ins-aa/ring-dcorsus for on-line forum support! Please read the help file and take traces before you post questions on-line!
Introduction
Welcome to the HS4 compatible version of the Ring Plugin.
If you run into an issue or have a question, when you post on the forum, what
is required is:
- Recreate the issue with debug logging on, typically the log level set to “errors and events” is sufficient.
- Log to disk! It is easy and makes sure that all info is present as using the HS log to cut/paste loses HTML tag information.
- Post screen shots of your configuration, i.e.. HS device page.
Detail what exactly you are doing and what exactly is not working.
READ THIS FIRST!!
- The Plugin does NOT start automatically when you start if for the first time, you MUST acknowledge the UELA. Click on: Plugins->Ring->Accept and read the information before you accept.
- Next thing you will need to do is to authenticate yourself with your ring service. You do this on the config screen by entering your username and password. If you have 2FA (2 Factor Authentication) active (if not you should), a code will be sent to your email account on file or your cellphone. Enter that code into the pop-up window.
- The PI will now retrieve your information from your Ring account and start populating devices and features.
- If you are on Windows and you see a window popping up requesting approval for the PI to access the network, do allow.
- Note that the author of this plugin has no relationship with Ring and that Ring can change its API at any time, which could render this plugin useless. Do consider and agree to that risk before buying, there will be no refunds if that were ever to happen.
- The Ring API exposes quite some proprietary information. When you post logs, make sure there is nothing proprietary in them. In case of doubt, PM me (personal message on message board) with the debug log information.
- If you have a new, apparently unsupported Ring device, the first thing I will ask you is to “capture” the information published by Ring for your set-up. If you want help, you can optimize the process by going to the settings->Debug and click on that “Capture” button and PM me the log file with a description of what you added.
- Ring has some support for 3rd party devices (example Car Camera), they tend to have therefore also no support via their API and this plugin cannot manage them.
- The PI allows live views BUT not all permutations of browsers versus platforms will work. If the right codecs are not installed or supported, the live view will not work. Before posting check your ring.com account from the same browser on the same platform and if you cannot use the ring.com app to see live view, neither can this plugin!
- . For 2-way audio to work during live view, browsers ONLY allow this to happen on an HTTPS (or localhost) connection. HS does not support native HTTPS access; your options are limited. Either access is local (localhost), or you have managed to install certificates and can do HTTPS access or you go through MyHS.
A bit about Ring’s API
Ring groups their products into families of “similar kind”. For example, there
will be:
- Doorbots: cameras, floodlights, doorbells …
- .Chimes
- Stick-up Cameras
- Base Stations (Alarm systems)
- Beams and Beam-Bridges (lights)
- Other: 3rd party devices such as a car camera ..
- Depending on the Ring device “kind”, this plugin will create a HS-device with a different feature set depending on its “kind”. Moreover, there is a very distinct difference between these families when it comes to events.
- This is important because cameras & doorbells (doorbots) cannot generate autonomous events so the plugin will have to periodically check for status changes.
- Alarm systems on the other hand are controlled with an always-on websocket based connection and any change is immediately received by this plugin.
- Consequently, under settings you will find a set of timer settings to define the periodicity for polling doorbots.
- I would recommend you do not change the default settings but note that you can and defining larger periods will on average make the plugin react slower to doorbot changes.
HS Devices
This plugin will create an HS device for each Ring device it discovers.
Discovery is NOT a local network activity; it is performed by querying your
Ring account. Therefore, discovery cannot work unless you have authenticated
yourself, neither can it work if your network is unable to connect to the Ring
Servers. Note that this plugin ONLY communicates with the Ring Servers, no
information can be retrieved directly via the local network from any of the
Ring Devices, this includes Ring Live Video Streams.
The plugin automatically creates devices and features. If you need to
‘refresh” a device or feature, say, a newer version of the plugin added some
more states, you can delete a device at any time but you can only delete a
feature while the plugin is running. The feature recreation applies to all
alarm devices’ features but not to camera features. If you restart the plugin
or click on “Refresh Devices’ Info” (Settings->Debug), the missing device(s)
or feature(s) will be recreated. If you deleted a feature while the plugin is
not running or in case of camera devices, that feature will not be recreated
unless you delete its device and have the device recreated by the plugin.
The Ring Master Control device
The plugin at startup will always create this device, there is only one and it represents the overall and common parts of the plugin. The first two features represent critical status of this plugin to function:
- Account Cloud Status: Indicates whether the plugin can communicate with the Ring server or not. If Offline, this plugin is not doing anything at all!
- Authenticate: this feature indicates whether the plugin is properly authenticated, if the status is not “Authenticated” go to the plugin Settings page and under the “General” tab, enter your Ring credentials. If this is the first time or perhaps you have been locked out, you need to “fully authenticate”, which means that the Ring Servers will send you a token/code you need to use to do the two-step authentication. If you have authenticated before and your account is still OK, typically a “re-authentication” will suffice and there will be no need to enter tokens/codes. In case of doubt, click on “Fully Authenticate Ring Client”.
Depending on your Ring configuration, if you have alarm hubs or light beam
hubs, this plugin will create additional features. For each location a
“Location Websocket Status” feature will be created. The status of that
feature shows whether the communication for that location is Online or
Offline. If Offline, no status changes will be received and this could be
caused by network issues or Ring Server issues, Authentication issues. If it
persists, first try to restart the plugin just to rule out plugin issues.
If the location has an Alarm Hub (as opposed to Beam), a “Location Mode
Status” feature will be created so you can use the “Arm” state of that
location for events or change its state.
There is also a “History Event count” feature, which allows you to download
all clips that are available on your Ring Account. A word of caution here,
each Ring Clip download easily takes 20 seconds of more, so downloading
hundreds or thousands of clips, will cause quite some load on the plugin, not
to mention, disk space requirements.
The Alarm Hub device
- For each alarm hub an HS device will be created that holds features that deal with the health of that Hub and/or features that related to the hub itself, such as the “arm state” or “siren state”.
- For each location that has an alarm hub, a permanent communication (WebSocket) will be established so any state changes will be received automatically and immediately. If your “Cloud Status” is not Online, then there will be any issue with the network, or the Ring Server and you will not receive any status updates!
- The “Failed Devices List” will have a list of all Ring devices that have failed, this is important because faulted devices may prevent you from arming your Ring alarm. The “Active Reminder List” shows which Ring devices you have “silenced” but are still in an active fault state.
- For the users who tend to leave debug logging on, the Ring servers will terminate the permanent communication channel to the plugin, about every four hours. The plugin will automatically re-establish a new connection.
The Camera or Doorbell device
The doorbell HS device allows the user to disable or enable all motion
detection, make a snapshot or create a live video clip.
A note of warning with respect to clips and video clips: The Ring API
implementation doesn’t seem to be very consistent. Depending on whether your
camera is battery fed or wired to power, its behavior could be quite
different. When on battery, the camera will preserve power by only allowing
periodic snapshots or videos. The plugin will attempt to make a new snapshot
or retrieve the next available snapshot. So depending on the camera, how it is
powered and network bandwidth, the result could vary quite a bit.
Video life snapshots tend to be 60 seconds long, so it will take a while
before the “Live View” feature status is updated. You should create an event
that triggers based on the value of that feature changing and use its value to
retrieve/display the clip. The value for the “Snapshot” or “Live View” feature
is based on a “relative” URL. You can do http retrievals by prepending the URL
with “http:
Indoor Stickup Camera
The camera features are nearly the same as the doorbell features except you might have a “Siren” or “Privacy Cover” feature.
Plugin Settings
Authentication Settings
Before you can do anything with this plugin, you must authenticate, using your Ring credentials. In your Ring App, you most likely have been forced to pick a Two Step Authentication, either by SMS, Email or Authenticator Application. The first time you authenticate or when you click on “Fully Authenticate Client”, a pop-up screen will appear.
You should have received a number from the Ring Server. The plugin doesn’t
care which form of Two Step Authentication was selected, but you need to enter
the code in this pop-up screen and click enter. A confirmation should pop-up
when successfully authenticated.
After the authentication, the plugin will have received a special token that
enables access to your Ring devices. This token will have a limited lifetime,
but the plugin will automatically renew it before it expires and there is no
need for any Two Step Authentication.
However, if the plugin has been disabled for an extended period or perhaps
you’ve had network issues over a prolonged period, you may find the plugin’s
authentication state as “not Authenticated”. In this case click on the
“Reauthenticate Ring Client” button first, if that doesn’t solve the problem,
click on “Fully Authenticate Ring Client”, which will have you go through the
two Step Authentication. You should always check your HS log for errors or
warnings. Excessive reauthenticating could lead to your account being locked
for a while.
Timer setting related to camera-based devices
As of version 1.0.1.2 the plugin will subscribe to Fire Based Messages (FCM) and receive events autonomously for camera devices when motion or dings are detected. This requires Node.JS to run a slew of applications. All these applications are compiled into one single executable and this executable will be started automatically. This will be the default setting going forward. However, if you experience missing events there are 2 known reasons why the plugin might not receive them:
-
If you enabled “Smart Alerts” (click on Motion Settings->Smart Alerts) you must enable the notifications as part of the motion zones.
-
There have been cases where no notifications are received unless the authorized user list is cleared. NOTE: you will have to do a full authorization again (click on Account Settings -> Authorized Client Devices -> Remove all Devices)
In addition to using notifications, which are fast, the plugin will also poll
for changes. I decided to do both polling and notifications, to avoid lengthy
trial and error sessions with users where we just can’t get the notifications
to work. Polling will be just slower.
The next paragraph only applies to system with “Use Push Notifications”
disabled.
For any Ring device that has a camera, the Ring API has default autonomous
notifications (only FCM based) of events, hence the plugin will query for
changes. There are three configurable periods if you feel the need to make
changes. I would recommend not changing the default values but note that the
option exists.
- Ding Check Period:
- In Ring API parlance, an event on a camera-device, be it motion or a press on the ring button is called a “Ding”.
- With the introduction of notification events the new default is 10 sec. The start of a new event will be received via FCM Push Messages. However, there is no “Off” notification so the plugin will still have to poll the end of the event (end motion).
- If you make this period longer, it will just take the plugin longer to update ring and motion state related features.
- Device Status Change Check Period: whilst the “Ding” timer checks (only) for ring and motion, this timer will check for other changes, examples are battery levels, communication status etc.
- History Check Period: this is the frequency when the plugin will check for new video clips available on the Ring server. If you are not interested in downloading these clips you could make this value much larger.
Count settings
This section mostly deals with counters to make the plugin’s overall performance more efficient.
- Maximum History Entries: if you tend to never delete video clips on your Ring account, or you have a lot of recorded events each day, retrieving that information could take a long time or potentially fail due to too large a message. You would notice this the most when you go to the “Settings->History” tab and find your browser unresponsive for a large period.
- Maximum # of http fails, and connection retry time settings tend to go together. The plugin will set its “Account Cloud Status” to Offline based on the configured number of allowed fails. If you have a bad connection, you could increase this value, but it would be better to fix that connection. Once the plugin goes off-line, it will reattempt to connect to the Ring server periodically, based on the setting here.
Videoclip Settings
The plugin has the option to automatically download any new video clips it discovers on your Ring account. This could be the preferred option for users who prefer to permanently store all video events. However, this could lead to huge disk space requirements so use this option wisely.
There is an option to store the video clips in a different location, perhaps a
NAS or some other form of large storage. It would require read-write access
for this plugin to that location to work and this needs to be a complete (not
relative) path.
Warning: defining a different directory location for your video clips most
likely will cause the built-in functions, to view and manage your History
(Settings->History), to fail.
HS4 has a built in HTTP webserver and its user accessible directory space is
based on
By default, the video info is in the html/Ring/videos subdirectory. The video (.mp4) filename has five parts:
Snapshot Settings
You can select what to do and where to put snapshots. When you select “Never” for “Select what Snaphot actions you want”, the plugin will not store any snapshot on the HS PC except when you instruct the plugin to take a snapshot through HS controls.
-
The default setting is “Only when motion events”. Any autonomous downloads of snapshots, in absence of a different path configured, will be stored in the html/Ring/snapshots subdirectory. You find a subdirectory per camera and that subdirectory is named after the camera ID. Snapshots will be put in the relevant subdirectories. Snapshots will not be overwritten, and you must delete them either manually (windows or Linux) or via the snapshot settings page.
In the html/Ring/snapshots directory, one snapshot per camera can be found here, and they are the latest snapshots. This snapshot will always be overwritten with the latest snapshot. The snapshot feature value on your HS devices will have the relative path value to that file so you can use it in events or HS Touch to show only the latest snapshot. -
The filenames are composed of 6 parts separated by a _ character.
-
If you select “Periodic & motion”, based on the value setting in “Retrieve snapshots periods in seconds”, the plugin will attempt to generate a snapshot for each camera and subsequently retrieve them. However, the Ring implementation appears very inconsistent and often, cameras ignore a command to make a snapshot and the only thing to work around it, is to retry, and for quite a long period.
-
If you don’t instruct cameras to make a snapshot, cameras tend to do it by themselves. The periodicity is very different whether the camera is on battery or connected to power. The “When auto generated & motion” selection will just download snapshots as the camera makes them by itself.
Debug Settings
You can set here the debug log level and whether you want it logged to disk. Note that the checkmark for logging to disk works as a “toggle”, so if you enable it, it will overwrite any existing file, so if you want to erase a log file, checkmark off/on and it will create a new log file. If you do take a log, don’t forget to uncheck the log to disk to make sure all information is properly written through.
Very important to debug, especially unsupported Ring devices, is the “Capture” function. When you click it, the plugin will retrieve all relevant information from the Ring server and store it in a disk file in JSON format. Important is not to edit this file, else it will be possible to “read” the JSON information. Also of extreme importance is that this file will contain proprietary information, so don’t post it on the forum, send it to me as a Personal Message.
If you deleted features or devices and you want them recreated, you can either
restart the plugin or click on “Refresh Devices’ Info”.
If you have an Alarm Hub, the Hub communicates with all its devices using
Z-Wave. You can here display some of the information published by the Ring
API.
History management
The plugin has the ability to download snapshots and videoclips. Read the
respective chapters on where and how these files are stored. These files are
never automatically deleted from your system hence the history management page
provides the necessary tools for you to manage your files. There is an option
to manage camera files or snapshots. You can also pull up the event log for
Alarms or Lights but here there are no options to delete anything.
- A few things to know, snapshots are not accessible on your Ring account, at least not for the user to browse them like videoclips. So, the snapshots you see under the History management screen are locally stored .jpg files.
- Videoclips are different, they are on your Ring account (assuming you have a proper subscription plan) and you can browse and manage them using the Ring App.
- By default, the plugin does not download video clips, so when you pull up the camera history, the entries you see are a combination of what is stored on your local HS PC and what Ring has stored for you.
The following is a typical entry in the camera list
The empty checkmark box allows you to select multiple entries and use the Bulk Action function to perform actions on all these entries.
Indicates that a video is available on your Ring account, and you can download
a copy to the HS PC.
Allows you to delete the video from your Ring account. If you had previously
downloaded a copy to your local HS PC, that copy will remain untouched.
The Erase function will remove everything locally and on your Ring account.
If you downloaded a video, you would typically see an entry as follows:
If you click on the greyed part, a screen will appear, and your video will
play.
Because there is now a local copy, the cloud download icon is replaced with a
file delete icon. If you click on this, the local file will be deleted but the
cloud video is still available and you can download it again, if you desire to
do so.
If you deleted the video from your Ring account but there is still a local
copy available, the file delete icon will be colored in red.
When a motion event causes your Ring device to make a video clip, the plugin
will automatically try to take a snapshot. This snapshot is stored together
with the video clips and is used to show a picture in the list even though you
might not have downloaded the video. Therefore, if you deleted the cloud copy
and deleted the local video, you will still see the Erase icon, which will
subsequently also delete the local snapshot.
History management
It would have been much harder to develop this plugin without the work done by
others. Specifically, @dgrief and @tsightler GitHub contributions were very
helpful. To use push notifications, this plugin makes use of Matthieu
Lemoine’s push receiver. For live views the plugin uses werift-webrtc
by@shinyoshiaki. My thanks for their open-source contributions.