Changes

RUTX Azure IoT Hub cloud connection (view source)

Revision as of 15:40, 28 June 2024

686 bytes added ,  28 June
no edit summary
Line 95: Line 95:  
===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 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 '''"Primary Connection String"'''</div>
−
<div>3. Press '''Save & Apply''' button </div>
+
<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>
Line 131: Line 131:  
3.1 Set connection type as a '''Device Provisioning Service (DPS)''';
 
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.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.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.  
 
3.4 Upload the certificate chain file and the private key file.  
Line 152: Line 152:  
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&amp%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&amp%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.
+
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 symm example 1.png|border|class=tlt-border]]
 
[[File:Azure symm example 1.png|border|class=tlt-border]]
Line 159: Line 159:     
<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 from Microsoft.</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 that was specified in the earlier script.</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].</li>
+
<li> In the '''"Symmetric key"''' field enter the output value of the script that was used earlier].</li>
 
</ul>
 
</ul>
   Line 170: Line 170:  
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.
+
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 symm example 3.png|border|class=tlt-border]]
 
[[File:Azure symm example 3.png|border|class=tlt-border]]
Line 186: Line 186:  
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].  
 
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 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] .
   −
The Azure IoT Explorer Direct Method tab will have a Payload field. In this field the '''api_call''' method expects JSON formatted data.
+
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, 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.
+
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]]
Line 200: Line 200:  
[[File:Azure RutOSconf 21.png|border|class=tlt-border]]
 
[[File:Azure RutOSconf 21.png|border|class=tlt-border]]
   −
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]].
Line 248: Line 248:  
====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 "'''Use built-in event hub'''" option is enabled and press the "'''Start'''" button. After some time you should see that data was sent from the device to the Azure IoT Hub.
+
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 some time you should see that data was sent from the device to the Azure IoT Hub.
    
[[File:Azure RutOSconf 29.png|border|class=tlt-border]]
 
[[File:Azure RutOSconf 29.png|border|class=tlt-border]]
Line 274: Line 274:  
====Modbus TCP Server====
 
====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]
+
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====
 
====Modbus TCP Client====
Line 293: Line 293:  
1. Go to '''Services -> Data to Server''' page and create a new collection instance.
 
1. Go to '''Services -> Data to Server''' page and create a new collection instance.
   −
1.1. Select the input '''Type''' to '''Modbus''';
+
1.1. Select the input '''Type''' to '''"Modbus"''';
   −
1.2. Change the '''Format type''' to '''Custom''';
+
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.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.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.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.
+
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====
 
====Monitoring and controlling incoming data====
Line 311: Line 313:  
[[File:Azure modbus example 1 modified 1.png|border|class=tlt-border]]
 
[[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.
+
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:
+
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;
+
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]]
 
[[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;
+
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]]
 
[[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).
+
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]]
 
[[File:Azure modbus example 4.png|border|class=tlt-border]]
Line 339: Line 341:  
# https://developers.teltonika-networks.com/
 
# https://developers.teltonika-networks.com/
 
# https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer
 
# https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer
 +
# https://learn.microsoft.com/en-us/azure/iot-dps/
 
# 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
 
# 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
−
# 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
+
# 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
 +
# https://learn.microsoft.com/en-us/azure/iot-dps/tutorial-custom-hsm-enrollment-group-x509?pivots=programming-language-ansi-c#create-an-enrollment-group
 +
# https://developers.teltonika-networks.com/reference/7.6.10/v1/modbus/
 +
# https://wiki.teltonika-networks.com/view/RUTX11_Modbus#Modbus_TCP_Client
 +
# https://wiki.teltonika-networks.com/view/RUTX11_Modbus#Modbus_TCP_Server
 +
# https://learn.microsoft.com/en-us/azure/digital-twins/concepts-models
 +
# https://developers.teltonika-networks.com/fundamentals/#request-and-response-structures
Retrieved from "https://wiki.teltonika-networks.com/view/Special:MobileDiff/126969...128196"

Navigation menu