Azure IoT Hub Cloud Connection

The information in this page is updated in accordance with the RUTX_R_00.02.01.1 firmware version.

Introduction

This article contains instructions on how to configure a Teltonika Networks device in order to connect to the Azure IoT Hub. Azure IoT Hub is a managed service hosted in the cloud that acts as a central message hub for communication between an IoT application and its attached devices.

Prerequisites

You will need:

A Teltonika Networks device;
An Azure IoT Hub account.

Azure account creation

Visit https://azure.microsoft.com/en-us/ and create an account that will suit your needs, for testing purposes we will be using free Azure account.

Managing Azure services

First you will want to create a Resource group for easier management of resources that will be added later. In Microsoft Azure home page.

Resource groups

More services

In new window, select Add

And finish creating the Resource group

Free Trial

Name your group
Choose server location for meta data. We will choose (South America) Brazil South and will use it during this example.

At this moment Tags will be skipped, press Review + create at the bottom of screen and click Create to finish setup.

After being redirected to Homepage click on Resource groups. You should see the newly created group, select it and press Add.

Select Internet of Things or simply search IoT Hub and press Create.

We leave default subscription and resource group and choose:
1. Region – (South America) Brazil South as before

2. Create a name for IoT Hub

3. Go to Size and scale tab

For testing purposes, we are using F1: Free tier

At the bottom of the screen Review + create

Click on >> Create

Note: Wait until resource deploys and press Go to Resources

Inside IoT Hub list:
Scroll down to Explorers and select IoT devices
Press New

In new device creation

1. Enter Device ID

2. Leave everything else on default and press Save

After creating a new device you will be redirected back to IoT devices. Select the newly created Device ID

In the device window you will find information needed to connect Teltonika devices to Azure IoT Hub.

For now only connection string will be used. Copy Primary Connection string.

Configuring Azure IoT Hub on RutOS

To configure an Azure IoT Hub instance on the Teltonika device it is essential to install the Azure IoT Hub package via the package manager.

To install required package navigate to System > Package Manager and install Azure IoT Hub package

Navigate to Services > Cloud solutions > Azure IoT Hub and add a new instance. In the pop-up window there will be two different connection types available:

Shared Access signature (SAS) key
Device Provisioning Service (DPS)

In this article both connection types will be demonstrated.

SAS key connection type configuration

Configuring Azure IoT Hub using the SAS key connection type is straightforward:

1. Make sure to enable the instance by pressing Enable button

2. Paste previously copied Connection String

3. Press Save & Apply button

After the instance is correctly configured the connection status icon will be visible. A green dot indicates that the connection is successful.

Device Provisioning Service (DPS) configuration

The IoT Hub Device Provisioning Service (DPS) is a helper service for IoT Hub that enables zero-touch, just-in-time provisioning to the right IoT hub without requiring human intervention, allowing customers to provision millions of devices in a secure and scalable manner.

One of the primary features of DPS is its capability to dynamically manage multiple device identities. This service manages the device identity creation using enrollments which can be configured using the following attestation types:

1. X.509 intermediate certificates
2. Symmetric keys

To learn more about DPS service read about it here

DPS X.509 attestation

1. The initial step generating certificates. The Microsoft guide for generating certificates can be found here which explains each step of the process in detail.

The required certificates and keys:

Root CA certificate

Intermediate CA certificate

Devices certificates

2. After successfully generating the certificates return to the Azure portal page and navigate to your Azure IoT Hub Device Provisioning Service (DPS) page. From there proceed create an enrollment group. The Microsoft guide for creating enrollment groups can be found here.

4. The final step is to return to the device WebUI and navigate to Services -> Cloud Solutions -> Azure IoT Hub page to create a new configuration instance:

4.1 Set connection type as a Device Provisioning Service (DPS);

4.2 Enter ID Scope of your DPS service page on Azure. This value can be retrieved from the DPS instance found on Azure Portal page or by following the earlier guide;

4.3 Specify the Registration ID. This is the subject common name (CN) of the device leaf certificate that was created using the earlier guide.

4.4 Upload the certificate chain file and the private key file.

With all the required values in place the configuration pop-up window should resemble the screenshot below:

After a couple of moments the status of the configured instance status icon should turn green indicating the device has successfully established connection to Azure server.

DPS Symmetric key mechanism

The Symmetric key mechanism configuration is more straightforward. To configure it go back to the Azure portal page, navigate to your DPS service page and create a new enrollment group with the Symmetric key attestation mechanism.

Inspecting the newly created enrollment group will reveal some keys. The primary key will be used to derive each individual device identity. This can be done using a simple script, which is available in this Microsoft guide

In the script, you will notice a couple of important variables: KEY and REG_ID. In the KEY field, you must specify the primary key, which can be obtained from the newly created enrollment group.

The REG_ID field specifies the device identity name that will be created. Upon executing the script a shared access key will be created.

Go back to the device WebUI Services -> Cloud Solutions -> Azure IoT Hub configuration page and add a new instance. In the configuration window select DPS connection type and Symmetric Key connection type.

In the ID scope field, specify your Azure DPS service ID. This value can be retrieved from the DPS instance found on Azure Portal page or by following the earlier guides.
In the Registration ID field enter the "REG_ID" value you specified in the script. For example, "wiki-newly-generated-device".
In the Symmetric key field enter the "SharedAccessKey" obtained from the script execution output.

If you are following this guide your configuration window should look similar to the screenshot below.

After a few moments the device should establish connection to the Azure server.

Moreover, we can return to the IoT Hub services in the Azure portal and check the device list. There we will see that the DPS service has created a new device identity named the same as what we specified in the REG_ID field in the script earlier.

Direct methods configuration

A direct method refers to a process where an action is initiated from the Azure IoT Hub to a specific device identity. The receiving device executes certain actions and returns a response back to the Azure portal. Let's see how this works on our devices.

By default, all configuration instances will have this option disabled. To enable it, navigate on the router WebUI to Services -> Cloud Solutions -> Azure IoT Hub and press the edit button on the specific instance. There, you will see the "Enable Direct Methods" button, which you need to press.

For testing and demonstration purposes, we will use the Azure IoT Explorer application. The Azure IoT Explorer is a graphical tool for interacting with devices connected to your IoT hub. If you are not familiar with it, you can follow this Microsoft installation and usage guide

After enabling the Direct Method feature, go to Azure IoT Explorer, select the appropriate device identity, and navigate to the Direct Methods tab. All our RUT devices support the api_call direct method, which exposes the API interface to be used from the Azure side. In this example, we will make a simple GET request to retrieve the I/O status of the device. Full documentation of Teltonika devices API can be found here

In the Azure IoT Explorer Direct Method tab, you will see a Payload field. It expects to receive JSON-formatted information.

The API call expects at least two parameters. The first one is called "method," which needs to have an integer value between zero and three, corresponding to the API method type - either "get", "out", "post", or "delete". The second parameter is "endpoint," which expects a string value of the API endpoint. In this case, we will call the /io/status endpoint.

After pressing the "Invoke Method" button, you will see the response from the device.

The response you see is a standard response as specified in our API documentation.

To determine the appropriate payload and method to use, we provide an additional file currently called "teltonikaGenericDevice.json." This file is written in Digital Twin Definition Language (DTDL). It is similar to SNMP MIB documents by design, as it also describes device capabilities. In this file, you can see that it supports the api_call method, which accepts three values. The request body is optional, as some methods, such as the GET method, may not require it. JSON files can be downloaded by pressing here

The IoT Explorer can be configured to parse DTDL files and display them to the user. Let's configure it.

IoT plug and Play configuration

To configure it, navigate to the "IoT Plug and Play components" tab on the IoT Explorer. Initially, there may be an error stating that it did not retrieve an interface model. To resolve this, click on the "Configure" button. You will then be able to add a local folder by pressing the "Add" button.

In the specified folder, you must have provided ".json" files. After adding the local folder, press the "Save" button.

After saving these settings, return to the device identity Plug and Play tab. Now, you will be able to see two components with model IDs named "genericDevice" and "deviceInformation". The generic device will display the DTDL interface description.

In the upper toolbar, select the "Commands" tab. There you will see that IoT Explorer has parsed the API call method and created three new fields. Now, we can try to call the same I/O status method that we called previously.

We can see that some information was correctly retrieved from the router, and everything works without any issues. This method makes it much easier to work with API calls from the Azure side.

Sending data with "Data to Server" feature

The Data to Server feature allows you to set up data senders that collect data from various sources and periodically send it to remote servers. We can configure this feature to send data from the router to Azure.

Data to server configurations

To configure the "Data to Server" service on RUT devices, please navigate to Services -> Data to Server on the WebUI and add a new instance. In the pop-up window, you will need to perform the following steps:

In the "Name" field, specify any name that you want;
In the "Type" field, we will leave "Base" option for this example;
In the "Format type" field, choose JSON;
Press "Next: Collection edit"" button;

In the collection configuration window, leave "Format type" as JSON, set the period to your preferred value, and press the "Next: Server configuration" button.;

In the server configuration configuration window, choose "Type" as a "Azure IoT Hub" option;

Cloud Solutions -> Azure IoT Hub

Select your preferred Azure IoT Hub instance;
Press "Save & Apply" button.

Checking if data reaches IoT Hub on Azure

To determine whether data successfully reaches Azure IoT Hub, select your device and navigate to the "Telemetry" tab on the Azure IoT Explorer. Ensure that "Use built-in event hub" option is enabled and press the "Start" button.

After a few seconds, you should see that data was sent from the device to the Azure IoT Hub. If you see a similar response, it indicates that everything was configured correctly.