Pembaruan Delta (Pratinjau)

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.

Persyaratan untuk menggunakan pembaruan delta di Device Update for IoT Hub

• File pembaruan sumber dan target harus dalam format SWUpdate (SWU).
• Dalam setiap file SWUpdate, harus ada gambar mentah yang menggunakan sistem file Ext2, Ext3, atau Ext4.

Proses pembuatan delta mengkompresi ulang pembaruan SWU target menggunakan kompresi gzip untuk menghasilkan delta yang optimal. Anda mengimpor pembaruan SWU target yang dikompresi ke layanan Pembaruan Perangkat bersama dengan file pembaruan delta yang dihasilkan.

Konfigurasi agen Pembaruan Perangkat untuk komponen prosesor delta

Untuk mengunduh dan menginstal pembaruan delta dari layanan Pembaruan Perangkat, perangkat Anda memerlukan agen Pembaruan Perangkat dengan penangan pembaruan dan komponen prosesor delta yang ada dan dikonfigurasi.

Agen Device Update

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

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.

Prosesor Delta

Prosesor delta di Azure/iot-hub-device-update-delta membuat ulang file gambar SWU asli di perangkat Anda setelah file delta diunduh, sehingga handler pembaruan Anda dapat menginstal file SWU. Untuk menambahkan komponen prosesor delta ke gambar perangkat Anda dan mengonfigurasinya untuk digunakan, Anda dapat mengunduh paket Debian untuk Ubuntu 20.04 dan yang lebih baru dari https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Jika Anda menggunakan distro lain, ikuti instruksi README.md untuk menggunakan CMAKE untuk membangun prosesor delta dari sumber sebagai gantinya. Dari sana, instal objek bersama libadudiffapi.so secara langsung dengan menyalinnya ke direktori /usr/lib , sebagai berikut:

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

Menambahkan file gambar SWU sumber ke perangkat Anda

Setelah file pembaruan delta diunduh ke perangkat, file tersebut dibandingkan dengan cache yang valid <source_archive> sebelumnya di perangkat. Proses ini memungkinkan pembaruan delta untuk membuat ulang gambar target lengkap.

Cara paling sederhana untuk mengisi gambar cache ini adalah dengan mengimpor dan menyebarkan pembaruan gambar lengkap ke perangkat melalui layanan Pembaruan Perangkat. Jika perangkat dikonfigurasi dengan agen Pembaruan Perangkat versi 1.0 atau yang lebih baru dan prosesor delta, agen 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>. Nilai provider adalah provider bagian 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

Pembuatan pembaruan Delta menggunakan alat DiffGen

Anda dapat membuat pembaruan delta dengan menggunakan alat Diff Generation (DiffGen).

Prasyarat lingkungan

Sebelum membuat delta dengan DiffGen, Anda perlu mengunduh dan menginstal beberapa hal di komputer lingkungan. Idealnya, gunakan lingkungan Linux Ubuntu 20.04, atau Subsistem Windows untuk Linux jika Anda menggunakan Windows.

Tabel berikut ini memperlihatkan konten yang diperlukan, tempat mendapatkannya, dan penginstalan yang direkomendasikan jika perlu.

Pembuatan pembaruan Delta menggunakan DiffGen

Alat DiffGen berjalan dengan argumen dan sintaks yang diperlukan berikut:

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

Perintah sebelumnya menjalankan skrip recompress_tool.py , yang membuat <recompressed_target_file>. DiffGen kemudian menggunakan alih-alih <recompressed_target_file><target_archive> sebagai file target untuk membuat diff. File gambar dalam <recompressed_target_archive> dikompresi dengan gzip.

Jika file SWU Anda ditandatangani, file tersebut juga memerlukan <signing_command> argumen dalam perintah DiffGen:

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

Parameter string perintah DiffGenTool dengan penandatanganan menjalankan skrip recompress_and_sign_tool.py . Skrip ini membuat <recompressed_target_file>. Selain itu, skrip ini juga menandatangani file sw-description dalam arsip untuk membuat file sw-description.sig .

Anda dapat menggunakan sampel skrip sign_file.sh dari repositori GitHub Azure/iot-hub-device-update-delta untuk membuat perbedaan antara file sumber input dan file target yang dikompresi dan ditandatangani kembali. Buka skrip, edit untuk menambahkan jalur ke file kunci privat Anda, dan simpan. Lihat bagian Contoh untuk penggunaan sampel.

Tabel berikut ini menjelaskan argumen secara lebih rinci:

Contoh DiffGen

Contoh berikut beroperasi di luar direktori /mnt/o/temp di Subsistem Windows untuk Linux.

Kode berikut 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 create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu

Jika Anda juga menggunakan parameter penandatanganan, yang harus Anda lakukan jika file SWU Anda ditandatangani, Anda dapat menggunakan sampel sign_file.sh skrip yang disebutkan sebelumnya. Buka skrip, edit untuk menambahkan jalur ke file kunci privat Anda, simpan skrip, lalu jalankan DiffGen sebagai berikut.

Kode berikut membuat perbedaan antara file sumber input dan file target yang dikompresi ulang dan ditandatangani ulang:

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

Impor pembaruan delta yang dihasilkan

Proses dasar mengimpor pembaruan delta ke layanan Pembaruan Perangkat sama dengan pembaruan lainnya. Jika Anda belum melakukannya, pastikan untuk meninjau Cara menyiapkan pembaruan untuk diimpor ke Azure Device Update for IoT Hub.

Membuat manifes impor

Untuk mengimpor pembaruan ke layanan Pembaruan Perangkat, Anda harus memiliki atau membuat file manifes impor. Untuk informasi selengkapnya, lihat Mengimpor pembaruan ke pembaruan perangkat.

Impor file manifes untuk pembaruan delta harus mereferensikan file berikut yang dibuat alat DiffGen:

• Gambar <recompressed_target_file> SWU
• Si <delta file>

Fitur pembaruan delta menggunakan kemampuan yang disebut file terkait yang memerlukan manifes impor versi 5 atau yang lebih baru. Untuk menggunakan fitur file terkait, Anda harus menyertakan objek relatedFiles dan downloadHandler dalam manifes impor Anda.

Anda menggunakan relatedFiles objek untuk menentukan informasi tentang file pembaruan delta, termasuk nama file, ukuran file, dan hash sha256. Yang terpenting, Anda juga harus menentukan dua properti berikut yang unik untuk fitur pembaruan delta:

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

Kedua properti khusus untuk yang <source image file> Anda gunakan sebagai input ke alat DiffGen saat Anda membuat pembaruan delta. Manifes impor membutuhkan informasi tentang gambar SWU sumber meskipun Anda tidak benar-benar mengimpor gambar sumber. Komponen delta pada perangkat menggunakan metadata ini tentang gambar sumber untuk menemukan gambar tersebut di perangkat setelah mereka mengunduh pembaruan delta.

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, gunakan yang berikut:downloadHandler

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

Anda dapat menggunakan perintah Azure CLI az iot du update init v5 untuk menghasilkan manifes impor untuk pembaruan delta Anda. Untuk informasi selengkapnya, lihat Membuat manifes impor dasar.

--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 dengan ekstensi file .importmanifest.json.

Mengimpor menggunakan portal Azure

Setelah Anda membuat manifes impor, impor pembaruan delta dengan mengikuti instruksi di Menambahkan pembaruan ke Device Update for IoT Hub. Anda harus menyertakan item berikut dalam impor:

• File *importmanifest.json yang sebelumnya Anda buat di langkah-langkah sebelumnya
• Gambar <recompressed_target_file> SWU yang dibuat alat DiffGen
• Alat <delta file> DiffGen dibuat

Penyebaran pembaruan Delta ke perangkat

Pengalaman penyebaran pembaruan delta di portal Azure sama dengan menyebarkan pembaruan gambar reguler. Untuk informasi selengkapnya, lihat Menyebarkan pembaruan dengan menggunakan Pembaruan Perangkat.

Setelah Anda membuat penyebaran untuk pembaruan delta Anda, layanan Pembaruan Perangkat dan klien secara otomatis menentukan apakah ada pembaruan delta yang valid untuk setiap perangkat yang Anda sebarkan. Jika menemukan delta yang valid, mereka mengunduh dan menginstal pembaruan delta pada perangkat tersebut.

Jika mereka tidak menemukan pembaruan delta yang valid, 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 dan perangkat berada di versi baru.
• Pembaruan delta tidak tersedia atau gagal diinstal, tetapi penginstalan fallback gambar lengkap berhasil, dan perangkat berada di versi baru.
• Penginstalan delta dan fallback gagal, dan perangkat masih pada versi lama.

Untuk menentukan hasil kegagalan 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 perlu.

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

• Jika pembaruan delta gagal tetapi fallback ke gambar lengkap berhasil, perangkat menunjukkan status kesalahan berikut:

  • resultCode: <nilai lebih besar dari 0>
  • extendedResultCode: <nilai bukan nol>

Memecahkan masalah pembaruan yang gagal

Pembaruan yang tidak berhasil menampilkan status kesalahan yang dapat Anda interpretasikan menggunakan instruksi berikut. Mulailah dengan kesalahan agen Pembaruan Perangkat di result.h.

Kesalahan dari agen Pembaruan Perangkat yang khusus untuk fungsionalitas pengunduhan handler pembaruan delta dimulai dengan 0x9:

Jika kode kesalahan tidak ada di result.h, mungkin kesalahan dalam komponen prosesor delta, terpisah dari agen Pembaruan Perangkat. Jika demikian, extendedResultCode adalah nilai desimal negatif dalam format 0x90AXXXXXheksadesimal .

• 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 Field Installation Tool (FIT)

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

Konten terkait

• Skema manifes impor Azure Device Update for IoT Hub
• Pemecahan masalah umum