Cara memahami dan menggunakan pembaruan delta di Device Update for IoT Hub (Pratinjau)

Artikel
03/05/2024

Pembaruan Delta memungkinkan Anda menghasilkan pembaruan kecil yang hanya mewakili perubahan antara dua pembaruan lengkap - gambar sumber dan gambar target. Pendekatan ini sangat ideal untuk mengurangi bandwidth yang digunakan untuk mengunduh pembaruan ke perangkat, terutama jika hanya ada beberapa perubahan antara pembaruan sumber dan target.

Catatan

Fitur pembaruan delta saat ini dalam pratinjau publik.

Persyaratan untuk menggunakan pembaruan delta di Device Update for IoT Hub

File pembaruan sumber dan target harus format SWUpdate (SWU).
Dalam setiap file SWUpdate, harus ada gambar mentah yang menggunakan sistem file Ext2, Ext3, atau Ext4. Gambar tersebut dapat dikompresi dengan gzip atau zstd.
Proses pembuatan delta mengkompresi ulang pembaruan SWU target menggunakan kompresi zstd untuk menghasilkan delta yang optimal. Impor pembaruan SWU target yang dikompresi ini ke layanan Pembaruan Perangkat bersama dengan file pembaruan delta yang dihasilkan.
Dalam SWUpdate pada perangkat, dekompresi zstd juga harus diaktifkan.
- Proses ini memerlukan penggunaan SWUpdate 2019.11 atau yang lebih baru.

Mengonfigurasi perangkat dengan agen Pembaruan Perangkat dan komponen prosesor delta

Agar perangkat Anda dapat mengunduh dan menginstal pembaruan delta dari layanan Pembaruan Perangkat, Anda memerlukan beberapa komponen yang ada dan dikonfigurasi.

Agen Device Update

Agen Pembaruan Perangkat mengatur proses pembaruan pada perangkat, termasuk tindakan unduh, instal, dan mulai ulang. Tambahkan agen Pembaruan Perangkat ke perangkat dan konfigurasikan untuk digunakan. Gunakan agen versi 1.0 atau yang lebih baru. Untuk petunjuknya, lihat Provisi agen Pembaruan Perangkat.

Perbarui handler

Handler pembaruan terintegrasi dengan agen Pembaruan Perangkat untuk melakukan penginstalan pembaruan aktual. Untuk pembaruan delta, mulailah dengan microsoft/swupdate:2 handler pembaruan jika Anda belum memiliki handler pembaruan SWUpdate Anda sendiri yang ingin Anda ubah. Jika Anda menggunakan handler pembaruan Anda sendiri, pastikan untuk mengaktifkan dekompresi zstd di SWUpdate.

Prosesor Delta

Prosesor delta membuat ulang file gambar SWU asli di perangkat Anda setelah file delta diunduh, sehingga handler pembaruan Anda dapat menginstal file SWU. Kode prosesor delta tersedia di repositori GitHub Azure/iot-hub-device-update-delta .

Untuk menambahkan komponen prosesor delta ke gambar perangkat Anda dan mengonfigurasinya untuk digunakan, ikuti instruksi README.md untuk menggunakan CMAKE untuk membangun prosesor delta dari sumber. Dari sana, instal objek bersama (libadudiffapi.so) secara langsung dengan menyalinnya ke /usr/lib direktori:

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

Menambahkan file gambar SWU sumber ke perangkat Anda

Setelah pembaruan delta diunduh ke perangkat, pembaruan harus dibandingkan dengan file SWU sumber yang valid yang sebelumnya di-cache pada perangkat. Proses ini diperlukan agar pembaruan delta membuat ulang gambar target lengkap. Cara paling sederhana untuk mengisi gambar cache ini adalah dengan menyebarkan pembaruan gambar lengkap ke perangkat melalui layanan Pembaruan Perangkat (menggunakan proses impor dan penyebaran yang ada). Selama perangkat dikonfigurasi dengan agen Pembaruan Perangkat (versi 1.0 atau yang lebih baru) dan prosesor delta, agen Pembaruan Perangkat menyimpan file SWU yang diinstal secara otomatis untuk penggunaan pembaruan delta nanti.

Jika Anda ingin langsung mengisi gambar sumber di perangkat Anda, jalur di mana gambar diharapkan adalah:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Secara default, BASE_SOURCE_DOWNLOAD_CACHE_PATH adalah jalur /var/lib/adu/sdc/[provider]. Nilainya [provider] adalah bagian Penyedia dari updateId untuk file SWU sumber.

ENCODED_HASH adalah string heksa base64 dari SHA256 dari biner, tetapi setelah pengodean ke string heksa base64, ia mengodekan karakter sebagai berikut:

+ dikodekan sebagai octets _2B
/ dikodekan sebagai octets _2F
= dikodekan sebagai octets _3D

Membuat pembaruan delta menggunakan alat DiffGen

Prasyarat lingkungan

Sebelum membuat delta dengan DiffGen, beberapa hal perlu diunduh dan/atau diinstal pada komputer lingkungan. Kami merekomendasikan lingkungan Linux dan khususnya Ubuntu 20.04 (atau Subsistem Windows untuk Linux jika asli di Windows).

Tabel berikut ini menyediakan daftar konten yang diperlukan, tempat untuk mengambilnya, dan penginstalan yang direkomendasikan jika perlu:

Nama Biner	Tempat memperoleh	Cara menginstal
DiffGen	Repositori GitHub Azure/iot-hub-device-update-delta	Dari folder akar, pilih Microsoft.Azure.DeviceUpdate.Diffs.[ versi].nupkg file. Pelajari selengkapnya tentang paket NuGet.
. NETCore Runtime, versi 6.0.0	Melalui Terminal / Manajer Paket	Instruksi untuk Linux. Hanya Runtime yang diperlukan.

Dependensi

zstd_compression_tool digunakan untuk mendekompresi file gambar arsip dan mengompresinya dengan zstd. Proses ini memastikan bahwa semua file arsip yang digunakan untuk pembuatan diff memiliki algoritma kompresi yang sama untuk gambar di dalam arsip.

Perintah untuk menginstal paket/pustaka yang diperlukan:

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

Membuat pembaruan delta menggunakan DiffGen

Alat DiffGen dijalankan dengan beberapa argumen. Semua argumen diperlukan, dan sintaks keseluruhan adalah sebagai berikut:

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

Skrip recompress_tool.py berjalan untuk membuat file [recompressed_target_archive], yang kemudian digunakan alih-alih [target_archive] sebagai file target untuk membuat diff.
File gambar dalam [recompressed_target_archive] dikompresi dengan zstd.

Jika file SWU Anda ditandatangani (kemungkinan), Anda juga memerlukan argumen lain:

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

Selain menggunakan [recompressed_target_archive] sebagai file target, menyediakan parameter string perintah penandatanganan berjalan recompress_and_sign_tool.py untuk membuat file [recompressed_target_archive] dan memiliki file sw-description dalam arsip yang ditandatangani (berarti file sw-description.sig ada). Anda dapat menggunakan skrip sampel sign_file.sh dari repositori GitHub Azure/iot-hub-device-update-delta . Buka skrip, edit untuk menambahkan jalur ke file kunci privat Anda, lalu simpan. Lihat bagian contoh untuk penggunaan sampel.

Tabel berikut ini menjelaskan argumen secara lebih rinci:

Argumen	Deskripsi
[source_archive]	Ini adalah gambar yang didasarkan pada delta saat membuat delta. Penting: gambar ini harus identik dengan gambar yang sudah ada di perangkat (misalnya, di-cache dari pembaruan sebelumnya).
[target_archive]	Ini adalah gambar tempat delta memperbarui perangkat.
[output_path]	Jalur (termasuk nama file delta yang diinginkan yang dihasilkan) pada komputer host tempat file delta ditempatkan setelah pembuatan. Jika jalur tidak ada, alat akan membuatnya.
[log_folder]	Jalur pada komputer host tempat log dibuat. Sebaiknya tentukan lokasi ini sebagai sub folder jalur output. Jika jalur tidak ada, alat akan membuatnya.
[working_folder]	Jalur pada komputer tempat jaminan dan file kerja lainnya ditempatkan selama pembuatan delta. Sebaiknya tentukan lokasi ini sebagai subfolder jalur output. Jika jalur tidak ada, alat akan membuatnya.
[recompressed_target_archive]	Jalur pada komputer host tempat file target yang dikompresi ulang dibuat. File ini digunakan alih-alih <target_archive> sebagai file target untuk pembuatan berbeda. Jika jalur ini ada sebelum memanggil DiffGenTool, jalur akan ditimpa. Sebaiknya tentukan jalur ini sebagai file di subfolder jalur output.
"[signing_command]" (opsional)	Perintah yang dapat disesuaikan yang digunakan untuk menandatangani file sw-description dalam file arsip yang dikompresi ulang. File sw-description dalam arsip yang dikompresi ulang digunakan sebagai parameter input untuk perintah penandatanganan; DiffGenTool mengharapkan perintah penandatanganan untuk membuat file tanda tangan baru, menggunakan nama input dengan `.sig` ditambahkan. Mengelilingi parameter dalam tanda kutip ganda diperlukan sehingga seluruh perintah diteruskan sebagai parameter tunggal. Selain itu, hindari menempatkan karakter '~' di jalur kunci yang digunakan untuk penandatanganan, dan gunakan jalur beranda lengkap sebagai gantinya (misalnya, gunakan /home/USER/keys/priv.pem alih-alih ~/keys/priv.pem).

Contoh DiffGen

Dalam contoh ini, kami beroperasi di luar direktori /mnt/o/temp (dalam WSL):

Membuat perbedaan antara file sumber input dan file target yang dikompresi ulang:

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]

Jika Anda juga menggunakan parameter penandatanganan (diperlukan jika file SWU Anda ditandatangani), Anda dapat menggunakan contoh sign_file.sh skrip yang direferensikan sebelumnya. Pertama, buka skrip dan edit untuk menambahkan jalur ke file kunci privat Anda. Simpan skrip, lalu jalankan DiffGen sebagai berikut:

Membuat perbedaan antara file sumber input dan file target yang dikompresi/ditandatangani ulang:

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

Mengimpor pembaruan delta yang dihasilkan

Proses dasar mengimpor pembaruan ke layanan Pembaruan Perangkat tidak berubah untuk pembaruan delta, jadi jika Anda belum melakukannya, pastikan untuk meninjau halaman ini: Cara menyiapkan pembaruan yang akan diimpor ke Azure Device Update for IoT Hub

Hasilkan manifes impor

Langkah pertama untuk mengimpor pembaruan ke layanan Pembaruan Perangkat adalah selalu membuat manifes impor jika Anda belum memilikinya. Untuk informasi selengkapnya tentang manifes impor, lihat Mengimpor pembaruan ke dalam Pembaruan Perangkat. Untuk pembaruan delta, manifes impor Anda perlu mereferensikan dua file:

Gambar SWU target yang dikompresi ulang dibuat saat Anda menjalankan alat DiffGen.
File delta yang dibuat saat Anda menjalankan alat DiffGen.

Fitur pembaruan delta menggunakan kemampuan yang disebut file terkait, yang memerlukan manifes impor yang versi 5 atau yang lebih baru.

Untuk membuat manifes impor untuk pembaruan delta Anda menggunakan fitur file terkait, Anda perlu menambahkan objek relatedFiles dan downloadHandler ke manifes impor Anda.

relatedFiles Gunakan objek untuk menentukan informasi tentang file pembaruan delta, termasuk nama file, ukuran file, dan hash sha256. Yang penting, Anda juga perlu menentukan dua properti yang unik untuk fitur pembaruan delta:

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

Kedua properti ini khusus untuk file gambar SWU sumber yang Anda gunakan sebagai input ke alat DiffGen saat membuat pembaruan delta Anda. Informasi tentang gambar SWU sumber diperlukan dalam manifes impor Anda meskipun Anda tidak benar-benar mengimpor gambar sumber. Komponen delta pada perangkat menggunakan metadata ini tentang gambar sumber untuk menemukan gambar pada perangkat setelah delta diunduh.

downloadHandler Gunakan objek untuk menentukan bagaimana agen Pembaruan Perangkat mengatur pembaruan delta, menggunakan fitur file terkait. Kecuali Anda menyesuaikan versi agen Pembaruan Perangkat Anda sendiri untuk fungsionalitas delta, Anda hanya boleh menggunakan downloadHandler ini:

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

Anda dapat menggunakan Azure Command Line Interface (CLI) untuk menghasilkan manifes impor untuk pembaruan delta Anda. Jika Anda belum menggunakan Azure CLI untuk membuat manifes impor sebelumnya, lihat Membuat manifes impor dasar.

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

Simpan JSON manifes impor yang dihasilkan ke file dengan ekstensi .importmanifest.json

Mengimpor menggunakan portal Azure

Setelah membuat manifes impor, Anda siap untuk mengimpor pembaruan delta. Untuk mengimpor, ikuti instruksi di Menambahkan pembaruan ke Device Update for IoT Hub. Anda harus menyertakan item ini saat mengimpor:

File .json manifes impor yang Anda buat di langkah sebelumnya.
Gambar SWU target yang dikompresi ulang dibuat saat Anda menjalankan alat DiffGen.
File delta yang dibuat saat Anda menjalankan alat DiffGen.

Menyebarkan pembaruan delta ke perangkat Anda

Saat Anda menyebarkan pembaruan delta, pengalaman di portal Azure terlihat identik dengan menyebarkan pembaruan gambar reguler. Untuk informasi selengkapnya tentang menyebarkan pembaruan, lihat Menyebarkan pembaruan dengan menggunakan Pembaruan Perangkat untuk Azure IoT Hub.

Setelah Anda membuat penyebaran untuk pembaruan delta Anda, layanan Pembaruan Perangkat dan klien secara otomatis mengidentifikasi apakah ada pembaruan delta yang valid untuk setiap perangkat yang Anda sebarkan. Jika delta yang valid ditemukan, pembaruan delta diunduh dan diinstal pada perangkat tersebut. Jika tidak ada pembaruan delta yang valid yang ditemukan, pembaruan gambar lengkap (gambar SWU target yang dikompresi ulang) diunduh sebagai fallback. Pendekatan ini memastikan bahwa semua perangkat yang Anda sebarkan pembaruannya untuk masuk ke versi yang sesuai.

Ada tiga kemungkinan hasil untuk penyebaran pembaruan delta:

Pembaruan Delta berhasil diinstal. Perangkat berada pada versi baru.
Pembaruan Delta tidak tersedia atau gagal diinstal, tetapi instalasi fallback yang berhasil dari gambar lengkap terjadi sebagai gantinya. Perangkat berada pada versi baru.
Delta dan fallback ke gambar penuh gagal. Perangkat masih dalam versi lama.

Untuk menentukan hasil di atas mana yang terjadi, Anda dapat melihat hasil penginstalan dengan kode kesalahan dan kode kesalahan yang diperluas dengan memilih perangkat apa pun yang dalam status gagal. Anda juga dapat mengumpulkan log dari beberapa perangkat yang gagal jika diperlukan.

Jika pembaruan delta berhasil, perangkat akan menampilkan status "Berhasil".

Jika pembaruan delta gagal tetapi melakukan fallback yang berhasil ke gambar lengkap, itu menunjukkan status kesalahan berikut:

resultCode: [nilai lebih besar dari 0]
extendedResultCode: [non-nol]

Jika pembaruan tidak berhasil, pembaruan menunjukkan status kesalahan yang dapat ditafsirkan menggunakan instruksi berikut:

Mulailah dengan kesalahan Agen Pembaruan Perangkat di result.h.

Kesalahan dari Agen Pembaruan Perangkat yang khusus untuk fungsi Unduh Handler yang digunakan untuk pembaruan delta dimulai dengan 0x9:

Komponen	Decimal	Hex	Catatan
EXTENSION_MANAGER	0	0x00	Menunjukkan kesalahan dari logika handler pengunduhan manajer ekstensi. Contoh: 0x900XXXXXX
PLUGIN	1	0x01	Menunjukkan kesalahan dengan penggunaan pustaka bersama plugin handler unduhan. Contoh: 0x901XXXXX
RESERVED	2 - 7	0x02 - 0x07	Dicadangkan untuk Pengunduhan handler. Contoh: 0x902XXXXXX
BIASA TERJADI	8	0x08	Menunjukkan kesalahan dalam logika tingkat atas ekstensi Delta Download Handler. Contoh: 0x908XXXXXX
SOURCE_UPDATE_CACHE	9	0x09	Menunjukkan kesalahan dalam Cache Pembaruan Sumber ekstensi pengunduhan Delta Download. Contoh: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Kode kesalahan untuk kesalahan dari API prosesor delta. Contoh: 0x90AXXXXXX

Jika kode kesalahan tidak ada di result.h, kemungkinan kesalahan dalam komponen prosesor delta (terpisah dari agen Pembaruan Perangkat). Jika demikian, extendedResultCode adalah nilai desimal negatif dari format heksadesimal berikut: 0x90AXXXXXX
- 9 adalah "Fasilitas Delta"
- 0A adalah "Komponen Prosesor Delta" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX adalah kode kesalahan 20-bit dari prosesor delta FIT

Jika Anda tidak dapat menyelesaikan masalah berdasarkan informasi kode kesalahan, ajukan masalah GitHub untuk mendapatkan bantuan lebih lanjut.

Langkah berikutnya

Pemecahan masalah umum

Bagikan melalui