Verwenden von IoT Plug & Play-Modellen in einer IoT-Lösung

Artikel
04/02/2024

In diesem Artikel wird beschrieben, wie Sie in einer IoT-Lösung die Modell-ID eines IoT Plug & Play Geräts identifizieren und dann seine Modelldefinition abrufen.

IoT-Lösungen lassen sich in zwei Hauptkategorien unterteilen:

Eine zweckgebundene Lösung funktioniert mit einer bekannten Auswahl an Modellen für die IoT Plug & Play Geräte, die eine Verbindung mit der Lösung herstellen. Diese Modelle werden bei der Entwicklung der Lösung verwendet.
Eine modellgesteuerte Lösung funktioniert mit dem Modell jedes IoT Plug & Play-Geräts. Die Entwicklung einer modellgesteuerten Lösung ist komplexer. Der Vorteil ist jedoch, dass Ihre Lösung mit allen zukünftig hinzugefügten Geräten funktioniert. Eine modellgesteuerte IoT-Lösung ruft ein Modell ab und ermittelt mit ihm die vom Gerät implementierten Telemetriedaten, Eigenschaften und Befehle.

Zum Verwenden eines IoT Plug & Play-Modells geht eine IoT-Lösung folgendermaßen vor:

Sie identifiziert die Modell-ID des Modells, das von dem IoT Plug & Play-Gerät oder -Modul oder dem IoT Edge-Modul implementiert wird, das mit der Lösung verbunden ist.
Sie verwendet die Modell-ID zum Abrufen der Modelldefinition des verbundenen Geräts aus einem Modellrepository oder einem benutzerdefinierten Speicher.

Identifizieren der Modell-ID

Wenn ein IoT Plug & Play-Gerät eine Verbindung mit IoT-Hub herstellt, registriert es die Modell-ID des von ihm implementierten Modells bei IoT Hub.

IoT Hub benachrichtigt die Lösung im Rahmen des Geräteverbindungsflows mit der Gerätemodell-ID.

Eine Lösung kann die Modell-ID des IoT Plug & Play-Geräts mithilfe einer der folgenden drei Methoden erhalten:

API zum Abrufen von Gerätezwillingen

Die Lösung kann die API zum Abrufen von Gerätezwillingen verwenden, um die Modell-ID des IoT Plug & Play-Geräts abzurufen.

Tipp

Verwenden Sie für Module und IoT Edge-Module ModuleClient.getTwin.

Im folgenden Antwortausschnitt eines Gerätezwillings enthält modelId die Modell-ID eines IoT Plug & Play-Geräts:

{
    "deviceId": "sample-device",
    "etag": "AAAAAAAAAAc=",
    "deviceEtag": "NTk0ODUyODgx",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00Z",
    "connectionState": "Disconnected",
    "lastActivityTime": "2020-07-17T06:12:26.8402249Z",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "modelId": "dtmi:com:example:TemperatureController;1",
    "version": 15,
    "properties": {...}
    }
}

API zum Abrufen von digitalen Zwillingen

Die Lösung kann die API zum Abrufen von digitalen Zwillingen verwenden, um die Modell-ID des Modells abzurufen, das vom IoT Plug & Play-Gerät implementiert wurde.

Im folgenden Antwortausschnitt eines digitalen Zwillings enthält $metadata.$model die Modell-ID eines IoT Plug & Play-Geräts:

{
    "$dtId": "sample-device",
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

Benachrichtigung über Änderungsereignis für einen digitalen Zwilling

Eine Geräteverbindung führt zu einer Benachrichtigung über ein Änderungsereignis für einen digitalen Zwilling. Eine Lösung muss diese Ereignisbenachrichtigungen abonnieren. Informationen zum Aktivieren des Routings für Ereignisse bei digitalen Zwillingen finden Sie unter Verwenden des IoT Hub-Nachrichtenroutings zum Senden von D2C-Nachrichten an verschiedene Endpunkte.

Die Lösung kann das im folgenden Codeausschnitt gezeigte Ereignis verwenden, um mehr über das IoT Plug & Play-Gerät zu erfahren, das eine Verbindung herstellt, und seine Modell-ID abzurufen:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:com:example:TemperatureController;1"
  }
]

Abrufen einer Modelldefinition

Eine Lösung verwendet die oben identifizierte Modell-ID, um die zugehörige Modelldefinition abzurufen.

Eine Lösung kann die Modelldefinition mithilfe einer der folgenden Optionen erhalten:

Modellrepository

Lösungen können DTDL-Modelle aus dem Gerätemodellrepository (DMR, Device Model Repository) abrufen. Das DMR ist ein öffentliches Repository, das von Microsoft gehostet wird und eine Sammlung kuratierter DTDL-Modelle enthält. Die im DMR gespeicherten öffentlichen Gerätemodelle stehen für alle zur Verfügung und können vom öffentlichen Endpunkt https://devicemodels.azure.com aus in Benutzeranwendungen integriert werden.

Nachdem Sie die Modell-ID für eine neue Geräteverbindung identifiziert haben, führen Sie die folgenden Schritte aus:

Rufen Sie die Modelldefinition mithilfe der Modell-ID aus dem Modellrepository ab. Weitere Informationen finden Sie unter Auflösen von Modellen.
Mithilfe der Modelldefinition des verbundenen Geräts können Sie die Funktionen des Geräts auflisten.
Mithilfe der aufgelisteten Funktionen des Geräts können Sie Benutzern ermöglichen, mit dem Gerät zu interagieren.

Auflösen von Modellen

Die DMR-Konventionen enthalten weitere Artefakte zur Vereinfachung der Nutzung von gehosteten Modellen. Diese Features sind für benutzerdefinierte oder private Repositorys optional.

Index: Alle verfügbaren DTMIs werden über einen Index verfügbar gemacht, der aus einer Sequenz von JSON-Dateien besteht, z. B.: https://devicemodels.azure.com/index.page.2.json
Erweitert. Eine Datei mit allen Abhängigkeiten ist für jede Schnittstelle verfügbar, z. B.: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadaten. Diese Datei macht wichtige Attribute eines Repositorys verfügbar und wird regelmäßig mit der momentaufnahme der neuesten veröffentlichten Modelle aktualisiert. Sie enthält Features, die ein Repository implementiert, z. B. ob der Modellindex oder erweiterte Modelldateien verfügbar sind. Sie können auf die DMR-Metadaten unter zugreifen. https://devicemodels.azure.com/metadata.json

Um programmgesteuert auf die öffentlichen DTDL-Modelle im DMR zuzugreifen, können Sie das im NuGet-Paket Azure.IoT.ModelsRepository verfügbare ModelsRepositoryClient-Objekt verwenden. Dieser Client ist standardmäßig so konfiguriert, dass er das unter devicemodels.azure.com verfügbare öffentliche DMR abfragt. Er kann für ein beliebiges benutzerdefiniertes Repository konfiguriert werden.

Der Client akzeptiert einen DTMI als Eingabe und gibt ein Wörterbuch mit allen erforderlichen Schnittstellen zurück:

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

Die erwartete Ausgabe zeigt den DTMI der drei in der Abhängigkeitskette gefundenen Schnittstellen an:

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

Der ModelsRepositoryClient kann so konfiguriert werden, dass ein benutzerdefiniertes DMR über HTTP(s) abgefragt und die Abhängigkeitsauflösung mit dem verfügbaren ModelDependencyResolution-Flag angegeben wird:

Deaktiviert. Gibt nur die angegebene Schnittstelle zurück, ohne jegliche Abhängigkeit.
Aktiviert. Gibt alle Schnittstellen in der Abhängigkeitskette zurück.

Tipp

Benutzerdefinierte Repositorys machen die .expanded.json-Datei möglicherweise nicht verfügbar. Wenn diese Datei nicht verfügbar ist, wird vom Client ein Fallback ausgeführt, um jede Abhängigkeit lokal zu verarbeiten.

Im nächsten Codebeispiel wird gezeigt, wie der ModelsRepositoryClient mit einer benutzerdefinierten Repository-Basis-URL initialisiert wird. In diesem Fall werden die raw-URLs aus der GitHub-API ohne die expanded-Variante verwendet, da diese am raw-Endpunkt nicht verfügbar ist. Der AzureEventSourceListener wird initialisiert, um die vom Client ausgeführte HTTP-Anforderung zu überprüfen:

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

Im Azure SDK-Repository auf GitHub finden Sie weitere Beispiele: Azure.Iot.ModelsRepository/samples.

Benutzerdefinierter Speicher

Lösungen können diese Modelldefinitionen in einem lokalen Dateisystem oder in einem öffentlichen Dateispeicher speichern oder eine benutzerdefinierte Implementierung nutzen.