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.

DeviceLO MQTTDeviceDeviceLO MQTTLO MQTTInit connectionNotify status : available config for updateOPTIONAL1Notify current configuration (params)2Save and compare withtarget configuration3Request configuration update4Apply5Response to config. update :new current configuration.6Save
Figure 1. Device configuration sync steps

  • (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".

NONEPENDINGCANCELEDSENTOKFAILEDSTART : Create parameterSet a target valuewaiting device connectionCancel the parameter updateForce cancelDevice is connectedand readyto parameter updatesdevice responds to the requestThe deviceacceptedthe target valueThe devicerejectedthe target value
Figure 2. Device configuration sync states

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.7.0 • Updated date 2026-08-11 12:37:29 UTC