186
edits
Changes
Getting started with Azure IoT hub (view source)
Revision as of 15:40, 29 August 2023
, 15:40, 29 August 2023Created page with "====NOTE==== {| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #FFCC33; border-bottom: 1px solid #FFCC33; border-left: 1px solid #FFCC33;border-top: 1..."
====NOTE====
{| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #FFCC33; border-bottom: 1px solid #FFCC33; border-left: 1px solid #FFCC33;border-top: 1px solid #FFCC33;border-right: 1px solid #FFCC33;background: #FEF6E7; color: black; text-align: left; padding: 10px;"
| style="width: 40px;height: 20px;padding: 10px;" | [[File:Warning.png|30 px|link=]]
|| <span style="color:black;">'''MQTT protocol is only implemented in base 28 and above FW and Configurators. This guide will not work with earlier versions of FW and CONFIGURATOR.'''</span>
|}
== '''Setup your Azure account''' ==
Refer to the online Azure documentation. Follow the steps outlined in the sections below to create your IoT hub and get started:<br>
* [https://azure.microsoft.com/en-us/free/ Create a free Azure account]
* [https://portal.azure.com/ Sign in to your account]
<br>
NOTE – The examples in this document are intended only for dev environments. All devices in your production fleet must have credentials with privileges that authorize only intended actions on specific resources. The specific permission policies can vary for your use case. Identify the permission policies that best meet your business and security requirements.
<br>
== '''Create Resources in Azure IoT''' ==
Refer to the online Microsoft Azure documentation. Follow the steps outlined in these sections to provision resources for your device:
<br>
* [https://learn.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal Create an IoT hub]
* [https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer Install and use IoT explorer]
<br>
NOTE – The examples in this document are intended only for dev environments. All devices in your production fleet must have credentials with privileges that authorize only intended actions on specific resources. The specific permission policies can vary for your use case. Identify the permission policies that best meet your business and security requirements.
<br>
=== Provision the Device with credentials ===
Whole device, Azure IoT and testing information can be downloaded in PDF format [https://wiki.teltonika-gps.com here.]
== '''Azure IoT hub Creation''' ==
When logged in the Azure console, Press [[File:Azure_menu_icon.png|35x35px]] and select – '''create new resource.'''
[[File:Create_new_resource.png|934x425px]]
<div style="text-align: center;">'''Figure 1.''' Create new resource</div><br>
Select '''Internet of things''' in the Categories on the left.
[[File:Select_IoT.jpg|934x425px]]
<div style="text-align: center;">'''Figure 2.''' Accessing Things</div><br>
Press '''Create''' near the [[File:IOThub_icon.png|35x35px]] icon.
==== '''Basics tab''' ====
1. In the '''Basics''' tab choose your '''subscription'''. Create a new '''Resource group'''. Enter '''IoT hub name''' (Can be any created name). Select '''Region''' that is closest to you ('''North Europe''' for Lithuania).
2. Choose the wanted Tier, '''Free tier''' should be used for testing purpose, alternatively use standard. (You can find all the necessary information about tiers when you click '''Comapare tiers''' below option box).
3. Then choose your '''Daily message limit''' according to your needs ('''8000''' for Free plan) (You can find all the necessary information about Daily message limit when you click See all options below option box).
4. Press: '''Review + create'''
[[File:IoT_hub_creation.png|934x425px]]
<div style="text-align: center;">'''Figure 3.''' Selecting IoT</div><br>
Check if all the parameters are as you intended and click Create.
[[File:Review_+_Create.png|934x425px]]
<div style="text-align: center;">'''Figure 4.''' Review + create</div><br>
== '''Add device to IoT hub''' ==
Press [[File:Azure_menu_icon.png|35x35px]] , '''Home''' and click on your created IoT Hub.
[[File:Recent_test_hub.png|934x425px]]
<div style="text-align: center;">'''Figure 5.''' Selecting IoT hub</div><br>
Copy hostname and press devices In the left menu.
{| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #FFCC33; border-bottom: 1px solid #FFCC33; border-left: 1px solid #FFCC33;border-top: 1px solid #FFCC33;border-right: 1px solid #FFCC33;background: #FEF6E7; color: black; text-align: left; padding: 10px;"
| style="width: 40px;height: 20px;padding: 10px;" | [[File:Warning.png|30px|link=]]
|| <span style="color:black;">'''If you see a message:'''</span>
|-
|
||{{{CL_01|<ul><li>This resource uses a certificate on the Baltimore CyberTrust Root which will expire in 2025 and must be migrated to the DigiCert Global G2 root.</li></ul>}}} <br> Go to: '''Migrate to DigiCert Global G2''' at the bottom of this tutorial.
|}
[[File:Overview.png|934x425px]]
<div style="text-align: center;">'''Figure 6.''' Hostname and devices</div><br>
Select Add Device in Devices tab.
[[File:Add_device.png|934x425px]]
<div style="text-align: center;">'''Figure 7.''' Add Device</div><br>
Once you are inside '''Create a device''' tab:
1. Enter your device '''IMEI''' in the '''device ID''' field.
2. Other fields here should be left '''default'''
3. Authentication type: Symmetric key Connection this device to an Iot Hub: '''Enabled'''
4. Press '''save'''.
[[File:Create_a_device.png|934x425px]]
<div style="text-align: center;">'''Figure 8.''' Creating a device</div><br>
== '''Shared access policies''' ==
To get your '''primary''' and '''secondary''' '''keys''' go to Shared access policies, change Connect using shared access policies to Allow and click on '''iothubowner'''.
[[File:Shared_access_policies.png|934x425px]]
<div style="text-align: center;">'''Figure 9.''' Device data endpoint</div><br>
An iothubowner tab will pop out on the right (These files will be used in configuration).<br>
Copy:
1.'''Primary key'''
2.'''Secondary key'''
3.'''“iothubowner”'''
[[File:Saving_keys.png|934x425px]]
<div style="text-align: center;">Figure 10. Certificate files</div><br>
== '''Configuration''' ==
In the GPRS tab, under Server Settings select: <br>
1.Domain – '''Hostname''' (copy here the host name from your Iot Hub overview window in Azure)
2.Port: '''8883'''
3.Protocol – '''MQTT'''
4.TLS Encryption – '''TLS/DTLS''' <br>
In the GPRS tab, under MQTT Settings select: <br>
1.MQTT Client type – '''Azure IoT'''
2.Device ID: '''IMEI'''
3.Primary SAS key – '''Primary key''' from ‘iothubowner’ shared access policy
4.Secondary SAS key – '''Secondary key''' from ‘iothubowner’ shared access policy
5.SAS Policy Name – '''iothubowner'''
[[File:Configuration_azure_mqtt.png|934x425px]]
<div style="text-align: center;">'''Figure 11.''' Device configuration</div><br>
== '''Certificate creation and upload''' ==
Download '''DigiCert Global Root G2''' certificate and put it inside a new folder: [https://cacerts.digicert.com/DigiCertGlobalRootG2.crt Download DER/CRT]
===Converting certificate to .pem format===
Follow the tutorial to convert certificate [https://theitbros.com/convert-crt-to-pem/#:~:text=cert.pem%20%E2%80%93text-,How%20to%20Convert%20CRT%20SSL%20Certificate%20to%20PEM%20on%20Windows%3F,-On%20Windows%2C%20there here]
{| class="main-table" style="background: #E7F1FE; color: black;"
{| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #0054A6; border-bottom: 1px solid #0054A6; border-left: 1px solid #0054A6;border-top: 1px solid #0054A6;border-right: 1px solid #0054A6;background: #E7F1FE; color: black; text-align: left; padding: 10px;"
| style="width: 40px;height: 20px;padding: 10px;" | [[File:Note_icon.png|30 px|link=]]
|| '''Please note:''' <br> Configurator only accepts PEM FILE format. You can use any method to convert .crt file to .pem format.
|}
|}
===Upload certificate to device===
Upload the file you have created to the device using configurator > '''Security''' > '''Certificate''' > '''upload'''
== '''Data sending''' ==
Trigger a high priority event so that device would start to send data to the server.
In the device configurator screen check for the Status > GSM Info > Records Sent records count.
[[File:Sent_records_count.jpg|934x425px]]
<div style="text-align: center;">'''Figure 12.''' Sent records count</div><br>
On the Azure service > IOT hub > Overview there is a Device to cloud chart that will show the records received.
{| class="main-table" style="background: #E7F1FE; color: black;"
{| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #0054A6; border-bottom: 1px solid #0054A6; border-left: 1px solid #0054A6;border-top: 1px solid #0054A6;border-right: 1px solid #0054A6;background: #E7F1FE; color: black; text-align: left; padding: 10px;"
| style="width: 40px;height: 20px;padding: 10px;" | [[File:Note_icon.png|30 px|link=]]
|| '''Please note:''' <br> This window has noticeable delay.
|}
|}
[[File:Overview_with_records.png|934x425px]]
<div style="text-align: center;">'''Figure 13.''' IoT hub overview</div><br>
c
===Downloading and installing Azure IoT Explorer===
Data sent from device can be found in the Azure IoT Explorer<br>
Go to: [https://github.com/Azure/azure-iot-explorer/releases Azure IoT Explorer releases]
Find the latest version and download the file with '''.msi''' header:
[[File:Azure_explorer_download.png|934x425px]]
<div style="text-align: center;">'''Figure 14.''' IoT Explorer download</div><br>
After opening Azure explorer click:<br>
1. '''IoThubs '''
2. '''Add connection'''<br>
In the pop-up bar enter primary connection string which you can get from Shared access policies which was explored in section '''Shared access policies'''.<br>
Click '''save''' after completion.
[[File:Azure_explorer_new_connection.png|934x425px]]
<div style="text-align: center;">'''Figure 15.''' New connection</div><br>
Click ib the Name of your hub which will be in blue color. <br>
Select the device that you want to explore by '''clicking''' on it’s '''IMEI'''.<br>
On the following window click '''Telemetry''' and the '''Start'''.
[[File:Telemetry.png|934x425px]]
<div style="text-align: center;">'''Figure 16.''' Telemetry</div><br>
Example of data sent in JSON format:
[[File:Records_JSON_Azure_IoT_Explorer.png|934x425px]]
<div style="text-align: center;">'''Figure 17.''' Records in JSON format</div><br>
Example of data sent in Codec 8 format:
[[File:Records_Azure_IoT_Explorer.png|934x425px]]
<div style="text-align: center;">'''Figure 18.''' Records in Codec 8 format</div><br>
== '''Migrate to DigiCert Global G2''' ==
In overview window click on the red error message
[[File:Warning_Baltimore.png|934x425px]]
<div style="text-align: center;">'''Figure 19.''' Warning message</div><br>
In the following window click '''Migrate to DigiCert Global G2'''
[[File:Migrate_to_G2.png|934x425px]]
<div style="text-align: center;">'''Figure 20.''' Migrate to G2</div><br>
On the next window check all the boxes and click '''Update'''
[[File:Migration_boxes.png|934x425px]]
<div style="text-align: center;">'''Figure 21.''' Update resource certificate</div><br>
Migration may take up to a minute. You can now continue with the instructions.
{| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #FFCC33; border-bottom: 1px solid #FFCC33; border-left: 1px solid #FFCC33;border-top: 1px solid #FFCC33;border-right: 1px solid #FFCC33;background: #FEF6E7; color: black; text-align: left; padding: 10px;"
| style="width: 40px;height: 20px;padding: 10px;" | [[File:Warning.png|30 px|link=]]
|| <span style="color:black;">'''MQTT protocol is only implemented in base 28 and above FW and Configurators. This guide will not work with earlier versions of FW and CONFIGURATOR.'''</span>
|}
== '''Setup your Azure account''' ==
Refer to the online Azure documentation. Follow the steps outlined in the sections below to create your IoT hub and get started:<br>
* [https://azure.microsoft.com/en-us/free/ Create a free Azure account]
* [https://portal.azure.com/ Sign in to your account]
<br>
NOTE – The examples in this document are intended only for dev environments. All devices in your production fleet must have credentials with privileges that authorize only intended actions on specific resources. The specific permission policies can vary for your use case. Identify the permission policies that best meet your business and security requirements.
<br>
== '''Create Resources in Azure IoT''' ==
Refer to the online Microsoft Azure documentation. Follow the steps outlined in these sections to provision resources for your device:
<br>
* [https://learn.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal Create an IoT hub]
* [https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer Install and use IoT explorer]
<br>
NOTE – The examples in this document are intended only for dev environments. All devices in your production fleet must have credentials with privileges that authorize only intended actions on specific resources. The specific permission policies can vary for your use case. Identify the permission policies that best meet your business and security requirements.
<br>
=== Provision the Device with credentials ===
Whole device, Azure IoT and testing information can be downloaded in PDF format [https://wiki.teltonika-gps.com here.]
== '''Azure IoT hub Creation''' ==
When logged in the Azure console, Press [[File:Azure_menu_icon.png|35x35px]] and select – '''create new resource.'''
[[File:Create_new_resource.png|934x425px]]
<div style="text-align: center;">'''Figure 1.''' Create new resource</div><br>
Select '''Internet of things''' in the Categories on the left.
[[File:Select_IoT.jpg|934x425px]]
<div style="text-align: center;">'''Figure 2.''' Accessing Things</div><br>
Press '''Create''' near the [[File:IOThub_icon.png|35x35px]] icon.
==== '''Basics tab''' ====
1. In the '''Basics''' tab choose your '''subscription'''. Create a new '''Resource group'''. Enter '''IoT hub name''' (Can be any created name). Select '''Region''' that is closest to you ('''North Europe''' for Lithuania).
2. Choose the wanted Tier, '''Free tier''' should be used for testing purpose, alternatively use standard. (You can find all the necessary information about tiers when you click '''Comapare tiers''' below option box).
3. Then choose your '''Daily message limit''' according to your needs ('''8000''' for Free plan) (You can find all the necessary information about Daily message limit when you click See all options below option box).
4. Press: '''Review + create'''
[[File:IoT_hub_creation.png|934x425px]]
<div style="text-align: center;">'''Figure 3.''' Selecting IoT</div><br>
Check if all the parameters are as you intended and click Create.
[[File:Review_+_Create.png|934x425px]]
<div style="text-align: center;">'''Figure 4.''' Review + create</div><br>
== '''Add device to IoT hub''' ==
Press [[File:Azure_menu_icon.png|35x35px]] , '''Home''' and click on your created IoT Hub.
[[File:Recent_test_hub.png|934x425px]]
<div style="text-align: center;">'''Figure 5.''' Selecting IoT hub</div><br>
Copy hostname and press devices In the left menu.
{| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #FFCC33; border-bottom: 1px solid #FFCC33; border-left: 1px solid #FFCC33;border-top: 1px solid #FFCC33;border-right: 1px solid #FFCC33;background: #FEF6E7; color: black; text-align: left; padding: 10px;"
| style="width: 40px;height: 20px;padding: 10px;" | [[File:Warning.png|30px|link=]]
|| <span style="color:black;">'''If you see a message:'''</span>
|-
|
||{{{CL_01|<ul><li>This resource uses a certificate on the Baltimore CyberTrust Root which will expire in 2025 and must be migrated to the DigiCert Global G2 root.</li></ul>}}} <br> Go to: '''Migrate to DigiCert Global G2''' at the bottom of this tutorial.
|}
[[File:Overview.png|934x425px]]
<div style="text-align: center;">'''Figure 6.''' Hostname and devices</div><br>
Select Add Device in Devices tab.
[[File:Add_device.png|934x425px]]
<div style="text-align: center;">'''Figure 7.''' Add Device</div><br>
Once you are inside '''Create a device''' tab:
1. Enter your device '''IMEI''' in the '''device ID''' field.
2. Other fields here should be left '''default'''
3. Authentication type: Symmetric key Connection this device to an Iot Hub: '''Enabled'''
4. Press '''save'''.
[[File:Create_a_device.png|934x425px]]
<div style="text-align: center;">'''Figure 8.''' Creating a device</div><br>
== '''Shared access policies''' ==
To get your '''primary''' and '''secondary''' '''keys''' go to Shared access policies, change Connect using shared access policies to Allow and click on '''iothubowner'''.
[[File:Shared_access_policies.png|934x425px]]
<div style="text-align: center;">'''Figure 9.''' Device data endpoint</div><br>
An iothubowner tab will pop out on the right (These files will be used in configuration).<br>
Copy:
1.'''Primary key'''
2.'''Secondary key'''
3.'''“iothubowner”'''
[[File:Saving_keys.png|934x425px]]
<div style="text-align: center;">Figure 10. Certificate files</div><br>
== '''Configuration''' ==
In the GPRS tab, under Server Settings select: <br>
1.Domain – '''Hostname''' (copy here the host name from your Iot Hub overview window in Azure)
2.Port: '''8883'''
3.Protocol – '''MQTT'''
4.TLS Encryption – '''TLS/DTLS''' <br>
In the GPRS tab, under MQTT Settings select: <br>
1.MQTT Client type – '''Azure IoT'''
2.Device ID: '''IMEI'''
3.Primary SAS key – '''Primary key''' from ‘iothubowner’ shared access policy
4.Secondary SAS key – '''Secondary key''' from ‘iothubowner’ shared access policy
5.SAS Policy Name – '''iothubowner'''
[[File:Configuration_azure_mqtt.png|934x425px]]
<div style="text-align: center;">'''Figure 11.''' Device configuration</div><br>
== '''Certificate creation and upload''' ==
Download '''DigiCert Global Root G2''' certificate and put it inside a new folder: [https://cacerts.digicert.com/DigiCertGlobalRootG2.crt Download DER/CRT]
===Converting certificate to .pem format===
Follow the tutorial to convert certificate [https://theitbros.com/convert-crt-to-pem/#:~:text=cert.pem%20%E2%80%93text-,How%20to%20Convert%20CRT%20SSL%20Certificate%20to%20PEM%20on%20Windows%3F,-On%20Windows%2C%20there here]
{| class="main-table" style="background: #E7F1FE; color: black;"
{| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #0054A6; border-bottom: 1px solid #0054A6; border-left: 1px solid #0054A6;border-top: 1px solid #0054A6;border-right: 1px solid #0054A6;background: #E7F1FE; color: black; text-align: left; padding: 10px;"
| style="width: 40px;height: 20px;padding: 10px;" | [[File:Note_icon.png|30 px|link=]]
|| '''Please note:''' <br> Configurator only accepts PEM FILE format. You can use any method to convert .crt file to .pem format.
|}
|}
===Upload certificate to device===
Upload the file you have created to the device using configurator > '''Security''' > '''Certificate''' > '''upload'''
== '''Data sending''' ==
Trigger a high priority event so that device would start to send data to the server.
In the device configurator screen check for the Status > GSM Info > Records Sent records count.
[[File:Sent_records_count.jpg|934x425px]]
<div style="text-align: center;">'''Figure 12.''' Sent records count</div><br>
On the Azure service > IOT hub > Overview there is a Device to cloud chart that will show the records received.
{| class="main-table" style="background: #E7F1FE; color: black;"
{| style="width: 800px;height: 60px; text-align: left; border: 1 px solid #0054A6; border-bottom: 1px solid #0054A6; border-left: 1px solid #0054A6;border-top: 1px solid #0054A6;border-right: 1px solid #0054A6;background: #E7F1FE; color: black; text-align: left; padding: 10px;"
| style="width: 40px;height: 20px;padding: 10px;" | [[File:Note_icon.png|30 px|link=]]
|| '''Please note:''' <br> This window has noticeable delay.
|}
|}
[[File:Overview_with_records.png|934x425px]]
<div style="text-align: center;">'''Figure 13.''' IoT hub overview</div><br>
c
===Downloading and installing Azure IoT Explorer===
Data sent from device can be found in the Azure IoT Explorer<br>
Go to: [https://github.com/Azure/azure-iot-explorer/releases Azure IoT Explorer releases]
Find the latest version and download the file with '''.msi''' header:
[[File:Azure_explorer_download.png|934x425px]]
<div style="text-align: center;">'''Figure 14.''' IoT Explorer download</div><br>
After opening Azure explorer click:<br>
1. '''IoThubs '''
2. '''Add connection'''<br>
In the pop-up bar enter primary connection string which you can get from Shared access policies which was explored in section '''Shared access policies'''.<br>
Click '''save''' after completion.
[[File:Azure_explorer_new_connection.png|934x425px]]
<div style="text-align: center;">'''Figure 15.''' New connection</div><br>
Click ib the Name of your hub which will be in blue color. <br>
Select the device that you want to explore by '''clicking''' on it’s '''IMEI'''.<br>
On the following window click '''Telemetry''' and the '''Start'''.
[[File:Telemetry.png|934x425px]]
<div style="text-align: center;">'''Figure 16.''' Telemetry</div><br>
Example of data sent in JSON format:
[[File:Records_JSON_Azure_IoT_Explorer.png|934x425px]]
<div style="text-align: center;">'''Figure 17.''' Records in JSON format</div><br>
Example of data sent in Codec 8 format:
[[File:Records_Azure_IoT_Explorer.png|934x425px]]
<div style="text-align: center;">'''Figure 18.''' Records in Codec 8 format</div><br>
== '''Migrate to DigiCert Global G2''' ==
In overview window click on the red error message
[[File:Warning_Baltimore.png|934x425px]]
<div style="text-align: center;">'''Figure 19.''' Warning message</div><br>
In the following window click '''Migrate to DigiCert Global G2'''
[[File:Migrate_to_G2.png|934x425px]]
<div style="text-align: center;">'''Figure 20.''' Migrate to G2</div><br>
On the next window check all the boxes and click '''Update'''
[[File:Migration_boxes.png|934x425px]]
<div style="text-align: center;">'''Figure 21.''' Update resource certificate</div><br>
Migration may take up to a minute. You can now continue with the instructions.
