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.
Firmware image metadata
When uploading a new image, you must associate it with an update type and version.
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:
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.
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.
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.
OTA Update tasks can be cancelled if they have not yet started execution on the device (
You can also use any of the following device management API endpoints:
- Get status of a task
- Get status of all tasks for a device type
- Get detailed status of a task
- Get task status history
- Get tasks by device
To handle OTA Update tasks requiring acceptance, see:
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)
|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:
- Firmware Update (object 5): Package URI (1), State (3), Update Result (5).
- Device (object 4): Firmware Version (3)
In object 5, Package (0), PkgName (6), and PkgVersion (7) are unused. Update Supported Objects (4) is optional.
SDKs for LWM2M
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.
The ARTIK cloud services LWM2M server will issue the Package URI to the device to initiate the OTA update.
- If the device is online, write
firmwareUpdate.packageURIto the device.
- The device should automatically start downloading the image file from the endpoint provided at
- 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
packageURIone more time before marking the task as
- When the download is done, device management will issue an execute
updateto 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
- 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
- The device can restart during the updating phase.
- Once the updating process is done on the device, device management marks the task as
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
|4201||Getting firmware version failed||Getting firmware version (
|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
|4303||Out of memory||Reported by device in
|4304||Connection lost||Reported by device in
|4305||CRC check failed||Reported by device in
|4306||Unsupported package type||Reported by device in
|4307||Invalid URI||Reported by device in
|4308||Firmware update failed||Reported by device in
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".
Under Device Properties, select "Enable Device Properties".
A popup will appear allowing you to change notification frequencies. Keep the default value and select "Enable".
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.
We're ready to do the OTA update!
Step 3: Start the OTA 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.
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.
Step 5: Execute an OTA update
On the Device Management page, select the device and then initiate an OTA update as shown below:
Next select the image file uploaded in Step 4 and perform the OTA update as shown below:
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:
If the firmware versions provided in Steps 3 and 4 do not match, an update task will show
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: