IoT Plug & Play in Azure Device Update for IoT Hub
Device Update for IoT Hub verwendet IoT Plug & Play zum Erkennen und Verwalten von Geräten, die OTA-Updates (Over-the-Air) empfangen können. In diesem Artikel wird beschrieben, wie der Device Update-Dienst Eigenschaften und Nachrichten an Geräte sendet und diese von Geräten empfängt, die IoT Plug & Play-Schnittstellen verwenden.
Weitere Informationen finden Sie im Leitfaden für IoT Plug & Play-Geräteentwickelnde und unter Erstellen des Device Update-Agents.
Device Update-Modelle
Intelligente Geräte nutzen IoT Plug & Play-Modell-IDs, um ihre Funktionen für Azure IoT-Anwendungen verfügbar zu machen. Für Device Update muss das intelligente IoT Plug & Play-Gerät im Rahmen der Geräteverbindung eine Modell-ID ankündigen. Weitere Informationen finden Sie unter Modell-ID-Ankündigung.
Device Update verfügt über mehrere definierte IoT Plug & Play-Modelle, die Device Update-Features unterstützen. Das Device Update-Modell **dtmi:azure:iot:deviceUpdateContractModel;3** unterstützt die Device Update-Kernfunktionen und verwendet die Device Update-Kernschnittstelle, um Updateaktionen und Metadaten an Geräte zu senden und den Updatestatus von Geräten zu empfangen.
Das andere unterstützte Modell ist **dtmi:azure:iot:deviceUpdateModel;3**. Es erweitert **deviceUpdateContractModel;3** und nutzt ebenfalls IoT Plug & Play-Schnittstellen, die Geräteeigenschaftsinformationen senden und Diagnosefeatures aktivieren. Informationen zu diesen und anderen Versionen finden Sie unter Azure IoT Plug & Play-Modelle für Device Update.
Der Device Update-Agent verwendet **dtmi:azure:iot:deviceUpdateModel;3**. Dieses Modell unterstützt alle aktuellen Features der Device Update-Version 1.1.0. Dieses Modell unterstützt die Importmanifestversion 5.0. Ältere Manifeste funktionieren mit den neuesten Agents, aber neue Features erfordern die aktuelle Manifestversion.
Agent-Metadaten
Der Device Update-Agent verwendet die folgenden Metadatenfelder des Agents, um Informationen an Device Update-Dienste zu senden.
| Name | Schema | Direction | Beschreibung |
|---|---|---|---|
| deviceProperties | Karte | Gerät an Cloud | Der Satz von Eigenschaften, die den Hersteller, das Modell und andere Geräteinformationen enthalten. Ausführliche Informationen finden Sie unter Geräteeigenschaften. |
| compatPropertyNames | Zeichenfolge (durch Kommas getrennt) | Gerät an Cloud | Bis zu fünf Eigenschaften, mit denen die Gerätekompatibilität für die Updatebereitstellung überprüft wird. Beispiel: "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Karte | Gerät an Cloud | Das vom Agent gemeldete Ergebnis mit dem Ergebniscode, dem erweiterten Ergebniscode und Ergebnisdetails für Hauptupdates und andere Schrittupdates. |
| resultCode | integer | Gerät an Cloud | Ein Code, der Informationen zum Ergebnis der letzten Aktualisierungsaktion enthält. Kann bei Erfolg oder Fehler mit Daten aufgefüllt werden. Beispiel: 700 |
| extendedResultCode | integer | Gerät an Cloud | Ein Code, der weitere Informationen zum Ergebnis enthält. Kann bei Erfolg oder Fehler mit Daten aufgefüllt werden. Beispiel: 0x80004005 |
| resultDetails | Zeichenfolge | Gerät an Cloud | Eine von Benutzenden bereitgestellte Zeichenfolge in Freihandform, um weitere Ergebnisdetails bereitzustellen. Wird ohne Parsen an den Zwilling zurückgegeben |
| stepResults | Karte | Gerät an Cloud | Das vom Agent gemeldete Ergebnis mit dem Ergebniscode, dem erweiterten Ergebniscode und Ergebnisdetails für Schrittupdates. Beispiel: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| state | integer | Gerät an Cloud | Ein Integerwert, der den aktuellen Status des Device Update-Agents angibt. Ausführliche Informationen finden Sie unter Status. |
| workflow | complex | Gerät an Cloud | Ein Satz von Werten, die die Bereitstellung, an der der Agent gerade arbeitet, die ID der derzeit installierten Bereitstellung und die Bestätigung aller Wiederholungsanforderungen angeben, die vom Dienst an den Agent gesendet werden. Die workflow-ID meldet den Wert "nodeployment", nachdem eine Bereitstellung abgebrochen wurde. Beispiel: "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| installedUpdateId | Zeichenfolge | Gerät an Cloud | Eine ID der derzeit installierten Device Update-Bereitstellung. Dieser Wert erfasst den Update-ID-JSON-Code oder null für ein Gerät, das nie ein Update über Device Update erhalten hat. Beispiel: "installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}" |
Beispiel für einen IoT Hub-Gerätezwilling:
"deviceUpdate": {
"__t": "c",
"agent": {
"deviceProperties": {
"manufacturer": "contoso",
"model": "virtual-vacuum-v1",
"contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;3",
"aduVer": "DU;agent/1.1.0",
},
"compatPropertyNames": "manufacturer,model",
"lastInstallResult": {
"resultCode": 700,
"extendedResultCode": 0,
"resultDetails": "",
"stepResults": {
"step_0": {
"resultCode": 700,
"extendedResultCode": 0,
"resultDetails": ""
}
}
},
"state": 0,
"workflow": {
"action": 3,
"id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
"retryTimestamp": "2022-01-26T11:33:29.9680598Z"
},
"installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
},
Hinweis
Das Gerät oder Modul muss zusätzlich den Marker {"__t": "c"} aufweisen, um anzugeben, dass das Element auf eine Komponente verweist. Weitere Informationen finden Sie unter Beispiel für eine schreibbare Eigenschaft eines Geräts mit mehreren Komponenten.
Geräteeigenschaften
Das Feld deviceProperties enthält die Hersteller- und Modellinformationen für ein Gerät.
| Name | Schema | Direction | BESCHREIBUNG |
|---|---|---|---|
| Hersteller | Zeichenfolge | Gerät an Cloud | Der Gerätehersteller, der über deviceProperties gemeldet wird.Die DeviceUpdateCore-Schnittstelle versucht zunächst, den aduc_manufacturer-Wert aus der Konfigurationsdatei zu lesen. Wenn der Wert in der Konfigurationsdatei nicht eingetragen ist, meldet die Schnittstelle standardmäßig die Kompilierzeitdefinition für ADUC_DEVICEPROPERTIES_MANUFACTURER. Diese Eigenschaft wird nur zum Startzeitpunkt gemeldet. Standardwert: „Contoso“ |
| model | Zeichenfolge | Gerät an Cloud | Das Gerätemodell des Geräts, das über gemeldet wird deviceProperties. Die DeviceUpdateCore-Schnittstelle versucht zunächst, den aduc_model-Wert aus der Konfigurationsdatei zu lesen. Wenn der Wert in der Konfigurationsdatei nicht eingetragen ist, meldet die Schnittstelle standardmäßig die Kompilierzeitdefinition für ADUC_DEVICEPROPERTIES_MODEL. Diese Eigenschaft wird nur zum Startzeitpunkt gemeldet. Standardwert: „Video“ |
| contractModelId | Zeichenfolge | Gerät an Cloud | Eigenschaft, die der Dienst verwendet, um die Basismodellversion zu identifizieren, die der Device Update-Agent zum Verwalten und Kommunizieren mit dem Agent verwendet. Wert: dtmi:azure:iot:deviceUpdateContractModel;3 für Geräte mit Device Update-Agent-Version 1.1.0. Hinweis: Agents, die dtmi:azure:iot:deviceUpdateModel;2 verwenden, müssen contractModelId als dtmi:azure:iot:deviceUpdateContractModel;3 melden, da deviceUpdateModel;3 von deviceUpdateContractModel;3 erweitert wird. |
| aduVer | Zeichenfolge | Gerät an Cloud | Version des Device Update-Agents, der auf dem Gerät ausgeführt wird. Dieser Wert wird nur dann aus dem Build gelesen, wenn während der Kompilierungszeit ENABLE_ADU_TELEMETRY_REPORTING auf 1 (TRUE) festgelegt wird. Sie können sich entscheiden, die Versionsberichterstellung zu deaktivieren, indem Sie den Wert auf 0 (FALSE) festlegen. Weitere Informationen finden Sie unter Erstellen des Device Update-Agents. |
| doVer | Zeichenfolge | Gerät an Cloud | Version des Übermittlungsoptimierungs-Agents, der auf dem Gerät ausgeführt wird. Der Wert wird nur dann aus dem Build gelesen, wenn während der Kompilierungszeit ENABLE_ADU_TELEMETRY_REPORTING auf 1 (TRUE) festgelegt wird. Sie können sich entscheiden, die Versionsberichterstellung zu deaktivieren, indem Sie den Wert auf 0 (FALSE) festlegen. Weitere Informationen finden Sie unter Anpassen der Eigenschaften des Übermittlungsoptimierungs-Agents. |
| Benutzerdefinierte Kompatibilitätseigenschaften | Benutzerdefiniert | Gerät an Cloud | Andere benutzerdefinierte Geräteeigenschaften, die für die Kompatibilitätsprüfung verwendet werden sollen, wenn die Updatebereitstellung als Ziel verwendet wird. |
Staat
Das Feld Status gibt den Status an, der vom Device Update-Agent als Reaktion auf eine Aktion, die vom Device Update-Dienst an den Device Update-Agent gesendet wurde, gemeldet wird. Weitere Informationen zu Anforderungen, die zwischen dem Device Update-Dienst und dem Device Update-Agent fließen, finden Sie unter Agent-Workflow.
| Name | Wert | BESCHREIBUNG |
|---|---|---|
| Idle | 0 | Das Gerät ist bereit, eine Aktion vom Device Update-Dienst zu empfangen. Nach einem erfolgreichen Update wird der Status in den Status Idle zurückgesetzt. |
| DeploymentInprogress | 6 | Eine Bereitstellung ist in Bearbeitung. |
| Fehler | 255 | Fehler beim Aktualisieren. |
| DownloadSucceeded | 2 | Erfolgreicher Download. Nur Geräte mit Agent-Version 0.7.0 oder früher melden diesen Status. |
| InstallSucceeded | 4 | Erfolgreiche Installation. Nur Geräte mit Agent-Version 0.7.0 oder früher melden diesen Status. |
Aktion
Das Feld Aktion stellt die Aktionen dar, die vom Device Update-Agent ausgeführt werden sollen, wie vom Device Update-Dienst angegeben. Der Device Update-Agent meldet einen Status für die Verarbeitung der empfangenen Aktion. Weitere Informationen zu Anforderungen, die zwischen dem Device Update-Dienst und dem Device Update-Agent fließen, finden Sie unter Agent-Workflow.
| Name | Wert | BESCHREIBUNG |
|---|---|---|
| applyDeployment | 3 | Anwenden des bereitgestellten Updates |
| cancel | 255 | Beenden Sie die Verarbeitung der aktuellen Aktion, und wechseln Sie zurück zu Idle, oder teilen Sie einem Agent im Status Failed mit, zu Idle zurückzukehren. |
| Download verfügbar ist | 0 | Herunterladen von veröffentlichtem Inhalt oder des Updates und sämtlicher anderer erforderlicher Inhalte. Diese Aktion wird nur an Geräte mit Agent-Version 0.7.0 oder früher gesendet. |
| Installieren | 1 | Installieren des Inhalts oder Updates. In der Regel bedeutet diese Aktion, dass das Installationsprogramm für den Inhalt oder das Update aufgerufen wird. Device Update sendet diese Aktion nur an Geräte mit Agent-Version 0.7.0 oder früher. |
| apply | 2 | Schließen Sie das Update ab, indem Sie es bei Bedarf neu starten. Device Update sendet diese Aktion nur an Geräte mit Agent-Version 0.7.0 oder früher. |
Dienstmetadaten
Dienstmetadaten enthalten Felder, die vom Device Update-Dienst zum Kommunizieren von Aktionen und Daten an den Device Update-Agent verwendet werden.
| Name | Schema | Direction | BESCHREIBUNG |
|---|---|---|---|
| action | integer | Cloud zu Gerät | Ein Integerwert, der einer Aktion entspricht, die der Agent ausführen soll. Ausführliche Informationen finden Sie unter Aktion. |
| updateManifest | Zeichenfolge | Cloud zu Gerät | Beschreibt den Inhalt eines Updates. Wird aus dem Importmanifest generiert. |
| updateManifestSignature | JSON-Objekt | Cloud zu Gerät | JSON Web Signature (JWS) mit JSON-Webschlüsseln (JSON Web Keys), die für die Quellüberprüfung verwendet werden sollen. |
| fileUrls | Karte | Cloud zu Gerät | Ordnet FileIDDownloadUrl zu. Informiert den Agent, welche Dateien heruntergeladen werden sollen und welcher Hash verwendet werden soll, um zu bestätigen, dass die Dateien ordnungsgemäß heruntergeladen wurden. |
Geräteinformationsschnittstelle
Die Geräteinformationsschnittstelle ist ein Konzept, das in der IoT Plug & Play-Architektur verwendet wird. Die Schnittstelle enthält Gerät-zu-Cloud-Eigenschaften, die Informationen zur Hardware und zum Betriebssystem des Geräts bereitstellen. Device Update verwendet die Eigenschaften DeviceInformation.manufacturer und DeviceInformation.model für Telemetrie und Diagnose. Ein Beispiel für die Geräteinformationsschnittstelle finden Sie unter https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json.
Wenn Sie diese Schnittstelle implementieren, ist der erwartete Komponentenname im Modell deviceInformation. Weitere Informationen finden Sie im Leitfaden zur Modellierung mit IoT Plug & Play.
| Name | type | Schema | Direction | BESCHREIBUNG | Beispiel |
|---|---|---|---|---|---|
| Hersteller | Eigenschaft | Zeichenfolge | Gerät an Cloud | Firmenname des Geräteherstellers. Der Hersteller kann mit dem Namen des OEM (Original Equipment Manufacturer, Originalgeräteherstellers) identisch sein. | Contoso |
| model | Eigenschaft | Zeichenfolge | Gerät an Cloud | Name oder ID des Gerätemodells. | IoT Edge-Gerät |
| swVersion | Eigenschaft | Zeichenfolge | Gerät an Cloud | Version der Software auf Ihrem Gerät. Bei swVersion kann es sich um die Version Ihrer Firmware handeln. | 4.15.0-122 |
| osName | Eigenschaft | Zeichenfolge | Gerät an Cloud | Der Name des Betriebssystems auf dem Gerät. | Ubuntu Server 18.04 |
| processorArchitecture | Eigenschaft | Zeichenfolge | Gerät an Cloud | Architektur des Prozessors auf dem Gerät. | ARM64 |
| processorManufacturer | Eigenschaft | Zeichenfolge | Gerät an Cloud | Der Name des Herstellers des Prozessors auf dem Gerät. | Microsoft |
| TotalStorage | Eigenschaft | Zeichenfolge | Gerät an Cloud | Gesamter verfügbarer Speicher auf dem Gerät in KB. | 2048 |
| totalMemory | Eigenschaft | Zeichenfolge | Gerät an Cloud | Gesamter verfügbarer Arbeitsspeicher auf dem Gerät in KB. | 256 |