Software and Over The Air Updates
It is highly desirable to be able to update and upgrade the software in your devices so you can deploy new features, patch security vulnerabilities and improve performance over time.
Via the Builder, you can define software updates for devices that will be managed and delivered Over-The-Air (OTA) to your devices.
Configuring Updates
Using the Builder OTA update manager, you can selectively deploy updates to any desired subset of your device population. Updates can be published that will be applied to your devices according to a distribution policy. In this way, you can selectively update all your devices or specific subsets as you require.
To configure a software update, you supply the following parameters:
- Product
- Update version
- Update description
- Distribution policy
- Device Cloud
- Update image
- GitHub commit reference
Update Selection
Each day, the device or update agent will connect to the device cloud for a "checkin". During this request, the agent will submit its update request to see if an update is available for this device.
The service will retrieve the most recent updates and check the updates in reverse version order and select the first matching update for the device.
The device cloud service will evaluate the distribution policy expression when the device checks-in and determine if the policy matches for the device.
Update Limits
Implementing a gradual update strategy can help minimize load and risk. Updating a large number of devices simultaneously can impose an excessive burden on your service, so staggering the rollout can distribute the load more evenly.
Despite thorough testing, some updates might still be considered "risky." To minimize this risk, you can update a small subset of your device population first to see if the update causes any issues.
The update service provides update limits and gradual rollout factors that allow you to control the rate of updates.
-
Max device limit and device percentage limits define the maximum number of devices that can be updated. Once either limit is reached, further updates are prevented.
-
For gradual rollouts, you can set a max updates per period, which limits the number of updates to a specified number over a defined period. For example, you could set a limit of 1000 updates per hour (3600 seconds).
If a device meets the distribution policy and rollout limits, the URL for the update image will be returned to the update agent. The agent will then fetch the update image and verify its integrity. If the image is verified, the scripts/update script is invoked to apply the update. If you are running the agent on an RTOS without scripting, you will need to monitor and respond to the device:update event using the rWatch API.
Product
When defining an update, select the product for which the software update applies. A device cloud may be managing many different products and the product selection in conjunction with the distribution policy defines the subset of devices that are eligible to receive the update.
You should define multiple product definitions if the different devices consistently require different firmware.
Software Version
The version number is your software release version number identifying this software release. The version numbers are compatible with the SemVer 2.0 version specification.
If you are using the Ioto agent, the current version for your device is defined via the version property in the config.json5 configuration file. NOTE: your device is versioned separately to the Ioto agent itself which has its own version string.
Software Release Description
The description is an informative description for your purposes.
Software Distribution Policy
The distribution policy is a simple Javascript-like expression that is evaluated at runtime to determine if the update is relevant for a specific device. If you leave the policy blank, then all devices whoes version is less than the software release version will be updated.
Here is a sample policy expression:
1 | |
The properties contained in the device.json5 configuration file are made available as variables. In this case, the "memory" and "ports" variables are supplied in the device.json5 file.
The full device version is accessible as the varible "version" and the software update version is provided via the "newVersion" variable.
The device version string is also split into SemVer components:
- major
- minor
- patch
The query language supports the operators:
1 | |
These extension operators have the following meaning:
- a ^= b means a starts with the string b
- a ^!= b means a does not start with the string b
- a $= b means a ends with the string b
- a $!= b means a does not end with the string b
- a >< b means a contains the string b
- a <> b means a does not contain the string b
Sub-expressions can be grouped with parenthesis and the boolean operators && and || can group conditional operands.
Regular expressions (delimited by slashes) may be used with the "==" and "!=" operators. The regular expression can be on either side of the operator.
The policy expression language understands the types: Numbers, Boolean, String literals, Regular Expressions and null.
The policy expression is run-time limited to evaluate up to 20 terms. This is to protect your cloud against denial of service attacks.
Opt-in Updates
Devices can implement an opt-in update strategy by defining variables in the device context that are passed with the update checkin request. These variables can be examined by the distribution policy expression. If a variable is set only when a device/user opts-in, then the distribution policy can target only those devices.
For example, say a device defined an opt-in field called try-beta-features that was set to "1" when users toggled a UI checkbox to signify they wished to receive beta features. The device would then pass this field with the update checkin request and the distribution policy could test that value.
1 | |
Rollback Updates
You can rollback errant updates by defining an update that has a distribution policy pinned to the errant version. For example, say the update 1.2.3 was bad and you wished to rollback devices to the prior 1.2.2 version. You would first disable the 1.2.3 bad update by deselecting the Enable checkbox for that update. Then, you would define an update 1.2.2 that had a distribution policy like this:
1 | |
This would target only the 1.2.3 devices and roll them back to version 1.2.2.
Device Cloud
Update images are stored in AWS S3 in your device cloud AWS account. When defining updates, you select the relevant device cloud to store and apply the updates. If you have multiple clouds, you will need to define updates in each cloud.
Applying Updates
When the update is downloaded to the device and verified, the update agent will save the update in a temporary file. Your device can be notified of an update by one of two means:
- The "./script/update" shell script will be invoked and passed the filename of the update.
- Ioto will indicate an update is available via the "device:update" signal. See rSignal/rWatch for details.
Enable
You can selectively enable or disable a release at any time via the Builder.