RUTX Azure IoT Hub cloud connection

From Teltonika Networks Wiki

Azure IoT Hub is an open and flexible cloud platform that supports open-source SDKs and multiple protocols.

Introduction

This article contains instructions on how to configure a RUT router in order to connect to the Azure IoT Hub.

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


Prerequisites

You will need:

  • A router from the RUTX09 or RUTX11
  • 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 you will add later. In Microsoft Azure home page.
      • Select Resource groups
      If it is not in very first page, click More services and locate it there.
    Azure01.png
  • In new window, select Add
    • Azure02.png
  • And then finish creating yours Resource group
    • Select your subscription, we are using Free Trial for this test.
    1. Name your group
    2. Finally, choose server location for meta data. We will choose (South America) Brazil South and will use it during test where available.
    Azure03 RUTX.png
  • At this moment we will skip adding Tags since we will be able to do that later if needed, so simply press Review + create at the bottom of screen and then click Create to finish setup.
    • Azure04.png
    Azure05 RUTX.png
  • You will be redirected to Homepage, then click on Resource groups. You should see yours newly created group, select it, and press Add.
    • Azure06 RUTX.png
  • Select Internet of Things or simply search IoT Hub and press Create.
    • Azure07.png
  • 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. Then go to Size and scale tab
    • Azure08 RUTX.png
  • For testing purposes, we are using F1: Free tier
    • At the bottom of the screen Review + create

    Azure09.png

    And finally, Click on >> Create

    Azure10 RUTX.png

    Note: Wait until resource deploys and press Go to Resources


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

    Azure11 RUTX.png

  • Press New
    • Azure12 RUTX.png
  • In new device creation
    1. Enter Device ID
    2. Leave everything else on default and press Save
    • Azure13 RUTX.png
  • After you finish creation, you will be redirected back to IoT devices select yours newly created Device ID
    • Azure14 RUTX.png
  • In your device window you will find information needed to connect RUT devices to Azure IoT Hub.
    • For now, we will only need connection string. Copy Primary Connection string by pressing copy icon next to it.

    Azure16 RUTX.png

Configuring Azure IoT Hub on RutOS

To configure an Azure IoT Hub instance on a RUT device, it is essential to first install the Azure IoT Hub package via the package manager.

  • To install required package, please on the router WebUI, navigate System > Package Manager and install Azure IoT Hub package
    • Azure RutOSconf 1.png

Now navigate to Services > Cloud solutions > Azure IoT Hub and add a new instance. In the pop-up window, you will notice two different connection types available:

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

In this article, we will demonstrate the configuration steps for both connection types.

SAS key connection type configuration

Configuring Azure IoT Hub using the SAS key connection type is quite simple and straightforward. Please follow these three steps:

1. Make sure to enable the instance by pressing Enable button
2. Paste previously copied Connection String
3. Press Save & Apply button

Azure RutOSconf 2.2.png

After the instance is correctly configured, you will be able to see the connection status on the Azure IoT Hub page of the WebUI. A green dot indicates that the connection is successful. Azure RutOSconf 3.png Additionally, you can check the connection status through the router command line by executing the following command: 

ubus call azure.1 get_connection_status

Upon executing this command, you will see its output. If the connection is successful, you will see the following output: Azure RutOSconf 4.png

If you are able to see that the connection status is succesfully and authorized it means that connection is established using SAS key connection type. Now, lets move foward with configuration of Device Provisioning Service (DPS) connection type.

Device Provisioning Service (DPS) configuration

One of the primary features of DPS is its capability to dynamically manage multiple device identities. This service manages the device identity creation process using mechanisms called attestations. There are two such mechanisms:

  • 1. X.509
  • 2. Symmetric keys

DPS X.509 mechanism

The first mechanism utilizes X.509 certificates. Each DPS service includes one or more services known as enrollment groups, which handle this task. Each enrollment group is configured to function with a specific IoT Hub, considering there may be multiple IoT Hubs. At the DPS, the root CA certificate needs to be registered. Additionally, each enrollment group should have one or more intermediate CAs that are signed by the root CA. Each RUT device must have a unique certificate signed by an intermediate CA. This certificate contains additional information, such as the subject ID field, which will serve as the device identity name on the IoT Hub. Now, let's delve into an actual example of configuring such a service.

    1. The initial step is to generate certificates. You can refer to the Microsoft guide to generate the required certificates successfully. The Microsoft guide can be found here: https://learn.microsoft.com/en-us/azure/iot-dps/tutorial-custom-hsm-enrollment-group-x509?pivots=programming-language-ansi-c#create-a-root-ca-certificate

    The required certificates and keys:

  • Root CA certificate
  • Intermediate CA certificate
  • Devices certificates
    • Please ensure to carefully follow the Microsoft guide to create certificates, making sure not to miss any steps as they are all crucial. Following the Microsoft guide, after creating the Root CA certificate, you will notice that it is named "Azure IoT Hub CA Cert Test Only". Azure RutOSconf 5.png After creating the root CA certificate, an intermediate CA certificate must be generated. Upon inspecting this certificate, you should notice that it is issued by the "Azure IoT Hub CA Cert Test Only", as seen previously. Azure RutOSconf 6.png After successfully creating the intermediate CA certificate, proceed with creating the device certificate and signing it using the intermediate authority. It's crucial to note that the subject field will be the name of the newly registered identity on the IoT Hub page. If you are following the provided Microsoft guide, you can observe "device-01" name, remember it as it will be used in later configurations steps. Azure RutOSconf 7.png Finally, we append the root CA, intermediate CA, and device certificates into one certificate chain. If you are following the guide, the "device-01-full-chain.cert.pem" file will be created. Later, we will upload this file to the RUT device WebUI page.

    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 to the certificate page and upload the root CA file. Azure RutOSconf 8.png

    3. Next, navigate to the "Manage Enrollments" page to register the intermediate CA and target our IoT Hub service instance.

    Azure RutOSconf 9.1.png Azure RutOSconf 10.png

    4. The final step is to return to the RUT device WebUI and navigate to Services -> Cloud Solutions -> Azure IoT Hub page to create a new configuration instance. In the configuration pop-up window, please follow these steps: 4.1 Set connection type as a Device Provisioning Service (DPS); 4.2 Enter ID Scope of your DPS service page on Azure; 4.3 Specify the Registration ID. Remember the "device-01" one? If you followed the Microsoft guide step by step, you need to enter "device-01" in the "Registration ID" field. 4.4 Lastly, 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:

    Azure RutOSconf 11.png

    After a couple of seconds, you will be able to observe the status of your configured instance in the Azure IoT Hub page on the router WebUI.

    Azure RutOSconf 12.png

    The device successfully connects to the Azure IoT Hub.

    DPS Symmetric key mechanism

    Symmetric key mechanism is a more basic one. To configure it, firstly head back to Azure portal your DPS service page and create new enrollment group with Symmetric key attestation mechanism.

    Azure RutOSconf 13.png

    Inspecting the newly created enrollment group will reveal some keys. The primary key will be used to derive each individual device indentities. This can be done with simple script, which is available on the following Microsoft guide: https://learn.microsoft.com/en-us/azure/iot-dps/how-to-legacy-device-symm-key?tabs=linux&amp%3Bpivots=programming-language-ansi-c&pivots=programming-language-ansi-c#derive-a-device-key

    In the script, you will see couple important variables - KEY and REG_ID. In the key field, we must specify primary key, which we take from new created enrollment group.

    Azure RutOSconf 14.1.png

Checking if Data reaches Azure IoT Hub

  • From router side, connect to it with CLI or SSH client and write in command azure_iothub and press Enter
    • - You should get answer that looks something like that, depending on what information you chose to send.

    Azure19 RUTX.png

  • From Azure IoT Hub side you can check if it receives data. Go to IoT Hub that you created previously. Select Overview, there you can see:
    • 1. How many devices are connected to hub, and how many messages it sent during chosen period of time.
    2. Device to cloud messages, that your router is sending.

    It should look something like that if IoT Hub is receiving data.

    Azure20 RUTX.png

  • To capture logs you will need Device Explorer for IoT Hub Devices.

    • Scroll down to Assets, download and install SetupDeviceExplorer.msi

    Azure21.png

  • Now you will need connection string of yours Azure IoT Hub, Not device. Navigate to IoT hub in your browser, then:
    • 1. Click Shared access policies
    2. Next choose iothubowner
    3. And copy Connection string – primary key

    Azure22-1 RUTX.png

  • After that go back to Device Explorer:
    • 1. In Configuration tab paste in Connection string that you just copied
    2. Copy HostName part from connection string and paste it in Protocol Gateway HostName
    3. Click Update

    Azure23 RUTX.png

  • Open Management tab
    • 1. Click Update
    2. You should see your device in the list below and Connection state

    Azure24 RUTX.png

  • Go to Data tab
    • 1. Click monitor, and wait for Event Hub Data to update (Depends on yours chosen interval)
    2. Messages like this should start appearing.

    Azure25 RUTX.png

    Setting router to Forward MQTT messages/commands to Azure IoT Hub

    First you will need MQTT broker to subscribe to, for testing purposes we will set MQTT Broker in same router, and will use PC from LAN to sent MQTT messages.
  • Go to Services > MQTT > Broker
    • 1. Click Enable
    2. Use same port in MQTT Broker and Azure IoT Hub settings.
    3. Press Save

    Azure26-1 RUTX.png

  • Go to Services > Cloud solutions > Azure IoT Hub
    • 1. Enable monitoring
    2. Use same Connection string as before (GSM values configuration)
    3. Messages Type choose MQTT messages
    4. Enter MQTT Host address, we are using 127.0.0.1 since our broker is set up on same router.
    5. Port Same as MQTT Broker
    6. And Topic under which router will subscribe to MQTT Broker
    7. Press Save, we will not need username or password.

    Azure27-2 RUTX.png

Checking if MQTT messages are being forwarded to Azure IoT Hub

Linux

    Connect to router with SSH, in logread you should see Router establishing connection to Azure IoT Hub:

    Azure27-1.png

  • Open terminal and publish to MQTT Broker message with previously chosen topic.
    For our example we are using example: mosquito_pub -h 192.168.1.1 -p 8883 -m ‘testing Azure MQTT messages’ -t test

    • If everything was configured correctly in Device Explorer Data tab you should receive message like:

    Azure28 RUTX.png

    This means our router Forwards MQTT messages to Azure IoT Hub.

Windows

  • Install a MQTT client software to do the test, for this example we used MQTT.fx
    • 1. Setup your Router IP Address
    2. Use the same broker port
    3. Paste your Connection string – primary key and click Apply

    Azure29-1 RUTX.png

    1. Connect to the server broker
    2. Use the created topic. For this example test
    3. Send a message

    Azure30 RUTX.png

  • If you did everything right this message will be shown in the device explorer
Retrieved from "https://wiki.teltonika-networks.com/index.php?title=RUTX_Azure_IoT_Hub_cloud_connection&oldid=126656"