Ring (Doorbells & Cameras, Cloud)

GEM links to a Ring account through Ring's cloud service and discovers the doorbells and cameras registered to it. One GEM device represents one Ring account; after you sign in, GEM automatically creates a zone under the Cameras subsystem for every camera on the account.

This is a cloud integration — there is no LAN/local path to the cameras. The GEM server needs outbound internet access to reach Ring, and the link is authorized once through Ring's two-factor sign-in, after which GEM keeps itself signed in by rotating a stored token.

What this driver does today

This integration authenticates to Ring, discovers the cameras on the account, and auto-creates a camera zone for each one (and keeps that account signed in). It does not currently feed live Ring video or snapshots into GEM's camera viewer, and it does not raise a GEM event when a doorbell is pressed or motion is detected. The created zones are discovery placeholders — useful for inventory, naming, and account health — not live video tiles. For cameras you want to watch live inside GEM today, use a camera that exposes an RTSP/ONVIF stream on the local network (see ONVIF).

Prerequisites

• A Ring account with the doorbells/cameras already set up and visible in the Ring app. If a camera shows up in the app, GEM can discover it.
• The account's email and password, plus access to the account's 2FA delivery (the phone number or email Ring sends the one-time code to) during setup.
• Outbound HTTPS (port 443) from the GEM server to Ring's cloud.
• A subsystem whose name contains "camera" — the default Cameras subsystem satisfies this out of the box. Discovered cameras are placed here.
• FFmpeg on the GEM host (the FFmpeg Path attribute defaults to /usr/bin/ffmpeg). This is what Ring's client library uses to produce a stream; it is listed as a prerequisite for that capability, but note the live-video wiring described in the note above is not yet exposed.

Setup

1. Add the device

1. Open Devices and add a new device of type Ring.
2. Fill in Ring Email (username) and Ring Password (password). The password is stored encrypted.
3. Leave Refresh Token and 2FA Code blank — GEM fills these in for you during the next step.
4. Save the device. There is no host, IP, or port to enter — Ring is reached through the cloud.

2. Authorize the account (one time)

The first link uses Ring's two-factor sign-in. You start it from GEM and complete it by typing the one-time code Ring sends you.

1. Run the get_token command against the device — from the device's command list, the Commands screen, or the Script Console.
2. GEM immediately shows a text prompt: "Enter ring 2fa code".
3. Ring sends a one-time 2FA code to the account's phone or email. Retrieve that code.
4. Type the code into the prompt and confirm. GEM hands it to Ring, receives a refresh token, stores it in the read-only Refresh Token attribute, clears the 2FA Code field, and reconnects a couple of seconds later.

tip

The 2FA code expires quickly (about five minutes), and GEM only watches for it for roughly two minutes after you run get_token. If the prompt times out or you fetch the code late, just run get_token again to get a fresh prompt and a fresh code.

After the first authorization

GEM only needs the stored Refresh Token to reconnect on later restarts or reloads — you do not run get_token again. Ring periodically rotates that token; GEM catches each new value and saves it automatically, so the link survives indefinitely. Re-run get_token only if the account password changes or the refresh token is invalidated (for example, you removed GEM from the account's authorized sessions).

3. Cameras become zones automatically

As soon as authorization succeeds (and on every reconnect), GEM reads the cameras on the account and creates one zone per camera under the Cameras subsystem. You do not create these zones by hand.

• Each zone is named and labeled from the camera's description in the Ring app.
• The zone Address is set to Ring's internal camera id — GEM fills this in; you don't type it.
• If a camera's zone already exists, GEM refreshes its name/label rather than duplicating it.

4. Restrict to one location (optional)

If the Ring account spans more than one location (for example, a home and an office) and you only want one location's cameras imported here:

1. Run get_locations against the device to list the account's locations and their ids.
2. Set the device's Ring Location ID (ring_location_id) attribute to the id you want.
3. Reload the device. From then on, only cameras at that location are turned into zones; the id must match exactly.

Attribute reference

Device attributes

Attribute	Required	Type	Default	Notes
username	yes	string	—	Ring Email — the account sign-in email.
password	yes	string (secure)	—	Ring Password — stored encrypted.
refresh_token	auto	string (secure, read-only)	—	Filled in by get_token and rotated automatically. This is what lets GEM reconnect without re-authorizing — do not clear it.
two_factor_code	auto	string	—	Transient. Set by the get_token prompt and cleared once consumed; normally you never touch it directly.
ring_location_id	no	string	—	Ring Location ID — when set, only cameras at this Ring location are imported as zones. Get valid ids from get_locations.
ffmpeg_path	no	string	/usr/bin/ffmpeg	FFmpeg Path — path to the FFmpeg binary Ring's client library uses.
control_center_display_name	no	string	GEM	Control Center Name — the name shown for this GEM instance in the Ring Control Center's list of authorized devices.

Zone attributes

Camera zones are created automatically; you normally don't add zone attributes by hand.

Attribute	Set by	Notes
address	GEM	Ring's internal camera id, written when the zone is created. Don't change it — it's how GEM keeps a camera matched to its zone.

Commands

These target the Ring account device (not a camera zone). get_locations and get_cameras only work after the account is authorized — run get_token first.

Command	Args	Notes
get_token	—	Starts the two-factor sign-in. Pops the 2FA-code prompt and, once you enter the code, stores the refresh token and reconnects.
get_locations	—	Lists the account's locations, including the location id you'd put in Ring Location ID.
get_cameras	—	Lists the cameras the account exposes. Useful for confirming what GEM can see before zones appear.

How authorization works

• Sign-in. get_token opens a session with Ring using the email and password and asks Ring to send a 2FA code. The command returns right away and shows you the code prompt; in the background GEM polls for the value you type for about two minutes.
• Token storage and rotation. When you enter the code, Ring issues a long-lived refresh token. GEM stores it (encrypted, read-only) and uses it to reconnect on every later boot. Ring rotates this token over time; GEM listens for the new value and re-saves it, so you never have to re-authorize under normal operation.
• Discovery. With a valid token, each connect reads the account's locations and cameras and creates or refreshes a zone per camera under the Cameras subsystem, honoring Ring Location ID if you set it.

Current limitations

• Discovery, not live video. The driver authorizes the account and inventories cameras into zones, but does not currently push live Ring streams or snapshots into GEM's camera viewer. The created zones won't render a moving picture on their own. Live in-GEM viewing today comes from cameras that publish a local RTSP/ONVIF stream.
• No doorbell/motion events. A Ring doorbell press or motion event is not turned into a GEM notification, trigger, or attribute change. Use the Ring app's own alerts for those.
• No camera control commands. There are no on/off, snapshot, or pan/tilt/zoom commands for Ring zones — the command surface is the three account-level discovery commands above.
• Cloud only. Everything depends on reaching Ring's cloud; there is no offline/LAN fallback.
• One account per device. To pull in cameras from a second Ring account, add a second Ring device and authorize it separately.

Troubleshooting

Symptom	Check
get_token prompt appears but never completes	The 2FA code expires fast (~5 min) and GEM only watches for it for ~2 minutes. Run get_token again and enter the fresh code promptly.
No zones appear after authorizing	Confirm the cameras are visible in the Ring app for the same account. If the account has multiple locations, either clear Ring Location ID or set it to the location that actually holds the cameras (its id must match exactly — get it from get_locations).
get_locations / get_cameras returns an error	These only work after a successful get_token. If the device hasn't authorized yet (no Refresh Token), run get_token first.
Device stops working after a few hours	Ring rotates the refresh token; GEM should re-save it automatically. Confirm the Refresh Token attribute is changing over time (check its attribute history). If it isn't, re-run get_token.
Camera zones exist but show no live picture	Expected — see Current limitations. This driver discovers cameras into zones but does not feed Ring video into the viewer; live in-GEM viewing requires a local RTSP/ONVIF stream.

See also

• Devices — where the Ring account device is added and get_token is run.
• Zones — the camera zones GEM auto-creates under the Cameras subsystem.
• Subsystems — the Cameras subsystem that holds the discovered zones.
• Commands — where get_token, get_locations, and get_cameras are dispatched.
• ONVIF — for local-network cameras that stream live inside GEM.