IotMqttSampleAzureIotHub

Sample for MQTT communication with the Microsoft Azure IoT Hub

This sample illustrates the 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.

SAS token The use of an SAS token is a basic requirement for connecting to the Azure IoT Hub via MQTT. This token can be generated with the Azure IoT Explorer, for example.

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 sample IotMqttSampleUsingQueue, 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;
  // fbMqttClient.stTLS.sCA := 'c:\TwinCAT\3.1\Config\Certificates\azure.crt';
  fbMqttClient.stTLS.sAzureSas := 'HostName=xxx.azure-devices.net;DeviceId=xxx;SharedAccessSignature=SharedAccessSignature sr=xxx.azure-devices.net%2fdevices%2fXXX&sig=121b5gJZxujK5pV%2bsFIFc2nddtpuhRuY7Tjfn8kJbtA%3d&se=1490275463';
END_IF

The structure element fbMqttClient.stTLS.sAzureSas enables transfer of the SAS token, which can be generated with the Azure IoT Explorer. The use of the structure element fbMqttClient.stTLS.sCA is optional. By default the driver uses the path specified above in the background. A root CA that is accepted by the Azure IoT Hub should be stored under this path. The topics for publish and subscribe are specified by the Azure IoT Hub and cannot be changed.

CA certificate When establishing a connection to the Microsoft Azure IoT Hub via MQTT, the specification of a CA certificate is mandatory. The Baltimore Cyber Trust Root CA can be used as CA certificate. The corresponding public key can be extracted from the Microsoft Windows certificate console (Start > Run > mmc.exe, then add the SnapIn certificate). The Baltimore CA can then be found under the heading Trusted Root Certification Authorities.

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

For 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.