Teltonika Networks Wiki

Changes

RUTX Azure IoT Hub cloud connection (view source)

Revision as of 11:33, 13 June 2024

2,935 bytes removed ,  13 June
clean up DPS page
Line 6: Line 6:  
__TOC__
 
__TOC__
 
==Introduction==
 
==Introduction==
−
 
+
This article contains instructions on how to configure a Teltonika Networks device in order to connect to the Azure IoT Hub. <b>Azure IoT Hub</b> 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.
−
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==
    
You will need:
 
You will need:
   −
*A Teltonika Networks router;  
+
*A Teltonika Networks device;  
 
*An Azure IoT Hub account.
 
*An Azure IoT Hub account.
   Line 22: Line 21:     
<ul>
 
<ul>
−
     <li>First you will want to create a Resource group for easier management of resources that you will add later. In Microsoft Azure home page.</li>
+
     <li>First you will want to create a Resource group for easier management of resources that will be added later. In Microsoft Azure home page.</li>
 
     <ul>Select '''Resource groups''' <br>If it is not in very first page, click '''More services''' and locate it there. </ul>  
 
     <ul>Select '''Resource groups''' <br>If it is not in very first page, click '''More services''' and locate it there. </ul>  
 
     <div>[[File:Azure01.png|border|class=tlt-border|800px]]</div>
 
     <div>[[File:Azure01.png|border|class=tlt-border|800px]]</div>
Line 28: Line 27:  
[[File:Azure02.png|border|class=tlt-border]]
 
[[File:Azure02.png|border|class=tlt-border]]
   −
<li>And then finish creating yours Resource group </li>
+
<li>And finish creating the Resource group </li>
   −
Select your subscription, we are using '''Free Trial''' for this test.  
+
Select your subscription, for this example '''Free Trial''' will be used.  
 
#Name your group
 
#Name your group
−
#Finally, choose server location for meta data. We will choose '''''(South America) Brazil South''''' and will use it during test where available.
+
#Choose server location for meta data. We will choose '''''(South America) Brazil South''''' and will use it during this example.
 
[[File:Azure03_RUTX.png|border|class=tlt-border]]
 
[[File:Azure03_RUTX.png|border|class=tlt-border]]
   −
<li>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.</li>
+
<li>At this moment Tags will be skipped, press '''Review + create''' at the bottom of screen and click Create to finish setup.</li>
 
[[File:Azure04.png|border|class=tlt-border]]
 
[[File:Azure04.png|border|class=tlt-border]]
 
<br>
 
<br>
 
[[File:Azure05_RUTX.png|border|class=tlt-border]]
 
[[File:Azure05_RUTX.png|border|class=tlt-border]]
   −
<li>You will be redirected to Homepage, then click on '''Resource groups'''. You should see yours newly created group, select it, and press '''Add'''.</li>
+
<li>After being redirected to Homepage click on '''Resource groups'''. You should see the newly created group, select it and press '''Add'''.</li>
    
[[File:Azure06_RUTX.png|border|class=tlt-border|800px]]
 
[[File:Azure06_RUTX.png|border|class=tlt-border|800px]]
Line 52: Line 51:  
     <div>1. Region – '''(South America) Brazil South''' as before</div>  
 
     <div>1. Region – '''(South America) Brazil South''' as before</div>  
 
     <div>2. Create a name for IoT Hub</div>
 
     <div>2. Create a name for IoT Hub</div>
−
     <div>3. Then go to '''Size and scale tab''' </div>
+
     <div>3. Go to '''Size and scale tab''' </div>
 
</li>
 
</li>
 
[[File:Azure08_RUTX.png|border|class=tlt-border|800px]]
 
[[File:Azure08_RUTX.png|border|class=tlt-border|800px]]
Line 58: Line 57:  
   <div>At the bottom of the screen '''Review + create'''</div>
 
   <div>At the bottom of the screen '''Review + create'''</div>
 
[[File:Azure09.png|border|class=tlt-border|800px]]
 
[[File:Azure09.png|border|class=tlt-border|800px]]
−
     <div>And finally, Click on >> '''Create''' </div>
+
     <div>Click on >> '''Create''' </div>
 
[[File:Azure10_RUTX.png|border|class=tlt-border|400px]]
 
[[File:Azure10_RUTX.png|border|class=tlt-border|400px]]
 
   <div>'''Note:''' Wait until resource deploys and press Go to '''Resources''' </div>
 
   <div>'''Note:''' Wait until resource deploys and press Go to '''Resources''' </div>
Line 75: Line 74:  
[[File:Azure13_RUTX.png|border|class=tlt-border|400px]]
 
[[File:Azure13_RUTX.png|border|class=tlt-border|400px]]
   −
     <li>After you finish creation, you will be redirected back to IoT devices select yours newly created '''Device ID'''</li>
+
     <li>After creating a new device you will be redirected back to IoT devices. Select the newly created '''Device ID'''</li>
 
[[File:Azure14_RUTX.png|border|class=tlt-border|800px]]
 
[[File:Azure14_RUTX.png|border|class=tlt-border|800px]]
   −
     <li>In your device window you will find information needed to connect RUT devices to Azure IoT Hub.</li>
+
     <li>In the device window you will find information needed to connect Teltonika devices to Azure IoT Hub.</li>
−
       <div>For now, we will only need '''connection string'''. Copy Primary Connection string by pressing copy icon next to it. </div>
+
       <div>For now only '''connection string''' will be used. Copy Primary Connection string. </div>
 
[[File:Azure16_RUTX.png|border|class=tlt-border|800px]]
 
[[File:Azure16_RUTX.png|border|class=tlt-border|800px]]
   Line 85: Line 84:     
==Configuring Azure IoT Hub on RutOS==
 
==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 configure an Azure IoT Hub instance on the Teltonika device it is essential to install the Azure IoT Hub package via the package manager.
 
<ul>
 
<ul>
−
<li>To install required package, please on the router WebUI, navigate '''System > Package Manager''' and install Azure IoT Hub package </li>
+
<li>To install required package navigate to '''System > Package Manager''' and install Azure IoT Hub package </li>
 
[[File:Azure RutOSconf 1.png|border|class=tlt-border]]
 
[[File:Azure RutOSconf 1.png|border|class=tlt-border]]
 
</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:
+
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:
 
<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 both connection types will be demonstrated.
 
===SAS key connection type configuration===
 
===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:
+
Configuring Azure IoT Hub using the SAS key connection type is straightforward:
 
<div>1. Make sure to enable the instance by pressing '''Enable''' button </div>
 
<div>1. Make sure to enable the instance by pressing '''Enable''' button </div>
 
<div>2. Paste previously copied '''Connection String'''</div>
 
<div>2. Paste previously copied '''Connection String'''</div>
Line 101: Line 100:  
[[File:Azure RutOSconf 2.2.png|border|class=tlt-border]]
 
[[File:Azure RutOSconf 2.2.png|border|class=tlt-border]]
 
</ul>
 
</ul>
−
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.
+
After the instance is correctly configured the connection status icon will be visible. A green dot indicates that the connection is successful.
 
[[File:Azure RutOSconf 3.png|border|class=tlt-border]]
 
[[File:Azure RutOSconf 3.png|border|class=tlt-border]]
−
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:
  −
[[File:Azure RutOSconf 4.png|border|class=tlt-border]]
     −
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===
 +
 
 +
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.
   −
===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 using enrollments which can be configured using the following attestation types:
−
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:
   
<ul>
 
<ul>
−
<li> 1. X.509 </li>
+
<li> 1. X.509 intermediate certificates </li>
 
<li> 2. Symmetric keys </li>
 
<li> 2. Symmetric keys </li>
 
</ul>
 
</ul>
−
====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.
      +
To learn more about DPS service read about it [https://learn.microsoft.com/en-us/azure/iot-dps/ here]
 +
 +
====DPS X.509 attestation====
 
<ul>
 
<ul>
−
<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 generating certificates. The Microsoft guide for generating certificates can be found [https://learn.microsoft.com/en-us/azure/iot-dps/tutorial-custom-hsm-enrollment-group-x509?pivots=programming-language-ansi-c#create-an-x509-certificate-chain here] which explains each step of the process in detail.
 +
 
 
The required certificates and keys:
 
The required certificates and keys:
 
<li> '''Root CA certificate''' </li>
 
<li> '''Root CA certificate''' </li>
Line 126: Line 124:  
<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.
+
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 [https://learn.microsoft.com/en-us/azure/iot-dps/tutorial-custom-hsm-enrollment-group-x509?pivots=programming-language-ansi-c#create-an-enrollment-group here].
−
 
  −
Following the Microsoft guide, after creating the Root CA certificate, you will notice that it is named "Azure IoT Hub CA Cert Test Only".
  −
[[File:Azure RutOSconf 5.png|border|class=tlt-border]]
  −
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.
  −
[[File:Azure RutOSconf 6.png|border|class=tlt-border]]
  −
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.
  −
[[File:Azure RutOSconf 7.png|border|class=tlt-border]]
  −
 
  −
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.
  −
</div>
  −
<div>
  −
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.  
  −
[[File:Azure RutOSconf 8.png|border|class=tlt-border]]
   
</div>
 
</div>
   −
3. Next, navigate to the "Manage Enrollments" page to register the intermediate CA and target our IoT Hub service instance.
+
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:
   −
[[File:Azure RutOSconf 9.1.png|border|class=tlt-border]]
+
4.1 Set connection type as a '''Device Provisioning Service (DPS)''';
−
[[File:Azure RutOSconf 10.png|border|class=tlt-border]]
  −
 
  −
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. This value can be retrieved from the DPS instance found on Azure Portal page or by following the earlier guide;
   −
4.2 Enter '''ID Scope''' of your DPS service page on Azure;
+
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.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 Upload the certificate chain file and the private key file.  
−
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:
+
With all the required values in place the configuration pop-up window should resemble the screenshot below:
    
[[File:Azure RutOSconf 11.png|border|class=tlt-border]]
 
[[File:Azure RutOSconf 11.png|border|class=tlt-border]]
   −
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.
+
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.
    
[[File:Azure RutOSconf 12.png|border|class=tlt-border]]
 
[[File:Azure RutOSconf 12.png|border|class=tlt-border]]
−
  −
The device successfully connects to the Azure IoT Hub.
      
====DPS Symmetric key mechanism====
 
====DPS Symmetric key mechanism====
−
The Symmetric key mechanism configuration is more straightforward. To configure it, first, go back to the Azure portal, navigate to your DPS service page, and create a new enrollment group with the Symmetric key attestation 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.
    
[[File:Azure RutOSconf 13.png|border|class=tlt-border]]
 
[[File:Azure RutOSconf 13.png|border|class=tlt-border]]
Line 177: Line 156:  
[[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.
+
The '''REG_ID''' field specifies the device identity name that will be created. Upon executing the script a shared access key will be created.
    
[[File:Azure_RutOSconf_15.png|border|class=tlt-border]]
 
[[File:Azure_RutOSconf_15.png|border|class=tlt-border]]
   −
After executing the script, go back to the RUT device '''Services -> Cloud Solutions -> Azure IoT Hub''' configurations page and add a new instance. In the configuration window, select DPS connection type and Symmetric Key connection type.
+
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.
    
<ul>
 
<ul>
−
<li> In the "'''ID scope'''" field, specify your Azure DPS service ID. </li>
+
<li> 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.</li>
−
<li> In the "'''Registration ID'''" field, enter the "REG_ID" value you specified in the script. For example, "wiki-newly-generated-device". </li>
+
<li> In the '''Registration ID''' field enter the "REG_ID" value you specified in the script. For example, "wiki-newly-generated-device". </li>
−
<li>In the "'''Symmetric key'''" field, enter the "SharedAccessKey" obtained from the script execution. </li>
+
<li> In the '''Symmetric key''' field enter the "SharedAccessKey" obtained from the script execution output.</li>
 
</ul>
 
</ul>
−
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.
+
 
−
[[File:Azure_RutOSconf_17.png|border|class=tlt-border]]
+
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.
+
 
 +
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.
      
</ul>
 
</ul>
Retrieved from "https://wiki.teltonika-networks.com/view/Special:MobileDiff/126783...126932"