IotMqttSampleAzureIotHub

Sample of MQTT communication with the Microsoft Azure IoT Hub

This sample shows communication with the Microsoft Azure IoT Hub, which is part of the Microsoft Azure cloud. The message broker can be reached via MQTT and requires authentication via an SAS token, which can be generated via the Azure IoT Hub platform, e.g. using the Azure IoT Explorer.

Initial setup of Azure IoT Hub For information on the initial setup of the Microsoft Azure IoT Hub and corresponding access data for devices to be connected, see the official Microsoft Azure IoT Hub documentation. We also recommend the Microsoft documentation article on using MQTT with the Azure IoT Hub.

Topic structure The topic structure for sending and receiving messages is predefined by the Microsoft Azure IoT Hub.

Authentication You can use either a SAS token or X509 certificates to authenticate the MQTT client.

QoS and Retain The Azure IoT Hub does not support QoS 2 and Retain messages.

In this sample, messages are sent to the Azure IoT Hub and received from it. Since this sample is essentially based on the IotMqttSampleUsingQueue sample, only the parts that are relevant for establishing a connection to the IoT Hub are explained in this section.

Parameters for establishing a connection

The following code snippet shows the parameters required for establishing a connection to the Azure IoT Hub. The parameters are essentially static parameters. These can also be specified in the declaration part during instantiation of the MQTT client.

IF bSetParameter THEN
  bSetParameter := FALSE;
  
  (* Option 1: authentication via Device SAS Token *)
  fbMqttClient.stTLS.sCA := 'c:\TwinCAT\3.1\Config\Certificates\DigiCertGlobalRootG2.cer'; // CA certificate
  fbMqttClient.stTLS.sAzureSas := 'PlaceDeviceSasTokenHere'; // Device SAS Token
  
  (* Option 2: authentication via X509 certificate *)
  //fbMqttClient.stTLS.sCA := 'c:\TwinCAT\3.1\Config\Certificates\DigiCertGlobalRootG2.cer'; // CA certificate
  //fbMqttClient.stTLS.sCert := 'c:\TwinCAT\3.1\Config\Certificates\MyDeviceCert.pem';
  //fbMqttClient.stTLS.sKeyFile := 'c:\TwinCAT\3.1\Config\Certificates\MyDeviceCert.key';
  //fbMqttClient.sHostName:= myIotHub.azure-devices.net';
  //fbMqttClient.nHostPort:= 8883;
  //fbMqttClient.sClientId := 'MyDevice';
  //fbMqttClient.sUserName := 'myIotHub.azure-devices.net/MyDevice/?api-version=2021-04-12';
   fbMqttClient.ipMessageQueue := fbMessageQueue;
END_IF

You can use either a SAS token or X509 certificates to authenticate the MQTT client on the Azure IoT hub. Depending on the authentication type, certain connection parameters must be set. The following table provides an overview of the parameters to be set.

CA certificate When establishing a connection to the Microsoft Azure IoT Hub via MQTT, the specification of a CA certificate is mandatory, both when using a SAS token and when using X509 certificates for client authentication. Please always consult the Microsoft documentation to find out the currently valid root CA. In most cases, the associated public key of the respective root CA can be extracted from the Microsoft Windows Certificate Console (Start > Run > mmc.exe, then add the SnapIn "Certificates"). The root CA can then be found under the heading Trusted Root Certification Authorities. See also screenshot below for comparison.

Publish

When data are published to the IoT Hub, the topic must be specified in the following form:

devices / deviceId / messages / events / readpipe

The DeviceId corresponds to the DeviceId of the registered device, as specified in the Azure IoT Explorer, for example.

Subscribe

When subscribing to data from the IoT Hub, the topic must be specified in the following form:

devices / deviceId / messages / devicebound / #

The DeviceId corresponds to the DeviceId of the registered device, as specified in the Azure IoT Explorer, for example.