On this page

IoT Hub Feature

This guide provides step-by-step instructions for connecting the Abeeway Micro Tracker and Abeeway Industrial Tracker to IoT Hub . The connection is through the IoT network in the new global standard LoRaWAN and ThingPark Wireless OSS intelligent logger (Actility). In this guide, we will use the free IoT Hub demo server iothub.magenta.at in this guide. This guide will be useful to anyone who wants to connect their trackers manufactured by Abeeway or another industrial IoT application to the LoRaWAN network.

• Prerequisites
• Integration overview
• Step 1. Checking the registration for the platform ThingPark Wireless company Actility
• Step 2. Creation UpLink and DownLink DATA Converters
• Step 3. Uplink Data Converter configuration
• Step 4. Downlink Data Converter configuration
• Step 5. Integration configuration
• Step 6. Verifying devices connectivity after the creation and configuration of the Integration.
• Step 7. Creation and configuration of the Dashboard
• Step 8: Post telemetry and verify the Integration configuration
• Step 9: Configuration the Root Rule Chain (Root)
• Step 10: Create and Sent Downlink messages
• Next steps

Prerequisites

We assume:

• You are registered on the Actility website.
• You have at least one Abeeway Micro Tracker or Abeeway Industrial Tracker that is already connected with ACTILITY THINGPARK IoT NETWORK and is active.
• We also assume you already have a IoT Hub server or free demo account. Otherwise, you can register for a 30-days free demo account here: iothub.magenta.at. We expect you to have at least a basic knowledge about IoT Hub, so we do recommend to complete the Getting Started guide.

Integration overview

IoT Hub Platform Integrations feature allows to push data from various platforms and connectivity solutions to IoT Hub. We will use platform ThingPark Wireless company Actility to consume data from LoRaWAN networks and automatically register devices in IoT Hub. Besides configuring the integration, we will also set IoT Hub up to decode incoming data, store it in the database, visualize on the dashboard and generate alarms based on configurable thresholds.

Step 1. Checking the registration for the platform ThingPark Wireless company Actility

• Registration and condition of devices

Few things to notice:

The DevEUI from the incoming message will become the Device Name in IoT Hub;

IoT Hub will automatically create device with type “tracker” and name equal to DevEUI;

Therefore, when creating a new device, in the Name field, enter the value DevEUI: from the Device Information (ThingPark Wireless OSS intelligent logger (Actility)) section

Step 2. Creation UpLink and DownLink DATA Converters

In order to create an Integration, we should create the Uplink Data Converter and the Downlink Data Converter first. The converters will decode incoming telemetry payload data from global standard LoRaWAN that contains in encoded hex string to human readable, simplified IoT Hub data format.

Screenshot of how to create Uplink converter (click to open expanded view)

Screenshot of how to create Downlink converter (click to open expanded view)

Step 3. Uplink Data Converter configuration

When creating an Uplink Converter, a default decoder is added to the Decoder section.

After creating the Uplink Converter to the Decoder section, you need to update the Decoder code to the following code.

It is necessary to edit the Uplink decoder

Alternatively, you can import it from this file

the following way: Go to Data Converters -> Add new Data Converter -> Import Converter (click to open expanded view)

Step 4. Downlink Data Converter configuration

When creating an Downlink Converter, a default decoder is added to the Decoder section.
After creating the Downlink Converter to the Decoder section, you need to update the Decoder code to the following code.

It is necessary to edit the Downlink decoder

Open Downlink Converter, editor mode, click “test decoder function” and replace the default code with a new code:

Screenshot edit the DownLink decoder (click to open expanded view)

JSON: output data after DownLink Data Converter looks like this:
(click to open expanded view)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
             {
                 {
                    /** Encoder **/                    
                    var data = {};                    
                    // Process data from incoming message and metadata                    
                    data.payload = msg.sentPayloadHex;
                    data.DevEUI = metadata['DevEUI'];
                    data.deviceType = metadata['deviceType'];
                    data.ContentType = "application/json";
                    data.Accept = "application/json";
                    data.urlPrefix = "/core/latest/api/devices/";
                    data.urlSufix = "/downlinkMessages";
                    data.urlSufixToken = "/admin/latest/api/oauth/token";
                    data.firstParamToken = "client_credentials";
                    data.urlSufixGetDevices = "/core/latest/api/devices";
                    // Result object with encoded downlink payload
                    var result = {
                        // downlink data content type: JSON, TEXT or BINARY (base64 format)
                        contentType: "JSON",
                        // downlink data
                        data: JSON.stringify(data),
                        msg: msg,
                        metadata:  metadata
                    };
                    return result;
                 }
             }
             

Alternatively, you can import it from this file

the following way: Go to Data Converters -> Add new Data Converter -> Import Converter (click to open expanded view)

Step 5. Integration configuration

Screenshot of creating integration on the IoT Hub platform
(click to open expanded view)

WARNING !!! After creation of the Integration…

• check of the base URL,
• check downLink URL in order to:
1. copy downLink URL - the HTTP Endpoint URL from the integration window (Example: https://thingparkenterprise.eu.actility.com/thingpark/dx/core/latest/api/devices)
2. paste this downLink URL to the URL of the Application server Actility where the device data is sent to and received from.

Screenshot of page ThingPark Wireless OSS intelligent logger (Actility), where you need to copy the downLink URL
(click to open expanded view)

Step 6. Verifying devices connectivity after the creation and configuration of the Integration.

After creating and configuring the integration and connecting it to platform ThingPark Wireless company Actility, IoT Hub will begin receiving the first reports of the telemetry from your devices.

Screenshot of receiving the first reports of the telemetry (click to open expanded view)

On the basis of these first messages IoT Hub system will automatically create devices with type and name under which devices were registered in the ThingPark Actility Enterprise.

Screenshot of how IoT Hub system will automatically create devices (click to open expanded view)

That’s why after creating and configuring the integration and before starting the Dashboard setup you need to check that all your devices are detected and visible in IoT Hub.

Step 7. Creation and configuration of the Dashboard

Screenshot of the Dashboard after finishing its creation (click to open expanded view)

Example: Dashboard in json format

- Creation of the Dashboard

Screenshot of the creation of the Dashboard (click to open expanded view)

1. Open Dashboard and add to:
   alias (List abeeways): filter_type: Entity_list, type: Device, device_names: DevEUI_1_, DevEUI_2_, DevEUI_3_...
Screenshot: open Dashboard and add to: alias (List abeeways): filter_type: Entity_list, type: Device, device_names: DevEUI_1_, DevEUI_2_, DevEUI_3_...
(click to open expanded view)

2. Open Dashboard and add to: alias (DigEntityFrom): type: Entity from dashboard state, type: Device
Screenshot: open Dashboard and add to: alias (DigEntityFrom): type: Entity from dashboard state, type: Device
(click to open expanded view)

- Add to the Dashboard new widgets:

1. widget number 1:
• Current_bundle: Cards -> latest_values -> Entities:
• Datasources: type: Entity, parameters: List abeeways
Screenshot of creation of the widget number 1 (click to open expanded view)

• Action: action sources: on row click, Name: ${entityName}, type: Update_current_dashboard_state, Set_entity_from_widget
Screenshot of widget settings - action sources: on row click to widget number 1 (click to open expanded view)

2. widget number 2:
• Current_bundle: Charts -> time_series: Timeseries_Float:
Screenshot of creation of the widget number 2 (click to open expanded view)

• Data_Source: type: Entity, parameters: List_abeeways, key:temperature, label: ${entityLabel}
Screenshot of adding datasource to widget number 2 (part 1) (click to open expanded view)

Screenshot of adding datasource to widget number 2 (part 2) (click to open expanded view)

3. widget number 3:
• Current_bundle: Digital_guages
Screenshot of creation of the widget number 3 (click to open expanded view)

• Data_Source: type: Entity, parameters: DigEntityFrom, key:temperature, label: temperature
Screenshot of adding datasource to widget number 3 click to open expanded view)

4. widget number 4:
• Current_bundle: Cards ->Timeseries
Screenshot of creation widget number 4 (click to open expanded view)

• Data_Source: type: Entity, parameters: DigEntityFrom
• keys:temperature, label: temperature
• keys:batteryVoltage, label: batteryVoltage ...
Screenshot of adding datasource to widget number 4 (click to open expanded view)

5. widget number 5:
• Current_bundle: Input widgets ->Update Multiple Attributes
Screenshot of creation of the widget number 5 (click to open expanded view)

• Data_Source: type: Entity, parameters: DigEntityFrom
• keys:sentPayloadHex, label: ${entityLabel}
Screenshot of adding datasource to the widget number 5 (click to open expanded view)

-Note:

• Widgets Number 1 and Number 2 with alias Entity_list.Device.
• Widgets Number 3 and Number 4 with alias DigEntityFrom.

Step 8: Post telemetry and verify the Integration configuration

Screenshot of Integration settings change log see here (click to open expanded view)

Screenshot of a log of incoming messages from from ThingPark Wireless OSS intelligent logger (Actility) Platform:
(click to open expanded view)

If your devices are active and you do everything correctly when you connect the ThingPark Wireless OSS intelligent
logger (Actility) Platform, then you will see incoming messages on the dashboard you created.

Screenshot of incoming messages to the dashboard you created (click to open expanded view)

Step 9: Configuration the Root Rule Chain (Root)

After adding widget number 5, it must be associated with the downlink decoder.
To do this, go to the “Rule Chain” tab and open the “Root Rule Chain”.

Screenshot of configuration of the Root Rule Chain for the message to be sent to device (click to open expanded view)

Editing the “Root Rule Chain”:

• To get the original name of the device via metadata After "Message Type Switch" add Enrichment node: "originator fields" with the name "Fetch Name and Type":
• name: deviceName
• type: deviceType
• The relationship between "Message Type Switch" and "Fetch Name and Type":
• "Rule node link details": "Attributes Update"
Screenshot of the created Enrichment node: "originator fields" (click to open expanded view)

• To receive downlink data by a decoder and transmit decoded data to "Action - rpc call request":
• between "Fetch Name and Type" and "Action - rpc call request"
• add: Action: "integration downlink": name: Actility_DownLink, integration: Test_ThigPark
Screenshot of the created Action: "integration downlink" (click to open expanded view)

• The relationship between "Fetch Name and Type" and "Actility_DownLink":
• "Rule node link details": "Success"
• The relationship between "Actility_DownLink" and "Action - rpc call request":
• "Rule node link details": "Success"

Step 10: Create and Sent Downlink messages

Before sending a message:

• you must create a heading in which the type of request is determined (information about the configuration, or about the status of the device, or about the new configuration)
  and also the content of the data itself (a detailed description of the data).

Next steps

• Getting started guides - These guides provide quick overview of main IoT Hub features. Designed to be completed in 15-30 minutes.

• Connect your device - Learn how to connect devices based on your connectivity technology or solution.

• Data visualization - These guides contain instructions how to configure complex IoT Hub dashboards.

• Data processing & actions - Learn how to use IoT Hub Rule Engine.

• IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.

• Advanced features - Learn about advanced IoT Hub features.