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 Ioto based devices that will be managed and delivered Over-The-Air (OTA) to your devices.
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:
- Update version
- Update description
- Distribution policy
- Device Cloud
- Update image
- GitHub commit reference
Each day, the Ioto agent will connect to the device cloud for a "checkin". During this request, the agent will submit its device.json5 contents to the device cloud to see if an update is available for this device.
The Ioto 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 if the policy matches for the device, the URL for the update image will be returned to the Ioto agent. The agent will then fetch the update image and verify the integrity of the update image. If 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 watch and react to the the event device:update using the rWatch API.
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.
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.
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
Here is a sample policy expression:
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:
The query language supports the operators:
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.
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.
GitHub Commit URL
For reference, you can define the GitHub commit URL, Git commit hash or tag to associate with the update.
When the update is downloaded to the device and verified, the Ioto agent will save the update in a temporary file. Your device can be notified of an update by one of two means:
- Ioto will invoke the "./script/update" shell script
- Ioto will indicate an update is available via the "device:update" signal. See rSignal/rWatch for details.
You can selectively enable or disable a release at any time via the Builder.