Skip to content

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 device or specific subsets as you require.

Software Modify

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 Ioto agent will connect to the device cloud for a "checkin". During this request, the agent will submit the device.json5 contents to the device cloud to see if an update is available for this device.

The device cloud 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.

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.

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
major >= 1 && minor >= 1 && patch >= 5 && memory >= 256 && ports == 32

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.

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.

GitHub Commit URL

For reference, you can define the GitHub commit URL, Git commit hash or tag to associate with the update.

Applying Updates

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.

Enable

You can selectively enable or disable a release at any time via the Builder.