19
edits
Changes
update link names
====DPS X.509 attestation====
====DPS X.509 attestation====
<ul>
<ul>
<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.
<div> 1. The initial step generating certificates. Refer to the Microsoft guide, section [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 "''Create an X.509 certificate chain''"] for in depth information that explains each step of the process in detail.
The required certificates and keys:
The required certificates and keys:
<li> '''Devices certificates''' </li>
<li> '''Devices certificates''' </li>
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].
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. Refer to the Microsoft guide, section [https://learn.microsoft.com/en-us/azure/iot-dps/tutorial-custom-hsm-enrollment-group-x509?pivots=programming-language-ansi-c#create-an-enrollment-group "''Create an enrollment group''"] for in depth information.
</div>
</div>
3. Return to the device WebUI and navigate to '''Services -> Cloud Solutions -> Azure IoT Hub''' page to create a new configuration instance:
3.1 Set connection type as a '''Device Provisioning Service (DPS)''';
3.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;
3.3 Specify the '''Registration ID'''. This is the subject common name (CN) of the device leaf certificate that was created using the earlier guide.
3.4 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 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&%3Bpivots=programming-language-ansi-c&pivots=programming-language-ansi-c#derive-a-device-key here]
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 on Microsoft DPS documentation [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 here].
The script contains a couple of variables: '''KEY''' and '''REG_ID'''. The KEY field shall contain the primary key which is obtained from the newly created enrollment group. 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 14.1.png|border|class=tlt-border]]
[[File:Azure symm example 1.png|border|class=tlt-border]]
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.
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. 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 from Microsoft.</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 that was specified in the earlier script.</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>
<li> In the '''Symmetric key''' field enter the output value of the script that was used earlier].</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 symm example 2 modified.png|border|class=tlt-border]]
After a few moments the device should establish connection to the Azure server.
After a few moments the device should establish connection to the Azure server.
After returning to the IoT Hub services in the Azure portal page it can be observed that the DPS service has created a new device identity was named the same as what we specified in the '''REG_ID''' field in the script.
[[File:Azure_RutOSconf_18.png|border|class=tlt-border]]
[[File:Azure symm example 3.png|border|class=tlt-border]]
</ul>
</ul>
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)'''. 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].
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]]
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 for easier work:
The IoT Explorer can be configured to parse DTDL files and display them to the user for easier work:
[[File:Azure RutOSconf 29.png|border|class=tlt-border]]
[[File:Azure RutOSconf 29.png|border|class=tlt-border]]
==Example use cases==
This section shows some practical examples that combines most of the features that are discussed earlier.
===Dynamically monitoring Modbus data===
This example shows how to monitor and dynamically control Modbus data purely from the Azure cloud. We will set up a simple Modbus TCP server and client with Data to Server which will forward all the incoming Modbus data to Azure IoT Hub. In the end, using Direct Methods we will showcase how Modbus TCP client can collect and report different data from the cloud.
[[File:Azure_drawio_diagram.png|border|class=tlt-border]]
For this we will be using the following services:
*Azure IoT Hub;
*Data to Server;
*Modbus TCP Server;
*Modbus TCP Client;
*An Azure IoT Hub account.
In this example the Azure IoT Hub WebUI service configuration will not be covered since all the necessary information can be found in the earlier sections.
====Modbus TCP Server====
Enable the service in '''Services -> Modbus -> Modbus TCP Server''' with '''Enable''' option. For more information about this service you can find it on our Modbus Wiki [https://wiki.teltonika-networks.com/view/RUTX11_Modbus#Modbus_TCP_Server TCP server section]
====Modbus TCP Client====
Go to '''Services -> Modbus -> Modbus TCP Client''' page and create a new instance. This part will assume most of the configuration for this page is already made. For more information about this service you can find it on our Modbus Wiki [https://wiki.teltonika-networks.com/view/RUTX11_Modbus#Modbus_TCP_Client TCP client section].
For this use case a single Modbus request configuration will be created to request the current device timestamp:
*Data type: '''32bit UINT, Byte order 1,2,3,4'''
*Function: '''Read holding registers (3)'''
*First register number: '''2'''
*Register counter/Values: '''2'''
For device specific Modbus register information refer to the appropriate Wiki documentation.
====Data to Server====
1. Go to '''Services -> Data to Server''' page and create a new collection instance.
1.1. Select the input '''Type''' to '''Modbus''';
1.2. Change the '''Format type''' to '''Custom''';
1.3. In the '''Format string''' we will enter the following data: '''{"Date (Linux timestamp)": %timestamp%, "MODBUS server ID": "%server_id%", "MODBUS server name" : "%server_name%", "Request name": "%name%", "Start register": "%addr%", "Register data (JSON object)": %data%, "Raw data": "%raw_data%"}'''. This will form requests about Modbus data including the register values;
1.4. In the '''Collection configuration''' page select the '''Format type''' to custom;
1.5. Change the '''Format string''' to '''{ "input1": %input1% }'''. Make sure to change the '''%input1%''' value to your specific input name. Note that this value is not enclosed in braces. This is intentional since the braces are present in the Modbus input '''Format string''' field;
1.6. In the '''Server configuration''' select the '''Type''' to '''Azure IoT Hub''' and configure the Azure configuration instance in accordance to your needs.
====Monitoring and controlling incoming data====
Inspecting the incoming data to the Azure IoT Hub using Azure IoT Explorer reveals that Modbus data is being received successfully.
[[File:Azure modbus example 1 modified 1.png|border|class=tlt-border]]
In order to change the type of Modbus data sent to the Azure IoT Hub without going to the device WebUI the '''Direct Methods''' feature can be utilized. Using Azure IoT Explorer go to the device identity that was configured on the Teltonika device and select '''Direct method''' tab.
Using the '''api_call''' direct method create API requests that update the Modbus TCP Client request configurations (API reference for Modbus services can be found [https://developers.teltonika-networks.com/reference/7.6.10/v1/modbus/ here]. In this example the request configuration will be changed to collect '''Mobile signal strength'''. To do this using only API we will need to resolve the Modbus TCP client instance ID then the request ID of the instance which currently collects the temperature data. Using both of the IDs we will form the last API PUT request to update the register values:
2.1. Invoke '''/modbus/client/tcp/config''' GET request and inspect the output on IoT Explorer. The '''"data"''' array will contain JSON objects of every configured client instance. The '''"id"''' value will be used when forming the next API request;
[[File:Azure modbus example 2.png|border|class=tlt-border]]
2.2. Invoke '''/modbus/client/tcp/{id}/requests/config''' GET request and replace the '''{id}''' with the '''"id"''' value from the previous step. Inspecting the output will reveal the '''"data"''' array which contain JSON objects of every configured request. The '''"id"''' value of the request that collects temperature data will be used when forming the next API request;
[[File:Azure modbus example 3.png|border|class=tlt-border]]
2.3. Invoke '''/modbus/client/tcp/{id}/requests/config/{request_id}''' PUT request and replace the '''{id}''' with the '''"id"''' value from the 2.1. step and replace the '''{request_id}''' with the '''"id"''' value from the 2.2. step. In the '''request_body''' field add values to change the first register and data type values: '''{"data":{"first_reg":"4","data_type":"32bit_int1234"}}''' which corresponds to mobile signal strength register (other parameters such as number of registers stay the same since the timestamp register count is the same too).
[[File:Azure modbus example 4.png|border|class=tlt-border]]
2.4. Observe the incoming telemetry data. At this point the register data shall contain the mobile signal strength values.
[[File:Azure modbus example 5.png|border|class=tlt-border]]
This concludes the Azure IoT Hub guide. Using Direct Methods with device API is a powerful tool that unlocks new capabilities of device monitoring and control from the cloud. Nearly all features available via device WebUI are also available using API.
'''
==External links==
==External links==