Device Update for IoT Hub und IoT Plug & Play

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. Der Device Update-Dienst sendet Eigenschaften und Nachrichten an Geräte und empfängt diese von Geräten, die IoT Plug & Play-Schnittstellen verwenden.

Weitere Informationen finden Sie unter:

• Grundlegendes zum IoT Plug & Play-Geräteclient.
• Erfahren Sie, wie der Geräteupdate-Agent implementiert wird.

Device Update-Modelle

Die Modell-ID gibt an, wie intelligente Geräte ihre Funktionen für Azure IoT-Anwendungen mit IoT Plug & Play ankündigen. Weitere Informationen zum Erstellen von intelligenten Geräten zum Ankündigen ihrer Funktionen für Azure IoT-Anwendungen finden Sie im Entwicklerleitfaden für IoT Plug & Play-Geräte.

Für Device Update for IoT Hub muss das intelligente IoT Plug & Play-Gerät im Rahmen der Geräteverbindung eine Modell-ID ankündigen. Weitere Informationen zum Ankündigen einer Modell-ID.

Für Device Update sind mehrere PnP-Modelle definiert, die DU-Features unterstützen. Das Device Update-Modell dtmi:azure:iot:deviceUpdateContractModel;3 unterstützt die 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 auch andere PnP-Schnittstellen, die Geräteeigenschaften und -informationen senden und Diagnosefunktionen aktivieren. Informieren Sie sich ausführlicher über [Device Update-Modelle und Schnittstellenversionen] (https://github.com/Azure/iot-plugandplay-models/tree/main/dtmi/azure/iot).

Der Device Update-Agent verwendet dtmi:azure:iot:deviceUpdateModel;3. Dieses Modell unterstützt alle aktuellen Features der Version 1.1.0. Dieses Modell unterstützt die V5-Manifestversion. Ältere Manifeste funktionieren mit den neuesten Agents, aber neue Features erfordern die Verwendung der neuesten Manifestversion.

Agent-Metadaten

Der Device Update-Agent verwendet die Metadatenfelder des Agents, um Informationen an Device Update-Dienste zu senden.

Name	Schema	Direction	BESCHREIBUNG	Beispiel
deviceProperties	Karte	Gerät an Cloud	Der Satz von Eigenschaften, die den Hersteller, das Modell und andere Geräteinformationen enthalten.	Details finden Sie im Abschnitt Geräteeigenschaften.
compatPropertyNames	Zeichenfolge (durch Kommas getrennt)	Gerät an Cloud	Die vom Gerät gemeldeten Eigenschaften, die verwendet werden, um die Kompatibilität des Geräts für die Updatebereitstellung zu überprüfen. Auf fünf Geräteeigenschaften beschränkt.	"compatPropertyNames": "manufacturer,model"
lastInstallResult	Karte	Gerät an Cloud	Das vom Agent gemeldete Ergebnis. Es enthält den Ergebniscode, den 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.	700
extendedResultCode	integer	Gerät an Cloud	Ein Code, der zusätzliche Informationen zum Ergebnis enthält. Kann bei Erfolg oder Fehler mit Daten aufgefüllt werden.	0x80004005
resultDetails	Zeichenfolge	Gerät an Cloud	Vom Kunden definierte Freiformzeichenfolge für die Bereitstellung zusätzlicher Ergebnisdetails. Wird ohne Analyse 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.	"step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
state	integer	Gerät an Cloud	Ein Integerwert, der den aktuellen Status des Device Update-Agents angibt.	Im Abschnitt Status finden Sie ausführliche Informationen hierzu.
workflow	complex	Gerät an Cloud	Ein Satz von Werten, die die Bereitstellung, an der der Agent gerade arbeitet, die ID der aktuellen Bereitstellung und die Bestätigung aller Wiederholungsanforderungen angeben, die vom Dienst an den Agent gesendet werden. Beachten Sie, dass die Workflow-ID den Wert „nodeployment“ meldet, nachdem die Bereitstellung abgebrochen wurde.	"workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"}
installedUpdateId	Zeichenfolge	Gerät an Cloud	Eine ID des Updates, das zurzeit (über Device Update) installiert wird. Bei diesem Wert handelt es sich um eine Zeichenfolge, die den JSON-Code der Update-ID oder NULL für ein Gerät erfasst, das noch nie ein Update über Device Update durchgeführt hat.	installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}"

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. Diese Eigenschaft wird aus einem von zwei Speicherorten gelesen. Die Schnittstelle DeviceUpdateCore versucht zunächst, den Wert „aduc_manufacturer“ aus der Konfigurationsdatei zu lesen. Wenn der Wert in der Konfigurationsdatei keine Daten enthält, wird standardmäßig die Kompilierzeitdefinition für ADUC_DEVICEPROPERTIES_MANUFACTURER gemeldet. 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. Diese Eigenschaft wird aus einem von zwei Speicherorten gelesen. Die Schnittstelle DeviceUpdateCore versucht zunächst, den Wert „aduc_model“ aus der Konfigurationsdatei zu lesen. Wenn der Wert in der Konfigurationsdatei nicht eingetragen ist, wird standardmäßig die Kompilierzeitdefinition für ADUC_DEVICEPROPERTIES_MODEL gemeldet. Diese Eigenschaft wird nur zum Startzeitpunkt gemeldet. Standardwert: „Video“
contractModelId	Zeichenfolge	Gerät an Cloud	Diese Eigenschaft wird vom Dienst verwendet, um die Basismodellversion zu identifizieren, die vom Device Update-Agent zum Verwalten und Kommunizieren mit dem Agent verwendet wird. Wert: „dtmi:azure:iot:deviceUpdateContractModel;3“ für Geräte mit der DU-Agent-Version 1.1.0. Hinweis: Agents, die „dtmi:azure:iot:deviceUpdateModel;2“ verwenden, müssen contractModelId angeben, da „dtmi:azure:iot:deviceUpdateContractModel;3“ als „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. Kunden können sich entscheiden, die Versionsberichterstellung zu deaktivieren, indem sie den Wert auf 0 (FALSE) festlegen. Anpassen der Eigenschaften des Device Update-Agents.
doVer	Zeichenfolge	Gerät an Cloud	Version des Übermittlungsoptimierungs-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. Kunden können sich entscheiden, die Versionsberichterstellung zu deaktivieren, indem sie den Wert auf 0 (FALSE) festlegen. Anpassen der Eigenschaften des Übermittlungsoptimierungs-Agents.
Benutzerdefinierte Kompatibilitätseigenschaften	Benutzerdefiniert	Gerät an Cloud	Implementierer können andere Geräteeigenschaften definieren, die für die Kompatibilitätsprüfung verwendet werden sollen, wenn die Updatebereitstellung als Ziel verwendet wird.

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.

State

Das Status-Feld gibt den Status an, der vom Device Update-Agent gemeldet wird, nachdem eine Aktion vom Device Update-Dienst empfangen wurde. „Status“ wird als Antwort auf eine Aktion gemeldet (siehe Abschnitt „Aktion“), die über den Device Update-Dienst an den Device Update-Agent gesendet wird. Weitere Informationen zu Anforderungen, die zwischen dem Device Update-Dienst und dem Device Update-Agent fließen, finden Sie unter Device Update-Agent.

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	Ein erfolgreicher Download. Dieser Status wird nur von Geräten mit Agent-Version 0.7.0 oder früher gemeldet.
InstallSucceeded	4	Eine erfolgreiche Installation. Dieser Status wird nur von Geräten mit Agent-Version 0.7.0 oder früher gemeldet.

Dienstmetadaten

Dienstmetadaten enthalten Felder, die von den Device Update-Diensten 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 im Abschnitt Aktion.
updateManifest	Zeichenfolge	Cloud zu Gerät	Wird verwendet, um den Inhalt eines Updates zu beschreiben. Wird aus dem Importmanifest generiert.
updateManifestSignature	JSON-Objekt	Cloud zu Gerät	Eine JSON Web Signature (JWS) mit JSON Web Keys, die für die Quellüberprüfung verwendet werden.
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.

Aktion

Das Feld Aktion stellt die Aktionen dar, die vom Device Update-Agent ausgeführt werden, 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 Device Update-Agent.

Name	Wert	BESCHREIBUNG
applyDeployment	3	Anwenden des Updates. Signalisiert dem Gerät, das bereitgestellte Update anzuwenden
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. Diese Aktion wird nur an Geräte mit Agent-Version 0.7.0 oder früher gesendet.
apply	2	Finalisieren des Updates. Weist das System an,einen Neustart auszuführen,wenn erforderlich. Diese Aktion wird nur an Geräte mit Agent-Version 0.7.0 oder früher gesendet.

Geräteinformationsschnittstelle

Die Geräteinformationsschnittstelle ist ein Konzept, das in der IoT Plug & Play-Architektur verwendet wird. Sie enthält Gerät-zu-Cloud-Eigenschaften, die Informationen zur Hardware und zum Betriebssystem des Geräts bereitstellen. Device Update for IoT Hub verwendet die Eigenschaften DeviceInformation.manufacturer und DeviceInformation.model für Telemetrie und Diagnose. Weitere Informationen bietet Ihnen dieses Beispiel der Geräteinformationsschnittstelle.

Der erwartete Komponentenname im Modell ist deviceInformation, wenn diese Schnittstelle implementiert wird. Weitere Informationen zu Azure IoT Plug & Play-Komponenten

Name	type	Schema	Direction	BESCHREIBUNG	Beispiel
Hersteller	Eigenschaft	Zeichenfolge	Gerät an Cloud	Firmenname des Geräteherstellers. Diese Eigenschaft kann mit dem Namen des OEM (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

Nächste Schritte

• Grundlegendes zur Konfigurationsdatei des Device Update-Agents

• Grundlegendes zum Device Update for Azure IoT Hub-Agent