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:
Command status summary table
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.
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 |
||
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
| JSON Params | Description |
|---|---|
req |
the command in string format |
arg |
List of parameters.
Should not contain field name with |
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 |
||
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
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
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 |
||
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
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. |
Timeouts during the process
Check the status of the command
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
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 |