Changes

RUTX Azure IoT Hub cloud connection (view source)

Revision as of 12:20, 13 June 2024

104 bytes added ,  13 June
update Direct Methods section
Line 150: Line 150:  
[[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 simple script, which is available [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 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&amp%3Bpivots=programming-language-ansi-c&pivots=programming-language-ansi-c#derive-a-device-key here]  
    
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.
Line 165: Line 165:  
<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 '''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 output.</li>
+
<li> In the '''Symmetric key''' field enter the output value of the script that was used earlier [https://learn.microsoft.com/en-us/azure/iot-dps/how-to-legacy-device-symm-key?tabs=linux&pivots=programming-language-ansi-c#derive-a-device-key here].</li>
 
</ul>
 
</ul>
   Line 179: Line 179:     
==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.
+
IoT Hub direct methods enable you to remotely invoke calls on devices from the cloud. Direct methods follow a request-response pattern and are meant for communications that require immediate confirmation of their result.
 +
 
 +
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. Afterwards the "'''Enable Direct Methods'''" option needs to be enabled.
    
[[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. 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. To learn more about this tool you can follow the Microsoft documentation [https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer 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]  
+
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 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.
+
The Azure IoT Explorer Direct Method tab will have a Payload field. In this field the '''api_call''' method expects JSON formatted data.
    
[[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 "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.
+
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, POST, PUT 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 "'''Invoke Method'''" button, you will see the response from the device.
+
After pressing the "'''Invoke Method'''" button the response from the device will be visible which is a standard API response specified in our [https://developers.teltonika-networks.com/fundamentals/#request-and-response-structures documentation].
    
[[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.
+
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)'''. To learn more about DTDLs and Digital Twins read about it in Microsoft documentation [https://learn.microsoft.com/en-us/azure/digital-twins/concepts-models 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]]
+
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 [[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 for easier work:
    
===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.
+
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. In this guide a local folder will be added 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.
+
The specified directory must have the DTDL '''".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.
+
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]]
   −
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.
+
We can see that some information was correctly retrieved from the router. This workflow makes it easier to work with API calls from the Azure side.
    
==Sending data with "Data to Server" feature==
 
==Sending data with "Data to Server" feature==
Retrieved from "https://wiki.teltonika-networks.com/view/Special:MobileDiff/126933"

Navigation menu