Commands

Principle

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.

There is a limitation of 10 queued commands for a specific device.

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 :

  • an application sub-mechanism that manages the displayed command statuses for the buisness applications and apply command cancel if need.

  • an additional sub-mechanism that manages the command delivery status to the device using the connectors.

Command status

The commands can have the following states:

Status Description

PENDING

The command is recorded and waiting for processing

RETRYING

The command has encountered an error, and will be retried. (same behaviour as PENDING)

PROCESSING

The command is being processed by the dedicated interface (waiting for an acknowledge)

PROCESSED

The command has reached its final acknowledgement level (FINAL STATE)

ERROR

An error occurred during the processing of the command (FINAL STATE)

CANCELED

The command was canceled before reaching PROCESSED state (FINAL STATE)

EXPIRED

The command could not be processed within the time limit (expirationTimeoutInSecond) (FINAL STATE)

Here is a status diagram with possible transitions:

Device commands states
@startuml
scale 0.8
' --- States style ---
skinparam state {
  BackgroundColor #FFF9C4
  BorderColor #B22222
  FontColor Black
  'FontStyle bold
}
skinparam StateBorderThickness 1.5
' --- Arrows style ---
skinparam ArrowColor #B22222
skinparam ArrowFontColor Black
'skinparam ArrowFontStyle bold

state "PENDING / RETRYING" as PENDING: The command is recorded\nand waiting for processing
PROCESSING: The command is being processed\n(waiting for an acknowledgment)
PROCESSED: The command has reached\nits final acknowledgement level
EXPIRED: The command could not be processed\nwithin the time limit
CANCELLED: The command was cancelled\nbefore reaching PROCESSED state
ERROR: An error occurred during\nthe processing of the command

[*] --> PENDING
PENDING --> PROCESSING : processing started
PENDING -down-> EXPIRED : expiration timeout
PENDING -down-> CANCELLED : soft cancel
PROCESSING -down-> CANCELLED : hard cancel

PROCESSING -up-> PENDING : error during processing\nwith available attempt

PROCESSING --> PROCESSED : requested acknowledgment level reached
PROCESSING --> ERROR : error during processing\nwithout available attempt

@enduml

Command status summary table

Table 1. Here is the list of possible command statuses provided by each connectivity

Command Status \ Connector

LoRa®

MQTT

SMS

External Connector

PENDING

☑

☑

☑

☑

PROCESSING

☑

☑

☑

☑

PROCESSED

☑

☑

☑

☑

EXPIRED

☑

☑

☑

☑

CANCELED

☑

☑

☐

☑

RETRYING

☑

☑

☐

☑

ERROR

☑

☑

☑

☑

Delivery status

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.

Device commands delivery states
@startuml
scale 0.8
' --- States style ---
skinparam state {
  BackgroundColor #FFF9C4
  BorderColor #B22222
  FontColor Black
  'FontStyle bold
}
skinparam StateBorderThickness 1.5
' --- Arrows style ---
skinparam ArrowColor #B22222
skinparam ArrowFontColor Black
'skinparam ArrowFontStyle bold

[*] --> SENDING
SENDING --> SENT
SENT --> DELIVERED
DELIVERED --> REPLIED

SENDING : Command is processed by available connectivity
SENT : Command was sent to device with success
DELIVERED : Command was successfully delivered to device \nCorresponding to a network acknowledgment
REPLIED : Command was acknowledged by device \nCorresponding to an applicative acknowledgment

@enduml

Acknowledgement level

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:

  • NONE : The device manager only listens to the internal acknowledgement that notifies the sending of the command. The command is output from Live Objects. Equivalent to the delivery status SENT

  • NETWORK : The device manager waits for protocol acknowledgment. Equivalent to the delivery status DELIVERED

  • APPLICATIVE : The device manager waits for an applicative acknowledgement, with potentially a response. Equivalent to the delivery status REPLIED

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.

Expiration Timeout

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.

Acknowledgement Timeout

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.

A command with NONE acknowledgement cannot have acknowledgement timeout. For the other cases, an acknowledgement timeout is enforced.
Do not hesitate to customize this value. A value adjusted to your needs allows for better error detections, as well as a better reactivity of the command process

Attempts number

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.

The default value of attempts is 1, which means there will be no retries. The maximum value is 5 (first attempt + 4 retries)
If the command status is RETRYING and the expiration timeout is reached, the new attempts is abort, and the command status is set to EXPIRED (same behavior as PENDING). It is advisable to define an expiration timeout upper than (acknowldegement timeout x (attempts - 1))

Command object model

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 :

{
    "id": "ae49129f-9ce4-4782-82c4c6a2",
    "targetDeviceId": "urn:lo:nsid:sensor:2327398",
    "request": {
        "connector": "...",
        "value": {
            [...]
        }
    },
    "response": {
      [...]
    },
    "status": "PROCESSED",
    "deliveryStatus": "REPLIED",
    "errorCode": "INVALID_COMMAND_REQUEST",
    "policy": {
        "expirationInSeconds": 120,
        "ackTimeoutInSeconds": 180,
        "ackMode": "APPLICATIVE",
        "attempts" : 1
    },
    "history": [
        {
            "timestamp": "2017-12-06T11:32:25.055Z",
            "status" : "PENDING"
        }, {
            "timestamp": "2017-12-06T11:38:22.481Z",
            "status": "PROCESSING",
            "deliveryStatus": "SENT",
            "errorCode": "INVALID_COMMAND_REQUEST",
            "nodeId": "2327398"
        }, {
            "timestamp": "2017-12-06T11:38:24.124Z",
            "status": "PROCESSED",
            "deliveryStatus": "REPLIED",
            "nodeId": "2327398",
        }
    ],
    "created": "2017-12-06T11:32:25.055Z",
    "updated": "2017-12-06T11:38:24.124Z"
}

The root fields are as follows:

JSON Params Description

id

Unique id of the command

targetDeviceId

Targeted device identifier

request

Command request (Cf. command request format)

response

Optional. Command response from device

status

Status of the command. Please refer to Command status for more details.

deliveryStatus

Optional. Delivery status of the command. Please refer to Delivery status for more details.

errorCode

Optional. Error code encountered during command processing.

policy

Policy for the command (Cf. Policy format)

history

Contains the history of changes in the status of the command. (Cf. Command history)

created

Registration date of the command

updated

Last "status" update date of the command.


The format of a command request is the following:

JSON Params Description

connector

connector/protocol to use to forward the command. Allowable values: mqtt, lora, sms or x-connector.

value

command value (protocol/connector-dependant) (Cf. MQTT value, LoRa® value, SMS value, External connector value)


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

JSON Params Description

expirationInSeconds

Optional. expiration in seconds since command creation date. (Cf. Expiration Timeout).

ackTimeoutInSeconds

Optional. acknowledgement timeout in seconds since command is being processed. Default depends on connectiviy. Min value is 10 seconds (Cf. Acknowledgement Timeout).

ackMode

Optional. Ack mode for this command. Please refer to Acknowledgement level for more details.

attempts

Optional. Number of attempts in case of ERROR. Default to 1 Please refer to Attempts number for more details.


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

JSON Params Description

timestamp

Timestamp of this event

status

Status of the command at that moment

deliveryStatus

Optional. Delivery status of the command at that moment

errorCode

Optional. Error code encountered during command processing.

nodeId

Optional. NodeId of the interface used to process the command


Command registering by connector

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

Case of MQTT

To see how the commands are processed by device and to learn more, see the command section "device mode"
Delivery status behaviour according to acknowledgement level
Acknowledgment NONE (just sent the command) APPLICATIVE (waiting for response to validate)

Description

MQTT connector sent the command through open connection

Applicative response from device (default value)

Sequence of events & evolution of the statuses

 
@startuml
scale 0.7
skinparam ParticipantBorderColor #B22222
skinparam ParticipantBorderThickness 1.5
skinparam NoteBackgroundColor #FFF3B0

participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
participant Device #lightgreen
BA -> LO : Register command
activate LO #orange
note over LO : *status : **PENDING**
LO -> LO : Waiting for the device subscription\n if it's not already done.
deactivate LO
Device -> LO : Subscribe on dev/cmd
activate Device #lightgreen
activate LO #orange

LO -> Device : Publish command\non topic dev/cmd
note over LO : *status : **PROCESSED** \n*deliveryStatus: **SENT**
@enduml
 
@startuml
scale 0.7
skinparam ParticipantBorderColor #B22222
skinparam ParticipantBorderThickness 1.5
skinparam NoteBackgroundColor #FFF3B0

participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
participant Device  #lightgreen
BA -> LO : Register command
activate LO #orange
note over LO : *status : **PENDING**
LO -> LO : Waiting for the device subscription\n if it's not already done.
deactivate LO
Device -> LO : Subscribe on dev/cmd

activate LO #orange
activate Device #lightgreen
LO -> Device : Publish command\non topic dev/cmd
note over LO : *status : **PROCESSING** \n*deliveryStatus: **SENT**
LO -> LO : Waiting for the device response

deactivate LO
Device -> LO : Publish command response\non topic dev/cmd/res
activate LO #orange
deactivate Device
note over LO : *status : **PROCESSED** \n*deliveryStatus: **REPLIED**

@enduml

Final Success Delivery Status

SENT

REPLIED

Default acknowledgement timeout

-

24h (7 days with v0 API), and the maximal value is 7 days.
Values for command registration

Value field can be any valid JSON

@startuml
hide footbox

scale 0.8
skinparam ParticipantBorderColor #B22222
skinparam ParticipantBorderThickness 1.5
skinparam NoteBackgroundColor #FFF3B0

participant "Business App" as BA
participant "Live Objects" as LO #orange
BA -> LO : Register command

@enduml
JSON Params Description

req

the command in string format

arg

List of parameters. Should not contain field name with . character or start with $ character

Example: Let’s take the case of a command recorded for a device with an online MQTT interface, with an APPLICATIVE acknowledgement level.

{
    "request": {
        "connector": "mqtt",
        "value": {
            "req": "reboot",
            "arg": {
                "delay": 1000
            }
        }
    },
    "policy": {
        "expirationInSeconds": 120,
        "ackMode": "APPLICATIVE"
    }
}

Please refer to the MQTT device mode part for messages that your device can send or receive.

To see an example, go to MQTT Command Example section.

Case of LoRa®

Delivery status behaviour according to acknowledgement level
Acknowledgment NONE (just sent the command) NETWORK (waiting for network/protocol ack)

Description

Downlink report received (default value)

Downlink acknowledge received

Sequence of events & evolution of the statuses

 
@startuml
scale 0.7
skinparam ParticipantBorderColor #B22222
skinparam ParticipantBorderThickness 1.5
skinparam NoteBackgroundColor #FFF3B0

participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
participant Device #lightgreen


BA -> LO : Register command
activate LO #orange

note over LO : *status : **PENDING**
LO -> LO : Waiting for join request\n if it's not already done
deactivate LO

Device -> LO : Join request
activate LO #orange
activate Device #lightgreen
LO -> LO : Waiting for next uplink
deactivate LO
deactivate Device

Device -> LO : Uplink
activate LO #orange
activate Device #lightgreen
LO -> Device : Downlink
deactivate Device
note over LO : *status : **PROCESSED** \n*deliveryStatus: **SENT**

@enduml
 
@startuml
scale 0.7
participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
participant Device #lightgreen


BA -> LO : Register command
activate LO #orange

note over LO : *status : **PENDING**
LO -> LO : Waiting for join request\n if it's not already done
deactivate LO
activate Device #lightgreen
Device -> LO : Join request
activate LO #orange
LO -> LO : Waiting for next uplink
deactivate LO
deactivate Device
Device -> LO : Uplink
activate LO #orange

activate Device #lightgreen
LO -> Device : Downlink with request
note over LO : *status : **PROCESSING**

Device -> LO : Uplink with ack downlink
note over LO : *status : **PROCESSED** \n*deliveryStatus: **DELIVERED**
deactivate Device
deactivate LO
@enduml

Final Success Delivery Status

SENT

DELIVERED

Default acknowledgement timeout

-

For LoRa®, the acknowledgement rely on a double mechanism: - first correlated with the device traffic: the LoRa® connector waits maximum 3 uplinks to get an ACK bit set to 1. Beyond 3 uplinks without ACK bit acknowledgement timeout is reached. - second is acknowledgement timeout delay: default: 7 days, max is 7 days.
Values for command registration
@startuml
hide footbox
scale 0.8
participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
BA -> LO : Register command

@enduml

Value field in request command sets the following parameters:

JSON Params Description

data

hexadecimal raw data of the command

port

port of the device on which the command will be sent (1 to 254)

Example:

{
    "request": {
    	"connector":"lora",
    	"value":{
    		"data": "A1FF20",
    		"port": 1
    	}
    },
    "policy": {
    	"expirationInSeconds" : 200,
    	"ackMode": "NONE"
    }
}
To see an example, go to LoRa® Command Example section.

Case of SMS

Delivery status behaviour according to acknowledgement level
Acknowledgment NONE (just sent the command)

Description

Message sent (default value)
Values for command registration
@startuml
hide footbox
scale 0.8
participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
BA -> LO : Register command

@enduml

Value field in request command sets the following data:

JSON Params Description

payload

message to send

TEXT : size max 160 characters and GSM 7 compatible characters (for more information, see GSM 03.38 standard or chapter 6.2.1 of https://www.etsi.org/deliver/etsi_gts/03/0338/05.00.00_60/gsmts_0338v050000p.pdf)

BINARY : size max 260 characters (140 octets) and hexadecimal characters

serverPhoneNumber

server phone number. Must be defined in the offer settings

type

message format in TEXT or BINARY

Example:

{
    "request": {
    	"connector": "sms",
        "value": {
            "payload": "Hello Live Objects!",
            "type": "TEXT",
            "serverPhoneNumber": "20406"
        }
    },
    "policy": {
    	"expirationInSeconds" : 30,
    	"ackMode": "NONE"
    }
}
To see an example, go to SMS Command Example section.

Case of External connector

Delivery status behaviour according to acknowledgement level
Acknowledge required NONE (just sent the command) APPLICATIVE (waiting for response to validate)

Description

External connector sent the command through open connection

Applicative response from device (default value)

Sequence of events & evolution of the statuses

 
@startuml
scale 0.7
participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
participant "Customer Backend\n(External connector)" as BC
participant Device #lightgreen

BA -> LO : Register command
note over LO : *status : **PENDING**
activate Device #lightgreen
Device -> BC : connect to customer\nbackend\n(proprietary protocol)
deactivate Device
activate BC
BC -> LO : Subscribe on topic:\n**<size:10>connector/v1/requests/command**
activate LO #orange

LO -> BC : Publish command on topic\n<size:10>**connector/v1/requests/command**
deactivate LO
BC -> Device : send command\n(proprietary protocol)
deactivate BC
activate Device #lightgreen
note over Device : the device process\nthe command
note over LO : **PROCESSED** \n*deliveryStatus: **SENT**
@enduml
 
@startuml
scale 0.7
participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
participant "Customer Backend\n(External connector)" as BC
participant Device #lightgreen

BA -> LO : Register command
note over LO : *status : **PENDING**
activate Device #lightgreen
Device -> BC : connect to customer\nbackend\n(proprietary protocol)
deactivate Device
activate BC
BC -> LO : Subscribe on topic:\n<size:10>**connector/v1/requests/command**
activate LO #orange

LO -> BC : Publish command on topic:\n<size:10>**connector/v1/requests/command**
deactivate LO
BC -> Device : send command\n(proprietary protocol)
activate Device #lightgreen
note over Device : the device process\nthe command
note over LO : *status : **PROCESSING**
Device -> BC : send result\n(proprietary protocol)
deactivate Device
BC -> LO : Publish command response on topic:\n<size:10>**connector/v1/responses/command**
deactivate BC
note over LO : *status : **PROCESSED** \n*deliveryStatus: **REPLIED**
@enduml

Final Success Delivery Status

SENT

REPLIED

Default acknowledgement timeout

-

For External connector, the default value of acknowledgement timeout is 24h, and the maximal value is 7 days. Beyond that, the acknowledgement timeout is reached
Values for command registration
@startuml
hide footbox
scale 0.8
participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
BA -> LO : Register command

@enduml

Value field in request command can be any valid JSON. It can contain a map of 100 entries maximum. Each entry can contain 255 characters maximum.

Example: Let’s take the case of a command recorded for a device with an online external connector interface, with an APPLICATIVE acknowledgement level.

{
    "request": {
      "connector": "x-connector",
      "value": {
        "myCommand": "turn on",
        "myParams": {
          "device": "6"
        }
      }
    },
    "policy": {
      "expirationInSeconds": 60,
      "ackMode": "APPLICATIVE"
    }
  }

Command examples by connector

Example for Mqtt

Let’s take the example of a smart lock, connected to Live Objects with an MQTT interface.

Description

From your smartphone, you want to unlock your door for a family member who forgot his keys. The application on your phone will create a command on Live Objects, who will send it to the door

  • You want to know if your unlock request has been well executed.

  • You need to set the maximum waiting time for your order to be executed : 2 minutes here, not three hours due to a connectivity issues.

To do this, you must :

  • Have smartphone business application connected to LO.

  • A smart lock system online who subscribe to the topic dev/cmd on Live Objects

  • Your device must support command capability (check the device before beginning).

Then apply this steps :

  • Send a command request.

  • Wait the processing time

  • Check the result from your smartphone.

Command request details

Your smartphone have to send the following request to LO :

API : POST /api/v1/deviceMgt/devices/<deviceId>/commands

Request sample :

{
    "request": {
        "connector": "mqtt",
        "value": {
            "req": "unlock",
            "arg": {
                "delay": 1000
            }
        }
    },
    "policy": {
        "expirationInSeconds": 120, (1)
        "ackMode": "APPLICATIVE"    (2)
        "ackTimeoutInSeconds": 180, (3)
    }
}
1 When you register a command you must set the expiration timeout, to fix a limit delay for PENDING/RETRYING status, this means that once the command has been registred, Live Objects will wait for a device subscription to the corresponding topic under this delay. Once this delay exceeded without new event from the device, the command status change automatically to EXPIRED.
2 Depending on the Acknowledgement level you have set, Live Objects will wait for a response from the smart lock.
3 If you have set the ackMode to applicative, you can also override the acknowledgement timeout to limit the maximum response time allowed to the device. In this case, we choose an APPLICATIVE acknowldegment level, so a response from the device is mandatory.
Process of the successful case
@startuml
scale 0.8
participant "Your smartphone" as BA #FFF9C4
participant "Live Objects" as LO #orange
participant "Connected **Smart Lock**" as Device #lightgreen

activate BA #green
BA -> LO : Send Command Request\n **"Unlock door"**
activate LO #orange

note over LO : *Request status : **PENDING** \n*Command : **registred**
LO -> Device : Command **"unlock door"** sent\n to topic subscribers
activate Device #lightgreen
LO -> LO : Waiting device response + ack
deactivate LO

note over LO : *status : **PROCESSING**\n*deliveryStatus : **SENT**

note over Device : The connected mechanism\n**receive command**
deactivate LO
note over Device : The Unlock mechanism\nprocess the command.\nthe door is now **unlocked**
note over BA : At any time,\nthe user or the business application\ncan check the **command status**.
Device -> LO : The Unlock mechanism send\nunlocking process result
deactivate Device
activate LO #orange
note over LO : *status : **PROCESSED** \n*deliveryStatus : **REPLIED**

LO --> BA : The request is done
deactivate LO
deactivate BA
@enduml
Timeouts during the process
Two kind of timeouts can happen : Expiration & Acknowledgment timeouts.
@startuml
scale 0.8
participant "Business App" as BA
participant "Live Objects" as LO #orange
participant "Connected **Smart Lock**" as Device #lightgreen

box "Live Objects Timeguard" #LightBlue
participant "Acknowledgement\nTimeout" as ACK
participant "Expiration\nTimeout" as EXP
end box

BA -> LO : Register command
activate LO #orange
note over LO : *status : **PENDING**

activate EXP #red

loop while retry limit not reached
    alt expiration case
        note over Device : Offline
        EXP --> LO : **ExpirationTimeout timeout** exceeded
        deactivate EXP
        note over LO : ERROR CASE 1 : The expiration timeout expired\nbefore being sent\n*status : **EXPIRED**

    end

    LO -> Device : Command **"unlock door"** sent
    activate ACK #red
    LO -> LO : Waiting device ack

    note over LO : *status : **PROCESSING**\n*deliveryStatus : **SENT**
    ACK --> LO : **Acknowledgement timeout** exceeded
    note over LO : *status : **RETRYING**
end


ACK --> LO : **Acknowledgement timeout** exceeded
deactivate ACK
note over LO : ERROR CASE 2 : The waiting ack delay expired\nThere is no more retry available\n*status : **ERROR**
@enduml
Check the status of the command
At anytime during process, you can check the command status or get the whole command
@startuml
hide footbox
scale 0.8
participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
BA -> LO : Check Command Status
activate LO #orange
LO -> BA : Command Status Response
deactivate LO

BA -> LO : Get Command
activate LO #orange
LO -> BA : Command Response
deactivate LO
@enduml

API : GET /api/v1/deviceMgt/commands/{commandId}/status

Response :

{
"content": "PROCESSED"
}

Response for the entire command, the request is the same but use another endpoint

API : GET /api/v1/deviceMgt/commands/<commandId>

Response :

{
    "id": "ae49129f-9ce4-4782-82c4c6a2",
    "targetDeviceId": "urn:lo:nsid:smartlock:123456",
    "request": {
        "connector": "mqtt",
        "value": {
            "req": "unlock",
            "arg": {
                "delay": 1000
            }
        }
    },
    "response": {
        "done": true
    },
    "status": "PROCESSED",
    "deliveryStatus": "REPLIED",
    "policy": {
        "expirationInSeconds": 120,
        "ackTimeoutInSeconds": 180,
        "ackMode": "APPLICATIVE"
    },
    "history": [
        {
            "timestamp": "2017-12-06T11:32:25.055Z",
            "status" : "PENDING"
        }, {
            "timestamp": "2017-12-06T11:38:22.481Z",
            "status": "PROCESSING",
            "deliveryStatus": "SENT",
            "nodeId": "abcd123456"
        }, {
            "timestamp": "2017-12-06T11:38:24.124Z",
            "status": "PROCESSED",
            "deliveryStatus": "REPLIED",
            "nodeId": "abcd123456"
        }
    ],
    "created": "2017-12-06T11:32:25.055Z",
    "updated": "2017-12-06T11:38:24.124Z"
}

Example for LoRa®

Let’s take the example of a smart sensor of water metering, connected to Live Objects with LoRa® interface.

Description

The objective is to monitor a water usage monthly. To do this, you must :

  • Send a "reset to zero" command to the water meter at the end of the month.

    • The command will be sent in a binary format supported by LoRa® connectivity.

  • Have water meter system connected to Live Objects with LoRa® interface.

Then apply this steps :

  • Register command through Live Objects portal or your business application.

  • Follow the command status during the operation.

  • Check the result

The LoRa® devices has a low energy consumption as well as sleeping time is relatively long. So, the command request takes time to be processed. The expiration timeout must be set with high values.
Command processing policy

-Set your command processing policy before registering_

POST /api/v1/deviceMgt/devices/urn:lo:nsid:lora:watermeter123/commands

{
    "request": {
        "connector": "lora",
        "value": {
            "data": "44D2F0",
            "port": "125"
        }
    },
    "policy": {
        "expirationInSeconds": 28800,  (1)
        "ackMode": "NETWORK"           (2)
    }
}
1 The expiration timeout can be setted to replace the default limit delay for PENDING/RETRYING status.
2 Depending on the Acknowledgement level setted, Live Objects will wait for a response from the water meter. In this case, we choose a NETWORK acknowldegment level, so a response from the LoRa® network is mandatory.

The acknowledgment timeout can’t be setted by the customer

Process of the successful case
@startuml
scale 0.8
participant "Business App" as BA #FFF9C4
participant "Live Objects & Network" as LO #orange
participant "Smart connected \nwater meter" as WM #lightgreen

BA -> LO : Send request to water meter\n(binary **downlink**) **"reset to zero"**

activate LO #orange

note over LO : *Status : **PENDING**\n*Command : **registred**

note over WM : Sleeping time
LO -> LO : Waiting for the device activity

deactivate LO
activate WM #lightgreen

WM -> LO :  Wakes up and send uplink
deactivate WM
activate LO #orange

LO -> WM : The network Send Command \n"reset to zero" (downlink)
activate WM #lightgreen

note over LO : *Status : **PROCESSING**\n*DeliveryStatus: **SENT**

LO -> LO : Waiting for the device activity with ack
deactivate LO
note over WM : Processing time

WM -> LO : Uplink with downlink ACK
deactivate WM
activate LO #orange
note over LO : *Status : **PROCESSED** :\n*SeliveryStatus: **DELIVERED**\n*Stored value for the water meter : **0**
LO --> BA : The request is done
deactivate LO
@enduml
Timeouts during the process
Two kind of timeouts can happen : Expiration & Acknowledgment timeouts.
@startuml
scale 0.8
participant "Business App" as BA #FFF9C4
participant "Live Objects" as LO #orange
participant "Smart connected \nwater meter" as WM #lightgreen

box "Live Objects Timeguard" #LightBlue
participant "Acknowledgement\nTimeout" as ACK
participant "Expiration\nTimeout" as EXP
end box

BA -> LO : Register command
activate LO #orange
note over LO : *status : **PENDING**
activate EXP #red

loop while retry limit not reached
    alt expiration case
        note over WM : Offline
        EXP --> LO : **ExpirationTimeout timeout** exceeded
        deactivate EXP
        note over LO : ERROR CASE 1 : The expiration timeout expired\nbefore being sent\n*status : **EXPIRED**

    end

    LO -> WM : Command **"reset to zero"** sent
    activate ACK #red
    note over LO : *status : **PROCESSING**\n*deliveryStatus : **SENT**
    activate WM #lightgreen
    LO -> LO : Waiting device **ack**
    deactivate LO
    loop while waiting ack limit not reached
        WM -> LO :  Wakes up and send uplink **without ack**
        deactivate WM
        activate LO #orange
    end
    ACK --> LO : **Acknowledgement timeout** exceeded\n(no ack on the **3** lasts uplinks)
    note over LO : *status : **RETRYING**
end


    ACK --> LO : **Acknowledgement timeout** exceeded\n(no ack on the 3 lasts uplinks \n& retry limit reached)
    deactivate ACK
deactivate EXP
note over LO : CASE 2 : The waiting ack max attempts was reached\n*status : **ERROR**

@enduml

Example for SMS

We return to the example presented previously of a smart lock with the MQTT interface, in this example we have connected our Unlock system to Live Objects with an SMS interface.

Now we register a command through an SMS interface and Live objects will be sent this command with an SMS message to connected device.

Register command
POST /api/v1/deviceMgt/devices/urn:lo:nsid:sms:unlock123/commands
{
    "request": {
      "connector": "sms",
      "value": {
        "payload": "unlock",
        "type": "TEXT"
      }
    },
    "policy": {
        "expirationInSeconds": 60,  (1)
        "ackMode": "NONE"           (2)
    }
 }
1 When you register a command you must set the expiration timeout, to fix a limit delay for PENDING/RETRYING status, this means that once the command has been registred, Live Objects will wait until the request was sent. Once this delay exceeded, the command status change automatically to EXPIRED. (This can happen if you have paused your SMS interface for exemple) In this case, after 60 seconds waiting, Live Objects change the status of the command at EXPIRED.
2 When your device use SMS interface, only ackMode NONE is supported.
Register a binary command

The same example with a binary command

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sms:unlock123/commands
{
    "request": {
      "connector": "sms",
      "value": {
        "payload": "756e6c6f636b", (1)
        "type": "BINARY"           (2)
      }
    },
    "policy": {
        "expirationInSeconds": 60,
        "ackMode": "NONE"
    }
 }
1 Payload in hex format, converted from string = "unlock".
2 Payload type must be set with value = BINARY
Version 2026.9.1 • Updated date 2026-10-08_07:03:47_UTC