IotMqttSampleAzureIotHub

Beispiel zur MQTT Kommunikation mit Microsoft Azure IoT Hub

In diesem Beispiel wird die Kommunikation zum Microsoft Azure IoT Hub gezeigt, welcher Bestandteil der Microsoft Azure Cloud ist. Der Message Broker ist über MQTT erreichbar und benötigt zur Authentifizierung ein sogenanntes SAS-Token, welches sich über die Azure IoT Hub Plattform generieren lässt, z. B. mithilfe des sogenannten Azure IoT Explorers.

IotMqttSampleAzureIotHub 1:

Ersteinrichtung vom Azure IoT Hub

Für Informationen zur Ersteinrichtung vom Microsoft Azure IoT Hub und entsprechender Zugangsdaten für zu verbindende Geräte konsultieren Sie die offizielle Microsoft Azure IoT Hub Dokumentation. Wir empfehlen auch den Microsoft Dokumentationsartikel zur Verwendung von MQTT mit dem Azure IoT Hub.

IotMqttSampleAzureIotHub 2:

Topic-Struktur

Die Topic-Struktur beim Senden und Empfangen von Nachrichten ist fest vom Microsoft Azure IoT Hub vorgegeben.

IotMqttSampleAzureIotHub 3:

Authentifizierung

Zur Authentifizierung des MQTT Clients können Sie entweder ein SAS Token oder X509 Zertifikate verwenden.

IotMqttSampleAzureIotHub 4:

QoS und Retain

Der Azure IoT Hub unterstützt kein QoS 2 und keine Retain-Nachrichten.

In diesem Beispiel werden sowohl Nachrichten an den Azure IoT Hub versendet als auch empfangen. Da das Beispiel im Wesentlichen somit auf dem Beispiel IotMqttSampleUsingQueue basiert, werden in diesem Abschnitt nur die relevanten Teile zur Verbindungsherstellung mit dem IoT Hub erklärt.

Parameter für Verbindungsaufbau

Das folgende Code Snippet zeigt die notwendigen Parameter für einen Verbindungsaufbau mit dem Azure IoT Hub. Im Wesentlichen handelt es sich hierbei um statische Parameter. Diese können auch im Deklarationsteil bei der Instanziierung des MQTT Client angegeben werden.

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

Für die Authentifizierung des MQTT Clients am Azure IoT Hub können Sie entweder ein SAS Token oder X509 Zertifikate verwenden. Je nach Authentifizierungstyp müssen bestimmte Verbindungsparameter gesetzt werden. Die folgende Tabelle gibt einen Überblick über die zu setzenden Parameter.

 

SAS Token

X509 Zertifikat

stTLS.sCA

Pfad zum vom Azure IoT Hub verwendeten CA Zertifikat. Siehe unten.

Pfad zum vom Azure IoT Hub verwendeten CA Zertifikat. Siehe unten.

stTLS.sAzureSas

SAS Token, welches über den Azure File Explorer generiert werden kann.

---

stTLS.sCert

---

Pfad zum Client-Zertifikat.

stTLS.sKey

---

Pfad zum Private Key.

sHostname

Muss nicht explizit gesetzt werden. Der Hostname ergibt sich aus dem SAS Token.

Hostname der Azure IoT Hub Instanz.

nHostPort

Muss nicht explizit gesetzt werden. Der Port wird bei Verwendung eines SAS Token automatisch auf 8883 eingestellt.

8883

sClientId

Muss nicht explizit gesetzt werden. Die Client-ID ergibt sich aus dem SAS Token.

Entspricht dem Device-Name des erzeugten Geräts im Azure IoT Hub.

sUserName

Muss nicht explizit gesetzt werden. Der Username ergibt sich aus dem SAS Token.

Entspricht einem festgelegten Namensschema, welches sowohl den IoT Hub Namen als auch Device-Name beinhaltet. Weitere Informationen hierzu entnehmen Sie bitte der Azure IoT Hub Dokumentation.

IotMqttSampleAzureIotHub 5:

CA-Zertifikat

Bei Herstellung einer Verbindung zum Microsoft Azure IoT Hub über MQTT ist die Angabe eines CA-Zertifikats zwingend erforderlich, sowohl bei Verwendung eines SAS Token als auch bei Verwendung von X509 Zertifikaten zur Client-Authentifizierung. Bitte konsultieren Sie immer auch die Microsoft Dokumentation, um die aktuell gültige Root-CA zu erfahren.

In den meisten Fällen kann der zugehörige Public Key der jeweiligen Root-CA aus der Microsoft Windows Zertifikatskonsole extrahiert werden (Start > Ausführen > mmc.exe, dann das SnapIn „Zertifikate“ hinzufügen). Die Root-CA befindet sich dann unter der Rubrik Vertrauenswürdige Stammzertifizierungsstellen. Siehe auch unten stehenden Screenshot als Vergleich.

IotMqttSampleAzureIotHub 6:

Publish

Beim Publishen von Daten an den IoT Hub muss das Topic in folgender Form angegeben werden:

devices / deviceId / messages / events / readpipe

Die DeviceId entspricht hierbei der DeviceId des registrierten Geräts, wie z. B. im Azure IoT Explorer angegeben.

IotMqttSampleAzureIotHub 7:

Subscribe

Beim Subscribe auf Daten vom IoT Hub muss das Topic in folgender Form angegeben werden:

devices / deviceId / messages / devicebound / #

Die DeviceId entspricht hierbei der DeviceId des registrierten Geräts, wie z. B. im Azure IoT Explorer angegeben.

Voraussetzungen

Entwicklungsumgebung

Zielplattform

Einzubindende SPS-Bibliotheken

TwinCAT v3.1.4022.0

IPC oder CX (x86, x64, ARM)

Tc3_IotBase,
Tc2_Utilities (>= v3.3.19.0)