Device configuration

Principle

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.

Device configuration sync steps
@startuml
scale 0.8
skinparam participant {
  BackgroundColor #FFF9C4
  BorderColor #B22222
  FontColor Black
  'FontStyle bold
}
skinparam ParticipantBorderThickness 1.5
Device <-[#A9A9A9]-> "LO MQTT": Init connection
Device -> "LO MQTT": Notify status : available config for update

autonumber
group OPTIONAL
Device -> "LO MQTT": Notify current configuration (params)
"LO MQTT" -> "LO MQTT" : Save and compare with\n target configuration

"LO MQTT" -> Device : Request configuration update
Device -> Device : Apply
Device -> "LO MQTT" : Response to config. update : //new current configuration.//
"LO MQTT" -> "LO MQTT" : Save
end
@enduml

  • (before) :

    • device initiates MQTT connection with Live Objects,

    • device subscribes in MQTT to a private topic, where it will receive later the configuration update requests,

  • step 0 : device notifies Live Objects that it is connected and available for configuration updates on a specific topic,

  • step 1 : device notifies Live Objects of its current configuration,

  • step 2 : Live Objects compares the current and target configuration for this device. If they differ:

    • step 3 : Live Objects sends to the device, on the topic indicated at step 0, the list of parameters to update, with their target value,

    • step 4 : device handles the request, and tries to apply the change(s),

    • step 5 : device respond to the change request with the new configuration,

    • step 6 : Live Objects saves the new configuration. Parameters that have been successfully updated now have the status "OK" and the others the status "FAILED".

Device configuration sync states
@startuml
scale 0.8
skinparam ParticipantBorderColor #B22222
skinparam ParticipantBorderThickness 1.5
skinparam NoteBackgroundColor #FFF3B0
skinparam ArrowColor #B22222

(*)  --> [ START : Create parameter] "NONE" #FFF3B0
"NONE" --> [ Set a target value] "PENDING" #FFF3B0
if "//waiting device connection//" then
--> [Cancel the parameter update] "CANCELED" #FFF3B0
"SENT" --> [Force cancel] "CANCELED"
else
 --> [Device is connected\nand ready\nto parameter updates] "SENT" #FFF3B0
endif
if "//device responds to the request//" then
--> [The device **accepted** the target value] "OK"#FFF3B0
else
--> [The device **rejected** the target value] "FAILED" #FFF3B0
@enduml

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.

Get device configuration parameters

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

Request

Endpoint:

GET /api/v1/deviceMgt/devices/<deviceId>/config/parameters

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/config/parameters

Response

HTTP Code:

200 OK

Body:

For each parameter, the following information is available :

{
  "{paramKey}": {
    "reported": {
        "type": {paramType},
        "value": {paramValue},
        "timestamp": {timestampsValue}
    },
    "requested": {
        "type": {paramType},
        "value": {paramValue},
        "timestamp": {timestampsValue}
    },
    "syncStatus": {paramStatus}
}

With:

paramKey

string uniquely identifying the device configuration parameter

paramType

indicates the config parameter type between: INT32, UINT32, BINARY, STRING or FLOAT

paramValue

value requested for the parameter

timestampsValue

update date of the parameter

paramStatus

parameter update status: NONE, PENDING, SENT, CANCELED, OK or FAILED

The section reported is present when the device has answered and corresponds to parameter configuration returned by the device, the paramStatus could be OK or FAILED.

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

404

DM_DEVICE_NOT_FOUND

Device not found

Example:

{
  "param1" : {
    "requested" : {
      "type" : "INT32",
      "value" : 1,
      "timestamp" : "2018-08-23T08:10:01.029Z"
    },
    "syncStatus" : "PENDING"
  },
  "param2" : {
    "requested" : {
      "type" : "UINT32",
      "value" : 4321,
      "timestamp" : "2018-08-01T14:39:16.216Z"
    },
    "syncStatus" : "PENDING"
  },
  "param3" : {
    "reported" : {
      "type" : "FLOAT",
      "value" : 3.2,
      "timestamp" : "2018-04-26T08:16:33.681Z"
    },
    "requested" : {
      "type" : "FLOAT",
      "value" : 3.2,
      "timestamp" : "2019-06-17T12:52:20.930Z"
    },
    "syncStatus" : "OK"
  },
  "param4" : {
    "requested" : {
      "type" : "BINARY",
      "value" : 11001,
      "timestamp" : "2018-08-01T14:37:52.579Z"
    },
    "syncStatus" : "CANCELED"
  },
  "param5" : {
    "reported" : {
      "type" : "STRING",
      "value" : "my data",
      "timestamp" : "2018-03-29T08:48:20.810Z"
    },
    "requested" : {
      "type" : "STRING",
      "value" : "info",
      "timestamp" : "2018-03-29T08:48:20.813Z"
    },
    "syncStatus" : "FAILED"
  }
}

Set device configuration parameters

Request

Endpoint:

POST /api/v1/deviceMgt/devices/<deviceId>/config

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json

Body:

JSON Params Description

parameters

list of device configuration update

Each parameter to update must have the following structure:

"{paramKey}": {
    "type": {paramType},
    "value": {paramValue}
}

With:

paramKey

a string uniquely identifying the device configuration parameter. Should not start with $ character

paramType

indicates the config parameter type between

"INT32"

the value must be an integer from -2,147,483,648 to 2,147,483,647,

"UINT32"

the value must a positive integer from 0 to 4,294,967,295,

"BINARY"

the value is a base64 encoded binary content,

"STRING"

the value is a UTF-8 string,

"FLOAT"

the value is float (64 bits) value.

Example:

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/config
{
    "parameters": {
        "MyParamINT32" : {
            "type" : "INT32",
            "value" : -333
        },
        "MyParamSTRING" : {
            "type" : "STRING",
            "value" : "My sentense"
        }
    }
}

Response

HTTP Code:

200 OK

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.
If the device does not exist, it will be auto-provisionned.

Get a description of the device configuration

Request

Endpoint:

GET /api/v1/deviceMgt/devices/<deviceId>/config

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/config

Response

HTTP Code:

200 OK

Body:

JSON Params Description

parameters

list of device configuration update

For each parameter, the following information is available :

{
  "parameters" : {
      "{paramKey}": {
          "reported": {
              "type": {paramType},
              "value": {paramValue},
              "timestamp": {timestampsValue}
          },
          "requested": {
              "type": {paramType},
              "value": {paramValue},
              "timestamp": {timestampsValue}
          },
          "syncStatus": {paramStatus}
      }
  }
}

With:

paramKey

string uniquely identifying the device configuration parameter

paramType

indicates the config parameter type between: INT32, UINT32, BINARY, STRING or FLOAT,

paramValue

value requested for the parameter,

timestampsValue

update date of the parameter,

paramStatus

parameter update status; NONE, PENDING, SENT, OK or FAILED.

The section reported is present when the device has answered and corresponds to parameter configuration return by the device, the paramStatus could be OK or FAILED.

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

404

DM_DEVICE_NOT_FOUND

Device not found

Example:

{
    "parameters": {
        "MyParamFLOAT": {
            "requested": {
                "type": "FLOAT",
                "value": 1245,
                "timestamp": "2018-03-07T10:55:21Z"
            },
            "syncStatus": "PENDING"
        },
        "MyParamBINARY": {
            "requested": {
                "type": "BINARY",
                "value": "Nzg3ODY4Ng==",
                "timestamp": "2018-03-07T10:54:55.948Z"
            },
            "syncStatus": "SENT"
        },
        "MyParamINT32": {
            "reported": {
                "type": "INT32",
                "value": -333,
                "timestamp": "2018-03-07T10:53:21.934Z"
            },
            "requested": {
                "type": "INT32",
                "value": -333,
                "timestamp": "2018-03-07T10:53:21.937Z"
            },
            "syncStatus": "OK"
        }
    }
}

Get state of a specific device configuration parameter

Request

Endpoint:

GET /api/v1/deviceMgt/devices/<deviceId>/config/parameters/<paramKey>

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/config/parameters/MyParamFLOAT

Response

HTTP Code:

200 OK

Body:

JSON Params Description

reported

Optional. reported configuration parameter value

requested

requested configuration parameter value

syncStatus

parameter update status; NONE, PENDING, SENT, CANCELED, OK or FAILED

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

404

DM_DEVICE_CONFIG_PARAM_NOT_FOUND

Device configuration parameter not found

Example:

{
    "requested": {
        "type": "FLOAT",
        "value": 1245,
        "timestamp": "2018-03-07T10:55:21Z"
    },
    "syncStatus": "PENDING"
}
Version 2026.9.1 • Updated date 2026-10-08_07:03:47_UTC