Device and connectivity

The version 1 of the device APIs (/api/v1/deviceMgt) comes up with a brand new model of devices in Live Objects.

We have worked on providing unified representations whatever the technology that is used to connect the device to Live Objects using IP connectivity (MQTT, HTTP), LoRa® or SMS, while maintaining the access to each specific technology.

Principles

A device is a generic term that can designate an equipment (sensor, gateway) or an entity observed by equipments (ex: a building, a car).

Device description

A device description is a set of JSON documents that store a device identity information, a device state information, a metadata (definition, activity, alias) a device connectivity information for each device that you will connect to Live objects.

Each device description has 2 sections to describe the device representation :

  • Device identity.

  • Device interface representation.

Devices representation

Device identifier format

A device identity is represented by a unique identifier. This identifier must respect the following format:

urn:lo:nsid:{ns}:{id}

Where:

  • ns: your device identifier "namespace", used to avoid conflicts between various families of identifier

  • id: your device id

Should only contain alphanumeric characters (a-z, A-Z, 0-9) and/or any special characters amongst : - _ and must avoid $ ' ' * # / !| + and must respect the following regular expression: ^urn:lo:nsid:([\w-]{1,128}):([:\w-]{1,128})$ (with max 269 characters).

If your device is auto-provisioned (first connection), the device identifier namespace is automatically completed according to the "urn:lo:nsid" prefix (if not available) + the set of characters according the previous rule of regular expression.

Device object model

Depending on your connectivity interface, the device object model may have a dedicated "definition" section to describe the parameters of your interface (s).

Device object model overview:

deviceid:Stringname:Stringdescription:StringdefaultDataStreamId:StringactivityState:Stringcreated:Dateupdated:Dateconfig:Stringresources:StringactivityState:StringtagsEnum[]propertieskey1:Stringkey2:String...interfaceconnector:StringdeviceId:stringnodeId:Stringenabled:Boolstatus:StringlastContact:Datecreated:Dateupdated:Datedefinitionsome parameters:...encoding:Stringdepending on your connectivity,see the adaptative modelof the interface definition LoRa® interface definitionMQTT interface definitionSMS interface definitionX-CONNECTOR interface definitioncapabilitiesconfigurationcommandresourcesactivitylastactivationTs:DatelastDeactivationTs:DatestaticLocationalt:Floatlat:Floatlon:Floatgroupid:Stringpath:Stringinterface_1interface_2
Figure 1. device representation model.

Device model in Json format

{
  "id": "urn:lo:nsid:sensor:temp001",
  "name": "mySensor001",
  "description": <<some description>>,
  "defaultDataStreamId": <<myStreamId>>,
  "activityState": <<monitoring the device>>
  "tags": ["Lyon", "Test"],
  "properties" : {
      "manufacturer": <<myManufacturer>>,
      "model": <<myModel>>
  },
  "group": {
      "id": <<id>>,
      "path": <<myPathId>>
  },
  "interfaces": [
        {
          "connector": <<myConnector>>,
          "nodeId": <<interface Id>>,
          "deviceId": "urn:lo:nsid:sensor:temp001",
          "enabled": <<true/false>>,
          "status": <<the status of the interface>>,
          "definition": {
                ........to learn more, see the "Device interface representation" section
          },
          "activity": {},
          "capabilities": {
                "command": {
                   "version" : <<versionNumber>>,
                   "available": <<true/false>>
                },
                "configuration": {
                   "available": <<true/false>>
                },
                "resources": {
                   "available": <<true/false>>
               }
           }
        }
    ],
    "created": <<date>>,
    "updated": <<date>>,
    "staticLocation": {
        "lat": <<Latitude value>>,
        "lon": <<Longitude value>>,
        "alt": <<Altitude value>>
    }
}

Device object model description:

JSON Params Description

id

device unique identifier (Cf. device identifier)

description

Optional. detailed description of the device

name

Optional. name of the device

defaultDataStreamId

default data stream id. Specify the streamId where the data will be store (Cf. "Manage your data stream" section).

tags

Optional. list of additional information used to tag device messages

properties

Optional. map of key/value string pairs detailing device properties

group

group to which the device belongs. The group is defined by its id and its path

interfaces

Optional. list of device network interfaces (Cf. interface object model)

created

creation date of the device

updated

last update date of the device

config

Optional. device configuration

firmwares

Deprecated device firmware versions (same value as "resources", available for compatibily reasons)

resources

Optional. device resource versions

activityState

Optional. device activity state aggregated from the activity processing service, the special state NOT_MONITORED means that the device is not targeted by any activity rule

staticLocation

Optional. the static location of device.
To avoid data personnal exposure, we strongly recommended to do not add a pesronnal and sensitive information in your tags and properties fields. This data are exposed and accessibles to Live Objects other services and components.

Device interface representation

An interface is a platform access. A device can have no, one or several interfaces, which represent different connectivities that the device could use to communicate with Live Objects. Each interface is associated to a protocol managed by Live Objects connector: LoRa®, SMS or MQTT. For the custom protocols, the devices must connected with external connector interface.

Interactive
Figure 2. devices with single/multi connectivity.

Interface object model:

JSON Params Description

connector

connector identifier

nodeId

interface unique identifier

deviceId

Optional. device unique identifier

enabled

define if the interface is enabled or disabled

status

interface status

definition

interface definition. The definition depends on connector.

lastContact

Optional. lastContact is the last date of the last uplink from the device, in LoRa® connectivity, this field is also updated during a join request sent by the device.

activity

interface activity. The activity depends on connector.

capabilities

interface capabilities.

locations

Optional. list of last interface location.

created

registration date of the interface

updated

last update date of the interface

For more information on each connector definition, activity and status, see the appropriate section:

Interface status

Each interface has a status field which shows the state of the corresponding interface. The values are the same for all connectors, but each connector sets the status differently. The following table shows which statuses are supported, or will soon be supported by connectors.

Status \ Connector

LoRa®

MQTT

SMS

External connector

LwM2M

REGISTERED

☑

☑

☐

☑

☑

ONLINE

☐

☑

☑

☑

☑

OFFLINE

☐

☑

☐

☑

☑

SLEEPING

☐

☐

☐

☐

☑

CONNECTIVITY_ERROR

☑

☐

☐

☐

☐

INITIALIZING

☑

☐

☐

☐

☐

INITIALIZED

☑

☐

☐

☐

☐

REACTIVATED

☑

☐

☐

☐

☐

ACTIVATED

☑

☐

☐

☐

☐

DEACTIVATED

☑

☑

☑

☐

☑

Each interface has an enabled flag which allows or forbids an interface to connect and communicate with Live Objects. The enabled flag changes the interface’s status.

This flag can be set when creating the interface or updating the interface.

The following table shows a description of each technical value of the interface status.

Status Value Description

REGISTERED

The device has been registered in the network with the parameters specified when it was created. No uplink data has yet been received by the platform.

INITIALIZING

The network received a Join Request from the device

INITIALIZED

The network sent a Join Accept to the device

ACTIVATED

At least one uplink issued by the device was received by Live Objects (excluding MAC messages)

DEACTIVATED

The device has been deactivated in Live Objects. He can no longer communicate on the network (See the paragraph "Deactivate and reactivate a LoRa® device" and see the deactivation of the LwM2M device.

REACTIVATED

The device has been reactivated in Live Objects. Not being able to know a priori the state of the device at the time of the reactivation, the state will pass to "Activated" if a Join Request is received, or directly to "Activated" if an uplink is received.

CONNECTIVITY_ERROR

This status, rare, is displayed in case of problem on configuration of the equipment in the network. If this status appears, contact your support.

ONLINE (MQTT)

The MQTT connection of the device is active

ONLINE (LwM2M)

The LwM2M device is registered and active

SLEEPING (LwM2M)

The LwM2M device is in sleeping mode but the session is still active.

OFFLINE (MQTT)

The device has already connected at least once but its MQTT connection is inactive

OFFLINE (LwM2M)

The LwM2M device is deregistred or deactivated.

ONLINE (SMS)

The SMS device is activated at Live Objects level

OFFLINE (SMS)

The SMS device is deactivated at Live Objects level

Capabilities

Capabilities \ Connector

LoRa®

MQTT

SMS

External connector

LwM2M

Command

☑

☑

☑

☑

☑

Configuration

☐

☑

☐

☐

☑

Resource

☐

☑

☐

☐

☑

Twin

☐

☐

☐

☐

☑

Interface capabilities represent the Live Objects features compatibility.

  • Command : Compatibility with the generic command engine and API

  • Configuration : Compatibility with config update feature. MQTT connectivity only for now

  • Resource : Compatibility with resource update feature. MQTT connectivity only for now

  • Twin : Compatibility with the Live Objects twin service. LwM2M/CoAP connectivity only for now

Device static location

The static location is a set of a declared geographical coordinates values (longitude, latitude and altitude). Its section in the device object model must have the following format:

"staticLocation": {
        "lat": <<Latitude value>>,
        "lon": <<Longitude value>>,
        "alt": <<Altitude value>>
    }

This info is useful for stationary devices, or devices that are not sending location information to Live Objects.

This section can be created if setted during device provisioning.
POST /api/v1/deviceMgt/devices/<myDeviceId>
{
    "id": "<myDeviceId>",
    "description": "Device 123",
    "name": "My Device",
    "defaultDataStreamId": "MydefaultStream"
    "interfaces": [
        {
            "connector": "mqtt",
            "enabled": true,
            "definition": {
                "clientId" : "<myDeviceId>",
                "encoding" : "myEncoding"
            }
        }
    ],
    "staticLocation": {
        "lat": <<Latitude value>>,
        "lon": <<Longitude value>>
    }
}

Device management basic

Register a device

Request

Endpoint:

POST /api/v1/deviceMgt/devices

HTTP Headers:

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

Body:

JSON Params Description

id

device unique identifier (Cf. device object model)

tags

Optional. (Cf. device object model)

name

Optional. (Cf. device object model)

description

Optional. (Cf. device object model)

defaultDataStreamId

Optional. (Cf. device object model)

properties

Optional. (Cf. device object model)

group

Optional. (Cf. device object model)

interfaces

Optional. (Cf. device object model)

Devices can be registered with one or more chosen interfaces.

Currently, you can associate an SMS interface (Cf. register device with an SMS interface example) or a LoRa® interface (Cf. register device with a LoRa® interface example) with the devices. The other supported interfaces, the MQTT and External connector interfaces can be automatically registered during the first MQTT connection.

Example: Register a device without interface

POST /api/v1/deviceMgt/devices
{
  "id": "urn:lo:nsid:sensor:temp001",
  "tags": ["Lyon", "Test"],
  "name": "mySensor001",
  "description": "moisture sensor",
  "properties" : {
      "manufacturer": "Orange",
      "model": "MoistureSensorV3"
  },
  "group": {
      "path": "/france/lyon"
  }
}

Response

HTTP Code:

200 OK

Body:

Cf. device object model

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

403

GENERIC_OFFER_DISABLED_ERROR

The requested service is disabled in your offer settings. Please contact a sales representative.

403

GENERIC_ACTION_FORBIDDEN_ERROR

You do not have the required permissions to execute this action.

404

DM_GROUP_NOT_FOUND

Group not found

409

DM_INTERFACE_DUPLICATE

Interface already exists. Conflict on (connector/nodeId)

409

DM_DEVICE_DUPLICATE

Conflict on device id

Example: Register a device without interface

{
    "id": "urn:lo:nsid:sensor:temp001",
    "description": "moisture sensor",
    "name": "mySensor001",
    "defaultDataStreamId": "urn:lo:nsid:sensor:temp001",
    "tags": ["Lyon", "Test"],
    "properties": {
        "manufacturer": "Orange",
        "model": "MoistureSensorV3"
    },
    "group": {
        "id": "sWyaL2",
        "path": "/france/lyon"
    },
    "created": "2018-02-12T13:29:52.442Z",
    "updated": "2018-02-12T13:29:52.442Z"
}

List devices

Request

Endpoint:

GET /api/v1/deviceMgt/devices

Query parameters:

Name Description

limit

Optional. maximum number of devices in response. 20 by default.

offset

Optional. the number of entries to skip in the results list. 0 by default.

sort

Optional. sorting selection. Prefix with '-' for descending order. Supported value: id, name, group, created, updated,interfaces.status, interfaces.enabled, interfaces.lastContact. Example: ["urn","-creationTs"]"..

id

Optional. device id

groupPath

Optional. groupPath, Supported filters are → exact match : foo, group or subgroups : foo/*

groupId

Optional. filter list by groupId

name

Optional. device name, Supported filters are → contains : *foo*, end with foo : *foo, start with foo : foo*, exact match : "foo" or foo

tags

Optional. filter list by device tags

connectors

Optional. filter list by interface connector

fields

Optional. fields to return for each device. By default, information returned are id, name, group and tags. Supported value: name, description, group, tags, properties, interfaces, config, firmwares (deprecated), resources, defaultDataStreamId, activityState, created and updated.

interfaces.nodeId

Optional. Filter list by nodeId.

interfaces.status

Optional. Filter list by interface status.

interfaces.enabled

Optional. Filter list by interface enabled state.

property.{\filterName\}

Optional. Multiple filters, Example: devices?property.temperature=25&property.humidity=58…​

filterQuery

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

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json
X-Total-Count: <boolean>

For more info about X-Total-Count, see "API v1 paging" section.

Simple devices list request:

Get name, creation date and group of device having name starting with mySensor sorted by id descending.

GET /api/v1/deviceMgt/devices?name=mySensor*&sort=-id&fields=name,created,group

RSQL advanced devices list request:

Get id field only of devices matching following (RSQL filter url-encoded under) filterQuery: groupPath==/France;tags==demo;connector==lwm2m or (connector==x-connector)

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

GET /api/v1/deviceMgt/devices?fields=id&filterQuery=groupPath%3d%3d/France%3btags%3d%3ddemo%3bconnector%3d%3dlwm2m+or+(connector%3d%3dx-connector)

Response

HTTP Code:

200 OK

Body: List of device object model

JSON Params Description

id

device unique identifier

description

Optional. detailed description of the device

name

Optional. name of the device

defaultDataStreamId

Optional. default data stream Id of the device

tags

Optional. list of device tags

properties

Optional. properties of the device

group

Optional. group to which the device belongs

interfaces

Optional. list of device’s network interfaces

created

Optional. registration date of the device

updated

Optional. last update date of the device

config

Optional. device configuration

firmwares

Deprecated device firmware versions (same value as "resources", available for compatibily reasons)

resources

Optional. device resource versions

activityState

Optional. device activity state aggregated from the activity processing service, the special state NOT_MONITORED means that the device is not targeted by any activity rule

Simple devices list response example:

[
    {
        "id": "urn:lo:nsid:sensor:temp002",
        "name": "mySensor002",
        "group": {
            "id": "root",
            "path": "/"
        },
        "created": "2021-07-01T09:02:40.616Z"
    },
    {
        "id": "urn:lo:nsid:sensor:temp001",
        "name": "mySensor001",
        "group": {
            "id": "sWyaL2",
            "path": "/france/lyon"
        },
        "created": "2021-07-01T09:02:40.616Z"
    }
]

Get a device

Request

Endpoint:

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

HTTP Headers:

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

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:mqtt:myTest

Response

HTTP Code:

*200 OK*

Body:

Cf. device object model

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

401

UNAUTHORIZED

Authentication failure.

404

DM_DEVICE_NOT_FOUND

Device not found.

Example:

{
    "id": "urn:lo:nsid:sensor:temp002",
    "name": mySensor002",
    "description": "This device was auto registered by the connector [mqtt] with the nodeId [urn:lo:nsid:mqtt:myTest]",
    "group": {
        "id": "root",
        "path": "/"
    },
    "defaultDataStreamId": "urn:lo:nsid:sensor:temp002",
    "created": "2021-07-01T09:02:40.616Z",
    "updated": "2021-07-01T09:04:46.752Z",
    "activityState": "NOT_MONITORED",
    "interfaces": [
        {
            "connector": "mqtt",
            "nodeId": "urn:lo:nsid:mqtt:myTest",
            "enabled": true,
            "status": "OFFLINE",
            "lastContact": "2021-08-13T09:05:06.751Z",
            "capabilities": {
                "configuration": {
                    "available": false
                },
                "command": {
                    "available": false
                },
                "resource": {
                    "available": false
                },
                "twin": {
                    "available": false
                }
            },
            "activity": {
                "apiKeyId": "60508c314ca6b82d6d605b1e",
                "mqttVersion": 4,
                "mqttUsername": "json+device",
                "mqttTimeout": 60,
                "remoteAddress": "82.13.102.175/27659",
                "lastSessionStartTime": "2021-08-13T09:03:21.158Z",
                "lastSessionEndTime": "2021-08-13T09:04:06.750Z"
            },
            "created": "2021-07-01T09:02:40.615Z",
            "updated": "2021-07-01T09:04:46.752Z"
        }
    ]
}

Delete device

Request

Endpoint:

DELETE /api/v1/deviceMgt/devices/<deviceId>

HTTP Headers:

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

Example:

DELETE /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001

Response

HTTP Code:

204 NO CONTENT

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

Device interface management

Add an interface to a registered device

Request

Endpoint:

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

HTTP Headers:

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

Body:

JSON Params Description

connector

connector id

enabled

define if the interface is enabled or disabled

definition

interface definition. The definition depends on connector (Cf. SMS interface definition or LoRa® interface definition).

Currently, you can only create an SMS or an LoRa® interface, MQTT interface will be auto-provisionned at the first connection.

Example: Create an SMS interface

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/interfaces
{
    "connector": "sms",
    "enabled": true,
    "definition": {
        "msisdn": "33601201201"
    }
}

Response

HTTP Code:

200 OK

Body:

Cf. Interface object model

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

403

GENERIC_OFFER_DISABLED_ERROR

The requested service is disabled in your offer settings. Please contact a sales representative.

404

DM_DEVICE_NOT_FOUND

Device not found

404

DM_CONNECTOR_UNAVAILABLE

Connector not found or unavailable

409

DM_INTERFACE_DUPLICATE

Interface already exists. Conflict on (connector/nodeId)

Example:

{
    "connector": "sms",
    "nodeId": "33601201201",
    "deviceId": "urn:lo:nsid:sensor:temp001",
    "enabled": true,
    "status": "ONLINE",
    "definition": {
        "msisdn": "33601201201"
    },
    "activity": {},
    "capabilities": {
        "command": {
            "version" : 1,
            "available": true
        },
        "configuration": {
            "available": false
        },
        "resources": {
            "available": false
        }
    },
    "created": "2018-03-02T15:54:33.943Z",
    "updated": "2018-03-02T15:54:33.943Z"
}

List device interfaces

Request

Endpoint:

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

HTTP Headers:

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

Example:

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

Response

HTTP Code:

200 OK

Body:

List of Interface object model

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:

[
  {
    "connector": "sms",
    "nodeId": "33601201201",
    "enabled": true,
    "status": "ONLINE",
    "activity": {},
    "definition" : {
        "msisdn" : "33601201201",
        "serverPhoneNumber" : "12345"
    },
    "capabilities": {
        "command": {
            "version" : 1,
            "available": true
        },
        "configuration": {
            "available": false
        },
        "resources": {
            "available": false
        }
    }
  },
  {
    "connector": "mqtt",
    "nodeId": "urn:lo:nsid:sensor:temp001",
    "enabled": true,
    "status": "ONLINE",
    "lastContact": "2018-03-02T15:57:23.772Z",
    "activity" : {
        "apiKeyId" : "6c2c569d91b5f174f60bd73d",
        "mqttVersion" : 4,
        "mqttUsername" : "json+device",
        "mqttTimeout" : 60,
        "remoteAddress" : "217.0.0.0/44341",
        "lastSessionStartTime" : "2019-07-24T15:09:22.560Z",
        "lastSessionEndTime" : "2019-07-24T16:20:37.333Z",
        "security" : {
            "secured": true,
            "protocol": "TLSv1.2",
            "cipher": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
            "clientCertAuthentication": true,
            "sniHostname": "mqtt.liveobjects.orange-business.com"
        }
    },
    "capabilities": {
        "command": {
            "version" : 1,
            "available": true ("false" if the device is "OFFLINE" or has not suscribed to the topic "dev/cmd")
        },
        "configuration": {
            "version" : 1,
            "available": true ("false" if the device is "OFFLINE" or has not suscribed to the topic "dev/cfg")
        },
        "resources": {
            "version" : 1,
            "available": true ("false" if the device is "OFFLINE" or has not suscribed to the topic "dev/rsc/upd")
        }
    },
    "firmwares" : { (same value as "resources", available for compatibility reasons)
        "MyFW" : "1.0.2"
    },
    "resources" : {
        "MyFW" : "1.0.2"
    }
  }
]

Get interface details

Request

Endpoint:

GET /api/v1/deviceMgt/devices/<deviceId>/interfaces/<interfaceId>

The interfaceId must respect the following format {connector}:{nodeId}.

HTTP Headers:

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

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/interfaces/sms:33601201201

Response

HTTP Code:

200 OK

Body:

Cf. Interface object model

Error case:

HTTP Code Error code message

403

GENERIC_OFFER_DISABLED_ERROR

The requested service is disabled in your offer settings. Please contact a sales representative.

404

DM_CONNECTOR_UNAVAILABLE

Connector not found or unavailable

404

DM_INTERFACE_NOT_FOUND

Interface not found

404

DM_DEVICE_NOT_FOUND

Device not found

Example:

{
        "connector": "sms",
        "nodeId": "33601201201",
    "deviceId": "urn:lo:nsid:sensor:temp001",
        "enabled": true,
        "status": "ONLINE",
        "definition": {
            "msisdn": "33601201201"
        },
        "activity": {
            "lastUplink": {
                "timestamp": "2018-03-05T10:43:46.268Z",
                "serverPhoneNumber": "20259"
            }
        },
    "capabilities": {
        "command": {
            "version" : 1,
            "available": true
    },
        "configuration": {
            "available": false
        },
        "resources": {
            "available": false
        }
    },
    "created": "2018-03-05T10:20:06.404Z",
    "updated": "2018-03-05T10:20:06.408Z"
}

Update an interface

Request

Endpoint:

PATCH /api/v1/deviceMgt/devices/<deviceId>/interfaces/<interfaceId>

The interfaceId must respect the following format {connector}:{nodeId}.

HTTP Headers:

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

Body:

JSON Params Description

deviceId

Optional. new device identifier

enabled

Optional. define if the interface is enabled or disabled

definition

Optional. new interface definition

Example:

PATCH /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/interfaces/sms:33601201201
{
    "deviceId": "urn:lo:nsid:sensor:temp002",
    "enabled": false,
    "definition": {
        "encoding": "myDecoder"
    }
}

Response

HTTP Code:

200 OK

Body:

Cf. Interface object model

Error case:

HTTP Code Error code message

404

DM_INTERFACE_NOT_FOUND

Interface not found

404

DM_DEVICE_NOT_FOUND

Device not found

Example:

{
    "connector": "sms",
    "nodeId": "33601201201",
    "deviceId": "urn:lo:nsid:sensor:temp002",
    "enabled": false,
    "status": "ONLINE",
    "definition": {
        "msisdn": "33601201201",
        "encoding": "myDecoder"
    },
    "activity": {
        "lastUplink": {
            "timestamp": "2018-03-05T10:43:46.268Z",
            "serverPhoneNumber": "20259"
        }
    },
    "capabilities": {
        "command": {
            "version" : 1,
            "available": true
        },
        "configuration": {
            "available": false
        },
        "resources": {
            "available": false
        }
    },
    "created": "2018-03-05T10:20:06.404Z",
    "updated": "2018-03-05T13:51:09.312Z"
}

Delete an interface

Request

Endpoint:

DELETE /api/v1/deviceMgt/devices/<deviceId>/interfaces/<interfaceId>

The interfaceId must respect the following format {connector}:{nodeId}.

HTTP Headers:

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

Example:

DELETE /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/interfaces/sms:33601201201

Response

HTTP Code:

204 NO CONTENT

Error case:

HTTP Code Error code message

403

GENERIC_OFFER_DISABLED_ERROR

The requested service is disabled in your offer settings. Please contact a sales representative.

404

DM_CONNECTOR_UNAVAILABLE

Connector not found or unavailable

404

DM_INTERFACE_NOT_FOUND

Interface not found

404

DM_DEVICE_NOT_FOUND

Device not found

Connectivity

LoRa® connector

Purpose

The LoRa® Connector in Live Objects implements the LoRa protocol over the LoRa connectivity interface.

It allows devices to communicate with the Live Objects platform and enables data ingestion, decoding, and optional features such as acknowledgments and location tracking.

The LoRa connectivity interface represents the network access channel, whereas the connector implements the protocol logic to integrate device data into Live Objects.

Definitions

devEUI

The global end-device ID of the interface (for more information, see the chapter 6.2.1 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf).

appEUI

The global application ID of the interface (for more information, see the chapter 6.1.2 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf).

appKey

The application key of the interface (for more information, see the chapter 6.2.2 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf).

activationType

OTAA: Over The Air Activation.

profile

profile of the Interface which represents the Class (A or C). Can be specific for an Interface (ex. LoRaMote devices) or generic (ex. LoRaWAN/DemonstratorClasseA or LoRaWAN/DemonstratorClasseC).

encoding

Optional. encoding type of the binary payload sent by the interface, the decoder must be registered first (Cf. "Decoding service" section).

connectivityOptions

connectivity options used for the interface. Supported options are ackUl and location.

connectivityPlan

connectivity plan to use for the interface.

Example:

{
    "devEUI": "0101010210101010",
    "profile": "Generic_classA_RX2SF9",
    "activationType": "OTAA",
    "appEUI": "9879876546543211",
    "appKey": "11223344556677889988776655443322",
    "connectivityOptions" : {
        "ackUl" : true,
        "location" : false
    },
    "connectivityPlan" : "orange-cs/CP_Basic"
}

Important Notice : Some features are only available if you have subscribed to the corresponding offer, so you may have the rights set on your tenant but no access to some features because these features are not activated on your tenant account (check the tenant offer).

If an option is applied to a device, it will be effective only if the option is allowed for the tenant. If both connectivityOptions and connectivityPlan are set, connectivityPlan will be selected. connectivityPlan should be used preferably at connectivityOptions but at least one of two shall be defined. connectivityPlan could be selected among list returned by the API LIST Connectivity plans .

Activity

JSON Params Description

lastActivationTs

Optional. last activation date of the interface

lastDeactivationTs

Optional. last deactivation date of the interface

lastSignalLevel

Optional. last signal level : this value is a signal level computed from last uplink. This value is the same as the one showed in the data message (Lora message signalLevel).

avgSignalLevel

Optional. average signal level : provides a level of the signal during the last uplinks transmitted by the device. The value is between 1 and 5 is computed from uplinks history (PER+SNR+ESP quality indicators aggregate). On frame counter reset, the uplinks history and average signal level are reset.

lastBatteryLevel

Optional. last battery level (for more information, see the chapter 5.5 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf).

lastDlFcnt

Optional. last downlink frame counter

lastUlFcnt

Optional. last uplink frame counter

Example:

{
    "activity": {
        "lastActivationTs": "2018-03-19T13:02:13.482Z",
        "lastActivationTs": "2018-03-20T14:10:26.231Z",
        "lastSignalLevel": 5,
        "avgSignalLevel": 4,
        "lastBatteryLevel": 54,
        "lastDlFcnt": 7,
        "lastUlFcnt": 1
    }
}

Status

LoRa® supports the following statuses: REGISTERED, INITIALIZING, INITIALIZED, ACTIVATED, DEACTIVATED, REACTIVATED, CONNECTIVITY_ERROR. The following diagram shows how LoRa® connector sets interfaces' status. The consistency check referred in the diagram is an automatic periodic check that verifies the consistency of information between Live Objets and the LoRa® network provider, it can detect potential problems on an LoRa® interface.

Enabled:falseEnabled:trueDEACTIVATEDREGISTEREDREACTIVATEDACTIVATEDINITIALIZINGCONNECTIVITY_ERRORINITIALIZEDDeactivationRegistrationReactivationInterfacereactivatedUplinkreceivedNew JoinrequestJoinRequestreceivedJoinJoinResponsecontainsan errorJoinAcceptsentInterfacedeactivated
Figure 3. Status state machine in LoRa® connector

Examples

Register a device with LoRa® interface

For more explanation on device creation, please see Register a device section.

Request:

POST /api/v1/deviceMgt/devices
{
    "id": "urn:lo:nsid:lora:0101010210101010",
    "tags": ["Lyon", "Test"],
    "name": "myLoraSensor",
    "description": "device with LoRa interface",
    "properties" : {
        "manufacturer": "Orange",
        "model": "LoraSensor"
    },
    "interfaces": [
        {
            "connector": "lora",
            "enabled": true,
            "definition": {
                "devEUI": "0101010210101010",
                "profile": "Generic_classA_RX2SF9",
                "activationType": "OTAA",
                "appEUI": "9879876546543211",
                "appKey": "11223344556677889988776655443322",
                "connectivityOptions" : {
                    "ackUl" : true,
                    "location" : false
                },
                "connectivityPlan" : "orange-cs/CP_Basic"
            }
        }
    ],
    "group": {
        "id": "sWyaL2",
        "path": "/france/lyon"
    }
}

Response:

200 OK
{
    "id": "urn:lo:nsid:lora:0101010210101010",
    "name": "myLoraSensor",
    "description": "device with LoRa interface",
    "tags": [
        "Test",
        "Lyon"
    ],
    "properties": {
        "manufacturer": "Orange",
        "model": "LoraSensor"
    },
    "group": {
        "id": "sWyaL2",
        "path": "/france/lyon"
    },
    "interfaces": [
        {
            "connector": "lora",
            "nodeId": "0101010210101010",
            "enabled": true,
            "status": "REGISTERED",
            "definition": {
                "devEUI": "0101010210101010",
                "profile": "Generic_classA_RX2SF9",
                "activationType": "OTAA",
                "appEUI": "9879876546543211",
                "appKey": "11223344556677889988776655443322",
                "connectivityOptions" : {
                    "ackUl" : true,
                    "location" : false
                },
                "connectivityPlan" : "orange-cs/CP_Basic"
            }
        }
    ],
    "defaultDataStreamId": "urn:lo:nsid:lora:0101010210101010",
    "created": "2018-03-06T13:23:37.712Z",
    "updated": "2018-03-06T13:23:37.945Z"
}

Add a LoRa® interface to a registered device

For more information on interface addition, please see Add a interface section.

Request:

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/interfaces
{
    "connector": "lora",
    "enabled": true,
    "definition": {
        "devEUI": "0202020220202020",
        "profile": "Generic_classA_RX2SF9",
        "activationType": "OTAA",
        "appEUI": "4573876546543211",
        "appKey": "11113344556677889988776655443322",
        "connectivityOptions" : {
            "ackUl" : true,
            "location" : false
        },
        "connectivityPlan" : "orange-cs/CP_Basic"
    }
}

Response:

201 CREATED
{
    "connector": "lora",
    "nodeId": "0202020220202020",
    "deviceId": "urn:lo:nsid:sensor:temp001",
    "enabled": true,
    "status": "REGISTERED",
    "definition": {
        "devEUI": "0202020220202020",
        "activationType": "OTAA",
        "profile": "Generic_classA_RX2SF9",
        "appEUI": "4573876546543211",
        "connectivityPlan" : "orange-cs/CP_Basic"
    },
    "activity": {},
    "created": "2018-03-06T13:37:31.397Z",
    "updated": "2018-03-06T13:37:31.397Z"
}

List LoRa® connectivity plans

A connectivity plan defines the interface capabilities and parameters that are needed by the network for access service. These information elements shall be provided by the manufacturer.

Request

Endpoint:

GET /api/v1/deviceMgt/connectors/lora/connectivities

HTTP Headers:

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

Response

HTTP Code:

200 OK

Body:

[ {
  "id" : "orange-cs/CP_Basic",
  "name" : "CP_Basic",
  "parameters" : {
    "nbTransMax" : 3,
    "location" : false,
    "ackUl" : false,
    "sfMax" : 12,
    "sfMin" : 7,
    "nbTransMin" : 1
  }
}, {
  "id" : "orange-cs/CP_ACK",
  "name" : "CP_ACK",
  "parameters" : {
    "nbTransMax" : 3,
    "location" : false,
    "ackUl" : true,
    "sfMax" : 12,
    "sfMin" : 7,
    "nbTransMin" : 1
  }
} ]
HTTP Code Error code message

403

4030

Service is disabled. Please contact your sales entry point.

Get LoRa® interfaces profiles

An interface-profile defines the interface capabilities and boot parameters that are needed by the network for access service. These information elements shall be provided by the manufacturer.

The profile of the interface which represents the Class (A or C). Can be specific for an Interface (ex. LoRaMote devices) or generic (ex. LoRaWAN/DemonstratorClasseA or LoRaWAN/DemonstratorClasseC).

Request

Endpoint:

GET /api/v1/deviceMgt/connectors/lora/profiles

HTTP Headers:

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

HTTP Code:

200 OK

Body:

[ "JRI", "DP_Generic_AS923_ClassA", "ERCOGENER_EG-IoT", "Sensing_Labs_T_IP68", "ESM 5k ELSYS Class A", "NETVOX_R711_AS923_ClassA", "Connit Pulse", "OCEAN_OBR-L", "ATIM Class A", "Adeunis RF Demonstrator_US_915", "DECENTLAB_DLR2-EU868", "DIGITAL_MATTER_EU868"]

Error case:

HTTP Code Error code message

403

4030

Service is disabled. Please contact your sales entry point.

MQTT connector

For information about MQTT interface and messages that your device can send or receive, please refer to the MQTT device mode.

Definition

clientId

device clientId used in mqtt MQTT device mode.

encoding

Optional. name of the decoder that will be used to decode data received from this interface. It will override 'metadata.encoding' value from this device’s data messages. The decoder must be registered first (Cf. "Decoding service" section).

 
{
    "clientId" : "mydevice_001",
    "encoding" : "myEncoding_v1"
}

Activity

JSON Params Description

apiKeyId

Optional. id of the API KEY used for the last device connection

mqttVersion

Optional. mqtt version used by the device mqtt client

mqttUsername

Optional. mqtt username used by the device mqtt client

mqttTimeout

Optional. mqtt timeout configured by the device mqtt client

remoteAddress

Optional. public IP address of the device mqtt client

lastSessionStartTime

Optional. last mqtt session start date

lastSessionEndTime

Optional. last mqtt session end date

security

security information

security has the following format:

JSON Params Description

secured

is (or was) a security protocol used

protocol

Optional. security protocol used

cipher

Optional. cipher suite used

clientCertAuthentication

Optional. is (or was) client certificate authentication used

sniHostname

Optional. hostname provided by the Server Name Indication extension

Example:

{
    "activity" : {
      "apiKeyId" : "5de8d14085a455f5c8525655",
      "mqttVersion" : 4,
      "mqttUsername" : "json+device",
      "mqttTimeout" : 60,
      "remoteAddress" : "217.167.1.65/61214",
      "lastSessionStartTime" : "2020-08-18T15:32:33.510Z",
      "lastSessionEndTime" : "2020-08-18T15:48:51.488Z",
      "security" : {
        "secured": true,
        "protocol": "TLSv1.2",
        "cipher": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
        "clientCertAuthentication": true,
        "sniHostname": "mqtt.liveobjects.orange-business.com"
      }
    }
}

Status

MQTT connector supports the ONLINE, OFFLINE, REGISTERED and DEACTIVATED statuses. The following diagram shows how the MQTT connector sets interfaces' status.

Enabled:falseEnabled:trueDEACTIVATEDREGISTEREDONLINEOFFLINEDeactivationRegistrationNode creationby APIAuto-registrationMQTT connectionopenedMQTT connectionclosedMQTT connectionopenedInterfacedeactivated
Figure 4. Status state machine in MQTT connector

Examples

Register a device with an MQTT interface

For more information on device creation, please see Register a device section.

Request:

POST /api/v1/deviceMgt/devices

{
    "id": "urn:lo:nsid:mqtt:mydevice_001",
    "tags": ["Lyon", "Test"],
    "name": "mySensor002",
    "description": "moisture sensor",
    "properties" : {
        "manufacturer": "Orange",
        "model": "MoistureSensorV3"
    },
    "interfaces": [
        {
            "connector": "mqtt",
            "enabled": true,
            "definition": {
                "clientId" : "mydevice_001"
            }
        }
    ],
    "group": {
        "id": "sWyaL2",
        "path": "/france/lyon"
    }
}

Response:

200 OK
{
    "id": "urn:lo:nsid:mqtt:mydevice_001",
    "name": "mySensor002",
    "description": "moisture sensor",
    "tags": [
        "Test",
        "Lyon"
    ],
    "properties": {
        "manufacturer": "Orange",
        "model": "MoistureSensorV3"
    },
    "group": {
        "id": "sWyaL2",
        "path": "/france/lyon"
    },
    "interfaces": [
        {
            "connector": "mqtt",
            "nodeId": "mydevice_001",
            "enabled": true,
            "status": "REGISTERED",
            "definition": {
                "clientId" : "mydevice_001"
            }
        }
    ],
    "defaultDataStreamId": "urn:lo:nsid:mqtt:mydevice_001",
    "created": "2018-03-06T11:30:42.777Z",
    "updated": "2018-03-06T11:30:42.819Z"
}

LwM2M/CoAP Connector

Based on the LWM2M protocol, this connector implements the LwM2M connectivity based on the CoAP messaging protocol.

LwM2M interface representation

In addition to the unified representation of Live Objects interfaces, the LwM2M interface has specific fields that can provide information specific to LwM2M devices. :

deviceid:Stringname:Stringdescription:StringdefaultDataStreamId:StringactivityState:Stringcreated:Dateupdated:Dateconfig:Stringresources:StringactivityState:StringtagsEnum[]propertieskey1:Stringkey2:String...interfaceconnector: "lwm2m"nodeId:Stringenabled:Boolstatus:StringlastContact:Datecreated:Dateupdated:DatedefinitionendpointName:Stringsecuritymode:StringpskInfoidentity:Stringsecret:Stringcapabilitiescommandavailable:Boolconfigurationavailable:Boolresourceavailable:Booltwinavailable:Boolversion:Stringactivitylwm2mVersion:StringremoteAddress:StringremotePort:IntlastRegistrationDate:DateregistrationLifetime:StringqueueMode:Boolbindings: [String,String,etc.]lastUpdateDate:DatestaticLocationalt:Floatlat:Floatlon:Floatgroupid:Stringpath:Stringinterface_1interface_2
Figure 5. device representation model.

Definition

This section contains all security credentials used by the LWM2M device.

"definition": {
    "endpointName": "My_Device_End_Point_Name",
    "security": {
        "mode": "PSK",
        "pskInfo": {
            "identity": "My_PSK_Identity"
        }
    },
    "bootstrap": {
        "managed": false
    }
}
Json Params Description

endpointName

Unique identifier of the LWM2M interface.

security.mode

The security mode. Example: "PSK" for Pre-Shared Key mode. The security mode "PSK" for DTLS Pre-Shared Key is currently the only supported security mode.

security.pskInfo.identity

The Pre-Shared key (PSK) identity.

security.pskInfo.secret

The Pre-Shared key (PSK) secret.

bootstrap.managed

Whether the LiveObjects Bootstrap server is allowed to automatically provision information in the interface definition (e.g. the security section) or not. If enabled, the 'security' section must not be set manually.

Activity

The activity item provides a data on the connectivity as the device is active (or inactive) on the network and its interact with Live Objects connector.

"activity": {
    "lwm2mVersion": "1.1",
    "remoteAddress": "190.92.12.113",
    "remotePort": 59436,
    "queueMode": false,
    "bindings": [
        "U"
    ],
    "lastRegistrationDate": "2022-02-16T09:08:26.995Z",
    "registrationLifetime": 300,
    "lastUpdateDate": "2022-02-16T09:17:17.301Z",
    "lastBootstrapProvisioningDate": "2022-02-16T09:08:23.621Z"
}
Json Params Description

lwm2mVersion

Supported LwM2M protocol version.

remoteAddress

Used in the IP connections, the IP adress of the device wich have been registered on the LwM2M Live Objects service.

remotePort

Used port.

lastRegistrationDate

Last registration date.

registrationLifetime

Max duration of registered status of the interface. The lifetime is set by LwM2M device connector, when expires, the device is automatically deregistered and the connector change the interface status to OFFLINE. The value is expressed in seconds and can be announced by the the device during the registering (by default : value = 300 seconds).

queueMode

Bolean to set the max of the lifetime timeout before the device go to the sleeping status. This parmeter is set to false, only the the devices with the queuing mode can have the queueMode setted to true.

bindings

List of the network/transport protocols binding supported by the device (Only UDP ="U") will be supported until now.

lastUpdateDate

Last update date of the LwM2M interface parameters.

lastBootstrapProvisioningDate

the last time the device definition was updated by the LiveObjects Bootstrap server (only if bootstrap.managed is true in the interface definition or if it is an auto-provisioned device).

Status

The LwM2M device interface can supports the following statuses :

Status Description

REGISTERED

The lwm2m interface is registered on LiveObjects, and LwM2M connector is waiting for connection from the device. The Capability TWIN is set to FALSE (device Twin is added at the time as the interface is created)

ONLINE

The lwm2m interface is connected to LwM2M connector and is in active listening. The TWIN capability is set to TRUE.

SLEEPING

The LwM2M interface is connected to LwM2M connector but is no longer in active listening (PSM = Power Saving Mode, used if QueueMode supported by the device).

OFFLINE

The LwM2M interface is disconnected and the LwM2M connector is waiting for the next connection request. The twin capability is set to FALSE.

DEACTIVATED

The LwM2M interface was deactivated by the user.
LwM2M interface STATUSInterface EnabledInterface DisabledREGISTEREDONLINE(re)initialize LwRegisterLifetime(re)initialize LwPresenceLifetimeSLEEPINGStill wRegisterLifetime>0but no more LwPresenceLifetimeOFFLINEDEACTIVATEDforce LwRegisterLifetime=0force LwPresenceLifetime=0user creationdeviceLW_REGISTERdeviceLW_DEREGISTERLwRegisterLifetimeout  device LW_UPDATEor LW_REGISTER  device LW_UPDATEor LW_REGISTERLwPresenceLifetimeoutdeviceLW_UPDATEor LW_REGISTERdeviceLW_DEREGISTERLwRegisterLifetimeoutuserdeactivationuseractivation(when no activity before)userdeactivationuserdeactivationuseractivation(when activity before)Legend**              Flow whenqueue modenot supported             Flow whenqueue modesupported (Additional flow to that one of the "unsupported queue mode")             Flwo when interfacedeactivated  
Figure 6. The diagram above shows how LwM2M connector sets interfaces' status.

Examples

Create a LwM2M device

In order to provision a CoAP identity to connect your device, you will have to use the dedicated REST API as described in a following section.

When you need to create a new device, you must use the same way to create every type of Live Objects devices. The LwM2M interface is specific, so you can provision it by following this way:

Request

Endpoint:

POST /api/v1/deviceMgt/devices

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json
{
    "id": "urn:lo:nsid:lwm2m:test12",
    "name": "Lwm2m device",
    "description": "device for test",
    "defaultDataStreamId": "urn:lo:nsid:lwm2m:test13Stream",

    "interfaces": [
        {
            "connector": "lwm2m",
            "enabled": true,
            "definition": {
                "endpointName": "urn:lo:lwm2m:my_endpoint123",
                "security": {
                    "mode": "PSK",
                    "pskInfo": {
                        "identity": "test_lwm2m_id2",
                        "secret" : "my_psk_secret"
                    }
                }
            }
        }
    ]

}
Refer to definition to learn more about the definition section fields. The credentials endpointName, identity and secret are mandatory.

Body:

JSON Params Description

id

device unique identifier (Cf. device object model)

tags

Optional. (Cf. device object model)

name

Optional. (Cf. device object model)

description

Optional. (Cf. device object model)

defaultDataStreamId

Optional. (Cf. device object model)

properties

Optional. (Cf. device object model)

group

Optional. (Cf. device object model)

interfaces

Optional. (Cf. device object model)

Devices can be registered with one or more chosen interfaces. It mean that the LwM2M device can have other connectivity (MQTT, SMS, Lora or External connector)

Response

{
    "id": "urn:lo:nsid:lwm2m:test12",
    "name": "Lwm2m device",
    "description": "device for test",
    "tags": [],
    "properties": {},
    "group": {
        "id": "root",
        "path": "/"
    },
    "interfaces": [
        {
            "connector": "lwm2m",
            "nodeId": "urn:lo:lwm2m:my_endpoint123",
            "enabled": true,
            "status": "REGISTERED",
            "definition": {
                "endpointName": "urn:lo:lwm2m:my_endpoint123",
                "security": {
                    "mode": "PSK",
                    "pskInfo": {
                        "identity": "test_lwm2m_id2"
                    }
                }
            },
            "capabilities": {
                "configuration": {
                    "available": false
                },
                "command": {
                    "available": false
                },
                "resource": {
                    "available": false
                },
                "twin": {
                    "available": false,
                    "version": 1
                }
            },
            "activity": {},
            "created": "2022-02-17T13:21:52.838Z",
            "updated": "2022-02-17T13:21:52.838Z"
        }
    ],
    "defaultDataStreamId": "urn:lo:nsid:lwm2m:test13Stream",
    "created": "2022-02-17T13:21:52.831Z",
    "updated": "2022-02-17T13:21:52.874Z",
    "activityState": "NOT_MONITORED"
}

The twin capability is automatically loaded by the service but not operational until the first device connection.

For the security raisons, the value of the PSK key is deliberately hidden.

From this moment and after the complete provisioning of the LwM2M interface with the twin capability, the device can perform a register operation.

Create a LwM2M device managed by the LiveObjects Bootstrap server

If your device is managed by the LiveObjects LwM2M Bootstrap server, the security info will be automatically provisioned by the Bootstrap server during the bootstrap process. To allow this, the device must be created with the bootstrap.managed parameter set to true.

Request

Endpoint:

POST /api/v1/deviceMgt/devices

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json
{
    "id": "urn:lo:nsid:lwm2m:test12",
    "name": "Lwm2m device managed by Bootstrap",
    "description": "device for test",
    "defaultDataStreamId": "urn:lo:nsid:lwm2m:test13Stream",
    "interfaces": [
        {
            "connector": "lwm2m",
            "enabled": true,
            "definition": {
                "endpointName": "urn:lo:lwm2m:my_endpoint123",
                "bootstrap": {
                    "managed": true
                }
            }
        }
    ]
}

Checking the LwM2M interface

Endpoint:

GET /api/v1/deviceMgt/devices/my_device_id/interfaces

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json
[
    {
        "connector": "lwm2m",
        "nodeId": "urn:lo:lwm2m:my_endpoint123",
        "enabled": true,
        "status": "REGISTERED",
        "definition": {
            "endpointName": "urn:lo:lwm2m:my_endpoint123",
            "security": {
                "mode": "PSK",
                "pskInfo": {
                    "identity": "test_lwm2m_id2"
                }
            }
        },
        "capabilities": {
            "configuration": {
                "available": false
            },
            "command": {
                "available": false
            },
            "resource": {
                "available": false
            },
            "twin": {
                "available": false,
                "version": 1
            }
        },
        "activity": {},
        "created": "2022-02-17T13:21:52.838Z",
        "updated": "2022-02-17T13:21:52.838Z"
    }
]

SMS connector

Definitions

msisdn

device msisdn. Number uniquely identifying a subscription in a Global System for Mobile communications.

serverPhoneNumber

Optional. server phone number. Must be defined in the offer settings.

encoding

Optional. name of the decoder that will be used to decode received SMSs, the decoder must be registered first (Cf. "Decoding service" section).

 
{
    "msisdn": "33601201201",
    "serverPhoneNumber": "20259",
    "encoding": "myDecoder"
}

Msisdn is an international phone number : 6..15 digits starting with country code (ex. '33') and without international prefix (ex. '00').

Dummy examples of phone numbers:

  • Belgium: 32654332211

  • France: 33654332211

  • Spain: 34654332211

  • Romania: 40654332211

  • Slovakia: 421654332211

Eligible cellular subscriptions for SMS connectivity

To send and receive SMS messages to/from a device using an SMS interface, this device must have a cellular subscription from the following operators :

  • Orange France

  • Orange Poland

  • Orange Romania

  • Orange Slovakia

  • Orange Spain

Activity

JSON Params Description

lastUplink

Optional. last uplink date of the interface

lastDownlink

Optional. last downlink date of the interface

lastUplink and lastDownlink have the following format:

JSON Params Description

timestamp

date of the activity

serverPhoneNumber

server phone number used

Example:

{
    "activity": {
      "lastUplink" : {
        "timestamp" : "2020-09-07T14:50:04.352Z",
        "serverPhoneNumber" : "+3320259"
      },
      "lastDownlink" : {
        "timestamp" : "2020-09-07T14:42:24.180Z",
        "serverPhoneNumber" : "20259"
      }
    }
}

Status

The SMS connector supports the following statuses describes in interface status. When an SMS interface is created, its status is set to ONLINE and it will not change. When an SMS interface is disabled, its status is set to DEACTIVATED.

Examples

Register a device with an SMS interface

For more information on device creation, please see Register a device section.

Request:

POST /api/v1/deviceMgt/devices
{
    "id": "urn:lo:nsid:sensor:temp002",
    "tags": ["Lyon", "Test"],
    "name": "mySensor002",
    "description": "moisture sensor",
    "properties" : {
        "manufacturer": "Orange",
        "model": "MoistureSensorV3"
    },
    "interfaces": [
        {
            "connector": "sms",
            "enabled": true,
            "definition": {
                "msisdn": "33600000001",
                "serverPhoneNumber" : "20259"
            }
        }
    ],
    "group": {
        "id": "sWyaL2",
        "path": "/france/lyon"
    }
}

Response:

200 OK
{
    "id": "urn:lo:nsid:sensor:temp002",
    "name": "mySensor002",
    "description": "moisture sensor",
    "tags": [
        "Test",
        "Lyon"
    ],
    "properties": {
        "manufacturer": "Orange",
        "model": "MoistureSensorV3"
    },
    "group": {
        "id": "sWyaL2",
        "path": "/france/lyon"
    },
    "interfaces": [
        {
            "connector": "sms",
            "nodeId": "33600000001",
            "enabled": true,
            "status": "ONLINE",
            "definition": {
                "msisdn": "33600000001",
                "serverPhoneNumber" : "20259"
            }
        }
    ],
    "defaultDataStreamId": "urn:lo:nsid:sensor:temp002",
    "created": "2018-03-06T11:30:42.777Z",
    "updated": "2018-03-06T11:30:42.819Z"
}

Add an SMS interface to a registered device

For more information on interface addition and example with SMS interface, please see Add a interface section.

Request:

POST /api/v1/deviceMgt/devices/urn:lo:nsid:sensor:temp001/interfaces
{
    "connector": "sms",
    "enabled": true,
    "definition": {
      "msisdn": "33600000001",
      "serverPhoneNumber" : "20259"
    }
}

Response:

201 CREATED
{
    "connector": "sms",
    "nodeId": "33600000001",
    "deviceId": "urn:lo:nsid:sensor:temp001",
    "enabled": true,
    "status": "ONLINE",
    "definition": {
      "msisdn": "33600000001",
      "serverPhoneNumber" : "20259"
    },
    "activity": {},
    "created": "2018-03-06T13:37:31.397Z",
    "updated": "2018-03-06T13:37:31.397Z"
}

External connector

External connector

When you will connect devices that can not use a native connectivity in Live Objects (MQTT, LoRa®, SMS, COAP/LWM2M), you can use this API with the MQTT protocol and the external connector interface to connect and manage your devices. The protocol adapters (MQTT ⇐⇒ proprietary protocol) must be developed and maintained by the client.

The external connector mode purpose is to :

  • publish data and devices status

  • manage devices commands : subscribe to command requests and publish command responses

Typically, use this mode when you want to connect your back-end service (where your devices are connected to) to Live Objects.

Interactive
Figure 7. "Connector" mode usage

Definition

nodeId

the external connector’s id of the device. This is the shared id with Live Objects that will be used in all communication regarding this device.

encoding

Optional. name of the decoder that will be used to decode data received from this interface. It will override 'metadata.encoding' value from this device’s data messages. The decoder must be registered first (Cf. "Decoding service" section).

 
{
    "nodeId" : "myDevice_101",
    "encoding" : "myEncoding_v1"
}

Register a device with external connector interface

Before registering a device with an external connector interface, you must register a device. For more explanation on device creation, please see Register a device section.

Request:

POST /api/v1/deviceMgt/devices

{
  "id": "urn:lo:nsid:external:measures",
  "name": "sensor #12",
  "description": "MyDeviceMaker sensor #12",
  "defaultDataStreamId": "urn:lo:nsid:external:measures",
  "tags": [
    "demo",
    "sensor"
  ],
  "properties": {
    "manufacturer": "MyDeviceMaker, Inc.",
    "hwVersion": "2.0.1.7-us_64"
  },
  "interfaces": [
    {
      "connector": "x-connector",
      "enabled": true,
      "definition" : {
        "nodeId" : "myDevice1234"
      }
    }
  ]
}

Response:

{
  "id": "urn:lo:nsid:external:measures",
  "name": "sensor #12",
  "description": "MyDeviceMaker sensor #12",
  "tags": [
    "sensor",
    "demo"
  ],
  "properties": {
    "manufacturer": "MyDeviceMaker, Inc.",
    "hwVersion": "2.0.1.7-us_64"
  },
  "group": {
    "id": "root",
    "path": "/"
  },
  "interfaces": [
    {
      "connector": "x-connector",
      "nodeId": "myDevice1234",
      "enabled": true,
      "status": "REGISTERED",
      "definition": {
        "nodeId": "myDevice1234"
      },
      "capabilities": {
        "configuration": {
          "available": false
        },
        "command": {
          "available": false
        },
        "resource": {
          "available": false
        }
      },
      "created": "2020-02-06T09:31:44.461Z"
    }
  ],
  "defaultDataStreamId": "urn:lo:nsid:external:measures",
  "created": "2020-02-06T09:31:44.389Z",
  "updated": "2020-02-06T09:31:44.479Z",
  "activityState": "NOT_MONITORED"
}
When you register your device with an external connector interface, you must set a nodeId field in the definition section. The nodeId must be a string between 1 and 128 characters long, containing no spaces or special characters except :, - or _ . The nodeId must be unique.

When connected through this mode, this is the x-connector interface of the device which is used.

Auto-register

By default, the auto-provisioned deviceId for nodeId will be:

urn:lo:nsid:x-connector:{nodeId}

Status

The device behind the external connector interface supports only the REGISTERED, ONLINE and OFFLINE statuses. To learn more about how the device publish it’s statuses, see NodeStatus publication.

To learn more about how your external connector work, see External connector mode section.

Node statusREGISTEREDONLINEOFFLINERegistrationAuto-registrationNode creationby APIMQTT publish in:connector/v1/nodes/{nodeId}/statusMQTT publish in:connector/v1/nodes/{nodeId}/status
Figure 8. External-connector node status
The REGISTERED status setted just after the registration step, once the new state is published, the REGISTERED status is no longer publishable in the connector/v1/nodes/{nodeId}/status topic.
Version 2026.7.0 • Updated date 2026-08-11 12:37:29 UTC