A group enables to bring devices together. Groups can be used to :

Groups behave mostly like directories in a filesystem (considering devices are files): a Group can include other groups and devices. For instance a device can only belong to one group at a time. There are however some exceptions to this analogy (see group deletion rules).

Each tenant has a default root group. A group, except root group, must have a parent group and can have subgroups. In the same tenant, the complete path of each group must be unique but several groups can have the same local identifier (pathNode). The complete path enables to have the tree view of your group.

Group object model:

The group id is fixed, but the group path is calculated because he depends on both the pathNode and the location of the group in the tree. Moving a group in the tree logically leads to a modification of the group path.

Example:

A device can declare one or many parameters: a parameter is identified by a string "key" and can take a typed value (binary, int32, uint32, timestamp).

Live Objects can track the changes of the current value of a device parameters, and allow users to set different target values for those parameters. Live Objects will then try to update the parameters on the device once it’s connected and available.

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.

To retrieve the details of the configuration map of the device we can use the GET API.

HTTP Code:

200 OK

Body:

Error case:

Example:

This section describe how to set up command requests before sending them to the devices.

A command request is a downlink message that Live Objects sends to the device, with acknowledgement mechanism. Depending on the interface (protocol & connectivity) used, a command response can be sent by the device to Live Objects.

You can register commands targeting a specific device: as soon as an interface for this device is available for commands, Live Objects will send them one by one, waiting for an acknowledgment for each command before sending the next one.

Live Objects keeps a record of every registered command with its status, and possible response after processing by device.

The command control mechanism consists of two sub-mechanisms :

The commands can have the following states:

Here is a status diagram with possible transitions:

During the PROCESSING state, the device manager exposes an additional information: the delivery status. The delivery status provides more detailed information on the processing step of the command, based on the acknowledgement information available, depending on the connectivity used.

The acknowledgement level determines the transition from the PROCESSING state to the PROCESSED state of a command.

The device manager offers three different levels of acknowledgement:

For each connector, the acknowledgement level implies a specific delivery status as described in MQTT acknowledge/status, LoRa® acknowledge/status, SMS acknowledge/status, External connector acknowledge/status.

In most cases, the device availability cannot be accurately predicted, due to connectivity reason for example. In some cases, we need the command to be executed in a near future or not at all.

Let’s return to the example of our connected lock: when we send an "unlock" command, we want that the command will be executed within the next two minutes, not in three hours due to a connectivity issues.

The command API proposes the expiration timeout (default: 7 days, min: 5 seconds, max: 30 days). This is the maximal amount of time allowed to reach the status PROCESSING. If this value is exceeded, the status of the command goes to the status EXPIRED.

The command API proposes the acknowledgement timeout. This is the maximal amount of time allowed to reach the status PROCESSED when command is being processed (status PROCESSING). If this value is exceeded, the status of the command goes to the status ERROR with the error code ACK_TIMEOUT.

For each connector, the acknowledgement level implies a specific delivery status as described in MQTT ack timeout value, LoRa® ack timeout value, External connector ack timeout value.

For some reasons (network issues, or acknowledgement default), a command can reach the acknowledgement timeout. In this case, we may have to retry sending command. This is the purpose of the attempts field in the command policy.

If another attempt can be made, instead of ERROR, the command status is set to RETRYING, equivalent to the PENDING status, but showing that it’s not the first attempt. Then, the command is treated normally.

If all attempts have been used, the command status is set to ERROR.

We will detail the command object model of the device manager, as used in API v1.

All possible operations on this object are detailed in the swagger.

Here is an unrealistic example, using a blank interface :

The root fields are as follows:

The format of a command request is the following:

The format of the policy for a command is the following:

The format of the history for a command is an array of this:

For each kind of connectivity, the command registering uses specific values, the final delivery status is also different according to acknowledgement level.

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 :

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.

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:

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.

Campaign management is a Live Objects feature that allows a fleet manager to schedule execution of device management operations on a large number of devices.

The following operations are supported in a campaign definition:

Campaign options section could be empty or omitted.

Example of campaign options:

Options are:

whereas others (non-dynamics) campaigns could end as soon as all devices operations ended or end date reached.

A campaign includes one or more operations:

For each device, operations are executed one after the other, each operation waits for the success of the previous operation.

All operations definitions (except TWIN operations) could embed an optional maxRetry attribute:

If an operation fails after maxRetry attempts (or is canceled) for a device, the remaining operations are not executed for this device and the sequence ends in failure (or in canceled status).

Example of config operation definition:

The following table shows how the config operation statuses are converted into sequence statuses

Example of command version 1 operation definition:

The following table shows how the command operation statuses are converted into sequence statuses

Campaign supports both resource update operations:

Campaign supports all Twin operations.

Campaign devices targets: either idList or filterQuery (exclusively).

idList is a flat list of devices identifiers.

Devices are identified using a URN identifier.

The format of this identifier must be urn:lo:nsid:{ns}:{id} with

idList is not compatible with dynamicallyAddEligibleDevice option.

Below is an example of campaign targets definition using idList:

filterQuery: Device filter expression to target devices using RSQL notation. Supported device properties are tags, properties, groupId,groupPath, connector . Supported RSQL operators are ==, !=, =in=, =out=, =lt=, =le=, =gt=, =ge=, and, or.

Below is an example of campaign targets definition using filterQuery:

Below are example of filterQuery values.

For example, devices with at least tags "FUT" and "TEST1" whatever the order or additional tags

For example, devices having /France as path and demo in tags, and (lwm2m or x-connector) as connector

Below are examples of campaign definition:

A campaign can be canceled with the following REST API endpoint:

If the campaign is already running, canceling it will set its state to CANCELING and the campaign will cancel pending sequences and wait for in progress sequences to end. Then the campaign state will switch to CANCELED.

To abort in progress sequences, the force flag can be used.

A campaign can be deleted with the following REST API endpoint:

If the campaign is in RUNNING or CANCELING state, it cannot be deleted. In this case the force flag can be used to execute a forced cancelation and automatically delete the campaign once it is in CANCELED state.