The MQTT Adapter
This article describes the configuration concept for the i4connected MQTT Adapter, capable of reading and writing data using the machin-to-machine protocol.
This article describes the configuration concept for the i4connected MQTT Adapter.
The i4connected MQTT Adapter is an IoT-ready adapter, capable of reading and writing data (measurements) using the machine-to-machine (M2M) connectivity protocol.
The MQTT specific settings of a device can be configured using the Add Device panel in the Administrative section of the i4connected portal.
The MQTT Settings in Add Device panel
The MQTT Adapter configuration is split into two important steps:
MQTT Broker Settings
When adding a new MQTT device, the following specific properties must be set:
Note
Only users with the Manage adapters permission enabled can add and edit Adapters.
MQTT name - Specifies the name of the MQTT Broker (Server) to which the device will be connected. Clicking this option will open the Select the MQTT Server panel, allowing the user to select an existing Broker or to add a new one.
The "Select the MQTT Server" panel
Clicking the Add button will open the Add MQTT Broker panel allowing the user to configure a new broker using the following properties:
The "Add MQTT Server" panel
Name - The name of the new MQTT broker, which will be displayed in the MQTT Device properties, as well.
Description - the user-friendly description of the MQTT Adapter.
Connection string - The IP or DNS name of the new MQTT broker.
Port - The port number used by the new MQTT broker.
MQTT SSL Protocol - The SSL protocol used for communication. The options are:
none (default value)
SSLv3
TLSv1.0
TLSv1.1
TLSv1.2
ClientId - The Client Identifier (ClientId) identifies the Client to the Server. Each Client connecting to the Server has a unique ClientId. The ClientId must be used by Clients and by Servers to identify the state that they hold relating to this MQTT Session between the Client and the Server.
User - The user name that is able to authenticate on the MQTT Broker.
Password - The password used to access the MQTT Broker.
Raw - If the Raw option is enabled, the data will be taken as a direct value and the timestamp will be set to the time when the system received the data. Having this option enabled, the Json option will be disabled.
Json - If the Json option is enabled, the data will be parsed in JSON format. Having this option enabled, the Raw option will be disabled. When this option is enabled, the device will be populated with an additional field, allowing the user to define a JSON payload (e.g. {"_SignalName_":"_SignalValue_"} ).
Select owner - the name of the Adapter owner.
Adapter owner selector
By clicking on the owner selector, the Select Users panel is opened allowing the user to choose the Adapter's owner.
Select Users panel
Important
When adding a new Adapter the creator user is by default set as Adapter's owner. However, the owner can be changed after the Adapter was saved, by all users having at least the Manage adapters permission enabled.
Time zone - The time zone used by the new MQTT broker.
Trace level - The level of logging used for the new MQTT broker. Trace levels determine which events the trace provider generates. The Trace level value can be Trace, Debug, Info, Warn, Error, Fatal, or Off.
Topic - the device topic. This topic is a string that acts like a filter when used in combination with the signal's topics.
The topic set here will be inherited by all the signals defined for this device and appended to them, like this: [device topic]/[signal topic]. The device and signal topic combinations are used to filter the received data.
The MQTT Settings - "Topic"
Tip
For more details about the MQTT Signal settings please also visit the dedicated article here.
MQTT Adapter Data Parsing
The MQTT Adapter receives all the data from the MQTT broker to which it is connected based on the device and signal's topic. The data is then parsed and filtered, thus only the required data is converted to measurements and placed in the right signals and devices. This is why the next step of the adapter configuration is setting up the filters which parse the received data.
The Filter option is available in the MQTT settings area, under the Add Device panel, immediately under the MQTT Topic.
The "Select filter" option
By clicking on the Select filter field, the Test Expression panel is opened.
The "Test Expression" panel
The Test Expressions panel features the following settings:
JSONPath Syntax - The JSONPath Syntax is configured using JSONPath expressions, an XML Path Language syntax for JSON objects.
JSON - The actual JSON Syntax
Tip
For a more complex JSON Path please visit the additional online helper, under JSONPath Online Evaluator for creating and testing JSONPath expressions.
Device filters - JSON objects with a Filter property, which check for the existence of a particular object or property specified in the filter expression. By default, the filter is empty (null), so the Device Name is used to check if it matches with the Device ID standard built-it event property.
When a filter expression is specified, the expression is run against the JSON payload of the event. If a match is found in the JSON payload, the event is associated with the device.
Examples:
Filter that accepts any measurement for the device:
filter: @
Filter that accepts any payload that contains a property called value:
filter: @.value
Signal filters - JSON objects with Filter, Value and Timestamp properties, which check for the existence of a particular object of property specified in the filter expression. Each of the three properties of a Signal filter will handle the data in different methods:
the Filter property works similar to a Device filter, it runs the Filter expression against the JSON payload and if a match is found, the corresponding event is associated with the signal. The Filter property is by default empty (null) and the Value property is used instead.
Examples:
Filter that accepts any payload that contains a property "tag" with the value "tag1" and a property "signal" with the value "signalA":
filter: @.tag == 'tag1' && @.signal == 'signalA'
the Value property extracts the value that matches the expression and associates it with the measurement. By default, the Value property is empty (null) and the adapter searches the JSON payload for the property which has the same name as the signal name. If found, it associates the value of that property with the signal. If the Value property is used, it will search for the specified property and associate it's value with the signal. The accepted data types of the values can be found here: MSDN - TypeCode Enumeration.
Examples:
Filter that extracts the value from a property called Consumption:
value: Consumption
Filter that extracts an array of values from a property "v", on a "measurements" collection where the elements have a property "id" that matches "Consumption":
{ "Consumption": 123 }
JSON payload for the filter example:
value: measurements[?(@.id == 'Consumption')].v
JSON payload for the filter example:
{
"measurements": [
{
"id": "Consumption",
"t": "2016-01-01",
"v": 123
},
{
"id": "Consumption",
"t": "2016-01-02",
"v": 155
}
]
}Filter that extracts the value from a "Value" property on a "TagData" element collection that matches the Tag "Tag1":
value: TagData[?(@.Tag == 'Tag1')].Value
JSON payload for the filter example:
{
"TagData": [
{
"Tag": "Tag1",
"Value": 123
}
]
}the Timestamp property extracts the timestamp that matches the expression and associates it with the measurement. By default, the Timestamp property is empty (null) and the adapter searches the JSON payload for the property which has the same Timestamp. If found, it associates the value of that property with the measurement. If the Timestamp property is used, it will search for the specified property and associate its value with the measurement timestamp. The allowed timestamp formats are ISO Datetime and UNIX Datetime formats.
Examples:
Filter that extracts an array of timestamps from a property "t", on a "measurements" collection where the elements have a property "id" that matches "Consumption":
timestamp: measurements[?(@.id == 'Consumption')].t
JSON payload for the filter example:
{
"measurements": [
{
"id": "Consumption",
"t": "2016-01-01",
"v": 123
},
{
"id": "Consumption",
"t": "2016-01-02",
"v": 155
}
]
}Filter that extracts the timestamp value from a property called time:
timestamp: time
JSON payload for the filter example:
{
"time": "2016-01-01T00:00:00Z"
}Filter that extracts the timestamp from a "Time" property on a "TagData" element collection that matches the Tag "Tag1":
"value": "TagData[?(@.Tag == 'Tag1')].Time"
JSON payload for the filter example:
{
"TagData": [
{
"Tag": "Tag1",
"Value": 123,
"Time": 1471995721
}
]
}Note
If the value and timestamp expressions result in an array property, a timestamp and value pair will be processed for each element of that array.
JSON Payload Recommended Format
In order for the configuration to be as simple as possible, the format of the JSON payload, as recommended by Microsoft and Ewon by HMS Networks is:
{
"DeviceId": "Power Meter 1",
"Power Consumption": 52,
"Peak Consumption": 64,
"Current": 218,
"Timestamp": "2016-08-23T09:22:18Z"
}With such a JSON payload, all the properties will be matched automatically by Device Name and Signal Name without the need of specifying any custom filters.