Filter results by

OTA updates

The device management features of ARTIK cloud services can be used to trigger OTA (over-the-air) updates on devices, e.g. firmware updates. Doing so runs an OTA Update task. An OTA update can be performed for device types owned by your organization.

See OTA Update task for workflow details.

Before you can execute an OTA update, Device Properties must be enabled for the device type and at least one device of that device type connected by a user. The device must then be registered with ARTIK cloud services using an ARTIK cloud services LWM2M client.

Execute an OTA update in 5 minutes gives a hands-on tutorial using a simulated LWM2M device.

Upload and manage images

In the Developer Dashboard, images and their metadata are managed per device type using the OTA Updates tab under Device Management.

New images can be uploaded and stored here. An image cannot exceed 1 GB and its filename must be unique within the device type.

ARTIK Cloud OTA update images

Firmware image metadata

When uploading a new image, you must associate it with an update type and version.

ARTIK Cloud Upload OTA image

There are three update types:

  • System/OS: Software update to the operating system that is installed on a Gateway Device
  • Application: Software update for an application (user space) that is installed on a Device
  • Edge Node: Software update on an edge device connected to a cloud through a Gateway

After a successful update, the version that the device returns in device.firmwareVersion (LWM2M resource 3) must match the version number you provided here. This and other Device Properties can be viewed and filtered on the Device Management page.

The description field is optional and could be used to provide a list of update notes or differentiate the image from other images.

Search firmware images

Uploaded images can be filtered using the search box on the OTA Updates page. The following criteria are searchable:

ARTIK Cloud OTA image search

Upload and Modified Time are searched as timestamps in milliseconds.

Execute OTA update

An OTA update can be executed on one or more devices. This can be done on the Device Management page or using the task API.

The Device Management page lists all connected devices of the device type. You can filter the list of devices by entering filter criteria in the search box (for example, a key/value pair such as "Firmware Package Version 1.4").

After filtering, use the checkboxes or "Select All" to specify the devices to update, then select OTA Update in the Execute menu.

ARTIK Cloud execute OTA update

The dialog on the next page allows you to select an image file for the selected group of devices. You may either select one of the image files previously uploaded on the OTA Updates page, or upload a new image file.

ARTIK Cloud upload OTA image

You may optionally schedule the OTA update and/or specify if user acceptance is required for this OTA update. If an OTA update requires user acceptance, the user must accept or decline the update within 30 days or the task will expire. Note that it is the application developer's responsibility to display an OTA update notification to the user, polling the API to determine if this is necessary.

You can now execute the OTA update. ARTIK cloud services will push a unique URL to each device where the image can be retrieved. Once the device is connected over LWM2M, it will retrieve the image. The workflow is detailed in OTA Update task.

You can also use the API to programmatically create OTA Update tasks:

For a successful update, your device client must verify that device.firmwareVersion (LWM2M resource 3) matches the version number you provided for the firmware image. This is handled in our SDKs for LWM2M.

Monitor update task

The task status of the OTA update can be tracked using the Tasks tab under Device Management.

ARTIK Cloud LWM2M tasks

OTA Update tasks can be cancelled if they have not yet started execution on the device (REQUESTED or QUEUED status).

You can also use any of the following device management API endpoints:

To handle OTA Update tasks requiring acceptance, see:

See the possible task statuses, device task statuses and acceptance statuses, and device task error codes (5001-5015 are specific to the OTA Update task).

LWM2M client requirements

Your client must implement the following LWM2M resources:

Object (ID) Resource (ID) ARTIK Cloud name Notes
Device (4) Firmware Version (3) firmwareVersion The device must report the new firmware version in this resource after the update has successfully completed. Otherwise the server will mark the update as failed.
Firmware Update (5) Package URI (1) packageURI The package URI can exceed the 255-byte length specified in the LWM2M spec.

The initial URI will return a 302 redirect to another URI that the device must follow in order to download the actual image binary.
Firmware Update (5) Update (2) update  
Firmware Update (5) State (3) state 0: Idle (before downloading or after successfully updating)
1: Downloading (the data sequence is on the way)
2: Downloaded
3: Updating
Firmware Update (5) Update Result (5) updateResult Contains the result of downloading or updating the firmware.

0: Initial value. Once the updating process is initiated (Download/Update), this resource MUST be reset to Initial value.
1: Firmware updated successfully
2: Not enough storage for the new firmware package
3. Out of memory during downloading process
4: Connection lost during downloading process
5: CRC check failure for new downloaded package
6: Unsupported package type
7: Invalid URI
8: Firmware update failed

This resource MAY be reported by sending Observe operation.

To perform an OTA update, the developer implementing the client should ensure the following LWM2M resources are appropriately updated:

In object 5, Package (0), PkgName (6), and PkgVersion (7) are unused. Update Supported Objects (4) is optional.

SDKs for LWM2M

You can use our Java SDK for LWM2M and C/C++ SDK for LWM2M to perform OTA updates. See each corresponding README for installation details.

OTA Update task

The OTA Update task is built on top of the LWM2M Firmware Update object and runs the LWM2M Firmware Update functions as a single task. See the LWM2M technical specification (E.6 LWM2M OBJECT: FIRMWARE UPDATE) for more details.

The OTA update workflow is illustrated below.

ARTIK Cloud OTA update workflow

The ARTIK cloud services LWM2M server will issue the Package URI to the device to initiate the OTA update.

  1. If the device is online, write firmwareUpdate.packageURI to the device.
  2. The device should automatically start downloading the image file from the endpoint provided at packageURI.
    • During the download, device management checks the device on the download status every 30 seconds.
    • This status polling check will continue for 60 minutes.
    • If the device cannot complete the download within 60 minutes, device management will retry writing packageURI one more time before marking the task as FAILED.
  3. When the download is done, device management will issue an execute update to the device (this task is performed internally and is not visible in the task status table).
    • The device should complete the update within 60 minutes. device management will check on this every 30 seconds.
    • If the device fails to start updating, the OTA Update task is marked as FAILED.
  4. Once the device starts updating,
    • The update should be done within 60 minutes. device management will check on this every 30 seconds.
    • If the device fails to complete updating, the OTA Update task is marked as FAILED.
  5. The device can restart during the updating phase.
  6. Once the updating process is done on the device, device management marks the task as COMPLETE.

As per the LWM2M default timeout, any LWM2M call from ARTIK cloud services to the device or device client should be responded to within 15 seconds.

OTA update errors

Code Error message Condition
4201 Getting firmware version failed Getting firmware version (device.firmwareVersion) from device failed
4202 Update not found Update image not found in ARTIK cloud services
4203 Invalid initial firmware update state The initial state was not 0 - idle or 2 - downloaded
4204 Package URI write failed The write of the package URI to the client failed
4205 Read state failed Reading the firmware update state failed unexpectedly
4206 Download timeout The download did not complete before the timeout was reached
4207 Update timeout The update did not complete before the timeout was reached
4208 Unable to issue execute update The execute update command to the device failed
4209 Firmware update version verification failed The firmware version reported by the device after the update was applied did not match the version of the update
4302 Not enough storage Reported by device in firmwareUpdate.updateResult. Not enough storage for the new firmware package
4303 Out of memory Reported by device in firmwareUpdate.updateResult. Out of memory during downloading process
4304 Connection lost Reported by device in firmwareUpdate.updateResult. Connection lost during downloading process
4305 CRC check failed Reported by device in firmwareUpdate.updateResult. CRC check failure for new downloaded package
4306 Unsupported package type Reported by device in firmwareUpdate.updateResult. Unsupported package type
4307 Invalid URI Reported by device in firmwareUpdate.updateResult. Invalid URI
4308 Firmware update failed Reported by device in firmwareUpdate.updateResult. Firmware update failed

Execute an OTA update in 5 minutes

This is a six-step guide to performing OTA updates on devices. We will use a simulated LWM2M device, upload a new image, and finally trigger an OTA update on the device.

Step 1: Enable Device Properties

Enable Device Properties for your device type.

Open the Developer Dashboard —> Select device type —> Select Device Management —> Click "SET UP PROPERTIES".

ARTIK Cloud device management

Under Device Properties, select "Enable Device Properties".

ARTIK Cloud Device Properties

A popup will appear allowing you to change notification frequencies. Keep the default value and select "Enable".

ARTIK Cloud Device Properties

Step 2: Connect a device

Open My ARTIK Cloud and connect a device (or use one that you already own) of the device type. Get the device ID and token from the Device Info screen as shown below. You will need this info when running the client.

ARTIK Cloud Device Info

We're ready to do the OTA update!

Step 3: Start the OTA client

Download the LWM2M client.

Java JDK v8 update 77 or higher is required.

The LWM2M client simulates the firmware update. To start the client, run the following command at the directory where the JAR file is located:

1
  java -jar ota-lwm2m-client-1.0.jar -d YOUR_DEVICE_ID -t YOUR_DEVICE_TOKEN -f FIRMWARE_VER_AFTER_UPDATE

You provide the device ID, token, and firmware version as input arguments.

You got the device ID and token in Step 2. The firmware version (e.g. V1) should indicate the version after the firmware update.

In a real-world scenario, an LWM2M device should obtain the firmware version from the updated image.

From the terminal printout, observe that the client establishes a connection to the ARTIK cloud services LWM2M server and is now waiting to receive an OTA update from the server.

Step 4: Upload new image

Go to the Developer Dashboard to upload a new image for your device type.

ARTIK Cloud OTA update images

In the firmware image metadata screen, you can upload any file type (e.g. PDF) as an image. In addition, enter the following information:

  • Choose "Application" as the update type.
  • Set "version" to the firmware version you typed into the command line at Step 3.

ARTIK Cloud Upload OTA image

Step 5: Execute an OTA update

On the Device Management page, select the device and then initiate an OTA update as shown below:

ARTIK Cloud Upload OTA image

Next select the image file uploaded in Step 4 and perform the OTA update as shown below:

ARTIK Cloud Upload OTA image

Now go back to the terminal of the sample app. You should see logs similar to the following:

1
2
3
4
5
6
7
>>>Downloading firmware image ...
     Image url:https://api.artik.cloud/v1.1/updates/urls/ed26b48d9
     Content-Length = 81292
>>>Downloading complete and save to ./firmware_V1

>>>Simulate updating ...
>>>Updating completed with version V1

You should see the downloaded firmware file under the current directory. Enter ctrl-C in the terminal to kill the client. This sample client is good to use for one update.

Step 6: Monitor OTA update tasks

Go to the Developer Dashboard to monitor OTA update tasks. You should see one task for each run of the client:

OTA update tasks

If the firmware versions provided in Steps 3 and 4 do not match, an update task will show FAILED status.

That's it!

Now you have a feel for the ARTIK cloud services OTA update: connecting an LWM2M device to ARTIK Cloud, initiating OTA update from the Developer Dashboard, and observing the firmware update on the device.

You can programmatically execute an OTA update and check update status. Read more about: