How to register data models

Data models describe the format in which sensor data is sent to the MBP. The MBP needs this information for each sensor or actuator to process the possibly heterogenous, complex sensor data for each attached IoT component in a proper way.

Data models are mandatory for the component types:

• Sensor
• Actuator

Therefore, before registering operators for those components (see How to register operators), it is necessary to have data model instances registered which describe the data format which is expected to be sent to the MBP.

Data models are not needed for the component types:

• Device

Devices are bound by extraction/control operator to the MBP which are expected to send only single floating point numbers. An example for a MQTT payload for these monitoring operators can be found here.

Steps for creating data models

1. Be clear about what data your sensor/actuator should send to the MBP.

Sensor data is sent to the MBP within a MQTT playload JSON object string. This JSON object must include a key (at the highest object level) named "value". The value of this key must be a JSON object. The structure of this JSON object can be chosen freely by the developer of the operator script which means that nearly arbitrary JSON objects can be sent to the MBP as sensor value. However, the chosen structure of a sensor message must be fix after it is was chosen for the first time. So be sure about the data format in which data should be sent to the MBP.

Here is an example for a complete MQTT playload for sending sensor data to the MBP. The object with the key value is the example sensor data which should be sent to the MBP:

{
  "component": "SENSOR",
  "id": "600db8c76dc71450f89a3927",
  "value": {
  "temp": 14.2,
  "location": {
    "latitude": 15.23,
    "longitude": -50.12},
  "acceleration": [
    0.25,
    20.21,
    41.0]
  }
}

2. Define the data model

A data model describes the JSON structure of the sensor data to be sent as a n-ary tree structure. For the above data example the data model is a n-ary tree looking like this (bold is the node type, beneath the respective key value):

An important characteristic of this data model definition is that arrays are defined as one parent array element with a certain size followed by exactly one child node representing the data type of the arrays elements. This restrictions leads to the circumstance that no sensor JSON object data can be defined which uses mixed typed elements for their arrays.

This data model can be then registered to the MBP in the corresponding data model menu in the MBP frontend (see the image below).

After clicking on the + a modal appears with a graphical data model creation tool. With the help of this tool it is possible to create data model trees like the one showed in the example before.

The data model creation tool works with the following operators:

• 🖊 Edit: Edits properties of a node like name, data type, unit and array size.
• ➕Add: Adds a child node to the current node. Only available for the types array and object.
• 🗑 Delete: Deletes the children nodes of one node.

Available data types for data model nodes:

Complex types

• Object (models a JSON object)
• Array (models a JSON array)

Primitive types

• Integer (32 bits)
• Long (64 bits)
• Double (64 bits)
• Decimal128 (128 bits)
• String
• Date (JSON representation: either a number in POSIX time or a string conform to common date string patterns)
• Binary (JSON representation: String using the Base64 encoding)

3. Recheck the data model

Once the data model was successfully created recheck your defined data model by using the MQTT message example functioality of the data model menu. The popup shows an example how sensor data can look like that can be sent to the MBP using the respective data model.

Add data models from an existing .json definition file

For Ready-to-use operators a predefined data model definition is provided in the respective resource folder in the form of a .json file. The following screenshot shows this file for an examplary ready-to-use extraction operator in the MBP's resource directory:

The content of this file is a JSON object defining a data model tree which can be used to register it to the MBP by using the REST API. However for the graphical data model tree creation tool only the JSON Array with the key treeNodes is relevant and can be copied into the input box which appears after clicking on the Show JSON definition button.

After pasting the node array to the input box you just have to give the data model a name and then click on Create to create the data model.

Default data model for monitoring operators

Monitoring scripts executed by Monitoring Operators are meant to send only single floating point numbers instead of an arbitrary JSON object like shown in the following example MQTT payload example:

{
  "component": "DEVICE",
  "id": "600db8c76dc71450f89a3927",
  "value": 12.3
}