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:
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 |
HTTP Headers:
X-API-Key: <your API key> Accept: application/json X-Total-Count: <boolean>
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:
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"
}
]
}