Delta-frissítések (előzetes verzió)

A Delta-frissítések lehetővé teszik, hogy olyan kis frissítéseket hozzon létre, amelyek csak a két teljes frissítés, a forráskép és a célrendszerkép közötti változásokat jelölik. Ez a módszer ideális a frissítés eszközre való letöltéséhez használt sávszélesség csökkentésére, különösen akkor, ha a forrás- és a célfrissítések között csak néhány változás van.

Az IoT Hub eszközfrissítésében a változásfrissítések használatára vonatkozó követelmények

• A forrás- és célfrissítési fájloknak SWUpdate (SWU) formátumban kell lenniük.
• Minden SWUpdate-fájlban rendelkeznie kell egy nyers képpel, amely az Ext2, az Ext3 vagy az Ext4 fájlrendszert használja.

A változásgenerálási folyamat gzip-tömörítéssel újrakompresszítja a cél SWU-frissítést az optimális változás érdekében. Importálja az újracsomagolt cél SWU-frissítést az eszközfrissítési szolgáltatásba a létrehozott deltafrissítési fájllal együtt.

Eszközfrissítési ügynök konfigurációja a deltaprocesszor-összetevőhöz

A változásfrissítések eszközfrissítési szolgáltatásból való letöltéséhez és telepítéséhez az eszköznek szüksége van az Eszközfrissítési ügynökre a frissítéskezelővel és a deltaprocesszor-összetevővel, amely jelen van és konfigurálva van.

Eszközfrissítési ügynök

Az Eszközfrissítési ügynök vezényli az eszközön a frissítési folyamatot, beleértve a letöltési, telepítési és újraindítási műveleteket. Az Eszközfrissítési ügynök eszközhöz való hozzáadásához és konfigurálásához tekintse meg az Eszközfrissítési ügynök üzembe helyezését. Használja az ügynök 1.0-s vagy újabb verzióját.

Frissítéskezelő

A frissítéskezelő integrálható az eszközfrissítési ügynökkel a tényleges frissítés telepítésének végrehajtásához. A változásfrissítések esetében kezdje a microsoft/swupdate:2 frissítéskezelővel , ha még nincs saját SWUpdate frissítéskezelője, amelyet módosítani szeretne.

Delta processzor

Az Azure/iot-hub-device-update-delta delta processzora újra létrehozza az eredeti SWU-lemezképfájlt az eszközön a deltafájl letöltése után, így a frissítéskezelő telepítheti az SWU-fájlt. Ha hozzá szeretné adni a deltaprocesszor-összetevőt az eszköz lemezképéhez, és konfigurálni szeretné, letöltheti az Ubuntu 20.04-hez és újabb https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0verziókhoz készült Debian-csomagot.

Ha egy másik disztribúciót használ, kövesse az README.md utasításokat, hogy a CMAKE-t használja a deltaprocesszor forrásból való létrehozásához. Innen közvetlenül a /usr/lib könyvtárba másolva telepítse a megosztott objektumot libadudiffapi.so az alábbiak szerint:

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

Forrás SWU-képfájl hozzáadása az eszközhöz

Miután a változásfrissítési fájl letöltődik egy eszközre, összehasonlítja a rendszer az eszközön korábban gyorsítótárazott érvényes <source_archive> fájllal. Ez a folyamat lehetővé teszi, hogy a változásfrissítés újra létrehozza a teljes célrendszerképet.

A gyorsítótárazott rendszerkép feltöltésének legegyszerűbb módja egy teljes rendszerkép-frissítés importálása és üzembe helyezése az eszközön az Eszközfrissítés szolgáltatáson keresztül. Ha az eszköz az Eszközfrissítési ügynök 1.0-s vagy újabb verziójával és a deltafeldolgozóval van konfigurálva, az ügynök automatikusan gyorsítótárazza a telepített SWU-fájlt a későbbi változásfrissítések használatához.

Ha ehelyett közvetlenül előre szeretné feltölteni a forrásrendszerképet az eszközön, a rendszerkép várható elérési útja.<BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH> Alapértelmezés szerint <BASE_SOURCE_DOWNLOAD_CACHE_PATH> a /var/lib/adu/sdc/<provider> elérési út. Az provider érték a provider forrás SWU-fájl updateId azonosítójának része.

ENCODED_HASH a bináris SHA256 alap64 hexa sztringje, de miután a base64 hexa sztringre kódolást végzett, a karaktereket a következőképpen kódolja:

• + kódolása: octets _2B
• / kódolása: octets _2F
• = kódolása: octets _3D

Delta-frissítés létrehozása a DiffGen eszközzel

A Diff Generation (DiffGen) eszközzel deltafrissítéseket hozhat létre.

Környezeti előfeltételek

Mielőtt delta-okat hoz létre a DiffGen használatával, több dolgot kell letöltenie és telepítenie a környezeti gépen. Ideális esetben használjon Ubuntu 20.04 Linux-környezetet, vagy windowsos Linuxos Windows-alrendszer.

Az alábbi táblázat a szükséges tartalmat, a lekérés helyét és a javasolt telepítést mutatja be, ha szükséges.

Delta-frissítés létrehozása a DiffGen használatával

A DiffGen eszköz a következő kötelező argumentumokkal és szintaxissal fut:

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

Az előző parancs futtatja a recompress_tool.py szkriptet, amely létrehozza a <recompressed_target_file>. A DiffGen ezután a <recompressed_target_file>célfájl helyett <target_archive> a diffet használja. A bennük lévő <recompressed_target_archive> képfájlok gzip-vel vannak tömörítve.

Ha az SWU-fájlok aláírtak, a <signing_command> DiffGen parancs argumentumát is meg kell követelniük:

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

Az aláírási parancs sztringparaméterével rendelkező DiffGenTool a recompress_and_sign_tool.py szkriptet futtatja. Ez a szkript létrehozza a <recompressed_target_file>. Emellett ez a szkript az sw-description fájlt is aláírja az archívumban egy sw-description.sig fájl létrehozásához.

Az Azure/iot-hub-device-update-delta GitHub-adattárból származó sign_file.sh példaszkripttel létrehozhat egy különbséget a bemeneti forrásfájl és az újracsomagolt és újra aláírt célfájl között. Nyissa meg a szkriptet, szerkessze, és adja hozzá az elérési utat a titkos kulcsfájlhoz, és mentse. A mintahasználatért tekintse meg a Példák szakaszt.

Az alábbi táblázat részletesebben ismerteti az argumentumokat:

DiffGen-példák

Az alábbi példák az /mnt/o/temp könyvtárból működnek Linuxos Windows-alrendszer.

A következő kód egy diffiffet hoz létre a bemeneti forrásfájl és az újracsomagolt célfájl között:

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

Ha az aláírási paramétert is használja, amelyet az SWU-fájl aláírásakor kell használnia, használhatja a korábban említett sign_file.sh példaszkriptet. Nyissa meg a szkriptet, szerkessze, hogy hozzáadja az elérési utat a titkos kulcsfájlhoz, mentse a szkriptet, majd futtassa a DiffGent az alábbiak szerint.

A következő kód egy diffiffet hoz létre a bemeneti forrásfájl és egy újracsomagolt és újra aláírt célfájl között:

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

A változásfrissítések generált importálása

A változásfrissítés eszközfrissítési szolgáltatásba való importálásának alapvető folyamata megegyezik minden más frissítéssel. Ha még nem tette meg, mindenképpen tekintse át az IoT Hubhoz készült Azure Device Update-be importálandó frissítés előkészítését.

Az importálási jegyzék létrehozása

Ha frissítést szeretne importálni az Eszközfrissítési szolgáltatásba, rendelkeznie kell vagy létre kell hoznia egy importálási jegyzékfájlt. További információ: Frissítések importálása az eszközfrissítésbe.

A változásfrissítések jegyzékfájljainak importálásához a DiffGen eszköz által létrehozott alábbi fájlokra kell hivatkoznia:

• Az <recompressed_target_file> SWU-rendszerkép
• A <delta file>

A változásfrissítési funkció egy kapcsolódó fájlok nevű képességet használ, amelyhez 5-ös vagy újabb verziójú importálási jegyzék szükséges. A kapcsolódó fájlok funkció használatához fel kell vennie a relatedFiles és downloadHandler objektumokat az importálási jegyzékbe.

Az objektummal relatedFiles megadhatja a változásfrissítési fájl adatait, beleértve a fájl nevét, méretét és sha256 kivonatát. A legfontosabb, hogy az alábbi két tulajdonságot is meg kell adnia, amelyek egyediek a deltafrissítési funkcióhoz:

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

Mindkét tulajdonság a DiffGen eszköz bemeneteként a deltafrissítés létrehozásakor használt tulajdonságokra jellemző <source image file> . Az importálási jegyzéknek szüksége van a forrás SWU-lemezképére vonatkozó információkra annak ellenére, hogy valójában nem importálja a forráslemezképet. Az eszközön található delta-összetevők a forrásrendszerkép metaadatait használják a rendszerkép megkereséséhez az eszközön a deltafrissítés letöltése után.

downloadHandler Az objektum használatával megadhatja, hogy az eszközfrissítési ügynök hogyan vezényelje a delta frissítést a kapcsolódó fájlok funkciójával. Ha nem szabja testre az Eszközfrissítési ügynök saját verzióját a változásfunkciókhoz, használja a következőket downloadHandler:

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

Az Azure CLI az iot du update init v5 paranccsal létrehozhat egy importálási jegyzékfájlt a változásfrissítéshez. További információ: Alapszintű importálási jegyzék létrehozása.

--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>"}' 

Mentse a létrehozott importálási jegyzék JSON-fájlját a .importmanifest.json fájlkiterjesztéssel.

Importálás az Azure Portal használatával

Az importálási jegyzék létrehozása után importálja a változásfrissítést az IoT Hub eszközfrissítésének hozzáadása című témakör utasításait követve. Az importálásba a következő elemeket kell belefoglalnia:

• A korábban a korábbi lépésekben létrehozott *importmanifest.json fájl
• A <recompressed_target_file> DiffGen eszköz által létrehozott SWU-rendszerkép
• A <delta file> létrehozott DiffGen eszköz

Delta update deployment to devices

Az Azure Portalon a változásfrissítés üzembe helyezése ugyanaz, mint egy normál rendszerkép-frissítés üzembe helyezése. További információ: Frissítés üzembe helyezése eszközfrissítéssel.

Miután létrehozta a deltafrissítés központi telepítését, az eszközfrissítési szolgáltatás és az ügyfél automatikusan megállapítja, hogy van-e érvényes változásfrissítés minden olyan eszközhöz, amelybe üzembe helyez. Ha találnak egy érvényes különbözetet, letöltik és telepítik a delta frissítést az eszközön.

Ha nem találnak érvényes változásfrissítést, a rendszer a teljes képfrissítést (az újracsomagolt cél SWU-lemezképet) tartalékként tölti le. Ez a megközelítés biztosítja, hogy a frissítést üzembe helyező összes eszköz a megfelelő verzióhoz jusson.

A deltafrissítés üzembe helyezésének három lehetséges eredménye lehet:

• A delta frissítés sikeresen telepítve van, és az eszköz az új verzión van.
• A változásfrissítés nem volt elérhető, vagy nem sikerült telepíteni, de a teljes rendszerkép tartalék telepítése sikeres volt, és az eszköz az új verzión van.
• A delta és a tartalék telepítés sem sikerült, és az eszköz továbbra is a régi verzióban van.

A hiba kimenetelének megállapításához a telepítési eredményeket hibakóddal és kiterjesztett hibakóddal tekintheti meg a sikertelen állapotú eszközök kiválasztásával. Szükség esetén több sikertelen eszközről is gyűjthet naplókat .

• Ha egy változásfrissítés sikeres volt, az eszköz sikeres állapotot jelenít meg .

• Ha egy változásfrissítés sikertelen volt, de a teljes rendszerképre való visszalépés sikeres volt, az eszköz a következő hibaállapotot jeleníti meg:

  • resultCode: <0-nál nagyobb érték>
  • extendedResultCode: <nem nulla érték>

Sikertelen frissítések hibaelhárítása

A sikertelen frissítések olyan hibaállapotokat jelenítenek meg, amelyeket az alábbi utasítások segítségével értelmezhet. Kezdje az eszközfrissítési ügynökkel a result.h fájlban megjelenő hibákkal.

Az Eszközfrissítési ügynöknek a deltafrissítések letöltéskezelő funkciójával kapcsolatos hibái a következőkkel 0x9kezdődnek:

Ha a hibakód nem jelenik meg a result.h fájlban, az valószínűleg hiba a deltaprocesszor összetevőben, az Eszközfrissítési ügynöktől elkülönítve. Ha igen, akkor a extendedResultCode negatív decimális érték hexadecimális formátumban 0x90AXXXXX.

• 9 a "Delta Facility"
• 0A a "Delta Processor Component" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
• XXXXX a mezőtelepítési eszköz (FIT) deltaprocesszorának 20 bites hibakódja

Ha a hibakód adatai alapján nem tudja megoldani a problémát, küldjön egy GitHub-problémát, hogy további segítséget kapjon.

Kapcsolódó tartalom

• Az Azure Device Update for IoT Hub importálási jegyzékséma
• Gyakori problémák megoldása