Remote software update

Prerequisites

Before doing remote software update make sure that you have the following:

1. A linked GRiSP Board: If you don't have a linked GRiSP board you can follow this guide.
2. An API token If you don't have an API token, you can request one using our rebar3 plugin. You can find more informations here.

In this guide you will learn how to:

1. Upload a package
2. Update a device with the uploaded package
3. Manage automatic software updates using device groups

Upload a package

To upload a package to the platform, you must use the command:

rebar3 grisp-io upload

The command will deduce the release package informations using the informations provided in your rebar.config file.

You can find more informations about the upload command here.

If the upload was successful, the following message should be displayed on your terminal:

# package-name format is <platform>.<application name>.<Version>.
# For example: grisp2.grisp_io_demo.1.0.0
Package <package-name>.tar succesfully uploaded to grisp.io

When the upload is finished, a notification is also displayed on the "Device details" page (only if it was open during the upload):

Once the package is uploaded it should be visible in any "Device details" page in the package list under the "Software version" pannel.

Update a device

The remote update of a device is divided in 3 steps:

1. Deploying the update
2. Rebooting the device
3. Validate or rollback

Deploy an update

You can deploy an update in 2 different ways:

• Using the interface of the website
• Using the command line and our rebar3 plugin for grisp.io

Using the website

After you uploaded your package, access the "Device details" page by clicking on the button "Logs and more" of the device you want to update. On this page, select the package you want to use for the update in the panel "Software version".

Once you selected your package, click on "Deploy software version".

You can observe the progress of the upload of the package on the website.

Using the plugin

When the package is uploaded, you can deploy the update to a specific device using the deploy command.

rebar3 grisp-io deploy -d <device serial number>

With this command, the package name will be deduced from the informations contained in the rebar.config file.

If you want to specify the package you can use the --package or -p option:

rebar3 grisp-io deploy -d <device serial number> -p <package name>

Reboot the device

As soon as the deployement is complete, you need to reboot the board. You can do that using 2 different ways:

💡 Tip

If there a mounted SD card on the GRiSP board, you must remove it before rebooting.

1. Clicking on the "Reboot" button displayed on the website

2. Manually rebooting by pressing the button on the board

Validate the update

After reboot you have 2 choices:

• You want to revert to the previous version (i.e. the new version has a bug). In that case you can manually reboot the board and the board will automatically use the previous version
• You are satisfied with the new version. In that case you need to validate the new version

If you want to validate the update you can do it in 2 different ways:

• Using the website
• Using our rebar3 plugin for grisp.io

Using the website

To validate the update on the website, you need to click on the button "Validate". Afterwards, if you reboot your card, it will automatically boot on the new version.

Using the plugin

To validate the update using the plugin you need to use the validate command:

rebar3 grisp-io validate -d <device serial number>

Device group and automated software updates

Now that you know how to perform remote software udpate, you can automate them using device groups

By default, every user has one group, the default group. All devices belonging to that user are automatically assigned to this group.

Update mode

Devices can operate in one of two update modes:

Manual Mode (Default): In this mode, updates for this device must be triggered manually. The device is not added to the update queue of its group, and no automatic updates are performed.

Group Mode: In this mode, updates for this device are managed automatically. If the device meets specific conditions, it is added to its group's update queue and updated without further manual intervention.

Conditions for adding a device to the update queue

1. Automatic updates are enabled for this group see enabling automatic updates
2. The device is connected
3. The device update mode is set to group
4. The current software version of the device differs from the target version of the group.

Managing the update queue

Each device group has an update queue attached to it. The queue is configurable with the following parameters:

Error mode

• Stop (by default): If an error occures during one of the update, the queue will enter in a suspended state. No furhter updates will be started until the user manually resumes the queue.
• Continue: If an error occures during one of the update, the queue will continue to udpate the remaining devices in the queue.

Maximum parallel updates

This this the number of device that can be updating simultaneously.

Enabling automatic updates

The parameter Automatic updates allows you to enable or disable the automatic updates for a specific group.

• false (by default): Automatic updates are disabled for this group. No new updates will be started and the queue is emptied
• true: Automatic updates are enabled for this group.

Additionally, you need to set a target version to enable automatic updates. Without one, the queue will stay empty.

How does the update queue operates ?

Updates are processed in FIFO (first in, first out) order. As long as the number of ongoing updates is below the Max Parallel Updates limit, the queue continues to process updates.

💡 Tip

For automatic updates, the reboot of the device is done automatically. As a user you only have to validate each updates.