Teilen über


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:

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