Software 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.

For Ioto devices, via the Builder, you can define software updates 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.

See Builder Software Updates for details on how to configure software updates.

Cloud-Based or Local-Based

You can use the Software Update facility whether you are managing your devices from the cloud or not. If you are not using cloud-based management, you still create a Device Cloud, but you do not need to create a Device Manager, nor do you need to provision your device with MQTT certificates.

To enable software updates, set the services.update to true in the ioto.json5 configuration file.

Update Selection

At regular intervals, the Ioto agent will connect to the device cloud for an "update check". During this request, the agent will submit the device.json 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.

Software Version

The current version for your device is defined via the version property in the ioto.json5 configuration file. NOTE: your device is versioned separately to the Ioto agent itself which has its own version string.

The version numbers must be compatible with the SemVer 2.0 version specification.

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.

Checking for Updates

The Ioto agent will issue an update HTTP request to the device cloud to query if there are any relevant updates for the device. This request submits the device.json5 file and receives back a URL that refers to the update image.

If there is an applicable update, Ioto will download the image, verify the contents and then signal that an update is ready.

Your embedded code can watch for "device:update" events via the rWatch API. Alternatively, you can customize the scripts/update shell script that will be passed the local filename containing the update.

Controlling Updates

The ioto.json5 configuration file has a set of properties that control how the Ioto agent will check, download and apply updates.

Note: these are in addition to the Builder update distribution policies and roll-out limits.

For example:

{
    update: {
        schedule: '* * * * *',
        period: '24 hr',
        jitter: 0,
        throttle: 0,
        apply: '* * * * *',
    }
}

The schedule property defines the time window when the agent will check and download new updates. This is a Cron-like schedule string.

The apply property defines the time window to apply previously downloaded updates. This is useful to separate the impact of downloading updates vs applying updates. For example, you may wish to download updates during the day and only apply at night after business hours.

The period property defines the minimum delay in seconds before checking for a new software update. The period can be a number of seconds or a string with suffixes like: "min", "hr", "day". The period will be applied as well as the defined schedule. i.e. an update checkin will only happen during the specified schedule and no less then the defined period since the last checkin.

The jitter property defines a randomize time period in seconds to delay the scheduled software update check so that multiple devices will not all hit the service at once.

The throttle property defines a time in milliseconds to pause between reading 4K of a software download update. This delay is useful to lessen the CPU and network impact on the device due to downloading a software update. Set to zero for no delay.