-
Notifications
You must be signed in to change notification settings - Fork 116
Upgrading to v5.x
The 5.x release of ring-mqtt includes a number of changes that will likely require manual steps to return an upgraded system to a fully operational state. These changes are broken down below into configuration and functional changes so please read each section carefully to understand the differences.
The 5.x release of ring-mqtt uses the more flexible mqtt_url option to define the MQTT connection parameters vs separate options for MQTT host/port/user/password as in previous version. This option uses the standard MQTT URL format mqtt(s)://[username[:password]@]host[:port] which allows the required connection information to be specified as a single option. The port number is optional and, if not present, defaults to 1883 for non-encrypted connections (mqtt://) and 8883 for TLS encrypted connections (mqtts://).
There is also now an "mqtt_options" configuration parameter which accepts a comma separate list of advanced options that can be used for self-signed certificates, certificate based client authentication, or other advanced MQTT client options accepted by the MQTT.js library. See MQTT Advanced Options for more details.
The exact steps to adapt the configuration will vary based on the installation method. Select the installation method below to review the specific steps:
After making the required configuration changes review the functional changes section to learn more about important changes in behavior vs prior versions.
Upgrading to ring-mqtt v5.x will revert the MQTT configuration to use automatic MQTT service discovery with the default mqtt_url value of mqtt://auto_username:auto_password@auto_hostname. If automatic MQTT settings were working previously then this should lead to no changes and it's possible to simply remove the legacy MQTT settings and save the updated configuration. If manual MQTT settings were in use prior to the upgrade, those settings will require manual migration to the new mqtt_url format prior to removing the MQTT legacy settings. For example, if you previously had settings like this:
mqtt_host: 192.168.1.180
mqtt_port: 11883
mqtt_user: mqtt_user
mqtt_password: myMqttAuth
Then it will need to become the following:
mqtt_url: mqtt://mqtt_user:[email protected]:11883
Note that individual URL fields can be left at the default values to get automatic configuration for those specific fields. For example, to use a manual username/password with TLS enabled MQTT on the default port with the built in Mosquitto addon the following configuration is valid:
mqtt_url: mqtts://mqtt_user:myMqttAuth@auto_hostname
With this URL the hostname and port will be automatically detected via the HA services API, but the username and password will use the manually configured values.
Once all manually configured legacy MQTT settings have been migrated to the MQTT URL format they should be deleted from the options list and saved. Also, any remaining legacy configuration options such as snapshot_mode, beam_duration and ring_token should be removed from the configuration.
Previously, Docker installation of ring-mqtt used environment variables for configuration, however, with the release of v5.x this configuration method is deprecated. Docker installs now require a persistent volume to be mapped to the /data folder of the container (this was already highly recommended so will hopefully be common). On the first run of the 5.x version the existing environment variables will be used and a new config.json file will be written to the containers /data directory. During future startups this file will be read for all settings and any environment variables will be ignored (the DEBUG environment variable is the only exception to this).
While leaving these environment variables set will not cause any issues, it is recommended to remove the legacy environment settings after the creation of the config.json file.
When used with a manual local installation the existing configuration file will be read during startup and automatically updated, converting legacy MQTT settings to the new mqtt_url option and removing any legacy global options. This should happen automatically as long as ring-mqtt can write to the main ring-mqtt directory (this should already be the case as, in prior versions, this was how the ring token was stored for this install method). Also, standard installs will now create and use a ring-state.json in the same manner as other installation methods, for storing the authentication token, persistent systemId, and device state information.
Prior versions of ring-mqtt used a polling method to detect ding and motion events every 2 seconds. While this method was reliable, it was not as responsive as the push notification used for fast notifications in the Ring app and also was missing capabilities, such as the ability to get the UUID of the snapshot image included with those notifications. Starting with v5.x push notifications are now used for this, however this does introduce some changes of behavior:
- Push notifications to ring-mqtt use the same settings as the Ring app. If, for example, Smart Alerts are enabled and notifications for "Other Motion" events are disabled, these notifications will also not be received by ring-mqtt.
- For battery/low-power cameras which cannot take snapshots while recording, ring-mqtt uses the image UUID from the notification to retrieve the snapshot from Ring. This requires a Ring Protect subscription and for the Rich Notifications feature to be enabled.
Previously snapshot mode was a global configuration that applied to all cameras and, while the snapshot interval could be set per-camera, the interval would not be remembered during restart and had to be constantly reset. With 5.x the global option has been removed and the snapshot mode and interval settings are now configured per-camera and will be remembered across restarts. The default snapshot mode is now "Auto" which enables both interval and motion snapshots for high-power cameras, but enables only motion snapshots for low-power/battery powered cameras to avoid battery drain, however, any mode can be selected for any camera and settings will be remembered across restarts.
Prior versions of ring-mqtt provided a switch to enable a global arming bypass mode. When this switch was turned on any faulted sensors would be automatically bypassed during arming functions. This switch has been removed and the functionality replaced with a new "Bypass Mode Selector" on individual alarm sensors that allows selecting specific bypass behavior. The available modes for most sensors are "Never", "Faulted", and "Always" (motion and glassbreak sensors support only "Never" and "Always"). "Never" means a sensor will never by bypassed during arming, "Faulted" means a sensor will be bypassed if it is in faulted state during arming, and "Always" means the sensor will be bypassed during arming regardless of state. Please adjust any automations to take advantage of the new behavior.
Previous versions of ring-mqtt used the global setting beam_duration to set the duration Smart Lights would remain on when powered on via ring-mqtt. This value is now available on a per-device level and will be remembered as part of device state. The default value is "0" which means to use the default timeout or the last duration the device was turned on in the app.