Bereitstellen von Delta-Updates auf Geräten

In diesem Artikel wird gezeigt, wie Delta-Updatedateien generiert, in Azure Geräteupdate für IoT Hub importiert und auf Geräten bereitgestellt werden. Delta-Dateien können entweder mithilfe des DiffGen-Tools oder als Teil eines Yocto-basierten Builds generiert werden. Eine Übersicht finden Sie unter Azure Device Update für IoT Hub-Deltaupdates.

Voraussetzungen

• Ein Azure Geräteupdate für IoT Hub Konto und Instanz.
• Ein IoT-Gerät oder -Simulator, das bzw. der für Geräteupdate bereitgestellt wurde und in das bzw. den die Agentreferenzimplementierung in Version 1.3.0 oder höher integriert ist. Anweisungen finden Sie unter Geräteupdate-Agent-Bereitstellung.
• Quell- und Zielaktualisierungsdateien im SWUpdate -Format (SWU) mit einem rohen Bild innerhalb. Das Microsoft Referenzbeispiel verwendet das Ext4 Dateisystem, aber Ext2 und Ext3 werden ebenfalls unterstützt.

Konfigurieren des Geräts

Um Delta-Updates anzuwenden, benötigt das Gerät den Geräteupdate-Agent mit einem kompatiblen Updatehandler und der installierten Delta-Prozessorerweiterung. In den folgenden Abschnitten wird beschrieben, wie jede Komponente eingerichtet wird.

Update-Handler

Der Updatehandler ist in den Geräteupdate-Agent integriert, um die tatsächliche Updateinstallation auf dem Gerät auszuführen.

Beginnen Sie für Delta-Updates mit dem microsoft/swupdate:2 update handler wenn Sie noch keinen benutzerdefinierten SWUpdate-Updatehandler haben.

Delta-Prozessorerweiterung

Die Delta-Prozessorerweiterung rekonstruiert das vollständige Zielupdate auf dem Gerät, indem das heruntergeladene Delta-Update mit dem Quellupdate bereits auf dem Gerät kombiniert wird. Der Updatehandler installiert dann das rekonstruierte Update.

Es gibt zwei Möglichkeiten zum Installieren der Delta-Prozessorerweiterung. Beide Optionen führen dazu, dass die Erweiterung auf dem Gerät verfügbar ist – der Unterschied besteht darin, ob Sie sie direkt auf dem Gerät installieren oder während des Geräteimagebuilds einschließen.

• Option 1: Installieren Sie die Erweiterung direkt auf dem Gerät. Dies ist der häufigste Ansatz, wenn Sie ein vordefiniertes Betriebssystem verwenden oder mit einem vorhandenen Gerät arbeiten.
• Option 2: Schließen Sie die Erweiterung als Teil Ihres Geräteimagebuilds ein. Diese Option gilt, wenn Sie bereits eigene Geräteimages erstellen und verwalten (z. B. mit Yocto).

Option 1: Installieren der Erweiterung auf dem Gerät

Verwenden Sie diese Option, wenn Sie die Delta-Prozessorerweiterung auf einem vorhandenen Gerät installieren möchten. Dieser Ansatz wird empfohlen, wenn Sie ein vordefiniertes Betriebssystem verwenden oder ihr Geräteimage nicht ändern.

Laden Sie die Delta-Prozessorerweiterung aus dem Repository Azure/iot-hub-device-update-delta herunter.

Vorgefertigte Pakete sind unter der Version 3.0.0 verfügbar. Wählen Sie das Paket aus, das dem Betriebssystem und der Architektur Ihres Geräts entspricht.

Installieren Sie für Ubuntu 20.04 und höher das Debian-Paket direkt.

Wenn ein vordefiniertes Paket für Ihre Plattform nicht verfügbar ist, befolgen Sie die Build- und Installationsanweisungen im Repository README, um die Erweiterung aus der Quelle zu erstellen.

Kopieren Sie nach dem Erstellen der Bibliothek die Shared-Object-Datei libadudiffapi.so nach /usr/lib und aktualisieren Sie den Cache der Systembibliotheken:

sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig

Option 2: In einen Yocto-Build integrieren

Verwenden Sie diese Option, wenn Sie Ihr eigenes Geräteimage erstellen und möchten, dass die Delta-Prozessorerweiterung als Teil dieses Images enthalten sein soll.

Bei diesem Ansatz wird die Erweiterung während des Imagebuilds installiert, sodass Sie sie nicht separat auf dem Gerät installieren müssen.

Um die Delta-Updateunterstützung in Ihren Build zu integrieren, verwenden Sie die Yocto-Layer, die im iot-hub-device-update-yocto repository bereitgestellt werden.

Ausführliche Informationen zu den verfügbaren Ebenen und deren Einbeziehung in Ihren Build finden Sie im Abschnitt Microsoft bereitgestellten Yocto-Ebenen.

Informationen dazu, wie Delta-Komponenten als Teil der Buildausgabe gepackt und zur Verfügung gestellt werden, finden Sie unter Delta-Toolsverteilung.

Nachdem Sie das Image mit diesen Ebenen erstellt haben, ist die Delta-Prozessorerweiterung bereits auf dem Gerät verfügbar, und es sind keine zusätzlichen Installationsschritte erforderlich.

Nach Abschluss einer der beiden Möglichkeiten ist die Delta-Prozessor-Erweiterung auf dem Gerät installiert und bereit, während der Bereitstellung Delta-Updates zu rekonstruieren.

Bereiten Sie die Quellaktualisierung auf dem Gerät vor.

Für ein Delta-Update muss ein gültiges Quellupdate auf dem Gerät verfügbar sein. Während der Installation wird das Delta-Update mit dem Quellupdate auf dem Gerät kombiniert, um das vollständige Zielupdate zu rekonstruieren.

Die einfachste Möglichkeit, das Quellupdate auf dem Gerät verfügbar zu machen, besteht darin, ein vollständiges Update über den Geräteupdatedienst zu importieren und bereitzustellen . Wenn das Gerät das Update installiert, speichert der Geräteupdate-Agent es automatisch für die Verwendung mit zukünftigen Delta-Updates zwischen.

Dieses Verhalten ist unabhängig davon, wie Sie die Delta-Prozessorerweiterung installieren. Wenn Sie z. B. ein Yocto-basiertes Image verwenden, wird das installierte Update nach der Bereitstellung immer noch automatisch zwischengespeichert, sodass keine zusätzlichen Schritte erforderlich sind.

Wenn Sie das Quellupdate manuell vorstufen müssen, anstatt sich auf den Cache zu verlassen, platzieren Sie das Bild unter: <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>

Ort:

• <BASE_SOURCE_DOWNLOAD_CACHE_PATH> ist der Basisverzeichnispfad, der für zwischengespeicherte Quellupdates verwendet wird. Standardmäßig ist dieser Pfad /var/lib/adu/sdc/<provider>.

• <provider> ist der provider Wert der Aktualisierungsidentität der SWU-Quelldatei.

• <ENCODED_HASH> ist der base64-codierte SHA256-Hash des Quellimages mit den folgenden Ersetzungen:

Generieren einer Delta-Updatedatei

Generieren Sie Delta-Updatedateien mithilfe von DiffGen, einem Microsoft bereitgestellten Referenztool, das auf einem Buildcomputer ausgeführt wird.

DiffGen verwendet eine SWU-Quelldatei und eine Ziel-SWU-Datei als Eingaben, komprimiert das Ziel mithilfe von gzip und erzeugt eine Delta-Updatedatei, die nur die Unterschiede zwischen den beiden enthält.

Es gibt zwei Möglichkeiten zum Generieren von Delta-Updatedateien:

• Option 1: Herunterladen und Ausführen von DiffGen auf einem Buildcomputer
• Option 2: Verwenden von Deltagenerierungstools aus einem Yocto-Build

Option 1: Manuelles Herunterladen und Ausführen von DiffGen

Verwenden Sie diese Option, wenn Sie Delta-Updates auf einem separaten Entwicklungs- oder Buildcomputer generieren.

Laden Sie das DiffGen-Tool aus dem repository Azure/iot-hub-device-update-delta herunter.

Vordefinierte Binärdateien sind in der version 3.0.0 verfügbar. Wählen Sie die Version aus, die dem Betriebssystem und der Architektur Ihres Buildcomputers entspricht.

Weitere Informationen zum DiffGen-Tool und deren Verwendung finden Sie im Abschnitt Diff Generation (DiffGen) im Repository.

Führen Sie DiffGen auf einem Buildcomputer aus. Ubuntu 20.04 oder 22.04 (oder Windows-Subsystem für Linux) wird empfohlen.

Bevor Sie DiffGen ausführen, installieren Sie Folgendes auf Ihrem Buildcomputer:

Option 2: Verwenden von DiffGen aus einem Yocto-Build

Verwenden Sie diese Option, wenn Sie Ihr Geräteimage mit Yocto erstellen und die im Rahmen dieses Builds generierten Tools verwenden möchten.

Während eines Yocto-basierten Builds werden das DiffGen-Tool und zugehörige Komponenten zusammen mit dem Geräteimage erstellt. Sie können diese Tools auf einem kompatiblen Buildhost packen und ausführen.

Informationen zu den ersten Schritten finden Sie im Repository iot-hub-device-update-yocto, das die erforderlichen Ebenen und Buildkonfigurationen bereitstellt.

Ausführliche Informationen zum Packen und Verwenden der generierten Tools finden Sie unter Delta tools distribution.

DiffGen ausführen

Führen Sie diffGen nach der Installation der Abhängigkeiten mithilfe der folgenden Syntax aus:

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive>

Dieser Befehl führt das recompress_tool.py-Skript aus, das die <recompressed_target_archive> erstellt. DiffGen verwendet beim Generieren des Delta-Updates das neu komprimierte Archiv anstelle von <target_archive>. Bilddateien im rekomprimierten Archiv werden mithilfe von gzip komprimiert.

Wenn Ihre SWU-Dateien signiert sind, schließen Sie das <signing_command> Argument ein:

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"

Wenn Sie einen Signaturbefehl bereitstellen, führt DiffGen das recompress_and_sign_tool.py Skript aus. Dieses Skript erstellt das <recompressed_target_archive> und signiert die darin enthaltene sw-description-Datei, wodurch eine sw-description.sig-Datei erzeugt wird.

Verwenden Sie das Beispielskript sign_file.sh aus dem Repository Azure/iot-hub-device-update-delta, um ein Delta-Update zwischen einer Quelldatei und einer neu komprimierten und erneut signierten Zieldatei zu generieren. Aktualisieren Sie das Skript so, dass er den Pfad zu Ihrem privaten Schlüssel enthält, und führen Sie es dann als Teil des DiffGen-Befehls aus. Informationen zur Verwendung finden Sie im Abschnitt „Beispiele“.

DiffGen-Argumente

DiffGen-Beispiele

In den folgenden Beispielen wird ein Arbeitsverzeichnis von /mnt/o/temp in Windows-Subsystem für Linux vorausgesetzt.

Erstellen eines Delta-Updates:

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu
/mnt/o/temp/<delta file to create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu

Erstellen Sie ein Delta-Update mit Signatur:

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu   
/mnt/o/temp/<delta file to create>  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/<recompressed target file to create>.swu  
/mnt/o/temp/<path to script>/<sign_file>.sh

Importieren Sie das Delta-Update

Der grundlegende Prozess zum Importieren eines Delta-Updates in den Geräteupdatedienst entspricht dem Importieren anderer Updates. Hintergrundinformationen finden Sie unter So bereiten Sie ein Update für den Import in Azure Device Update for IoT Hub vor.

Generieren des Importmanifests

Um ein Update in den Device Update-Dienst zu importieren, müssen Sie über eine Importmanifestdatei verfügen oder diese erstellen. Weitere Informationen finden Sie unter Importieren von Updates in Device Update.

Für Delta-Updates muss das Importmanifest auf die folgenden Dateien verweisen, die vom DiffGen-Tool erstellt wurden:

• Das <recompressed_target_file> SWU-Image
• Der <delta file>

Delta-Updates verwenden eine Funktion namens verwandte Dateien, für die ein Importmanifest der Version 5 oder höher erforderlich ist. Um dieses Feature zu verwenden, schließen Sie sowohl die relatedFiles - als auch downloadHandler-Objekte in Ihr Manifest ein.

Sie verwenden das relatedFiles-Objekt, um Informationen zur Delta-Updatedatei anzugeben, darunter Dateiname, Dateigröße und SHA256-Hash. Vor allem müssen Sie auch die folgenden zwei speziellen Eigenschaften des Features für Delta-Updates angeben:

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "<source SWU image file hash>"
}

Beide Eigenschaften beziehen sich auf das Quellupdate, das beim Generieren des Delta-Updates als Eingabe für das DiffGen-Tool verwendet wird. Das Importmanifest erfordert diese Informationen, auch wenn die Quell-SWU-Datei nicht im Import enthalten ist.

Die Delta-Komponenten auf dem Gerät verwenden diese Metadaten zum Quellimage, um das Bild auf dem Gerät nach dem Herunterladen des Delta-Updates zu suchen.

Verwenden Sie Folgendes downloadHandler, es sei denn, Ihre Implementierung des Device Update-Agents wurde so geändert, dass sich das erwartete Verhalten beim Delta-Download und bei der Installation ändert:

"downloadHandler": {
  "id": "microsoft/delta:1"
}

Generieren des Importmanifests mithilfe des Azure CLI

Sie können den Befehl az iot du update init v5 der Azure-Befehlszeilenschnittstelle (Command Line Interface, CLI) verwenden, um ein Importmanifest für Ihr Delta-Update zu generieren. Weitere Informationen finden Sie unter Erstellen eines einfachen Importmanifests.

--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}' 

Speichern Sie Das generierte Importmanifest JSON mit der Dateierweiterung *.importmanifest.json.

Importieren über das Azure-Portal

Nachdem Sie Ihr Importmanifest erstellt haben, importieren Sie das Delta-Update, indem Sie die Anweisungen in Add an update to Device Update for IoT Hub folgen.

Fügen Sie die folgenden Elemente in den Import ein:

• Die *.importmanifest.json-Datei.
• Das <recompressed_target_file> von DiffGen erstellte SWU-Bild
• Die von DiffGen erstellte <delta file>

Bereitstellen des Delta-Updates

Die Bereitstellung eines Delta-Updates folgt demselben Prozess wie die Bereitstellung eines vollständigen Imageupdates. Schrittweise Anleitungen finden Sie unter Bereitstellen eines Updates mithilfe von Geräteupdates.

Um Geräte mit unterschiedlichen Startversionen zu unterstützen, schließen Sie ein Delta-Update für jede Quellversion ein, die Sie unterstützen möchten, sowie das vollständige Zielupdate.

Beispiel:

• Ein v1-→ v3-Delta-Update
• Ein v2-→ v3-Delta-Update
• Vollständiges v3-Update

Nachdem Sie eine Bereitstellung erstellt haben, bestimmen der Geräteupdatedienst und der Client automatisch, ob für jedes Gerät ein gültiges Delta-Update verfügbar ist.

• Wenn ein gültiges Delta gilt (z. B. Geräte auf v1 oder v2), lädt das Gerät das Delta-Update herunter und installiert es.
• Wenn kein gültiges Delta verfügbar ist (z. B. Geräte auf v0), lädt das Gerät das vollständige Update herunter und installiert es (stattdessen das rekomprimierte SWU-Zielimage).

Dieses Verhalten stellt sicher, dass alle Geräte auf die Zielversion aktualisieren können, auch wenn kein übereinstimmende Delta-Update verfügbar ist.

Bereitstellungsergebnisse

Nach der Bereitstellung tritt eines der folgenden Ergebnisse auf:

• Das Delta-Update wird erfolgreich installiert, und das Gerät wird auf die Zielversion aktualisiert.
• Das Delta-Update ist nicht verfügbar oder schlägt fehl, aber das fallback vollständige Update wird erfolgreich installiert.
• Sowohl das Delta-Update als auch das vollständige Fallback-Update schlagen fehl, und das Gerät bleibt auf der vorherigen Version.

Um das Ergebnis eines Geräts zu ermitteln, sehen Sie sich die Installationsergebnisse im Azure-Portal an. Überprüfen Sie bei fehlgeschlagenen Updates die resultCode und extendedResultCode.

• Wenn das Delta-Update erfolgreich ist, zeigt das Gerät den Status "Erfolgreich" an.

• Wenn das Delta-Update fehlschlägt, aber der Fallback erfolgreich ist, zeigt das Gerät einen Fehlerstatus mit:

  • resultCode: <Wert größer als 0>
  • extendedResultCode: <Wert ungleich Null>

Sie können bei Bedarf auch Protokolle von fehlgeschlagenen Geräten erfassen. Weitere Informationen finden Sie unter Sammeln von Protokollen.

Problembehandlung bei fehlgeschlagenen Updates

Bei nicht erfolgreichen Updates wird ein Fehlerstatus angezeigt, den Sie mithilfe der folgenden Anweisungen interpretieren können.

Beginnen Sie mit den Fehlerdefinitionen des Geräteaktualisierungs-Agents in result.h.

Fehler des Device Update-Agents, die sich auf die Downloadhandlerfunktion für Delta-Updates beziehen, beginnen mit 0x9:

Wenn der Fehlercode in result.h nicht vorhanden ist, stammt er wahrscheinlich aus der Delta-Prozessorerweiterung. In diesem Fall ist dies extendedResultCode ein negativer Dezimalwert im Hexadezimalformat 0x90AXXXXX, wobei:

• 9 gibt die Delta-Einrichtung an
• 0A bezeichnet die „Delta-Prozessor-Komponente“ (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
• XXXXX ist der vom Delta-Prozessor zurückgegebene 20-Bit-Fehlercode.

Wenn Sie das Problem nicht mithilfe des Fehlercodes beheben können, sammeln Sie Protokolle vom Gerät und speichern ein GitHub Problem, um weitere Unterstützung zu erhalten.

Verwandte Inhalte

• Azure Device Update für IoT Hub-Delta-Updates
• Importmanifestschema für Azure Device Update for IoT Hub
• Häufige Probleme beheben