Cloud Sink with Azure IoT Hub

In this Jumpstart we will create a new Azure IoT Hub, which supports MQTT communications, and configure it. Next we are going to use system:inmation Cloud Sink as a publisher to send a message to Azure IoT Hub using the MQTT protocol.

Prerequisites

To complete the examples in this Jumpstart the following things are required:

  • Azure account

  • Visual Studio CODE (for SAS Token Authentication)

  • OpenSSL (for X.509 CA Authentication)

  • system:inmation with Data Studio

Preparing Azure infrastructure

  1. Login to Azure Portal and click on the   Create a resource   button

  2. Add a new IoT Hub

    IoT Hub
    Figure 1. Adding a new IoT Hub
  3. Make sure you have the following parameters set using the suggested values or use the below screenshot as a guide:

    On the Basics tab enter the following parameters.

    On the Size and Scale tab enter the following parameters.

    • Pricing and scale tier - Any desired option. For this example we will use the Free tier option.

      Free tier allows to send up to 8000 messages, which is sufficient for testing purposes
    Basics
    Figure 2. Basic configurational tab
    Scale and size
    Figure 3. Scale and Size configurational tab
  4. When finished, select the   Review + create   tab and then click   Create   and wait until the resource is deployed

Creating a device with SAS Token Authentication

  1. When IoT Hub is up and running, select it (you can find it in   All Resources  )

  2. Find the connection string to configure under the iothubowner Policy. Make a note of it for later, we will need this connection string to generate the SAS Token.

    Connection string
    Figure 4. Obtaining Connection String for IoT Hub
  3. Open Visual Studio CODE and go to Extensions tab to install the Azure IoT Tools extension

    Azure IoT Tools
    Figure 5. Azure IoT Tools: a Visual Studio CODE extension
  4. To connect Visual Studio Code to the IoT Hub, open the Explorer tab in Visual Studio CODE and open AZURE IOT HUB. You should see something like this:

    Set Connection string
    Figure 6. Setting Connection String to access IoT Hub through Visual Studio CODE extension

    Click on → Set IoT Hub Connection String and insert the string obtained in the Device with SAS Token Authentication step into the popup input box.

  5. Now go back to the Azure Portal and select the IoT Hub resource

  6. Click on IoT Devices to create a new device

    New device
    Figure 7. Creating a new IoT Device
  7. Enter a Device ID name and keep a note of it, we will need when configuring the the Cloud Sink object later. Set Authentication type to Symmetric key and leave everything else as it is. Click   Create   button.

    Create a device
    Figure 8. Configuring IoT Device
  8. Return to Visual Studio CODE. Refresh the Device section and your newly created device should appear in the list.

    Right-click on it and select Generate SAS Token for Device Option

    Generate SAS Token
    Figure 9. Generating SAS Token with Visual Studio CODE extension

    Insert an expiration date in the input box, for example 24 hours.

  9. Now we need to create a certificate for DigiCert Baltimore Root certificate. This file should have .cer extension

    You can create this file by copying the certificate information from certs.c in the Azure IoT SDK for C. Include the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, remove the " marks at the beginning and end of every line, and remove the \r\n characters at the end of every line.

Cloud Sink configuration

  1. In DataStudio create a new Cloud Sink object by selecting a Connector and right-clicking. Select Admin  New  History  Cloud Sink from the context menu. Give the object a name a click Create to create it in the I/O Model.

  2. Select the Cloud Sink object and in the Object Properties panel, open the Configuration MQTT Publisher Interface.

  3. Under MQTT Publisher parameters enter for the Topic property, the following path but inserting the IoT Device ID from earlier ''devices/DeviceID/messages/events/''

  4. Under Connection Parameters, enter the following values for the parameters:

  5. Under the Credentials and SSL parameters property groups, configure the parameters as instructed below:

  6. To check that the interface is working, double-click on Cloud Sink object’s Faceplate and enter a string in the Write Value dialog.

    Writing to Cloud Sink
    Figure 12. Writing some value to Cloud Sink Item Value
  7. Now check the Azure IoT Hub metric to see that the message has been sent

    Metric Result
    Figure 13. Azure IoT Hub metric with the number of incoming messages
    A single device cannot be connected multiple times to Azure IoT Hub. If you want to create a write → read chain, you need to have 2 separate devices with 2 different SAS Tokens

Creating a device with X.509 CA Certificate Authentication

This part of the tutorial based on the following resources:

This tutorial is applicable for testing purposes only. Do not use self generated certificates in production.
  1. Install OpenSSL (https://www.openssl.org/)

  2. Download all files form this link

  3. Open PowerShell terminal with administrative privileges

    1. Change directory to the path with scripts from Device with X.509 CA Certificate Authentication

      cd "C:\\CACertificates"
    2. Create an environment variable with path to openssl.cnf configurational file

      $ENV:OPENSSL_CONF = "C:\Program Files\OpenSSL-Win64\bin\cnf\openssl.cnf"
    3. Set execution policy to unrestricted

      Set-ExecutionPolicy-ExecutionPolicy Unrestricted

      Reply Yes or Yes to All in case of a prompting

    4. Bring functions from main script to the current scope

      . .\ca-certs.ps1
    5. Check preconditions.

      If you have already done certificate generation: 1) Win+R and open certlm.msc 2) delete all certificates issued by "Azure IoT CA TestOnly Root CA" in Personal, Trusted Root and Intermediate certification storages
      Test-CACertsPrerequisites
    6. Create a new certificate chain. Note that RSA algorithm should be used.

      New-CACertsCertChain rsa

      As an output you should obtain a new file RootCA.cer

      Do not close the terminal. We will return to it later

  4. Now go back to Azure Portal. Select your IoT Hub resource

  5. Upload generated RootCA.cer to Azure

    Upload Root certificate
    Figure 14. Uploading Root Certificate to Azure
  6. Click on the newly added certificate, next click Generate Verification Code (see Figure 15: Button 1) and copy generated data Verification Code (see Figure 15: Button 2)

    Verification
    Figure 15. Generating verification code and uploading verification file
  7. Run the following in the PowerShell (in the same terminal from Device with X.509 CA Certificate Authentication)

    New-CACertsVerificationCert $VERIFICATION_CODE #Verification code from Azure

    As an output you should obtain a new file VerifyCert4.cer

    Do not close the terminal. We will return to it later

  8. Next upload the generated VerifyCert4.cer file (see Figure 15: Button 3) and click   Verify   button

    Verified
    Figure 16. Root Certificate has been successfully verified
  9. Create a new device with X.509 CA Signed authentication mode. This step is similar to Device with SAS Token Authentication. But in this case X.509 CA Signed verification algorithm should be selected. Remember DEVICE_ID , we will need it later

  10. Run the following in the PowerShell (in the same terminal from Device with X.509 CA Certificate Authentication: Step 7)

    New-CACertsDevice $DEVICE_ID #Device Id you specified in <<step-3-9,Device with X.509 CA Certificate Authentication>>

    As an output you should obtain a new file <DEVICE_ID>.pfx

  11. Open command prompt with administrative privileges. Make sure path to openssl.exe is in PATH environment variable

    1. Run the following command to obtain CLIENT_CERTIFICATE.crt and CLIENT_CERTIFICATION_KEY.key

      openssl pkcs12 -in <DEVICE_ID>.pfx -nocerts -out CLIENT_CERTIFICATION_KEY_ENCRIPTED.key
    2. Run the following command to obtain CLIENT_CERTIFICATE.crt

      openssl pkcs12 -in <DEVICE_ID>.pfx -clcerts -nokeys -out CLIENT_CERTIFICATE.crt
    3. Run the following command to obtain CLIENT_CERTIFICATION_KEY.key

      openssl rsa -in CLIENT_CERTIFICATION_KEY_ENCRIPTED.key -outform PEM -out CLIENT_CERTIFICATION_KEY.key
  12. We will also need DigiCert Baltimore Root certificate, the same that used for SAS Token Authenticated devices. Device with SAS Token Authentication will explain how to get it. Also remember the Device ID, we will need that for Cloud Sink configuration.

  13. In Data Studio create a new Cloud Sink. It’s available under the Connector object. Select MQTT Publisher Interface.

    Configure MQTT Publisher parameters:

    Cloud Sink Topic configuration
    Figure 17. Cloud Sink MQTT configuration

    Configure Credentials and SSL parameters:

    • Username - Broker Address + / + Client ID + /?api-version=2018-06-30

    For x.509 Authentication algorithm password field stays clear
    Cloud Sink Credentials and SSL parameters
    Figure 18. Cloud Sink Credentials and SSL configuration
    1. Write any desired string to Cloud Sink Item Value

      Writing to Cloud Sink
      Figure 19. Writing some value to Cloud Sink Item Value
    2. Check the Azure IoT Hub metric

      Metric Result
      Figure 20. Azure IoT Hub metric with the number of incoming messages