Skip to main content

i4connected Knowledge Base

The Azure IoT Adapter

Abstract

Azure IoT Adapter is a ready adapter capable of importing and writing data measurements from the Microsoft Azure IoT Hub.

This article describes the configuration concept for the i4connected Azure IoT Adapter.

The i4connected Azure IoT Adapter is an IoT (Internet of Things) ready adapter capable of importing and writing data (measurements) from the Microsoft Azure IoT Hub. Because it uses the Service Bus Protocol, it is able to communicate with any other services that use the Service Bus Protocol, for example, Microsoft Azure Event Hub.

The IoT Adapter configuration is split into two important steps:

IoT Adapter Hub connection

The IoT Hub is configured as follows:

Note

Only users with the Manage adapters permission enabled can add and edit Adapters.

Add_IoT_Hub_Adapter.jpg

The Add IoT Hub panel

  • Name - the name of the i4connected IoT Hub

  • Description - the user-friendly description of the IoT Hub Adapter.

  • Connection String - the IoT Adapter connects to the Azure IoT Hub (or Events Hub) using a Service Bus connection string. In this field, the IoT Endpoint connection string is expected. This can be extracted from Microsoft Azure, from the Built-in endpoints menu entry.

    IoT_Hub_Endpoint.jpg

    Azure IoT Hub - Built-in Endpoints

    Example connection string (Endpoint):

    Endpoint=[Endpoint];SharedAccessKeyName=[Access policy name];SharedAccessKey=[Access Key];EntityPath=[Path]

  • IoT Hub ConnectionString - this is the IoT hub connection string. It is needed to call the direct method from the IoT Device. It can be found in the Microsoft Azure portal, under Shared access policies, by clicking on the iothubowner field. The Primary Key here can be copied to clipboard, using the dedicated Microsoft Azure Copy option.

    SharedAccessPolicies.jpg

  • TransportType - the type of protocol to call the method from IoT device. The user can select from:

    • Amqp - (Advanced Message Queuing Protocol) is an open standard internet protocol for passing business messages between applications or organizations. This messaging protocol allows multiple modes of operation.

    • Amqp_Websocket_Only - with AMQP over WebSockets, a bridge is set up, exposing the MQTT protocol over HTML5 WebSockets.

  • Method Name - the name of the method which should be called.

  • Method Payload - the JSON payload method.

  • Method Response Timeout in Seconds - the timeout, expressed in seconds, for waiting for a response from the method (min: 0 / max: 300, default: 120)

  • Method Connection Timeout in Seconds - the timeout, expressed in seconds, for waiting for the IoT device connection (min: 0, default: 0, cannot be more than the Method Response Timeout in Seconds.

  • Select owner - the name of the Adapter owner.

    select_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.

    select_users_panel.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 of the user.

  • Trace level - trace levels determine which events the trace provider generates:

    • Off

    • Trace

    • Debug

    • Warn

    • Error

    • Fatal

IoT Adapter data parsing

The IoT Adapter receives all the events from the Hub to which it is connected. The data is then parsed and filtered, thus only the required data is covered 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 filters run in two steps in the IoT Adapter:

  • Device filters

  • Signal filtering

Both filters are configured using the JSONPath expressions, an XML Path Language syntax for JSON objects.

Tip

The JSONPath Online Evaluator can be used for creating and testing JSONPath expressions.

Device filters

The Device filters are 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-in 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.

Example 1:

  • Filter that accepts any measurement for the device:

    filter: @

  • Filter that accepts any payload that contains a property called value:

    filter: @.value
Signal filters

The Signal filters are JSON objects with Filter, Value, and Timestamp properties, which check for the existence of the particular object of the 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.

    Example:

    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 its value with the signal. The accepted data types of the values can be found here: MSDN- TypeCode Enumeration.

    Examples:

    1. Filter that extracts the value from a property called Consumption:

      value: Consumption

      JSON payload for the filter example:

      {
    "Consumption": 123
}

    2. 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":

      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
        }
    ]
}

    3. 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:

    1. 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
        }
    ]
}

    2. 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"
}

    3. 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
        }
    ]
}

Important

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.

In this section: