Geräteimplementierungen und bewährte Methoden für IoT Central

  • Artikel

Dieser Artikel enthält Informationen zum Implementieren von Geräten, die eine Verbindung mit Ihrer IoT Central-Anwendung herstellen. Außerdem sind einige bewährte Methoden enthalten. Weitere Informationen zum gesamten Verbindungsprozess finden Sie unter Verbinden eines Geräts.

Beispielcode für die Geräteimplementierung finden Sie unter Tutorial: Erstellen einer Clientanwendung und Verbinden dieser Anwendung mit Ihrer Azure IoT Central-Anwendung.

Implementieren des Geräts

Geräte, die eine Verbindung mit IoT Central herstellen, sollten die IoT Plug & Play-Konventionen befolgen. Eine dieser Konventionen ist, dass ein Gerät die Modell-ID des Gerätemodells senden soll, das beim Herstellen der Verbindung implementiert wird. Die Modell-ID ermöglicht es der IoT Central-Anwendung, das Gerät der richtigen Gerätevorlage zuzuweisen.

Eine IoT Central-Gerätevorlage enthält ein Modell, mit dem die Verhaltensweisen angegeben werden, die von einem Gerät des entsprechenden Typs implementiert werden sollen. Diese Verhaltensweisen betreffen die Bereiche Telemetrie, Eigenschaften und Befehle.

Jedes Modell verfügt über einen eindeutigen digitalen Zwilling-Modellbezeichner (Device Twin Model Identifier, DTMI), z. B. dtmi:com:example:Thermostat;1. Wenn ein Gerät eine Verbindung mit IoT Central herstellt, sendet es den Gerätezwilling-Modellbezeichner des implementierten Modells. IoT Central kann dem Gerät dann die richtige Gerätevorlage zuweisen.

Bei IoT Plug & Play wird eine Reihe von Konventionen definiert, die von einem Gerät eingehalten werden müssen, wenn es ein Digital Twin Definition Language (DTDL)-Modell implementiert.

Die Azure IoT-Geräte-SDKs verfügen auch über Unterstützung für die IoT Plug & Play-Konventionen.

Gerätemodell

Ein Gerätemodell wird mithilfe der Modellierungssprache DTDL V2 definiert. Mit dieser Sprache können Sie Folgendes definieren:

  • Die vom Gerät gesendeten Telemetriedaten. Die Definition umfasst den Namen und den Datentyp der Telemetriedaten. Beispiel: Ein Gerät sendet die Telemetriedaten für die Temperatur als Wert vom Typ „double“.
  • Die Eigenschaften, die vom Gerät an IoT Central gemeldet werden. Eine Eigenschaftsdefinition umfasst den Namen und den Datentyp. Beispiel: Ein Gerät meldet den Zustand eines Ventils als booleschen Wert.
  • Die Eigenschaften, die das Gerät von IoT Central empfangen kann. Optional können Sie eine Eigenschaft als schreibbar markieren. Beispiel: Von IoT Central wird eine Zieltemperatur als Wert vom Typ „double“ an ein Gerät gesendet.
  • Die Befehle, auf die ein Gerät reagiert. Die Definition enthält den Namen des Befehls sowie die Namen und Datentypen beliebiger Parameter. Beispiel: Ein Gerät reagiert auf einen Neustartbefehl, mit dem angegeben wird, wie viele Sekunden vor dem Neustarten gewartet werden soll.

Hinweis

IoT Central definiert einige Erweiterungen für die DTDL v2-Sprache. Weitere Informationen finden Sie unter IoT Central-Erweiterung.

Bei einem DTDL-Modell kann es sich um ein Modell ohne Komponenten oder mit mehreren Komponenten handeln:

  • Modell ohne Komponenten: Ein einfaches Modell verwendet keine eingebetteten oder weitergegebenen Komponenten. Alle Telemetriedaten, Eigenschaften und Befehle werden als einzelne Stammkomponente definiert. Ein Beispiel hierfür finden Sie unter dem Thermostat-Modell.
  • Modell mit mehreren Komponenten: Ein komplexeres Modell, das mindestens zwei Komponenten umfasst. Diese Komponenten umfassen eine einzelne Stammkomponente und mindestens eine geschachtelte Komponente. Ein Beispiel hierfür finden Sie unter dem Temperature Controller-Modell.

Tipp

Sie können aus einer IoT Central-Gerätevorlage ein vollständiges Gerätemodell oder eine einzelne Schnittstelle importieren und exportieren und zwar als DTDL v2-Datei.

Weitere Informationen zu Gerätemodellen finden Sie im Leitfaden zur Modellierung mit IoT Plug & Play.

Konventionen

Ein Gerät sollte die IoT Plug & Play-Konventionen einhalten, wenn es Daten mit IoT Central austauscht. Die Konventionen umfassen Folgendes:

  • Senden des Gerätezwilling-Modellbezeichners bei der Verbindungsherstellung mit IoT Central
  • Senden Sie von richtig formatierten JSON-Nutzlasten und -Metadaten an IoT Central
  • Korrektes Reagieren auf schreibbare Eigenschaften und Befehle von IoT Central
  • Einhalten der Namenskonventionen für Komponentenbefehle

Hinweis

Derzeit werden die DTDL-Datentypen Array und Geospatial von IoT Central nicht vollständig unterstützt.

Weitere Informationen zu den IoT Plug & Play-Konventionen finden Sie unter IoT Plug & Play-Konventionen.

Weitere Informationen zum Format der JSON-Nachrichten, die ein Gerät mit IoT Central austauscht, finden Sie unter Telemetrie-, Eigenschaften- und Befehlsnutzlasten.

Geräte-SDKs

Mithilfe eines der Azure IoT-Geräte-SDKs können Sie das Verhalten Ihres Geräts implementieren. Der Code sollte folgende Aufgaben erfüllen:

  • Das Gerät mit DPS registrieren und mithilfe der Informationen von DPS eine Verbindung mit dem internen IoT-Hub in Ihrer IoT Central-Anwendung herstellen.
  • Ankündigen des Gerätezwilling-Modellbezeichners des vom Gerät implementierten Modells.
  • Senden von Telemetriedaten in dem Format, das vom Gerätemodell angegeben wird. Von IoT Central wird das Modell in der Gerätevorlage genutzt, um zu ermitteln, wie die Telemetriedaten für Visualisierungen und Analysen verwendet werden sollen.
  • Synchronisieren von Eigenschaftswerten zwischen dem Gerät und IoT Central. Das Modell gibt die Eigenschaftsnamen und Datentypen an, damit IoT Central die Informationen anzeigen kann.
  • Implementieren von Befehlshandlern für die im Modell angegebenen Befehle. Das Modell gibt die Befehlsnamen und Parameter an, die das Gerät verwenden sollte.

Weitere Informationen zur Aufgabe von Gerätevorlagen finden Sie unter Was sind Gerätevorlagen?.

In der folgenden Tabelle wird die Zuordnung von Azure IoT Central-Gerätefeatures zu IoT Hub-Features zusammengefasst:

Azure IoT Central Azure IoT Hub
Telemetrie Nachrichten, die von Geräten an die Cloud gesendet werden
Offlinebefehle Cloud-zu-Gerät-Messaging
Eigenschaft Gemeldete Eigenschaften von Gerätezwillingen
Eigenschaft (beschreibbar) Gewünschte und gemeldete Eigenschaften von Gerätezwillingen
Get-Help Direkte Methoden

Kommunikationsprotokolle

Kommunikationsprotokolle, über die ein Gerät eine Verbindung mit IoT Central herstellen kann, sind MQTT, AMQP und HTTPS. IoT Central verwendet intern einen IoT-Hub, um Gerätekonnektivität ermöglichen. Weitere Informationen zu den Kommunikationsprotokollen, die IoT Hub für die Gerätekonnektivität unterstützt, finden Sie unter Auswählen eines Kommunikationsprotokolls.

Wenn Ihr Gerät keines der unterstützten Protokolle verwenden kann, führen Sie mithilfe von Azure IoT Edge eine Protokollkonvertierung durch. IoT Edge unterstützt weitere Intelligence-on-the-Edge-Szenarien, um die Verarbeitung von der Azure IoT Central-Anwendung auszulagern.

Telemetriezeitstempel

IoT Central verwendet beim Anzeigen von Telemetriedaten auf Dashboards und in Diagrammen standardmäßig die Uhrzeit, zu der die Nachricht in die Warteschlange eingereiht wurde. Diese Uhrzeit wird intern festgelegt, wenn IoT Central die Nachricht vom Gerät empfängt.

Ein Gerät kann die Eigenschaft iothub-creation-time-utc festlegen, wenn es eine Nachricht erstellt, die an IoT Central gesendet werden soll. Wenn diese Eigenschaft vorhanden ist, verwendet IoT Central sie beim Anzeigen von Telemetriedaten auf Dashboards und in Diagrammen.

Sie können sowohl den Zeitpunkt der Einreihung in die Warteschlange als auch die Eigenschaft iothub-creation-time-utc exportieren, wenn Sie Telemetriedaten aus Ihrer IoT Central-Anwendung exportieren.

Weitere Informationen zu Nachrichteneigenschaften finden Sie unter Systemeigenschaften von Gerät-zu-Cloud-IoT Hub-Nachrichten.

Bewährte Methoden

Diese Empfehlungen unterstützen Sie dabei, Geräte so zu implementieren, dass Sie die Vorteile der integrierten Hochverfügbarkeit, Notfallwiederherstellung und automatischen Skalierung in IoT Central nutzen können.

Verarbeiten von Verbindungsfehlern

Zu Skalierungs- oder Notfallwiederherstellungszwecken kann IoT Central die zugrunde liegenden IoT-Hubs aktualisieren. Damit die Konnektivität bestehen bleibt, sollte Ihr Gerätecode spezifische Verbindungsfehler behandeln können, indem eine Verbindung mit einem neuen IoT Hub-Endpunkt hergestellt wird.

Wenn für das Gerät beim Herstellen einer Verbindung einer der folgenden Fehler angezeigt wird, sollte es den Bereitstellungsprozess mit DPS wiederholen, um eine neue Verbindungszeichenfolge abzurufen. Diese Fehler bedeuten, dass die Verbindungszeichenfolge nicht mehr gültig ist:

  • Der IoT Hub-Endpunkt kann nicht erreicht werden.
  • Das Sicherheitstoken ist abgelaufen.
  • Das Gerät wurde in IoT Hub deaktiviert.

Wenn für das Gerät beim Herstellen einer Verbindung einer der folgenden Fehler angezeigt wird, sollte eine Backoffstrategie verwendet werden, um noch mal zu versuchen, die Verbindung herzustellen. Diese Fehler bedeuten, dass die Verbindungszeichenfolge weiterhin gültig ist. Vorübergehende Bedingungen verhindern aber, dass das Gerät eine Verbindung herstellen kann:

  • Der Operator hat das Gerät blockiert.
  • Es wird ein interner Fehler 500 vom Dienst ausgegeben.

Weitere Informationen zu Fehlercodes für Geräte finden Sie unter Troubleshooting für Geräteverbindungen.

Weitere Informationen zum Implementieren von automatischen Verbindungswiederherstellungen finden Sie unter Verwalten von Verbindungswiederherstellungen mit Geräten zum Erstellen resilienter Anwendungen.

Testen von Failoverfunktionen

Über die Azure CLI können Sie die Failoverfunktionen Ihres Gerätecodes testen. Der CLI-Befehl verschiebt eine Geräteregistrierung vorübergehend auf einen anderen internen IoT-Hub. Zur Überprüfung, ob das Gerätefailover funktioniert hat, überprüfen Sie, ob das Gerät weiterhin Telemetriedaten sendet und auf Befehle reagiert.

Wenn Sie den Failovertest für Ihr Gerät durchführen möchten, führen Sie den folgenden Befehl aus:

az iot central device manual-failover \
    --app-id {Application ID of your IoT Central application} \
    --device-id {Device ID of the device you're testing} \
    --ttl-minutes {How to wait before moving the device back to it's original IoT hub}

Tipp

Die Anwendungs-ID finden Sie in Ihrer IoT Central-Anwendung unter Anwendung > Verwaltung.

Wenn der Befehl erfolgreich ausgeführt wurde, wird eine Ausgabe angezeigt, die etwa so aussieht:

Command group 'iot central device' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
{
  "hubIdentifier": "6bd4...bafa",
  "message": "Success! This device is now being failed over. You can check your device'’'s status using 'iot central device registration-info' command. The device will revert to its original hub at Tue, 18 May 2021 11:03:45 GMT. You can choose to failback earlier using device-manual-failback command. Learn more: https://aka.ms/iotc-device-test"
}

Weitere Informationen zum CLI-Befehl finden Sie unter az iot central device manual-failover.

Jetzt können Sie überprüfen, ob die Telemetriedaten aus dem Gerät Ihre IoT Central-Anwendung weiterhin erreichen.

Tipp

Beispiele für Gerätecode zur Verarbeitung von Failovern in verschiedenen Programmiersprachen finden Sie unter Beispiele für IoT Central-Hochverfügbarkeitsclients.

Nächste Schritte

Als Nächstes werden folgende Schritte vorgeschlagen: