-
Notifications
You must be signed in to change notification settings - Fork 111
Configuration Details
| Config Option | Description | Default |
|---|---|---|
| mqtt_url | URL for connecting to MQTT broker in standard MQTT URL format: mqtt(s)://[username[:password]@]host[:port]. Addon users leveraging the default Home Assistant Mosquitto integration should not need to change this value as connection details are discovered via the Home Assistant Services API, manually setting this will override this automatic discovery, but should not normally be required. For other users, replaces localhost with the IP/hostname of your MQTT server. Special characters in the username/password must be entered using percent encoding format. |
mqtt://localhost:1883 |
| mqtt_options | Comma separated list of options that will be passed to MQTT.js client library. Mostly useful for self-signed certificates or client side certificate authentication. See MQTT Advanced Options for more details. | blank |
| livestream_user | Specify a password for RTSP connections. Highly recommended if the RTSP port for external media player access is enabled. The livestream_password option must also be defined or this option is ignored. | blank |
| livestream_pass | Specify a password for RTSP connections. Highly recommended if the RTSP port for external media player access is enabled. The livestream_user option must also be defined or this option is ignored. | blank |
| disarm_code | Used only with Home Assistant, when defined this option causes the Home Assistant Alarm Control Panel integration to require entering this code to disarm the alarm | blank |
| enable_cameras | Enables support for cameraa/chimes, set to false to discover only alarm and smart lighting devices. Access to Chimes cannot be granted to shared users so Chime support requires use of the primary Ring account. | true |
| enable_modes | Enable support for Location Modes for sites without a Ring Alarm Panel | false |
| enable_panic | Enable panic buttons on Alarm Control Panel device | false |
| location_ids | Array of location Ids in format: ["loc-id", "loc-id2"], see Limiting Locations for details | blank |
The following options are only available for manual or Docker installs, but not with the Home Assistant addon:
| Config Option | Description | Default |
|---|---|---|
| hass_topic | The topic to monitor for Home Assistant restarts (MQTT birth/last will messages) | homeassistant/status |
| ring_topic | The top level topic for all device state and command topics | ring |
By default, ring-mqtt 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="). Locations IDs are also logged during addon startup as part of the initial device discovery.
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 and can be useful as to provide a still image for UI presentation of live/event streaming cameras as well. The snapshot mode can be configured 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. |
Any time snapshot support is enabled, the script always attempts to grab a current snapshot during 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 default 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.
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 bypass modes, while motion and glassbreak sensors do not support "Faulted" mode.
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.