Azure IoT Hub Connection

This section will lead you step by step to create a cellular connection to the Azure IoT Hub with the Pico LTE board and MQTT protocol

The Pico LTE device provides all the components needed to connect with Azure IoT Hub.

Before starting this Pico LTE tutorial, the Pico LTE SDK installation and configuration steps must be completed. Below are the system requirements for this tutorial. If you haven't followed the SDK installation steps, please refer to the page below before proceeding with the tutorial. The details of these steps will not be covered in this tutorial.

System Requirements

Hardware Requirements Software Requirements
• Sixfab Pico LTE
• Micro USB cable
• Thonny IDE

If you have completed all the requirements, you are ready to use Azure IoT Hub with Pico LTE. Let's get started!

Preparing Coding Environment

  1. Download the Pico LTE SDK repository to your local machine. If you have already downloaded it, skip this step.
  2. Open script "examples → azure → mqtt_publish.py or mqtt_subscribe.py" from the repository via Thonny IDE.
  3. If you haven't, create a config.json file in the root directory of Pico LTE device.

Publishing Data to Azure IoT Hub using MQTT

Register and Activate Azure IoT Hub

1. Register or login to your Azure account. You may want to follow this tutorial on Microsoft Azure's documentation.

2. Type IoT Hub onto the search bar, and choose the service which has the same name with what we wrote. Click Create IoT Hub button.





3. If the resource group is not created, click "Create new" to create it, then select a resource group to connect your Azure IoT Hub, and give a name to your hub. "IoT hub name" will be used in the config.json file. Therefore, note it somewhere. Please note that you may want to see other details such as Pricing in the Managment tab before pressing the Review + create button.



4. Review the information and if everything seems OK, press Create. Azure is going to deploy your service. Press Go to resource.



5. Creating Certificates

  • Create a new empty directory. It will be called as "certGenDirectory" in this tutorial.

  • Download certification files for Linux and MacOS or Windows. Unzip the file. You should be downloaded 3 files named “certGen.sh”, “openssl_device_intermediate_ca.cnf” and “openssl_root_ca.cnf” in the unzipped file.

  • Open “certGen.sh” file with a proper text editor or an IDE. Change the value of “cert_password” variable in 11th line. Be careful about string format and type new password between the double-quotes. Also do not add any empty spaces to the line. For example: cert_password="12345678”. This step is not a must but it is recommended.

  • Move the files to certGenDirectory.

  • To continue you need OpenSSL and a terminal for unix commands.

    • In windows, the easiest way is installing Git. So, you download both in that way. Download and install Git to your computer from here. During the installation process, you can use the default settings.
    • In Linux or MacOS, there is a proper terminal as default. You can also install OpenSSL via Git. Install Git for Linux from here and MacOS for here.

  • Run the terminal in certGenDirectory.

    • In windows, open certGenDirectory and run Git Bash from rigth click menu.



    • In Linux, rigth click the folder and run terminal from the menu. In MacOS, apply same and click “New Terminal at Folder” from the right click menu.



    • You can also perform this step using Linux commands, with the help of this beginner tutorial: Command Line for Beginners.

  • Run the command for file permissions:

  •                
    sudo chmod 700 certGen.sh 
                    

    If needed, input your administrator password after execution the command.

  • Run this command to create the certificate chain:

  • 
    sudo ./certGen.sh create_root_and_intermediate
                    
  • Go to your IoT Hub. Type “Certificates” in the left menu and click “Certificates”.



  • Click “Add”.



  • In the side menu, you can add certificate. Input a certificate name. Then select certificate file in your certificate directory. The path is certGenDirectory/certs/azure-iot-test-only.root.ca.cert.pem. Lastly, press the button “Set certificate status to verified on upload” and click “Save”.



  • Type “Devices” in the left menu and click “Devices”.



  • Click “Add Device”.



  • Give an ID to your device and note it. It will be used in the next step and also in the config.json file. Select “X.509 CA Signed” in the “Authentication type” section and press “Save”.



  • Go back to Git Bash and run this command to add a new device to certificate. Input your Device ID determined in the previous step.

  • 
    sudo ./certGen.sh create_device_certificate [DEVICE_ID]
                    

6. Download this certificate and save it to somewhere with cacert.pem file name. This certificate file is the root certificate for Azure IoT Hub services.

Upload the Certificates to Your Pico LTE

1. Create a folder named cert.

Note

Please note that it should be somewhere else then the directory created by certGen script in previous section's Step 5.

2. Rename the certificates you have with the names below, as indicated next to them, and copy them to the cert folder.

  • "certGenDirectory/certs/new-device.cert.pem" → client.pem
  • "certGenDirectory/private/new-device.key.pem" → user_key.pem

3. Copy the cacert.pem file that is created in previous section's Step 6 into the cert directory you've created.

4. Upload this cert directory to your root directory of Pico LTE device.






Test the Code Example

Copy the following code block into the config.json file and enter your credentials.

{
    "azure":{
        "hub_name": "YOUR_AZURE_IOT_HUB_NAME",
        "device_id": "YOUR_DEVICE_ID",
    }
}

Run the "mqtt_publish.py" script that you opened in Thonny IDE.



The output you get in the code should look like this:

>>> %Run -c $EDITOR_CONTENT INFO: Publishing data to Azure IoT Hub... INFO: Certificates uploaded secure storage. Deleting from file system... INFO: Certificates found in modem. INFO: Result {'status': 0, 'response': ['OK'], 'interval': 0}

Now, go to your Internet browser and open the Azure IoT Hub dashboard. Select Devices from the sidebar, and choose the device we created for our Pico LTE. You may see a button called Device Twin, press it.



This panel is a JSON-looking descriptive document to see your configurations and data about your device. The data published from the device is always saved under the reported property. If you cannot see your message in this Device twin, click to Refresh button and check it again.



Subscribing (Cloud-to-Device) Azure IoT Hub using MQTT

Register and Activate Azure IoT Hub

1. Register or login to your Azure account. You may want to follow this tutorial on Microsoft Azure's documentation.

2. Type IoT Hub onto the search bar, and choose the service which has the same name with what we wrote. Click Create IoT Hub button.



3. If the resource group is not created, click "Create new" to create it, then select a resource group to connect your Azure IoT Hub, and give a name to your hub. "IoT hub name" will be used in the config.json file. Therefore, note it somewhere. Please note that you may want to see other details such as Pricing in the Managment tab before pressing the Review + create button.



4. Review the information and if everything seems OK, press Create. Azure is going to deploy your service. Press Go to resource.



5. Creating Certificates

  • Create a new empty directory. It will be called as "certGenDirectory" in this tutorial.

  • Download certification files for Linux and MacOS or Windows. Unzip the file. You should be downloaded 3 files named “certGen.sh”, “openssl_device_intermediate_ca.cnf” and “openssl_root_ca.cnf” in the unzipped file.

  • Open “certGen.sh” file with a proper text editor or an ide. Change the value of “cert_password” variable in 11th line. Be careful about string format and type new password between the double-quotes. Also do not add any empty spaces to the line. For example: cert_password="12345678”. This step is not a must but it is recommended.

  • Move the files to certGenDirectory.

  • To continue you need OpenSSL and a terminal for unix commands.

    • In windows, the easiest way is installing Git. So, you download both in that way. Download and install Git to your computer from here. During the installation process, you can use the default settings.
    • In Linux or MacOS, there is a proper terminal as default. You can also install OpenSSL via Git. Install Git for Linux from here and MacOS for here.

  • Run the terminal in certGenDirectory.

    • In windows, open certGenDirectory and run Git Bash from rigth click menu.



    • In Linux, rigth click the folder and run terminal from the menu. In MacOS, apply same and click “New Terminal at Folder” from the right click menu.



    • You can also perform this step using Linux commands, with the help of this beginner tutorial: Command Line for Beginners.

  • Run the command for file permissions:

  •                
    sudo chmod 700 certGen.sh 
                    

    If needed, input your administrator password after execution the command.

  • Run this command to create the certificate chain:

  • 
    sudo ./certGen.sh create_root_and_intermediate
                    
  • Go to your IoT Hub. Type “Certificates” in the left menu and click “Certificates”.



  • Click “Add”.



  • In the side menu, you can add certificate. Input a certificate name. Then select certificate file in your certificate directory. The path is certGenDirectory/certs/azure-iot-test-only.root.ca.cert.pem. Lastly, press the button “Set certificate status to verified on upload” and click “Save”.



  • Type “Devices” in the left menu and click “Devices”.



  • Click “Add Device”.



  • Give an id to your device. Select “X.509 CA Signed” in the “Authentication type” section and press “Save”.



  • Give an ID to your device and note it. It will be used in the next step and also in the config.json file. Select “X.509 CA Signed” in the “Authentication type” section and press “Save”.

  • 
    sudo ./certGen.sh create_device_certificate [DEVICE_ID]
                    

6. Download this certificate and save it to somewhere with cacert.pem file name. This certificate file is the root certificate for Azure IoT Hub services.

Upload the Certificates to Your Pico LTE

1. Create a folder named cert.

Note

Please note that it should be somewhere else then the directory created by certGen script in previous section's Step 5.

2. Rename the certificates you have with the names below, as indicated next to them, and copy them to the cert folder.

  • "certGenDirectory/certs/new-device.cert.pem" → client.pem
  • "certGenDirectory/private/new-device.key.pem" → user_key.pem

3. Copy the cacert.pem file that is created in previous section's Step 6 into the cert directory you've created.

4. Upload this cert directory to your root directory of Pico LTE device.






Test the Code Example

Copy the following code block into the config.json file and enter your credentials.

{
    "azure":{
        "hub_name": "YOUR_AZURE_IOT_HUB_NAME",
        "device_id": "YOUR_DEVICE_ID",
        "mqtts": {
            "sub_topics": [
            ["[SUB_TOPIC/1]", [QOS]],
            ["[SUB_TOPIC/2]", [QOS]],
            ],
        }
    }
}

Note

The key "mqtts":{"sub_topics"} should be in this format: "sub_topics": [ [ "devices/[DEVICE_ID] /messages/devicebound/#” , 1] ]

Before running the code, you should go to your IoT Hub dashboard. Select Devices from the sidebar, and choose the device we created for our Pico LTE. Then, click the Message to Device button to open the form to send a message from cloud-to-device.



Run the "mqtt_subscribe.py" script that you opened in Thonny IDE, and return to look to Message to Device panel, send a message and look to the console output.



The output you get in the code should look like this:

>>> %Run -c $EDITOR_CONTENT INFO: Subscribing to topics... INFO: {'status': 0, 'response': ['+QMTSUB: 0,1,0,1'], 'interval': 0} INFO: Reading messages from subscribed topics... INFO: [] INFO: [] INFO: INFO: ['4,"devices/first_device/messages/devicebound/%24.to=%2Fdevices%2Ffirst_device%2Fmessages%2FdeviceBound&%24.ct=text%2Fplain%3B%20charset%3DUTF-8&%24.ce=utf-8","Hello Pico"']