i4connected Knowledgebase 5.6

The MQTT Adapter

Abstract

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.

MQTT_settings.jpg

The MQTT Settings in Add Device panel

The MQTT Adapter configuration is split in 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.

    Select_MQTT_Adapter_list.jpg

    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:

    Add_MQTT_Adapter_panel.jpg

    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.

    • Host 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 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 Raw option is enabled, the data will be parsed as RawJSON format. Having this option enabled, the Json option will be disabled.

    • Json - If Json option is enabled, the data will be parsed as JSON format. Having this option enabled, the Raw option will be disabled.

    • Select owner - name of the Adapter owner.

      IoT_owner.jpg

      Adapter owner selector

      By clicking on the owner selector, the Select Users panel is opened allowing the user to chose the Adapter's owner.

      List_of_users.jpg

      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 signals 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 topics combinations is used to filter the received data. If no topic is defined, the data from all signals will be received.

    Topic.jpg

    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 signals topics. 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.

Select_filter.jpg

The "Select filter" option

By clicking on the Select filter field, the Test Expression panel is opened.

Test_expression.jpg

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 it's 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 WEBfactory 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.