Add a device

Heads up!

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
ColumnDescription
devEUIPhysical ID of sensor
internalIDDeviceID used in diwise
latLatitude
lonLongitude
whereEnvironments
typestype of measurements
decodername of the decoder to use, supported sensor types
nameDisplay name to be used i dashboard
descriptionDescription to be used in dashboard
activetrue or false, only active sensors will pubslish output
tenantname of tenant
interval0

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

%%{init:{"theme":"neutral", "sequence":{"showSequenceNumbers":true}}}%% sequenceDiagram LoRa->>iot-agent: uplink message loop iot-agent->>iot-agent: POST to /api/v0/messages end iot-agent-->>iot-device-mgmt: device metadata lookup iot-device-mgmt-->>iot-agent: deviceID, sensor type iot-agent->>iot-core: measurements iot-core-->>iot-device-mgmt: device metadata lookup iot-device-mgmt-->>iot-core: environment, position, more iot-core->>iot-transform-fiware: PUBLISH output

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:

AttributeDescription
deviceIDThe internal ID that will be used by diwise
sensorTypethe type of sensor, see Supported sensor types. Used to select a decoder to decode the sensor payload
activeonly active sensors will send measurements.
typestype of measurement that the sensor will provide, see type of measurements
environmentadditional 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.