Difference between revisions of "Azure IoT Hub Cloud Connection"
(24 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
+ | |||
+ | <b>Azure IoT Hub</b> is an open and flexible cloud platform that supports open-source SDKs and multiple protocols. | ||
__TOC__ | __TOC__ | ||
==Introduction== | ==Introduction== | ||
− | |||
− | + | This article contains instructions on how to configure a RUT router in order to connect to the Azure IoT Hub.<br> | |
− | + | {{Template:Networking_rutx_manual_fw_disclosure | |
+ | | fw_version = RUTX_R_00.02.01.1 | ||
+ | }} | ||
− | |||
==Prerequisites== | ==Prerequisites== | ||
Line 14: | Line 16: | ||
You will need: | You will need: | ||
− | *A | + | *A router from the RUTX09 or RUTX11 |
− | *An Azure IoT Hub account | + | *An Azure IoT Hub account |
==Azure account creation== | ==Azure account creation== | ||
Line 24: | Line 26: | ||
<ul> | <ul> | ||
− | <li>First you will want to create a Resource group for easier management of resources that will | + | <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> |
<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 30: | Line 32: | ||
[[File:Azure02.png|border|class=tlt-border]] | [[File:Azure02.png|border|class=tlt-border]] | ||
− | <li>And finish creating | + | <li>And then finish creating yours Resource group </li> |
− | Select your subscription, | + | Select your subscription, we are using '''Free Trial''' for this test. |
#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. |
[[File:Azure03_RUTX.png|border|class=tlt-border]] | [[File:Azure03_RUTX.png|border|class=tlt-border]] | ||
− | <li>At this moment Tags will be | + | <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> |
[[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> | + | <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> |
[[File:Azure06_RUTX.png|border|class=tlt-border|800px]] | [[File:Azure06_RUTX.png|border|class=tlt-border|800px]] | ||
Line 54: | Line 56: | ||
<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. | + | <div>3. Then 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 60: | Line 62: | ||
<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>Click on >> '''Create''' </div> | + | <div>And finally, 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 77: | Line 79: | ||
[[File:Azure13_RUTX.png|border|class=tlt-border|400px]] | [[File:Azure13_RUTX.png|border|class=tlt-border|400px]] | ||
− | <li>After | + | <li>After you finish creation, you will be redirected back to IoT devices select yours 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 | + | <li>In your device window you will find information needed to connect RUT devices to Azure IoT Hub.</li> |
− | <div>For now only '''connection string''' | + | <div>For now, we will only need '''connection string'''. Copy Primary Connection string by pressing copy icon next to it. </div> |
[[File:Azure16_RUTX.png|border|class=tlt-border|800px]] | [[File:Azure16_RUTX.png|border|class=tlt-border|800px]] | ||
Line 87: | Line 89: | ||
==Configuring Azure IoT Hub on RutOS== | ==Configuring Azure IoT Hub on RutOS== | ||
− | To configure an Azure IoT Hub instance on | + | 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. |
<ul> | <ul> | ||
− | <li>To install required package navigate | + | <li>To install required package, please on the router WebUI, navigate '''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: | |
− | <ul> <li> | + | <ul> <li> Shared Access signature (SAS) key </li> |
− | <li> | + | <li> Device Provisioning Service (DPS) </li> </ul> |
− | In this article 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=== | ||
− | Configuring Azure IoT Hub using the SAS key connection type is straightforward: | + | Configuring Azure IoT Hub using the SAS key connection type is quite simple and straightforward. Please follow these three steps: |
− | <div>1. Make sure to enable the instance by pressing ''' | + | <div>1. Make sure to enable the instance by pressing '''Enable''' button </div> |
− | <div>2. Paste previously copied ''' | + | <div>2. Paste previously copied '''Connection String'''</div> |
− | <div>3. Press ''' | + | <div>3. Press '''Save & Apply''' button </div> |
[[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 the connection status | + | 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. |
[[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 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=== | ===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: | |
− | |||
− | |||
− | One of the primary features of DPS is its capability to dynamically manage multiple device identities. This service manages the device identity creation using | ||
<ul> | <ul> | ||
− | <li> 1. X.509 | + | <li> 1. X.509 </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. | ||
− | |||
− | |||
− | |||
<ul> | <ul> | ||
− | <div> 1. The initial step | + | <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 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: | The required certificates and keys: | ||
− | <li> | + | <li> Root CA certificate </li> |
− | <li> | + | <li> Intermediate CA certificate </li> |
− | <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. | |
− | |||
− | + | 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> | ||
− | 3. | + | 3. Next, navigate to the "Manage Enrollments" page to register the intermediate CA and target our IoT Hub service instance. |
− | + | [[File:Azure RutOSconf 9.1.png|border|class=tlt-border]] | |
+ | [[File:Azure RutOSconf 10.png|border|class=tlt-border]] | ||
− | 3.4 | + | 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: | + | 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 | + | 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. |
[[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 go back to the Azure portal | + | 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. |
[[File:Azure RutOSconf 13.png|border|class=tlt-border]] | [[File:Azure RutOSconf 13.png|border|class=tlt-border]] | ||
− | 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 script which is available | + | 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 the following Microsoft guide.: 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 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]] | ||
− | + | 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: | + | [[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. | |
<ul> | <ul> | ||
− | <li> In the | + | <li> In the "ID scope" field, specify your Azure DPS service ID. </li> |
− | <li> In the | + | <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 | + | <li>In the "Symmetric key" field, enter the "SharedAccessKey" obtained from the script execution. </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]] |
− | + | 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: | + | [[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. | |
− | + | [[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. | |
− | |||
− | |||
− | [[File: | ||
</ul> | </ul> | ||
==Direct methods configuration== | ==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. | |
− | |||
− | By default, all configuration instances will have this option disabled. To enable it, navigate on the router WebUI to | ||
[[File:Azure RutOSconf 19.png|border|class=tlt-border]] | [[File:Azure RutOSconf 19.png|border|class=tlt-border]] | ||
− | 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. | + | 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 https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer |
− | |||
− | |||
− | After enabling the | + | 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 https://developers.teltonika-networks.com/ |
− | + | In the Azure IoT Explorer Direct Method tab, you will see a Payload field. It expects to receive JSON-formatted information. | |
[[File:Azure RutOSconf 20.png|border|class=tlt-border]] | [[File:Azure RutOSconf 20.png|border|class=tlt-border]] | ||
− | The API call expects at least two parameters. The first one is called | + | 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. |
[[File:Azure RutOSconf 22.1.png|border|class=tlt-border]] | [[File:Azure RutOSconf 22.1.png|border|class=tlt-border]] | ||
− | After pressing the " | + | After pressing the "Invoke Method" button, you will see the response from the device. |
[[File:Azure RutOSconf 21.png|border|class=tlt-border]] | [[File:Azure RutOSconf 21.png|border|class=tlt-border]] | ||
− | + | The response you see is a standard response as specified in our API documentation. | |
− | 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. | + | 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. INSERT FILES! |
− | The IoT Explorer can be configured to parse DTDL files and display them to the user | + | 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=== | ===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. | |
[[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. | |
− | + | 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 " | + | 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]] | ||
− | We can see that some information was correctly retrieved from the router. This | + | 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. |
+ | |||
+ | ==Checking if Data reaches Azure IoT Hub== | ||
+ | <ul> | ||
+ | <li>From router side, connect to it with CLI or SSH client and write in command '''azure_iothub''' and press Enter </li> | ||
+ | <div>- You should get answer that looks something like that, depending on what information you chose to send. </div> | ||
+ | [[File:Azure19_RUTX.png|border|class=tlt-border]] | ||
+ | <li>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: | ||
+ | </li> | ||
+ | <div>1. How many devices are connected to hub, and how many messages it sent during chosen period of time.</div> | ||
+ | <div>2. Device to cloud messages, that your router is sending.</div><br> | ||
+ | <div>It should look something like that if IoT Hub is receiving data. </div> | ||
+ | [[File:Azure20_RUTX.png|border|class=tlt-border|800px]] | ||
+ | <li>To capture logs you will need '''Device Explorer''' for IoT Hub Devices.</li> | ||
+ | <div>For Windows you can get here: https://github.com/Azure/azure-iot-sdk-csharp/releases/tag/2019-1-4 </div><br> | ||
+ | <div>Scroll down to Assets, download and install '''SetupDeviceExplorer.msi''' </div> | ||
+ | [[File:Azure21.png|border|class=tlt-border]] | ||
+ | <li>Now you will need connection string of yours Azure IoT Hub, Not device. Navigate to IoT hub in your browser, then:</li> | ||
+ | <div>1. Click '''Shared access policies'''</div> | ||
+ | <div>2. Next choose '''iothubowner'''</div> | ||
+ | <div>3. And copy '''Connection string – primary key'''</div> | ||
+ | [[File:Azure22-1_RUTX.png|border|class=tlt-border|800px]] | ||
+ | |||
+ | <li>After that go back to Device Explorer: </li> | ||
+ | <div>1. In Configuration tab paste in Connection string that you just copied</div> | ||
+ | <div>2. Copy HostName part from connection string and paste it in '''Protocol Gateway HostName'''</div> | ||
+ | <div>3. Click '''Update''' </div> | ||
+ | [[File:Azure23_RUTX.png|border|class=tlt-border|600px]] | ||
+ | |||
+ | <li>Open Management tab </li> | ||
+ | <div>1. Click Update </div> | ||
+ | <div>2. You should see your device in the list below and '''Connection state''' </div> | ||
+ | [[File:Azure24_RUTX.png|border|class=tlt-border|800px]] | ||
+ | |||
+ | <li>Go to Data tab</li> | ||
+ | <div>1. Click monitor, and wait for '''Event Hub Data''' to update (Depends on yours chosen interval)</div> | ||
+ | <div>2. Messages like this should start appearing. </div> | ||
+ | [[File:Azure25_RUTX.png|border|class=tlt-border|600px]] | ||
==Sending data with "Data to Server" feature== | ==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: | ||
− | + | <ul> | |
+ | <li> In the "Name" field, specify any name that you want; </li> | ||
+ | <li> In the "Type" field, we will leave "Base" option for this example; </li> | ||
+ | <li> In the "Format type" field, choose JSON; </li> | ||
+ | <li> Press "Next: Collection edit"" button; </li> | ||
− | = | + | [[File:Azure RutOSconf 26.png|border|class=tlt-border]] |
− | + | <li> In the collection configuration window, leave "Format type" as JSON, set the period to your preferred value, and press the "Next: Server configuration" button.;</li> | |
− | + | [[File:Azure RutOSconf 27.png|border|class=tlt-border]] | |
− | In the "Configuration type" field you can choose whether to use an existing Azure IoT Hub configuration or configure a new | + | <li> In the server configuration configuration window, choose "Type" as a "Azure IoT Hub" option; </li> |
+ | In the "Configuration type" field, you can choose whether to use an existing Azure IoT Hub configuration or configure a new, unique Azure IoT Hub configuration. In this example, we will stick with the previously created, existing Azure IoT Hub instance configuration. | ||
− | If you choose to create a new unique Azure IoT Hub configuration on the Data to Server instance you will | + | If you choose to create a new unique Azure IoT Hub configuration on the Data to Server instance, you will be able to choose connection types, upload certificates, connection strings, and more, just as we did previously on the '''Cloud Solutions -> Azure IoT Hub''' WebUI page. |
<li> Select your preferred Azure IoT Hub instance; </li> | <li> Select your preferred Azure IoT Hub instance; </li> | ||
− | <li> Press " | + | <li> Press "Save & Apply" button. </li> |
− | If you are following this guide your | + | If you are following this guide, after saving, your configurations should resemble the screenshot below. |
[[File:Azure RutOSconf 28.png|border|class=tlt-border]] | [[File:Azure RutOSconf 28.png|border|class=tlt-border]] | ||
Line 253: | Line 317: | ||
====Checking if data reaches IoT Hub on Azure==== | ====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 | + | 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 a response was received from the device. |
[[File:Azure RutOSconf 29.png|border|class=tlt-border]] | [[File:Azure RutOSconf 29.png|border|class=tlt-border]] | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
Revision as of 09:33, 12 June 2024
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.
- In new window, select Add
- And then finish creating yours Resource group Select your subscription, we are using Free Trial for this test.
- 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.
- 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.
- You will be redirected to Homepage, then click on Resource groups. You should see yours 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 before2. Create a name for IoT Hub3. Then go to Size and scale tab
- For testing purposes, we are using F1: Free tier
- Inside IoT Hub list:
Scroll down to Explorers and select IoT devices
- Press New
-
In new device creation1. Enter Device ID2. Leave everything else on default and press Save
- After you finish creation, you will be redirected back to IoT devices select yours newly created Device ID
- In your device window you will find information needed to connect RUT devices to Azure IoT Hub.
- Select Resource groups
If it is not in very first page, click More services and locate it there.
![Azure02.png](/images/d/d1/Azure02.png)
![Azure03 RUTX.png](/images/6/61/Azure03_RUTX.png)
![Azure04.png](/images/4/49/Azure04.png)
![Azure05 RUTX.png](/images/a/a4/Azure05_RUTX.png)
![Azure06 RUTX.png](/images/thumb/b/bc/Azure06_RUTX.png/800px-Azure06_RUTX.png)
![Azure07.png](/images/thumb/4/42/Azure07.png/800px-Azure07.png)
![Azure08 RUTX.png](/images/thumb/2/27/Azure08_RUTX.png/800px-Azure08_RUTX.png)
![Azure12 RUTX.png](/images/thumb/5/52/Azure12_RUTX.png/800px-Azure12_RUTX.png)
![Azure13 RUTX.png](/images/thumb/f/fd/Azure13_RUTX.png/400px-Azure13_RUTX.png)
![Azure14 RUTX.png](/images/thumb/c/ce/Azure14_RUTX.png/800px-Azure14_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](/images/b/bb/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:
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.
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:
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.
- 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".
- In the "ID scope" field, specify your Azure DPS service ID.
- 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.
The required certificates and keys:
![Azure RutOSconf 5.png](/images/c/c2/Azure_RutOSconf_5.png)
![Azure RutOSconf 6.png](/images/5/5e/Azure_RutOSconf_6.png)
![Azure RutOSconf 7.png](/images/d/d4/Azure_RutOSconf_7.png)
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.
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 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:
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.
The device successfully connects to the Azure IoT Hub.
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.
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 the following Microsoft guide.: 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 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 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.
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.
If you are following this guide, your configuration window should look similar to the screenshot below.
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.
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.
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.
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 https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer
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 https://developers.teltonika-networks.com/
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. INSERT FILES!
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.
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
- 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:
- To capture logs you will need Device Explorer for IoT Hub Devices.
- Now you will need connection string of yours Azure IoT Hub, Not device. Navigate to IoT hub in your browser, then:
- After that go back to Device Explorer:
- Open Management tab
- Go to Data tab
- 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; In the "Configuration type" field, you can choose whether to use an existing Azure IoT Hub configuration or configure a new, unique Azure IoT Hub configuration. In this example, we will stick with the previously created, existing Azure IoT Hub instance configuration. If you choose to create a new unique Azure IoT Hub configuration on the Data to Server instance, you will be able to choose connection types, upload certificates, connection strings, and more, just as we did previously on the Cloud Solutions -> Azure IoT Hub WebUI page.
- Select your preferred Azure IoT Hub instance;
- Press "Save & Apply" button. If you are following this guide, after saving, your configurations should resemble the screenshot below.
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:
![Azure RutOSconf 26.png](/images/2/2a/Azure_RutOSconf_26.png)
![Azure RutOSconf 27.png](/images/f/f7/Azure_RutOSconf_27.png)
![Azure RutOSconf 28.png](/images/c/cb/Azure_RutOSconf_28.png)
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 a response was received from the device.