Verstehen und Verwenden von Deltaupdates in Device Update for IoT Hub (Vorschau)

Artikel
06/01/2023

Mit Deltaupdates können Sie ein kleines Update generieren, das nur die Änderungen zwischen zwei vollständigen Updates darstellt – ein Quellimage und ein Zielimage. Dieser Ansatz ist ideal, um die Bandbreite für das Herunterladen eines Updates auf ein Gerät zu reduzieren, insbesondere wenn es nur wenige Änderungen zwischen dem Quell- und dem Zielupdate gibt.

Hinweis

Das Feature „Deltaupdate“ ist zurzeit als öffentliche Vorschauversion verfügbar.

Anforderungen für die Verwendung von Deltaupdates in Device Update for IoT Hub

Die Quell- und Zielupdatedateien müssen im SWUpdate-Format (SWU) vorliegen.
In jeder SWUpdate-Datei muss ein Rohimage vorhanden sein, das das Ext2-, Ext3- oder Ext4-Dateisystem verwendet. Dieses Image kann mit gzip oder zstd komprimiert werden.
Der Deltagenerierungsprozess komprimiert das SWU-Zielupdate mithilfe von zstd-Komprimierung erneut, um ein optimales Delta zu generieren. Importieren Sie dieses neu komprimierte Ziel-SWU-Update zusammen mit der generierten Delta-Update-Datei in den Geräteupdatedienst.
Innerhalb von SWUpdate auf dem Gerät muss auch zstd-Dekomprimierung aktiviert sein.
- Dieser Vorgang erfordert die Verwendung von SWUpdate 2019.11 oder höher.

Konfigurieren eines Geräts mit dem Device Update-Agent und einer Deltaprozessorkomponente

Damit Ihr Gerät Deltaupdates aus dem Device Update-Dienst herunterladen und installieren kann, müssen mehrere Komponenten vorhanden und konfiguriert sein.

Device Update-Agent

Der Device Update-Agent orchestriert den Updateprozess auf dem Gerät, einschließlich Download-, Installations- und Neustartaktionen. Fügen Sie den Device Update-Agent einem Gerät hinzu, und konfigurieren Sie ihn für die Verwendung. Verwenden Sie Agent Version 1.0 oder höher. Anleitungen finden Sie unter Bereitstellung des Device Update-Agents.

Updatehandler

Ein Updatehandler ist in den Device Update-Agent integriert, um die eigentliche Updateinstallation durchzuführen. Beginnen Sie bei Deltaupdates mit dem microsoft/swupdate:2Updatehandler, wenn Sie noch nicht über einen eigenen SWUpdate-Updatehandler verfügen, den Sie ändern möchten. Wenn Sie Ihren eigenen Updatehandler verwenden, müssen Sie zstd-Dekomprimierung in SWUpdate aktivieren.

Deltaprozessor

Der Deltaprozessor erstellt die ursprüngliche SWU-Imagedatei auf Ihrem Gerät neu, nachdem die Deltadatei heruntergeladen wurde, damit Ihr Update-Handler die SWU-Datei installieren kann. Der Code des Deltaprozessors ist im Azure/iot-hub-device-update-delta-GitHub-Repository verfügbar.

Um Ihrem Geräteimage die Komponente „Deltaprozessor“ hinzuzufügen und sie für die Verwendung zu konfigurieren, folgen Sie den Anweisungen in „README.md“ zum Erstellen des Deltaprozessors anhand des Quellcodes mit CMAKE. Installieren Sie dort das freigegebene Objekt (libadudiffapi.so) direkt, indem Sie es in das Verzeichnis /usr/lib kopieren:

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

Hinzufügen einer SWU-Quellimagedatei zu Ihrem Gerät

Nachdem ein Delta-Update auf ein Gerät heruntergeladen wurde, muss es mit einer gültigen SWU-Quelldatei verglichen werden, die zuvor auf dem Gerät zwischengespeichert wurde. Dieser Vorgang wird für das Delta-Update benötigt, um das vollständige Zielimage neu zu erstellen. Die einfachste Möglichkeit zum Auffüllen dieses zwischengespeicherten Images mit Daten besteht darin, ein vollständiges Imageupdate auf dem Gerät über den Device Update-Dienst bereitzustellen (unter Verwendung der vorhandenen Import- und Bereitstellungsprozesse). Solange das Gerät mit dem Device Update-Agenten (Version 1.0 oder höher) und dem Deltaprozessor konfiguriert ist, speichert der Device Update-Agent die installierte SWU-Datei automatisch für die spätere Verwendung des Delta-Updates.

Wenn Sie stattdessen das Quellimage direkt auf Ihrem Gerät vorausfüllen möchten, lautet der Pfad, in dem das Image erwartet wird:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Standardmäßig ist BASE_SOURCE_DOWNLOAD_CACHE_PATH der Pfad /var/lib/adu/sdc/[provider]. Der [provider]-Wert ist der Anbieterteil der updateId für die SWU-Quelldatei.

ENCODED_HASH ist die hexadezimale base64-Zeichenfolge des SHA256-Hashwerts der Binärdatei, aber nach der Codierung in einer hexadezimalen base64-Zeichenfolge werden die Zeichen wie folgt codiert:

+ codiert als octets _2B
/ codiert als octets _2F
= codiert als octets _3D

Generieren von Deltaupdates mithilfe des DiffGen-Tools

Umgebungsvoraussetzungen

Vor dem Erstellen von Deltas mit DiffGen müssen mehrere Komponenten heruntergeladen und/oder auf dem Umgebungscomputer installiert werden. Wir empfehlen eine Linux-Umgebung und speziell Ubuntu 20.04 (oder Windows-Subsystem für Linux, falls systemintern unter Windows).

Die folgende Tabelle enthält eine Liste der benötigten Inhalte, ihres Abruforts und der empfohlenen Installation, wenn erforderlich:

Name der Binärdatei	Abrufort	So führen Sie die Installation durch
DiffGen	GitHub-Repository Azure/iot-hub-device-update-delta	Wählen Sie im Stammordner die Datei Microsoft.Azure.DeviceUpdate.Diffs.[version].nupkg aus. Erfahren Sie mehr über NuGet-Pakete.
.NETCore Runtime-Version 6.0.0	Über Terminal/Paket-Manager	Anleitungen für Linux. Nur die Runtime ist erforderlich.

Abhängigkeiten

Das zstd_compression_tool wird verwendet, um die Imagedateien eines Archivs zu dekomprimieren und mit zstd erneut zu komprimieren. Dadurch wird sichergestellt, dass alle Archivdateien, die für die Generierung des Deltas verwendet werden, über denselben Komprimierungsalgorithmus für die Images in den Archiven verfügen.

Befehle zum Installieren der erforderlichen Pakete/Bibliotheken:

sudo apt update  
sudo apt-get install -y python3 python3-pip  
sudo pip3 install libconf zstandard

Erstellen eines Deltaupdates mithilfe von DiffGen

Das DiffGen-Tool wird mit mehreren Argumenten ausgeführt. Alle Argumente sind erforderlich, und die Gesamtsyntax lautet wie folgt:

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive]

Das Skript „recompress_tool.py“ wird ausgeführt, um die Datei „[recompressed_target_archive]“ zu erstellen, die dann anstelle von „[target_archive]“ als Zieldatei zum Erstellen des Diff verwendet wird.
Die Imagedateien in „[recompressed_target_archive]“ werden mit zstd komprimiert.

Wenn Ihre SWU-Dateien signiert sind (was wahrscheinlich ist), benötigen Sie noch ein weiteres Argument:

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive] "[signing_command]"

Zusätzlich zur Verwendung von „[recompressed_target_archive]“ als Zieldatei führt die Bereitstellung eines Signaturbefehl-Zeichenfolgenparameters „recompress_and_sign_tool.py“ aus, um die Datei „[recompressed_target_archive]“ zu erstellen und die Datei „sw-description“ im Archiv zu signieren (was bedeutet, dass eine Datei „sw-description.sig“ vorhanden ist). Sie können das Beispielskript sign_file.sh aus dem GitHub-Repository Azure/iot-hub-device-update-delta verwenden. Öffnen Sie das Skript, bearbeiten Sie es, um den Pfad zu Ihrer Datei mit dem privaten Schlüssel hinzuzufügen, und speichern Sie es anschließend. Beispiele für die Verwendung finden Sie im Abschnitt Beispiele.

In der folgenden Tabelle werden die Argumente ausführlicher beschrieben.

Argument	BESCHREIBUNG
[source_archive]	Dies ist das Image, auf dem das Delta bei der Erstellung des Deltas basiert. Wichtig: Dieses Image muss mit dem Image identisch sein, das bereits auf dem Gerät vorhanden ist (z. B. zwischengespeichert von einem vorherigen Update).
[target_archive]	Dies ist das Image, auf das das Delta das Gerät aktualisiert.
[output_path]	Der Pfad (einschließlich des gewünschten Namens der Deltadatei, die generiert wird) auf dem Hostcomputer, in dem die Deltadatei nach der Erstellung platziert wird. Wenn der Pfad nicht vorhanden ist, erstellt es das Tool.
[log_folder]	Der Pfad auf dem Hostcomputer, in dem Protokolle erstellt werden. Es wird empfohlen, diesen Speicherort als Unterordner des Ausgabepfads zu definieren. Wenn der Pfad nicht vorhanden ist, erstellt es das Tool.
[working_folder]	Der Pfad auf dem Computer, in dem während der Deltagenerierung Neben- und andere Arbeitsdateien platziert werden. Es wird empfohlen, diesen Speicherort als Unterordner des Ausgabepfads zu definieren. Wenn der Pfad nicht vorhanden ist, erstellt es das Tool.
[recompressed_target_archive]	Der Pfad auf dem Hostcomputer, in dem die erneut komprimierte Zieldatei erstellt wird. Diese Datei wird anstelle von <target_archive> als Zieldatei für die Diff-Generierung verwendet. Wenn dieser Pfad vor dem Aufrufen von DiffGenTool vorhanden ist, wird der Pfad überschrieben. Es wird empfohlen, diesen Pfad als Datei im Unterordner des Ausgabepfads zu definieren.
"[signing_command]" (optional)	Ein anpassbarer Befehl, der zum Signieren der Datei „sw-description“ in der erneut komprimierten Archivdatei verwendet wird. Die Datei „sw-description“ im erneut komprimierten Archiv wird als Eingabeparameter für den Signaturbefehl verwendet. DiffGenTool erwartet, dass der Signaturbefehl eine neue Signaturdatei unter Verwendung des Namens der Eingabe mit angefügter Erweiterung `.sig` erstellt. Das Einschließen des Parameters in doppelte Anführungszeichen ist erforderlich, damit der gesamte Befehl als einzelner Parameter übergeben wird. Vermeiden Sie außerdem, das Zeichen „~“ in einem Schlüsselpfad, der zum Signieren verwendet wird, und verwenden Sie stattdessen den vollständigen home-Pfad (verwenden Sie z. B. „/home/USER/keys/priv.pem“ anstelle von „~/keys/priv.pem“).

DiffGen-Beispiele

In diesen Beispielen operieren wir aus dem Verzeichnis /mnt/o/temp (in WSL):

Erstellen eines Deltas zwischen der Eingabequelldatei und der erneut komprimierten Zieldatei:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]  
/mnt/o/temp/[target file.swu]  
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]

Wenn Sie auch den Signaturparameter verwenden (erforderlich, wenn Ihre SWU-Datei signiert ist), können Sie das zuvor erwähnte sign_file.sh-Beispielskript aus dem GitHub-Repository nutzen. Öffnen Sie zunächst das Skript, und bearbeiten Sie es, um den Pfad zu Ihrer Datei mit dem privaten Schlüssel hinzuzufügen. Speichern Sie das Skript, und führen Sie DiffGen dann wie folgt aus:

Erstellen eines Deltas zwischen der Eingabequelldatei und der erneut komprimierten/signierten Zieldatei:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]
/mnt/o/temp/[target file.swu]   
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]  
/mnt/o/temp/[path to script]/sign_file.sh

Importieren des generierten Deltaupdates

Der grundlegende Prozess des Importierens eines Updates in den Device Update-Dienst ist für Deltaupdates unverändert. Lesen Sie also diese Seite, wenn dies noch nicht geschehen ist: Vorbereiten eines Updates für den Import in Azure Device Update for IoT Hub.

Generieren des Importmanifests

Der erste Schritt zum Importieren eines Updates in den Device Update-Dienst besteht immer darin, ein Importmanifest zu erstellen, wenn Sie noch nicht über ein solches verfügen. Weitere Informationen zu Importmanifesten finden Sie unter Importieren von Updates in Device Update. Für Deltaupdates muss Ihr Importmanifest auf zwei Dateien verweisen:

Das erneut komprimierte SWU-Zielimage, das beim Ausführen des DiffGen-Tools erstellt wurde.
Die Deltadatei, die beim Ausführen des DiffGen-Tools erstellt wurde.

Das Deltaupdatefeature verwendet eine Funktion namens Zugehörige Dateien, die ein Importmanifest mit Version 5 oder höher erfordert.

Um ein Importmanifest für Ihr Delta-Update mithilfe der Funktion für zugehörige Dateien zu erstellen, müssen Sie Ihrem Importmanifest die Objekte relatedFiles und downloadHandler hinzufügen.

Verwenden Sie das Objekt relatedFiles, um Informationen zur Deltaupdatedatei anzugeben, einschließlich Dateiname, Dateigröße und SHA256-Hash. Wichtig ist, dass Sie auch zwei Eigenschaften angeben müssen, die für das Deltaupdatefeature eindeutig sind:

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "[insert the source SWU image file hash]"
}

Diese beiden Eigenschaften sind spezifisch für Ihre SWU-Quelldatei, die Sie bei der Erstellung Ihres Delta-Updates als Eingabe für das DiffGen-Tool verwendet haben. Die Informationen zum SWU-Quellimage werden im Importmanifest benötigt, auch wenn Sie das Quellimage nicht tatsächlich importieren. Die Deltakomponenten auf dem Gerät verwenden diese Metadaten über das Quellimage, um das Bild auf dem Gerät zu finden, sobald das Delta heruntergeladen ist.

Verwenden Sie das Objekt downloadHandler, um anzugeben, wie der Device Update-Agent das Deltaupdate mithilfe des Features „Zugehörige Dateien“ orchestriert. Sofern Sie nicht Ihre eigene Version des Device Update-Agenten für die Deltafunktionalität anpassen, sollten Sie nur diesen downloadHandler verwenden:

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

Sie können die Azure-Befehlszeilenschnittstelle (CLI) verwenden, um ein Importmanifest für Ihr Deltaupdate zu generieren. Wenn Sie die Azure CLI noch nicht zum Erstellen eines Importmanifests verwendet haben, finden Sie weitere Informationen unter Erstellen eines einfachen Importmanifests.

az iot du update init v5
--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 den generierten JSON-Importmanifestcode in einer Datei mit der Erweiterung .importmanifest.json.

Importieren über das Azure-Portal

Sobald Sie Ihr Importmanifest erstellt haben, können Sie das Delta-Update importieren. Befolgen Sie zum Importieren die Anleitungen unter Hinzufügen eines Updates zu Device Update for IoT Hub. Sie müssen die folgenden Elemente beim Importieren einschließen:

Die JSON-Importmanifestdatei, die Sie im vorherigen Schritt erstellt haben.
Das erneut komprimierte SWU-Zielimage, das beim Ausführen des DiffGen-Tools erstellt wurde.
Die Deltadatei, die beim Ausführen des DiffGen-Tools erstellt wurde.

Bereitstellen des Deltaupdates auf Ihren Geräten

Wenn Sie ein Deltaupdate bereitstellen, sieht die Benutzeroberfläche im Azure-Portal identisch wie bei der Bereitstellung eines regulären Imageupdates aus. Weitere Informationen zum Bereitstellen von Updates finden Sie unter Bereitstellen eines Updates mithilfe von Device Update for Azure IoT Hub.

Sobald Sie die Bereitstellung für Ihr Delta-Update erstellt haben, erkennen der Geräteaktualisierungsdienst und der Client automatisch, ob ein gültiges Delta-Update für jedes Gerät vorliegt, auf das Sie die Bereitstellung vornehmen. Wenn ein gültiges Delta gefunden wird, wird das Delta-Update heruntergeladen und auf diesem Gerät installiert. Wenn kein gültiges Delta-Update gefunden wird, wird stattdessen das vollständige Image-Update (das neu komprimierte Ziel-SWU-Image) als Ausweichlösung heruntergeladen. Auf diese Weise stellen Sie sicher, dass alle Geräte, auf denen Sie das Update verteilen, die richtige Version erhalten.

Es gibt drei mögliche Ergebnisse für eine Deltaupdatebereitstellung:

Das Deltaupdate wurde erfolgreich installiert. Das Gerät weist die neue Version auf.
Das Deltaupdate war nicht verfügbar oder konnte nicht installiert werden, aber stattdessen ist eine erfolgreiche Fallbackinstallation des vollständigen Images erfolgt. Das Gerät weist die neue Version auf.
Fehler bei Deltaupdate und Fallback auf vollständiges Image. Das Gerät verwendet noch die alte Version.

Um zu bestimmen, welches der oben genannten Ergebnisse aufgetreten ist, können Sie die Installationsergebnisse mit Fehlercode und erweitertem Fehlercode anzeigen, indem Sie ein beliebiges Gerät auswählen, das einen fehlerhaften Zustand aufweist. Sie können bei Bedarf auch Protokolle von mehreren fehlerhaften Geräten sammeln.

Wenn das Deltaupdate erfolgreich ist, zeigt das Gerät den Status „Erfolgreich“ an.

Wenn beim Deltaupdate ein Fehler aufgetreten ist, aber ein erfolgreiches Fallback auf das vollständige Image durchgeführt wurde, wird der folgende Fehlerstatus angezeigt:

resultCode: [Wert größer als 0]
extendedResultCode: [ungleich 0]

Wenn die Aktualisierung nicht erfolgreich war, wird ein Fehlerstatus angezeigt, der anhand dieser Anweisungen interpretiert werden kann:

Beginnen Sie mit den Device Update-Agent-Fehlern in result.h.

Fehler vom Device Update-Agent, die spezifisch für die Downloadhandlerfunktionalität sind, die für Deltaupdates verwendet wird, beginnen mit 0x9:

Komponente	Decimal	Hex	Hinweis
EXTENSION_MANAGER	0	0x00	Gibt Fehler aus der Downloadhandlerlogik des Erweiterungs-Managers an. Beispiel: 0x900XXXXX
PLUGIN	1	0x01	Gibt Fehler bei der Verwendung freigegebener Bibliotheken des Downloadhandler-Plug-Ins an. Beispiel: 0x901XXXXX
RESERVIERT	2–7	0x02 bis 0x07	Reserviert für Downloadhandler. Beispiel: 0x902XXXXX
COMMON	8	0x08	Gibt Fehler in der Logik der Deltadownloadhandler-Erweiterung auf oberster Ebene an. Beispiel: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Gibt Fehler im Quellupdatecache der Deltadownloadhandler-Erweiterung an. Beispiel: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Fehlercode für Fehler der Deltaprozessor-API. Beispiel: 0x90AXXXXXXX

Wenn der Fehlercode in result.h nicht vorhanden ist, handelt es sich wahrscheinlich um einen Fehler in der Deltaprozessorkomponente (getrennt vom Device Update-Agent). Wenn ja, ist der extendedResultCode ein negativer dezimaler Wert im folgenden hexadezimalen Format: 0x90AXXXXX
- 9 ist „Deltafunktion“.
- 0A ist „Deltaprozessorkomponente“ (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX ist der 20-Bit-Fehlercode vom FIT-Deltaprozessor.

Wenn Sie das Problem nicht basierend auf den Fehlercodeinformationen lösen können, melden Sie ein GitHub-Issue, um weitere Unterstützung zu erhalten.

Nächste Schritte

Häufig auftretende Probleme und Problembehandlung