Live Objects - complete developer guide

Device resources

Principle

LiveObjects offers a resource feature that allow customers to follow devices reported resources, manage new resource versions, and update device resource with fresh version.

The main goal is to provide resource update facility, where the update principle is :

The Device connects and exchanges with LiveObjects.
The Customers defines some resources for his tenant,
The Customers asks LiveObjects to update device resource versions for some devices.
The Device communicate with LiveObjects to process the update.
LiveObjects reports to the Customer the current state of updates and device resources.

Manage and follow resource update

LiveObjects provides to the Customer DM resource related API in order to:

Manage resource inventory for his tenant :

add, update, remove resource versions,

Manage device resources :

get device resources reported versions,
set, or reset device resources requested versions,

Follow and manage update operations :

create device resource update operation.
cancel an update.
get, or list device updates states,

Figure 1. Manage and follow resource update

Here is an example of Customers in-sequence actions :

create a new resource version for his tenant,
async trigger an update by setting a requested versions for a given device,
get latest device update to track update operation state.

Resource versions management

A resource is a versioned binary content (for example a device firmware). You can manage a repository of resources in your tenant account.

For each resource you can manage multiple resource versions.

Live Objects can track the current versions of resources on a specific device.

Customers can plan an update by setting a requested version for a given device resource version, or can order immediately an update.

Device resource requested versions

Device resource versions updated

Optional compatibility restrictions can be configured between versions to avoid compatibility issues when switching from a version to another.

Live Objects will refuse a resource update request that don’t match the compatibility restrictions.

Different kind of updates

As today, Live Objects supports two kind of updates:

a resource update that rely on http-updater updater (with mqtt and Lwm2m devices):

LiveObjects provides the resource in the form of a secure (https) or insecure (http) URL. Then the Device will decide when to act as http client and query that URL to retrieve the content.

a resource update that rely on lwm2m-updater updater with Lwm2m devices (Beta):

LiveObjects rely on Twin to send LwM2M operations, and will send the resource to the Device via downlink operation (ex. Twin write).

Here is a summary of resource updates mode compatibility and feature matrix

Updater	Connectivity	Update trigger
http-updater	MQTT	set requested version
create update
http-updater	LwM2M	create update
lwm2m-updater	LwM2M	create update

Updater

Connectivity

Update trigger

http-updater

MQTT

set requested version

create update

http-updater

LwM2M

create update

lwm2m-updater

LwM2M

create update

Resources inventory

Resources and versions definitions

Customer defines for his tenant a set of resources.

A resource is:

a resourceId: a unique identifier (ex. X113DevFirmware, EPROM7300_V12).
a label (optional)
a description (optional)
a connector (optional): the default related updater
some meta-data
some aliases (optional)

For each resource, Customer then defines one or more resource versions.

A resource version is:

a given unique version identifier (ex. 1.0, 1.1a),
a file content,
a checksum of the file content,
an optional list of the compatible versions from which you can update to this firmware.

Resources aliases

You can configure zero, one or several aliases on a resource to help you manage your resource update operations.

An alias can be used to replace with a string of your choice a resource version when requesting a new target for a resource.

For example you could create an alias preprod to refer or target the 1.1a resource version.

You can use up to 5 aliases per resource.

A same version can be used in several aliases. An alias key must be unique.

Resources versions compatibility

When a resource version includes at least one or more compatible versions, LiveObjects must check that the current device resource reported version is compatible in order to target an update to this resource version.

When a resource version compatible versions is empty or missing, LiveObjects is able to target an update to this resource version without version check.

For example, if 1.1a compatible versions are [0.8, 1.0, 1.1], then

a device which reports 0.8 as current version is compatible
whereas a device which didn’t report current version, or which reports 0.9 (or 1.2) version is NOT compatible and cant be updated to 1.1a.

Resource definition API examples

Create a new resource

POST /api/v0/rm/X113DevFirmware

{
  "connector": "http-updater",
  "resourceId": "X113DevFirmware",
  "label": "X113 DEV",
  "description": "X113 firmware of box, in DEV mode.",
  "metadata": {
    "BoxSeriesSuffix": "FF1Fxx42"
  }
}

Response

{
    "tenantId": "5ae04ef29a92790fd7f2a5e4",
    "resourceId": "X113DevFirmware",
    "label": "X113 DEV",
    "description": "X113 firmware of box, in DEV mode.",
    "connector": "http-updater",
    "metadata": {
        "BoxSeriesSuffix": "FF1Fxx42"
    },
    "creationTs": 1677496010873,
    "updateTs": 1677496010873
}

Remove a given resource

DELETE /api/v0/rm/X113DevFirmware

Create a new resource version

POST /api/v0/rm/X113DevFirmware/version

{
  "file": "iVBORw0KGgoAAAANSUh...UVORK5CYII=",
  "checksum": "9WeAuNlX/WaappCx4sSMYQ==",
  "resourceVersionId": "1.0",
  "compatibleVersions": ["0.5","0.8","0.9"]
}

This sample adds a new X113DevFirmware firmware resource version 1.0. This version is compatible with following versions: 0.5, 0.8, 0.9.

file attribute is base64 encoded file content (abbreviates in the example above).
checksum is md5 of the raw firmware content encoded in base64.

Example of generating md5 checksum :

  import com.google.common.hash.Hashing;
  import com.google.common.io.BaseEncoding;
  import java.io.File;
  import java.nio.file.Files;
  import org.apache.commons.io.FileUtils;
  import org.junit.Test;

  // ...

  File file = new File("C:/tmp/myFirmware.bin");

  byte[] fileBytes = FileUtils.readFileToByteArray(file);
  String fileB64 = BaseEncoding.base64().encode(fileBytes);

  byte[] fileMd5Sum = Hashing.md5().hashBytes(fileBytes).asBytes();
  String fileB64OfMd5Sum = BaseEncoding.base64().encode(fileMd5Sum);

  System.out.println("::fileB64> " + fileB64);
  System.out.println("::checksum> " + fileB64OfMd5Sum);

Remove a given resource version

DELETE /api/v0/rm/X113DevFirmware/version/1.0

This sample removes X113DevFirmware firmware resource version 1.0.

Version management

Device declaration

Depend of the protocol, the device could report the current version of his resources.

This device initiated declaration is mandatory when relying on resources with compatibility restrictions.

But LiveObjects is also able to execute update operation without device declaration when relying on resources with NO compatibility restrictions.

For MQTT, please refer to Current Resources publication section.
For LwM2M, as today there is no device declaration, and so update must rely on resources without compatibility restrictions.

Version operation

Set or Reset requested version

Customer can set requested versions on devices :

In order to plan an update, Customer can record some intention : set a requested versions on one or more device resources.

This way represent an asynchronous trigger of the update operation because the update operation is created at LiveObjects initiative: when we know that the device is compatible, and when the device is ready to accept a new update (cf. conditions bellow).

Customer can reset requested versions on devices :

To remove any update intention, the reset operation will clean the requested version.

In that case, there is a chance that the update were already created/started : in that case LiveObjects will cancel related update too.

Note that http-updater will be used if no updater has been declared as connector for the resource

Create an update

Customer can create an update operation on devices :

In order to immediately trigger an update, LiveObjects let you create a device update directly. This way represent a synchrone trigger of the update operation: the update operation is started at Customer initiative.

This operation may be immediately rejected in some case:

we already know that the device is not compatible,
an update is already in progress on that device.

When the device is not ready, or when we don’t know if he is compatible, then the update will stay in his initial state(PENDING), and will progress later.

Note that http-updater will be used if no updater has been declared as connector for the resource

Update trigger

Here is a summary of updates conditions

Connectivity Updater Update conditions

Connectivity	Updater	Update conditions
MQTT	http-updater	Mqtt connection is established, the device is listening resource update requests, and the compatibility restrictions (if any) are fulfilled.
LwM2M	lwm2m-updater	LwM2M device is connected, the device supports and instantiate the first Firmware Object (`/5/0`), the target resource has no compatibility restrictions, the device supports the delivery process : - firmware update state (`/5/0/3`) shall be idle - in-band delivery with lwm2m-updater : device must support push delivery method (`/5/0/9`) - out-of-band delivery with http-updater : device must support pull delivery method (`/5/0/9`) and support http or https protocol (`/5/0/8`)
http-updater

MQTT

http-updater

Mqtt connection is established, the device is listening resource update requests, and the compatibility restrictions (if any) are fulfilled.

LwM2M

lwm2m-updater

LwM2M device is connected, the device supports and instantiate the first Firmware Object (/5/0), the target resource has no compatibility restrictions, the device supports the delivery process :

- firmware update state (/5/0/3) shall be idle

- in-band delivery with lwm2m-updater : device must support push delivery method (/5/0/9)

- out-of-band delivery with http-updater : device must support pull delivery method (/5/0/9) and support http or https protocol (/5/0/8)

http-updater

Version management API examples

Set device resource requested version

Request

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/resources/MyResource001

{
    "version": "1.1",
    "metadata" : {
        "secured" : true
    }
}

Response

{
  "reported": {
    "version": "1.0",
    "timestamp": "2020-03-12T10:43:18.350Z"
  },
  "requested": {
    "version": "1.1",
    "timestamp": "2020-07-23T14:53:03.959Z"
  }
}

JSON Params	Description
reported	current device resource status
requested	requested resource status
version	resource version
timestamp	date of resource version association
metadata	metadata associated with this device (if any)

JSON Params

Description

reported

current device resource status

requested

requested resource status

version

resource version

timestamp

date of resource version association

metadata

metadata associated with this device (if any)

Set device resource version using alias

Configure an alias

Request

PUT /api/v0/rm/MyResource001

{
  "connector": "http-updater",
  "metadata": {
    "secured": true
  },
  "versionAliases" : {
      "prod" : "1.1",
      "preprod" : "1.2"
  }
}

Response

{
  "resourceId" : "MyResource001",
  "connector" : "http-updater",
  "metadata" : {
    "secured" : "true"
  },
    "versionAliases" : {
      "prod" : "1.1",
      "preprod" : "1.2"
  },
  "creationTs" : 1563191282476,
  "updateTs" : 1595594676082
}

Set requested version alias

Request

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/resources/MyResource001

{
    "version": "prod",
    "metadata" : {
        "secured" : true
    }
}

Response

{
  "reported": {
    "version": "1.0",
    "timestamp": "2020-03-12T10:43:18.350Z"
  },
  "requested": {
    "version": "1.1",
    "timestamp": "2020-07-23T14:53:03.959Z"
  }
}

The requested alias must exist and meet the compatibility restrictions

Reset device resource version

Request

DELETE /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/resources/MyResource001/requested

This DELETE call will remove the requested version of the device resource MyResource001 if related update has not been triggered.

If an update already exists for this device resource, then requested version is untouched. If the update is active, internally, a soft cancel is done.

Create resource update

Request

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/resources/MyResource001/updates

{
  "requestedVersion": "1.0",
  "connector": "http-updater",
  "metadata": {
    "secured": true
  }
}

Response

{
    "id": "5f3bf1ecb23f3277805478a7",
    "resourceId": "MyResource001",
    "created": "2023-03-02T15:21:16.128Z",
    "updated": "2023-03-02T15:21:16.128Z",
    "initialVersion": "0.8",
    "requestedVersion": "1.0",
    "connector": "http-updater",
    "status": "PENDING",
    "metadata": {
      "secured": true
    }
 }

JSON Params Description

JSON Params	Description
resourceId	device resource to update
created	resource update creation date
updated	resource update update date
initialVersion	device resource initial version
requestedVersion	device resource requested version
connector	updaterConnector to use. Can be `http-updater` OR `lwm2m-updater`. If not provided, the `connector` associated to the resource is used. If the resource has no associated `connector`, `http-updater` is used.
metadata	metadata associated to this update

resourceId

device resource to update

created

resource update creation date

updated

resource update update date

initialVersion

device resource initial version

requestedVersion

device resource requested version

connector

updaterConnector to use. Can be http-updater OR lwm2m-updater.

If not provided, the connector associated to the resource is used.

If the resource has no associated connector, http-updater is used.

metadata

metadata associated to this update

Update Operation

Update states

Customer can get, or list resource updates.

This is different states values for a resource update :

State	Description
PENDING	This is update operation initial state. The device is not yet ready or didn’t report his current version.
PREPARING_CONNECTOR	The update operation is now in progress and related update connector is initializing (internal).
PREPARING_ASSET	verify the device state or ask to the device to accept update.
WAITING_TRANSFER_INFO	waiting the device to accept the update
TRANSFER_PENDING	resource transfer is ready to start
TRANSFER_IN_PROGRESS	resource transfer is in progress
TRANSFER_SUCCESS	resource transfer is just done with success
CANCELED	The update operation has been canceled. This is a final state.
ERROR	The update operation has failed. This is a final state.
DONE	The update operation is done successfully. This is a final state.

State

Description

PENDING

This is update operation initial state. The device is not yet ready or didn’t report his current version.

PREPARING_CONNECTOR

The update operation is now in progress and related update connector is initializing (internal).

PREPARING_ASSET

verify the device state or ask to the device to accept update.

WAITING_TRANSFER_INFO

waiting the device to accept the update

TRANSFER_PENDING

resource transfer is ready to start

TRANSFER_IN_PROGRESS

resource transfer is in progress

TRANSFER_SUCCESS

resource transfer is just done with success

CANCELED

The update operation has been canceled. This is a final state.

ERROR

The update operation has failed. This is a final state.

DONE

The update operation is done successfully. This is a final state.

Update timeouts

An active update has 2 timeout windows:

after the resource update request (LiveObjects → Device request with http-updater update).
for the overall update (for http-updater, and lwm2m-updater updates).

After the resource update request:

the device does not confirm the resource update request and does not download or report the version. After 5 minutes, the update returns to the PENDING state.
the device accepts the resource update request but does not download or report the version. After 5 minutes, the update will end with a timeout error (ERROR state).

For the overall update

an active update (update with a state not in DONE,CANCELED,ERROR) MUST NOT be older than 24 hours. After 24 hours, the update will end with a timeout error (ERROR state).

Cancel an update

There is multiple ways to cancel an update :

reset device resource requested version to cancel a set requested version,
soft cancel a resource update.
hard (aka. force) cancel a resource update.

The "reset" method will clean an expected requested version. If the update has already been triggered and is always active, a soft cancel is internally done.

The "soft" cancel update method will interrupt an active update in the following state : PENDING, PREPARING_CONNECTOR.

The "hard" cancel update method will interrupt an active update in the following state : PENDING, PREPARING_CONNECTOR, PREPARING_ASSET,WAITING_TRANSFER_INFO, TRANSFER_PENDING, TRANSFER_IN_PROGRESS, TRANSFER_SUCCESS.

Update API examples

Create resource update

Cancel resource update

Request

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/resources/updates/MyResource001/status?force=true

CANCELED

Response

HTTP Code:

200 OK

Updaters

In order to send the binary content to a device, Live Objects is built to provide different type of transfert protocols.

Those protocols are handled by updaters.

Updaters can support configuration parameters called metadata.

Http-updater

Live Objects provides a http-updater updater that allows the device to download the resource using HTTP protocol. http-updater is available with devices that have MQTT or Lwm2m (through "out-of-band" mode)

http-updater supports the following metadata:

Meta-data Description

Meta-data	Description
`secured`	To enable https link for resources update, the default value is set to false (i.e. http link). It’s possible to set this "secured" metadata from device resource metadata, resource metadata, or update operation metadata.

secured

To enable https link for resources update, the default value is set to false (i.e. http link). It’s possible to set this "secured" metadata from device resource metadata, resource metadata, or update operation metadata.

Lwm2m-updater

Live Objects provides a lwm2m-updater updater that relies on LWM2M Specifications to process an update.

As today lwm2m-updater supports the push mode and rely on "Firmware(5)" object to read device firmware status, write, then execute firmware package and read firmware update result.

lwm2m-updater has no specific metadata.

Resource update process

Resource update with MQTT connector and HTTP updater

Live Objects will prepare the resource on public available endpoint and send update information to the device.

The device is responsible to download the resource, and then report his state to LiveObjects .

Trigger

How to trigger a resource update:

You can set the requested version of resources for a specific device in Live Objects that will then try to update the resources on the device as soon as the device is available for resource update.
You can trigger by creating an update directly.

step 1 - Resource update context

the customer defines some resources, and some resource versions with, or without compatibility constraints on Live Objects : cf resources definitions.
the device reports its current resources and versions.
the customer may set and reset requested versions on some device resources on Live Objects. cf. device resource set example, and device resource reset example.

If your device is connected in "Device mode", please refer to the MQTT device mode part for messages that your device can send or receive. There is some practical examples in Resources update section like Current Resources publication.

Figure 2. step 1) Device resource update context

step 2 - New update

customer creates an update directly via API. cf. create resource update example.
or Live Objects automatically triggers an update for not honored requested resource versions set.

Pre-requisites: a new update is activated when

the device is ready to receive resource update (resource capability is available),
there is no update in progress.

When there is compatibility restrictions, then the device resource current version MUST be known.

Figure 3. Device resource update steps

step 3 - Prepare connector

Live Objects prepares the resource version binary and generates a download link.

step 4 - Prepare asset

Live Objects sends the download link and resource version id to the device
optional the device can respond to indicate whether it accepts the new resource version or not.
optional the device can send a customized error. The operation will be stated as failed

step 5 - Transfer

the device can download the binary.
optional at anytime, the operation can be cancelled. In this case Live Objects will remove the download link. cf. the section dedicated to cancellation.
when the device does not start the download, then timeout can occur cf. section dedicated to timeout.
when the device has not responded to the request and does not start the download, the update returns to the PENDING state.

step 6 - Final

download is done
the device can check the file integrity using the provided md5, and perform internal updates.
to acknowledge the binary reception and the update, the device sends a new current resources message.
Live Objects compares the current and expected resource version and updates the operation status accordingly.

http-updater resource update states

Figure 4. Device resource update states

Resource update with Lwm2m connector - (Beta)

APIs allow to manage lwm2m-updater resource update only for LWM2M connector.

Live Objects will prepare te resource and send it to the device with a downlink operation.

The device MUST be compliant with related standard to accept the resource, and report his state to LiveObjects.

Trigger

How to trigger a resource update with lwM2M connector :

You can trigger by creating an update directly.

step 1 - Resource update context

the customer defines some resources, and some resource versions.

As today, you must use resource without compatibility restrictions.

step 2 - New update

customer creates an update directly via API. cf. create resource update example.
customer selects the connector : "lwm2m-updater" for push update or "http-updater" for pull update.

Pre-requisites: a new update is activated when

the device is ready to receive resource update (resource capability is available) : Lw device is connected and instantiate object /5/0,
there is no update in progress.
the device supports selected delivery method and http(s) protocol if "out-of-band" update is selected.

Figure 5. Device resource update steps

step 3 - Prepare resource

LiveObjects internally prepares the requested resource version content to send.

step 4 - Prepare device: await device initial state

LiveObjects will use Twin operations to ask to the device the first Firmware instance (/5/0).

This provides some relevant informations : state (/5/0/3), protocol support(/5/0/8), delivery method(/5/0/9).

In order to start a firmware update sequence, following conditions apply :

the device state MUST be 0:IDLE.
(when using http-updater) protocol support and delivery method MUST be compatible with underlying update.
On unexpected read/state issue, the read operation is retried with a retry backoff mechanism. Note that on unexpected compatibility there is no retry, the update is directly moved to ERROR.
On unexpected read/state issue and max retry attempts reached, the update is moved to ERROR.
On satisfying conditions, device update will go to the next step : transfer.

option - Interruption

During an update in progress, some interruptions can occur:

Customer can ask to cancel the update: on cancel, the update is moved to CANCELED. cf. the section dedicated to cancellation.
LiveObjects can detect that the update reached global update timeout: on timeout, the update is moved to ERROR. cf. section dedicated to timeout.

NOTE: once the update request (step 4 - prepare device) has been sent, the cancel or timeout interruption impacts only on the update state. Customer can order a new update that will overwrite current residual update operation and restart a fresh update from scratch.

step 5 - Transfer operation

In case of push update (in-band write)

Live Objects sends the firmware package to the device with Lwm2m write operation.
Live Objects will rely on Twin WRITE operation to push the content of the resource to the device.

In case of pull update (out-of-band)

Live Objects has created a HTTP(s) download link and provides this URI to the device.
Device downloads the package content from this URI.

step 6 - Transfer verify result

resource is moving on device side
the device is responsible to update his internal state (ex. from 1:DOWNLOADING to 2:DOWNLOADED)
Live Objects will rely on Twin READ operation to get back Firmware state (/5/0/3) and Firmware update result state (/5/0/5).
Live Objects expects state to be 2:DOWNLOADED and result state to be 0:INITIAL.
Live Objects reads state retries in the limit of max retries : cf. DM Resource limitations
on success, the transfer is considered as a success and the update moves to the next step,
on read issue or unexpected states after max retries, the update moves to ERROR state.

step 7 - Execute firmware update

Live Objects will rely on Twin EXECUTE operation Firmware update execute (/5/0/2).
resource is already on device side
the device can perform internal operations, updates, reboot, etc.
to acknowledge the binary reception and the update operation, the device is responsible to update his internal Firmware update result state.

step 7 - Await device update result state

update is in progress, then done on device side
the device is responsible to update his internal Firmware update result state (/5/0/5) to 1:UPDATED_SUCCESSFULLY
Live Objects will rely on Twin READ operation to get back Firmware update result state (/5/0/5).
Live Objects expects state to be 1:UPDATED_SUCCESSFULLY.
Live Objects reads update result retries in the limit of max retries : cf. DM Resource limitations
on success, the overall update is considered as a success and the update is DONE.
on read issue or unexpected states after max retries, the update moves to ERROR state.

lwm2m-updater resource update states

Figure 6. Device resource update states