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.
Feljegyzés
Az Azure Device Update for IoT Hub változásfrissítési funkciója jelenleg nyilvános előzetes verzióban érhető el.
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.
Bináris név | Hol szerezhető be? | Telepítés |
---|---|---|
DiffGen | Azure/iot-hub-device-update-delta GitHub-adattár | Töltse le az operációs rendszernek megfelelő verziót vagy disztribúciót a gépen a deltafrissítések létrehozásához. |
. NETCore-futtatókörnyezet, 8.0.0-s verzió | Terminál- vagy csomagkezelőken keresztül | Telepítse a .NET-et Linuxon. Csak a futtatókörnyezetre van szükség. |
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:
Argumentum | Leírás |
---|---|
<source_archive> |
Az alaprendszerkép, amelyet a DiffGen kiindulási pontként használ a delta létrehozásához. Fontos: Ennek a rendszerképnek meg kell egyeznie az eszközön már meglévő képpel, például egy korábbi frissítésből gyorsítótárazva. |
<target_archive> |
Az a kép, amellyel a delta frissíti az eszközt. |
<output_path> |
A gazdagép azon elérési útja, ahová a deltafájlt a létrehozás után helyezni szeretné, beleértve a létrehozott deltafájl kívánt nevét is. Ha az elérési út nem létezik, az eszköz létrehozza. |
<log_folder> |
A gazdagép azon elérési útja, amellyel naplókat hozhat létre. A legjobb, ha ezt a helyet a kimeneti elérési út almappájaként definiálja. Ha az elérési út nem létezik, az eszköz létrehozza. |
<working_folder> |
A gép elérési útja a biztosítékok és egyéb munkafájlok elhelyezéséhez a deltagenerálás során. A legjobb, ha ezt a helyet a kimeneti elérési út almappájaként definiálja. Ha az elérési út nem létezik, az eszköz létrehozza. |
<recompressed_target_archive> |
A gazdagép elérési útja a <recompressed_target_file> bejelentkezés létrehozásához. A <recompressed_target_file> rendszer a <target_archive> diff-létrehozás célfájljaként használja ahelyett, hogy a célfájlt használná. Ha ez az elérési út a DiffGen eszköz meghívása előtt létezik, a program felülírja. A legjobb, ha ezt a fájlt a kimeneti elérési út egy almappájában definiálja. |
"<signing_command>" (választható) |
Testre szabható parancs az sw-description fájl aláírásához a <recompressed_target_archive> . Az újracsomagolt archívum sw-description fájlja az aláírási parancs bemeneti paramétere. A DiffGen azt várja, hogy az aláírási parancs hozzon létre egy új aláírási fájlt a bemenet nevével a .sig hozzáfűzéssel.A paramétert idézőjelekkel kell körülvenni, hogy az egész parancsot egyetlen paraméterként adja át. Emellett ne használja a karaktert az ~ aláíráshoz használt kulcsútvonalon, és használja helyette a teljes kezdőlapot. Használja például a /home/USER/keys/priv.pem parancsot a ~/keys/priv.pem helyett. |
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 0x9
kezdődnek:
Összetevő | Decimális | Rontás | Feljegyzés |
---|---|---|---|
EXTENSION_MANAGER | 0 | 0x00 | A Bővítménykezelő letöltéskezelőjének logikája által észlelt hibákat jelzi. Példa: 0x900XXXXX |
BEÉPÜLŐ MODUL | 0 | 0x01 | A letöltéskezelő beépülő modul megosztott kódtárainak használatával kapcsolatos hibákat jelez. Példa: 0x901XXXXX |
TARTÓZKODÓ | 2 - 7 | 0x02 – 0x07 | A letöltéskezelő számára fenntartva. Példa: 0x902XXXXX |
KÖZÖS | 8 | 0x08 | A Delta Download Handler bővítmény legfelső szintű logikájában észlelt hibákat jelzi. Példa: 0x908XXXXX |
SOURCE_UPDATE_CACHE | 9 | 0x09 | Hibákat jelez a Delta Download Handler bővítmény forrásfrissítési gyorsítótárában. Példa: 0x909XXXXX |
DELTA_PROCESSOR | 10 | 0x0A | Hibakód a deltaprocesszor API-ból származó hibákhoz. Példa: 0x90AXXXXX |
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.