Was sind Gerätevorlagen?

Eine Gerätevorlage in Azure IoT Central ist eine Blaupause, die die Merkmale und das Verhalten eines Gerätetyps definiert, der eine Verbindung mit Ihrer Anwendung herstellt. Beispielsweise definiert die Gerätevorlage die Telemetrie, die ein Gerät sendet, sodass IoT Central Visualisierungen mit den richtigen Einheiten und Datentypen erstellen kann.

Ein Lösungsgenerator fügt einer IoT Central-Anwendung Gerätevorlagen hinzu. Ein Geräteentwickler schreibt den Gerätecode, der die in der Gerätevorlage definierten Verhalten umsetzt. Weitere Informationen zu den Daten, die ein Gerät mit IoT Central austauscht, finden Sie unter Telemetrie-, Eigenschaften- und Befehlsnutzlasten.

Eine Gerätevorlage enthält die folgenden Abschnitte:

• Ein Gerätemodell. In diesem Teil der Gerätevorlage wird definiert, wie das Gerät mit Ihrer Anwendung interagiert. Jedes Gerätemodell hat eine eindeutige ID. Ein Geräteentwickler setzt die im Modell definierten Verhalten um.
  • Stammkomponente. Jedes Gerätemodell hat eine Stammkomponente. Die Schnittstelle der Stammkomponente beschreibt die spezifischen Funktionen des Gerätemodells.
  • Komponenten. Ein Gerätemodell kann zusätzlich zur Stammkomponente auch Komponenten enthalten, um Gerätefunktionen zu beschreiben. Jede Komponente verfügt über eine Schnittstelle, mit der die Funktionen der Komponente beschrieben werden. Komponentenschnittstellen können in anderen Gerätemodellen wiederverwendet werden. Beispielsweise können mehrere Smartphone-Gerätemodelle dieselbe Kameraschnittstelle verwenden.
  • Geerbte Schnittstellen. Ein Gerätemodell enthält eine oder mehrere Schnittstellen, mit denen die Funktionen der Stammkomponente erweitert werden.
• Ansichten. In diesem Teil der Gerätevorlage kann der Lösungsentwickler Visualisierungen zum Anzeigen von Daten aus dem Gerät und Formulare zur Verwaltung und Steuerung eines Geräts definieren. Ansichten haben keinen Einfluss auf den Code, den ein Geräteentwickler zum Implementieren des Gerätemodells schreibt.

Zuweisen eines Geräts zu einer Gerätevorlage

Damit ein Gerät mit IoT Central interagieren kann, muss es einer Gerätevorlage zugewiesen werden. Diese Zuweisung geschieht auf eine von vier Arten:

• Wenn Sie ein Gerät auf der Seite Geräte registrieren, können Sie die Vorlage identifizieren, die das Gerät verwenden sollte.
• Beim Massenimport einer Liste von Geräten können Sie die Gerätevorlage auswählen, die von allen Geräten in der Liste verwendet werden sollte.
• Nachdem eine Gerätevorlage verbunden wurde, können Sie ihr ein nicht zugewiesenes Gerät manuell zuweisen.
• Sie können ein Gerät einer Gerätevorlage automatisch zuweisen lassen, indem Sie eine Modell-ID senden, wenn das Gerät zum ersten Mal eine Verbindung mit Ihrer Anwendung herstellt.

Automatische Zuweisung

Wenn ein Gerät eine Verbindung herstellt, kann ihm IoT Central eine Gerätevorlage automatisch zuweisen. Beim Herstellen einer Verbindung sollte ein Gerät eine Modell-ID senden. IoT Central verwendet die Modell-ID, um die Gerätevorlage für dieses bestimmte Gerätemodell zu identifizieren. Der Ermittlungsvorgang funktioniert wie folgt:

1. Wenn die Gerätevorlage in der IoT Central-Anwendung bereits veröffentlicht wurde, ist das Gerät der Gerätevorlage zugeordnet.

2. Wenn die Gerätevorlage nicht bereits in der IoT Central-Anwendung veröffentlicht ist, sucht IoT Central im öffentlichen Gerätemodell-Repository nach dem Gerätemodell. Wenn IoT Central das Modell findet, wird es verwendet, um eine einfache Gerätevorlage zu generieren.

3. Wenn IoT Central das Modell im öffentlichen Modellrepository nicht findet, wird das Gerät als Nicht zugewiesen gekennzeichnet. Ein Operator kann:

   • Eine Gerätevorlage für das Gerät erstellen und dann das nicht zugeordnete Gerät zur neuen Gerätevorlage migrieren.
   • Generiert automatisch eine Gerätevorlage basierend auf den Daten, die das Gerät sendet.

Der folgende Screenshot zeigt, wie Sie die Modell-ID einer Gerätevorlage in IoT Central anzeigen. Wählen Sie in einer Gerätevorlage eine Komponente und dann Identität bearbeiten aus:

Sie können das Thermostatmodell im öffentlichen Modellrepository anzeigen. Die Definition der Modell-ID sieht so aus:

"@id": "dtmi:com:example:Thermostat;1"

Verwenden Sie die folgenden DPS-Nutzdaten, um das Gerät einer Gerätevorlage zuzuweisen:

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

Weitere Informationen zu DPS-Nutzdaten finden Sie im Beispielcode unter Tutorial: Erstellen und Verbinden einer Clientanwendung mit Ihrer Azure IoT Central-Anwendung.

Gerätemodelle

Ein Gerätemodell definiert, wie ein Gerät mit Ihrer IoT Central-Anwendung interagiert. Der Geräteentwickler muss sicherstellen, dass das Gerät die im Gerätemodell definierten Verhaltensweisen umsetzt, damit IoT Central das Gerät überwachen und verwalten kann. Ein Gerätemodell besteht aus einer oder mehreren Schnittstellen. Jede Schnittstelle kann eine Sammlung von Telemetrietypen, Geräteeigenschaften und Befehlen definieren. Ein Lösungsentwickler kann:

• Eine JSON-Datei, die ein komplettes Gerätemodell oder eine einzelne Schnittstelle definiert, in eine Gerätevorlage importieren.
• Die Web-UI in IoT Central verwenden, um ein Gerätemodell zu erstellen oder zu bearbeiten.

Hinweis

IoT Central akzeptiert jede gültige JSON-Nutzlast von einem Gerät, kann die Daten aber nur dann für Visualisierungen verwenden, wenn sie einer Definition im Gerätemodell entsprechen. Sie können Daten exportieren, die keiner Definition entsprechen, siehe Exportieren von IoT-Daten zu Cloud-Zielen mit Blob Storage.

Weitere Informationen zum Bearbeiten eines Gerätemodells finden Sie unter Bearbeiten einer vorhandenen Gerätevorlage.

Ein Lösungsentwickler kann auch eine JSON-Datei aus der Gerätevorlage exportieren, die ein vollständiges Gerätemodell oder eine einzelne Schnittstelle enthält. Ein Geräteentwickler kann anhand dieses JSON-Dokuments verstehen, wie das Gerät mit der IoT Central-Anwendung kommunizieren soll.

Die JSON-Datei mit der Definition des Gerätemodells verwendet Digital Twin Definition Language (DTDL) V2. IoT Central erwartet, dass die JSON-Datei das Gerätemodell mit inline und nicht in separaten Dateien definierten Schnittstellen enthält. In IoT Central erstellte Modelle haben den Kontext dtmi:iotcentral:context;2 definiert, um anzugeben, dass das Modell in IoT Central erstellt wurde:

"@context": [
  "dtmi:iotcentral:context;2",
  "dtmi:dtdl:context;2"
]

Weitere Informationen zu DTDL-Modellen finden Sie im Leitfaden zur Modellierung mit IoT Plug & Play.

Hinweis

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

Eigenschaften

Standardmäßig sind Eigenschaften schreibgeschützt. Schreibgeschützte Eigenschaften bedeuten, dass das Gerät Aktualisierungen der Eigenschaftswerte an Ihre IoT Central-Anwendung sendet. Ihre IoT Central-Anwendung kann den Wert einer schreibgeschützten Eigenschaft nicht festlegen.

Sie können eine Eigenschaft einer Schnittstelle auch als beschreibbar markieren. Ein Gerät kann eine Aktualisierung einer beschreibbaren Eigenschaft von Ihrer IoT Central-Anwendung empfangen und Aktualisierungen der Eigenschaftswerte an Ihre Anwendung senden.

Geräte müssen nicht verbunden sein, um Eigenschaftswerte festzulegen. Die aktualisierten Werte werden übertragen, wenn das Gerät das nächste Mal mit der Anwendung verbunden wird. Dieses Verhalten gilt sowohl für schreibgeschützte als auch beschreibbare Eigenschaften.

Verwenden Sie keine Eigenschaften, um Telemetriedaten von Ihrem Gerät zu senden. Beispielsweise bedeutet die schreibgeschützte temperatureSetting=80-Eigenschaft, dass die Gerätetemperatur auf 80 festgelegt wurde und das Gerät versucht, diese Temperatur zu erreichen oder zu halten.

Bei beschreibbaren Eigenschaften gibt die Geräteanwendung den Statuscode, die Version und die Beschreibung eines gewünschten Zustands zurück, um anzugeben, ob der Eigenschaftswert empfangen und angewandt wurde.

Cloudeigenschaften

Sie können der Stammkomponente des Modells auch Cloudeigenschaften hinzufügen. Mit Cloudeigenschaften können Sie Gerätemetadaten angeben, die in der IoT Central-Anwendung gespeichert werden sollen. Cloud-Eigenschaftswerte werden in der IoT Central-Anwendung gespeichert und nie mit einem Gerät synchronisiert. Cloudeigenschaften haben keinen Einfluss auf den Code, den ein Geräteentwickler zum Implementieren des Gerätemodells schreibt.

Ein Lösungsentwickler kann neben Geräteeigenschaften auch Cloudeigenschaften zu Geräteansichten und Formularen hinzufügen, um es einem Bediener zu ermöglichen, die mit der Anwendung verbundenen Geräte zu verwalten. Ein Lösungsentwickler kann Cloudeigenschaften auch als Teil einer Regeldefinition verwenden, damit ein Schwellenwert von einem Bediener bearbeitet werden kann.

Der folgende DTDL-Codeausschnitt zeigt eine Beispieldefinition für Cloudeigenschaften:

{
    "@id": "dtmi:azureiot:Thermostat:CustomerName",
    "@type": [
        "Property",
        "Cloud",
        "StringValue"
    ],
    "displayName": {
        "en": "Customer Name"
    },
    "name": "CustomerName",
    "schema": "string"
}

Telemetrie

Mit IoT Central können Sie Telemetrie in Geräteansichten und Diagrammen anzeigen sowie Regeln zum Auslösen von Aktionen verwenden, wenn Schwellenwerte erreicht werden. IoT Central verwendet die Informationen im Gerätemodell wie Datentypen, Einheiten und Anzeigenamen, um zu bestimmen, wie Telemetriewerte angezeigt werden sollen. Sie können Telemetriewerte auch auf Anwendungsdashboards und persönlichen Dashboards anzeigen.

Sie können die Datenexportfunktion von IoT Central nutzen, um Telemetrie an andere Ziele wie Azure Storage oder Event Hubs zu streamen.

Befehle

Ein Befehl muss standardmäßig innerhalb von 30 Sekunden ausgeführt werden, und das Gerät muss beim Eingehen des Befehls verbunden sein. Wenn das Gerät nicht rechtzeitig antwortet oder nicht verbunden ist, wird der Befehl nicht ausgeführt.

Befehle können Anforderungsparameter aufweisen und eine Antwort zurückgeben.

Offlinebefehle

Wenn ein Gerät zurzeit offline ist, können Sie Warteschlangenbefehle auswählen, indem Sie in der Gerätevorlage die Option Warteschlange (falls offline) für einen Befehl aktivieren.

Offlinebefehle sind unidirektionale Benachrichtigungen aus Ihrer Lösung an das Gerät. Offlinebefehle können Anforderungsparameter aufweisen, geben aber keine Antwort zurück.

Hinweis

Offlinebefehle werden als durable markiert, wenn Sie das Modell als DTDL exportieren.

Offline Befehle verwenden Cloud-zu-Gerät-Nachrichten von IoT Hub, um den Befehl und die Nutzlast an das Gerät zu senden.

Die Nutzlast der Nachricht, die das Gerät empfängt, ist der Rohwert des Parameters. Der Name des IoT Central-Befehls wird in der benutzerdefinierten Eigenschaft method-name gespeichert. Die folgende Tabelle zeigt einige Beispielnutzlasten:

IoT Central Anforderungsschema	Beispielnutzlast, die vom Gerät empfangen wurde
Kein Anforderungsparameter	@
Double	1.23
String	sample string
Objekt	{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines Befehls. Der Befehl enthält einen Objektparameter mit einem „DateTime“-Feld und einer Enumeration:

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

Wenn Sie die Option Warteschlange (falls offline) in der Benutzeroberfläche der Gerätevorlage für den Befehl im vorherigen Codeausschnitt aktivieren, enthält die vom Gerät empfangene Meldung die folgenden Eigenschaften:

Eigenschaftenname	Beispielswert
custom_properties	{'method-name': 'GenerateDiagnostics'}
data	{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

Ansichten

Ein Lösungsentwickler erstellt Ansichten, mit denen Bediener angeschlossene Geräte überwachen und verwalten können. Ansichten sind Teil der Gerätevorlage, sodass eine Ansicht einem bestimmten Gerätetyp zugeordnet ist. Eine Ansicht kann Folgendes enthalten:

• Diagramme zum Zeichnen von Telemetrie
• Kacheln zum Anzeigen schreibgeschützter Geräteeigenschaften
• Kacheln, damit der Bediener beschreibbare Geräteeigenschaften bearbeiten kann
• Kacheln, damit der Bediener Cloudeigenschaften bearbeiten kann
• Kacheln, damit der Bediener Befehle aufrufen kann, darunter solche, die eine Nutzlast erwarten
• Kacheln zum Anzeigen von Beschriftungen, Bildern oder Markdowntext

Nächste Schritte

Nachdem Sie sich über Gerätevorlagen informiert haben, sollten Sie als Nächstes den Artikel Telemetrie-, Eigenschaften- und Befehlsnutzlasten lesen, um mehr über die Daten zu erfahren, die ein Gerät mit IoT Central austauscht.