124
edits
Changes
no edit summary
==Introduction==
==Introduction==
This article contains instructions on how to configure a RUT router in order to connect to the Azure IoT Hub.<b>Azure IoT Hub</b> is an open and flexible cloud platform that supports open-source SDKs and multiple protocols.
This article contains instructions on how to configure a RUT router in order to connect to the Azure IoT Hub. <b>Azure IoT Hub</b> is an open and flexible cloud platform that supports open-source SDKs and multiple protocols.
==Prerequisites==
==Prerequisites==
</ul>
</ul>
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:
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:
<ul> <li> Shared Access signature (SAS) key </li>
<ul> <li> '''Shared Access signature (SAS) key''' </li>
<li> Device Provisioning Service (DPS) </li> </ul>
<li> '''Device Provisioning Service (DPS)''' </li> </ul>
In this article, we will demonstrate the configuration steps for both connection types.
In this article, we will demonstrate the configuration steps for both connection types.
===SAS key connection type configuration===
===SAS key connection type configuration===
[[File:Azure RutOSconf 4.png|border|class=tlt-border]]
[[File:Azure RutOSconf 4.png|border|class=tlt-border]]
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.
If you can see that the connection status is successful and authorized, it means that the connection is established using the SAS key connection type. Now, let's proceed with the configuration of the Device Provisioning Service (DPS) connection type.
===Device Provisioning Service (DPS) configuration===
===Device Provisioning Service (DPS) configuration===
<div> 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 [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 here]
<div> 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 [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 here]
The required certificates and keys:
The required certificates and keys:
<li> Root CA certificate </li>
<li> '''Root CA certificate''' </li>
<li> Intermediate CA certificate </li>
<li> '''Intermediate CA certificate''' </li>
<li> Devices certificates </li>
<li> '''Devices certificates''' </li>
Please ensure to carefully follow the Microsoft guide to create certificates, making sure not to miss any steps as they are all crucial.
Please ensure to carefully follow the Microsoft guide to create certificates, making sure not to miss any steps as they are all crucial.
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 [https://learn.microsoft.com/en-us/azure/iot-dps/how-to-legacy-device-symm-key?tabs=linux&%3Bpivots=programming-language-ansi-c&pivots=programming-language-ansi-c#derive-a-device-key in this Microsoft guide]
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 [https://learn.microsoft.com/en-us/azure/iot-dps/how-to-legacy-device-symm-key?tabs=linux&%3Bpivots=programming-language-ansi-c&pivots=programming-language-ansi-c#derive-a-device-key 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.
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.
[[File:Azure RutOSconf 14.1.png|border|class=tlt-border]]
[[File:Azure RutOSconf 14.1.png|border|class=tlt-border]]
In the REG_ID field, you can specify any name you want. Upon executing the script, a shared access key will be created. Please copy this key, as we will need it in the following steps.
In the '''REG_ID''' field, you can specify any name you want. Upon executing the script, a shared access key will be created. Please copy this key, as we will need it in the following steps.
[[File:Azure_RutOSconf_15.png|border|class=tlt-border]]
[[File:Azure_RutOSconf_15.png|border|class=tlt-border]]
If you are following this guide, your configuration window should look similar to the screenshot below.
If you are following this guide, your configuration window should look similar to the screenshot below.
[[File:Azure_RutOSconf_16.png|border|class=tlt-border]]
[[File:Azure_RutOSconf_16.png|border|class=tlt-border]]
Don't forget to press the Save & Apply button! A few seconds after saving the configuration, you should be able to observe that the device successfully connects to Azure.
Don't forget to press the '''Save & Apply''' button! A few seconds after saving the configuration, you should be able to observe that the device successfully connects to Azure.
[[File:Azure_RutOSconf_17.png|border|class=tlt-border]]
[[File:Azure_RutOSconf_17.png|border|class=tlt-border]]
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.
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.
[[File:Azure_RutOSconf_18.png|border|class=tlt-border]]
[[File:Azure_RutOSconf_18.png|border|class=tlt-border]]
If you see that the connection is successful on the router WebUI page and the newly created device appears in the Azure IoT Hub device list, it means that you have configured everything correctly.
If you see that the connection is successful on the router WebUI page and the newly created device appears in the Azure IoT Hub device list, it means that you have configured everything correctly.
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 [https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer this Microsoft installation and usage guide]
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 [https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer 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 [https://developers.teltonika-networks.com/ here]
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 [https://developers.teltonika-networks.com/ here]
In the Azure IoT Explorer Direct Method tab, you will see a Payload field. It expects to receive JSON-formatted information.
In the Azure IoT Explorer Direct Method tab, you will see a Payload field. It expects to receive JSON-formatted information.
The response you see is a standard response as specified in our API documentation.
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 [[Media:Teltonika-dtmi-docs.zip|here]]
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 [[Media:Teltonika-dtmi-docs.zip|here]]
The IoT Explorer can be configured to parse DTDL files and display them to the user. Let's configure it.
The IoT Explorer can be configured to parse DTDL files and display them to the user. Let's configure it.
[[File:Azure RutOSconf 23.png|border|class=tlt-border]]
[[File:Azure RutOSconf 23.png|border|class=tlt-border]]
In the specified folder, you must have provided ".json" files. After adding the local folder, press the "Save" 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.
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.
[[File:Azure RutOSconf 24.png|border|class=tlt-border]]
[[File:Azure RutOSconf 24.png|border|class=tlt-border]]
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.
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.
[[File:Azure RutOSconf 25.png|border|class=tlt-border]]
[[File:Azure RutOSconf 25.png|border|class=tlt-border]]
