Add a device
The device/sensor that should be added need to be of a known type, that is, a decoder for the type of sensor must already exist and the device/sensor should be provisioned within the LoRa application server.
How to add a new sensor
Add device metadata
Device metadata is stored in iot-device-mgmt. When iot-device-mgmt starts up it load data from csv-files and adds information to its database.
The file 30.devices.csv contains data about sensors.
devEUI;internalID;lat;lon;where;types;decoder;name;description;active;tenant;interval
a1b2bc3d4e5f6;intern-a1b2bc3d4e5f6;0;0;air;urn:oma:lwm2m:ext:3303;tem_lab_14ns;;;true;default;0
Column | Description |
---|---|
devEUI | Physical ID of sensor |
internalID | DeviceID used in diwise |
lat | Latitude |
lon | Longitude |
where | Environments |
types | type of measurements |
decoder | name of the decoder to use, supported sensor types |
name | Display name to be used i dashboard |
description | Description to be used in dashboard |
active | true or false, only active sensors will pubslish output |
tenant | name of tenant |
interval | 0 |
Compose override
Ensure that your Development environment is set up accordantly.
Then create an docker compose override file with your custom settings and modified 30.devices.csv with your added sensor.
version: '3'
services:
iot-agent:
environment:
MQTT_DISABLED: 'false'
MQTT_HOST: 'your.mqtt.host'
MQTT_PORT: '1883'
MQTT_USER: '<mqtt-user>'
MQTT_PASSWORD: '<mqtt-password>'
MQTT_TOPIC_0: '<mqtt-topic>'
iot-device-mgmt:
image: 'diwise/iot-device-mgmt:latest'
volumes:
- ./path/to/custom/data:/opt/diwise/config/data
Compose up the environment with the following command
docker compose -f deployments/docker/docker-compose.yaml -f /path/to/docker-compose.override.yaml up
If everything is set up correct diwise should start and begin to listen to incoming payloads.
Background
Uplink message
This is a example payload that comes from a tem_lab_14ns sensor.
{
"devEui": "a1b2bc3d4e5f6",
"sensorType": "tem_lab_14ns",
"payload": "01FE90619c10006A"
}
From this payload iot-agent will use devEUI to lookup metadata about the sensor (3). SensorType that is in the payload is not used for anything within diwise.
Device metadata (iot-device-mgmt)
The response (4) from iot-device-mgmt contains information about the device.
{
"devEUI": "a1b2bc3d4e5f6",
"deviceID": "intern-a1b2bc3d4e5f6",
"name": "name",
"description": "description",
"location": {
"latitude": 0,
"longitude": 0,
"altitude": 0
},
"environment": "air",
"types": [
"urn:oma:lwm2m:ext:3303"
],
"sensorType": {
"id": 1,
"name": "tem_lab_14ns",
"description": "",
"interval": 3600
},
"lastObserved": "2023-02-01T13:37:00Z",
"active": true,
"tenant": "default",
"status": {
"batteryLevel": 0,
"statusCode": 0,
"timestamp": ""
},
"interval": 60
}
For now we’re interested the following attributes:
Attribute | Description |
---|---|
deviceID | The internal ID that will be used by diwise |
sensorType | the type of sensor, see Supported sensor types. Used to select a decoder to decode the sensor payload |
active | only active sensors will send measurements. |
types | type of measurement that the sensor will provide, see type of measurements |
environment | additional information about the sensor, see environments |
Output
The decoded payload is converted to one or many measurements by iot-agent (3-5), enriched in iot-core (6, 7) and finally serialized as SenML and published (8) on a rabbitMQ topic.
In the output we find sensorID = deviceID. The pack is divided into several records, the first record contains the type of measurement, bn
, and a timestamp in unix time, bt
.
{
"sensorID": "intern-a1b2bc3d4e5f6",
"pack": [
{
"bn": "urn:oma:lwm2m:ext:3303",
"bt": 1675258662,
"n": "0",
"vs": "intern-a1b2bc3d4e5f6"
},
{
"n": "5700",
"v": -5.8
},
{
"u": "lat",
"v": 0
},
{
"u": "lon",
"v": 0
},
{
"n": "env",
"vs": "air"
},
{
"n": "tenant",
"vs": "default"
}
],
"timestamp": "2023-02-01T13:37:00.000000000Z"
}
The second record contains the measurement value, in this case it’s a SensorValue. The type urn:oma:lwm2m:ext:3303 is a temperature measurement.
{
"n": "5700",
"v": -5.8
}
This record shows that a sensor value ("n": "5700"
) of type float has the value -5.8. See the SenML specification for more information.