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:
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.
| 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:
-
LoRa®, see the following section LoRa® connector.
-
SMS, see the following section SMS connector.
-
MQTT, see the following section MQTT connector.
-
External connector, see the following section MQTT External connector.
-
LwM2M connector, see the following section LwM2M connector.
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 |
|||||
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 |
|||||
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.
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>>
}
}