IoT Hub için Cihaz Güncelleştirmesi'nde delta güncelleştirmelerini anlama ve kullanma (Önizleme)

Makale
03/05/2024

Delta güncelleştirmeleri, yalnızca iki tam güncelleştirme (kaynak görüntü ve hedef görüntü) arasındaki değişiklikleri temsil eden küçük bir güncelleştirme oluşturmanıza olanak tanır. Bu yaklaşım, özellikle kaynak ve hedef güncelleştirmeler arasında yalnızca birkaç değişiklik varsa, bir cihaza güncelleştirme indirmek için kullanılan bant genişliğini azaltmak için idealdir.

Not

Delta güncelleştirme özelliği şu anda genel önizleme aşamasındadır.

IoT Hub için Cihaz Güncelleştirmesi'nde değişiklik güncelleştirmelerini kullanma gereksinimleri

Kaynak ve hedef güncelleştirme dosyaları SWUpdate (SWU) biçiminde olmalıdır.
Her SWUpdate dosyasında Ext2, Ext3 veya Ext4 dosya sistemini kullanan bir ham görüntü olmalıdır. Bu görüntü gzip veya zstd ile sıkıştırılabilir.
Delta oluşturma işlemi, en iyi deltayı oluşturmak için zstd sıkıştırmasını kullanarak hedef SWU güncelleştirmesini yeniden sıkıştırıyor. Bu yeniden sıkıştırılan hedef SWU güncelleştirmesini, oluşturulan delta güncelleştirme dosyasıyla birlikte Cihaz Güncelleştirme hizmetine aktarın.
Cihazdaki SWUpdate'in içinde zstd dekompresyonu da etkinleştirilmelidir.
- Bu işlem SWUpdate 2019.11 veya sonraki bir sürümün kullanılmasını gerektirir.

Cihaz Güncelleştirme aracısı ve delta işlemci bileşeni ile cihaz yapılandırma

Cihazınızın Değişiklik güncelleştirmelerini Cihaz Güncelleştirmesi hizmetinden indirip yükleyebilmesi için çeşitli bileşenlerin mevcut ve yapılandırılmış olması gerekir.

Cihaz Güncelleştirme aracısı

Cihaz Güncelleştirmesi aracısı , indirme, yükleme ve yeniden başlatma eylemleri dahil olmak üzere cihazdaki güncelleştirme işlemini düzenler . Cihaz Güncelleştirmesi aracısını bir cihaza ekleyin ve kullanmak üzere yapılandırın. Aracı sürüm 1.0 veya üzerini kullanın. Yönergeler için bkz . Cihaz Güncelleştirmesi aracısı sağlama.

Güncelleştirme işleyicisi

Güncelleştirme işleyicisi, gerçek güncelleştirme yüklemesini gerçekleştirmek için Cihaz Güncelleştirme aracısı ile tümleşir. Değişiklik güncelleştirmeleri için, değiştirmek istediğiniz kendi SWUpdate güncelleştirme işleyiciniz yoksa güncelleştirme işleyicisiyle microsoft/swupdate:2 başlayın. Kendi güncelleştirme işleyicinizi kullanıyorsanız SWUpdate'te zstd sıkıştırmasını etkinleştirmeyi unutmayın.

Delta işlemci

Delta işlemcisi, delta dosyası indirildikten sonra cihazınızda özgün SWU görüntü dosyasını yeniden oluşturur, böylece güncelleştirme işleyiciniz SWU dosyasını yükleyebilir. Delta işlemci kodu Azure/iot-hub-device-update-delta GitHub deposunda kullanılabilir.

Delta işlemci bileşenini cihaz görüntünüze eklemek ve kullanmak üzere yapılandırmak için README.md yönergeleri izleyerek kaynaktan delta işlemcisi oluşturmak üzere CMAKE'yi kullanın. Buradan, paylaşılan nesneyi (libadudiffapi.so) doğrudan dizine /usr/lib kopyalayarak yükleyin:

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

Cihazınıza kaynak SWU görüntü dosyası ekleme

Bir delta güncelleştirmesi bir cihaza indirildikten sonra, daha önce cihazda önbelleğe alınmış geçerli bir kaynak SWU dosyasıyla karşılaştırılmalıdır. Delta güncelleştirmesinin tam hedef görüntüyü yeniden oluşturması için bu işlem gereklidir. Bu önbelleğe alınmış görüntüyü doldurmanın en basit yolu, Cihaz Güncelleştirme hizmeti (mevcut içeri aktarma ve dağıtım işlemlerini kullanarak) aracılığıyla cihaza tam görüntü güncelleştirmesi dağıtmaktır. Cihaz, Cihaz Güncelleştirme aracısı (sürüm 1.0 veya üzeri) ve delta işlemci ile yapılandırıldığı sürece, Cihaz Güncelleştirmesi aracısı yüklü SWU dosyasını daha sonra delta güncelleştirme kullanımı için otomatik olarak önbelleğe alır.

Bunun yerine, cihazınızdaki kaynak görüntüyü doğrudan önceden doldurmayı istiyorsanız, görüntünün beklendiği yol şudur:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Varsayılan olarak BASE_SOURCE_DOWNLOAD_CACHE_PATH yoludur /var/lib/adu/sdc/[provider]. [provider] değeri, kaynak SWU dosyasının updateId'sinin Sağlayıcı bölümüdür.

ENCODED_HASH , ikilinin SHA256'sının base64 onaltılık dizesidir, ancak base64 onaltılık dizeye kodlama yaptıktan sonra karakterleri şu şekilde kodlar:

+ olarak kodlanmış octets _2B
/ olarak kodlanmış octets _2F
= olarak kodlanmış octets _3D

DiffGen aracını kullanarak delta güncelleştirmeleri oluşturma

Ortam önkoşulları

DiffGen ile delta oluşturmadan önce, ortam makinesine birkaç şeyin indirilmesi ve/veya yüklenmesi gerekir. Linux ortamı ve özellikle Ubuntu 20.04 (veya yerel olarak Windows'daysa Linux için Windows Alt Sistemi) önerilir.

Aşağıdaki tabloda gereken içeriğin listesi, bunların alınacağı yer ve gerekirse önerilen yükleme sağlanır:

İkili Ad	Nereden edinileceği	Yükleme
DiffGen	Azure/iot-hub-device-update-delta GitHub deposu	Kök klasörden Microsoft.Azure.DeviceUpdate.Diffs'i seçin .[ version].nupkg dosyası. NuGet paketleri hakkında daha fazla bilgi edinin.
. NETCore Çalışma Zamanı, sürüm 6.0.0	Terminal /Paket Yöneticisi aracılığıyla	Linux yönergeleri. Yalnızca Çalışma Zamanı gereklidir.

Bağımlılıklar

zstd_compression_tool, bir arşivin görüntü dosyalarını sıkıştırmak ve zstd ile yeniden sıkıştırmak için kullanılır. Bu işlem, fark oluşturma için kullanılan tüm arşiv dosyalarının arşivler içindeki görüntüler için aynı sıkıştırma algoritmasına sahip olmasını sağlar.

Gerekli paketleri/kitaplıkları yüklemeye yönelik komutlar:

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

DiffGen kullanarak delta güncelleştirmesi oluşturma

DiffGen aracı birkaç bağımsız değişkenle çalıştırılır. Tüm bağımsız değişkenler gereklidir ve genel söz dizimi aşağıdaki gibidir:

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

Betik recompress_tool.py , [recompressed_target_archive] dosyasını oluşturmak için çalışır ve daha sonra fark oluşturmak için hedef dosya olarak [target_archive] yerine kullanılır.
[recompressed_target_archive] içindeki görüntü dosyaları zstd ile sıkıştırılır.

SWU dosyalarınız imzalıysa (büyük olasılıkla), başka bir bağımsız değişkene de ihtiyacınız vardır:

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

Hedef dosya olarak [recompressed_target_archive] kullanmaya ek olarak, [recompressed_target_archive] dosyasını oluşturmak ve arşivdeki sw-description dosyasının imzalanması için recompress_and_sign_tool.py bir imzalama komut dizesi parametresinin sağlanması (sw-description.sig dosyasının mevcut olduğu anlamına gelir) çalışır. Azure/iot-hub-device-update-delta GitHub deposundaki örnek sign_file.sh betiği kullanabilirsiniz. Betiği açın, özel anahtar dosyanıza yol eklemek için düzenleyin ve kaydedin. Örnek kullanım için örnekler bölümüne bakın.

Aşağıdaki tabloda bağımsız değişkenler daha ayrıntılı olarak açıklanmaktadır:

Bağımsız değişken	Açıklama
[source_archive]	Bu, delta oluşturulurken deltanın temel alındığı görüntüdür. Önemli: Bu görüntü, cihazda zaten var olan görüntüyle aynı olmalıdır (örneğin, önceki bir güncelleştirmeden önbelleğe alınmış).
[target_archive]	Bu, deltanın cihazı güncelleştirdiğinde görüntüdür.
[output_path]	Delta dosyasının oluşturulduktan sonra yerleştirildiği konak makinedeki yol (oluşturulan delta dosyasının istenen adı dahil). Yol yoksa araç bunu oluşturur.
[log_folder]	Konak makinesinde günlüklerin oluşturduğu yol. Bu konumu çıkış yolunun alt klasörü olarak tanımlamanızı öneririz. Yol yoksa araç bunu oluşturur.
[working_folder]	Delta oluşturma sırasında ikincil ve diğer çalışma dosyalarının yerleştirildiği makinedeki yol. Bu konumu çıkış yolunun alt klasörü olarak tanımlamanızı öneririz. Yol yoksa araç bunu oluşturur.
[recompressed_target_archive]	Yeniden sıkıştırılan hedef dosyanın oluşturulduğu konak makinedeki yol. Bu dosya, fark oluşturma için hedef dosya olarak target_archive> yerine <kullanılır. DiffGenTool çağrılmadan önce bu yol varsa, yolun üzerine yazılır. Bu yolu çıkış yolunun alt klasöründe bir dosya olarak tanımlamanızı öneririz.
"[signing_command]" (isteğe bağlı)	Yeniden sıkıştırılan arşiv dosyasında sw-description dosyasını imzalamak için kullanılan özelleştirilebilir bir komut. Yeniden sıkıştırılan arşivdeki sw-description dosyası, imzalama komutu için giriş parametresi olarak kullanılır; DiffGenTool, eklenen girişin `.sig` adını kullanarak imzalama komutunun yeni bir imza dosyası oluşturmasını bekler. Tüm komutun tek bir parametre olarak geçirilmesi için parametreyi çift tırnak içinde çevreleyin. Ayrıca, '~' karakterini imzalamak için kullanılan bir anahtar yoluna yerleştirmekten kaçının ve bunun yerine tam giriş yolunu kullanın (örneğin, ~/keys/priv.pem yerine /home/USER/keys/priv.pem kullanın).

DiffGen örnekleri

Bu örneklerde ,/mnt/o/temp dizininden (WSL'de) çalıştırıyoruz:

Giriş kaynak dosyası ile yeniden sıkıştırılan hedef dosya arasında fark oluşturma:

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]

İmzalama parametresini de kullanıyorsanız (SWU dosyanız imzalanmışsa gereklidir), daha önce başvurulan örnek sign_file.sh betiği kullanabilirsiniz. İlk olarak betiği açın ve özel anahtar dosyanıza yol eklemek için düzenleyin. Betiği kaydedin ve DiffGen'i aşağıdaki gibi çalıştırın:

Giriş kaynak dosyası ile yeniden sıkıştırılan/yeniden imzalanan hedef dosya arasında fark oluşturma:

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

Oluşturulan delta güncelleştirmesini içeri aktarma

Değişiklik güncelleştirmeleri için bir güncelleştirmeyi Cihaz Güncelleştirmesi hizmetine aktarmanın temel süreci değişmemiştir; bu nedenle henüz yapmadıysanız şu sayfayı gözden geçirmeyi unutmayın: IoT Hub için Azure Cihaz Güncelleştirmesi'ne aktarılacak güncelleştirmeyi hazırlama

İçeri aktarma bildirimi oluşturma

Bir güncelleştirmeyi Cihaz Güncelleştirmesi hizmetine aktarmanın ilk adımı, henüz bir güncelleştirmeyiniz yoksa her zaman bir içeri aktarma bildirimi oluşturmaktır. İçeri aktarma bildirimleri hakkında daha fazla bilgi için bkz . Güncelleştirmeleri Cihaz Güncelleştirmesi'ne aktarma. Delta güncelleştirmeleri için içeri aktarma bildiriminizin iki dosyaya başvurması gerekir:

DiffGen aracını çalıştırdığınızda oluşturulan yeniden sıkıştırılan hedef SWU görüntüsü.
DiffGen aracını çalıştırdığınızda oluşturulan delta dosyası.

Delta güncelleştirme özelliği, sürüm 5 veya üzeri bir içeri aktarma bildirimi gerektiren ilgili dosyalar adlı bir özellik kullanır.

İlgili dosyalar özelliğini kullanarak delta güncelleştirmeniz için bir içeri aktarma bildirimi oluşturmak için, içeri aktarma bildiriminize relatedFiles ve downloadHandler nesneleri eklemeniz gerekir.

relatedFiles Dosya adı, dosya boyutu ve sha256 karması dahil olmak üzere delta güncelleştirme dosyası hakkındaki bilgileri belirtmek için nesnesini kullanın. Daha da önemlisi, delta güncelleştirme özelliğine özgü iki özellik de belirtmeniz gerekir:

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

Bu özelliklerin her ikisi de delta güncelleştirmenizi oluştururken DiffGen aracına giriş olarak kullandığınız kaynak SWU görüntü dosyanıza özeldir. Kaynak görüntüyü gerçekten içeri aktarmasanız bile içeri aktarma bildiriminizde kaynak SWU görüntüsüyle ilgili bilgiler gereklidir. Cihazdaki delta bileşenleri, delta indirildikten sonra görüntüyü cihazda bulmak için kaynak görüntüyle ilgili bu meta verileri kullanır.

downloadHandler İlgili dosyalar özelliğini kullanarak Cihaz Güncelleştirmesi aracısının delta güncelleştirmesini nasıl düzenleneceğini belirtmek için nesnesini kullanın. Delta işlevselliği için cihaz güncelleştirme aracısının kendi sürümünü özelleştirmediğiniz sürece, yalnızca şu downloadHandler'ı kullanmalısınız:

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

Delta güncelleştirmeniz için bir içeri aktarma bildirimi oluşturmak için Azure Komut Satırı Arabirimi'ni (CLI) kullanabilirsiniz. Daha önce içeri aktarma bildirimi oluşturmak için Azure CLI kullanmadıysanız bkz . Temel içeri aktarma bildirimi oluşturma.

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

Oluşturduğunuz içeri aktarma bildirimi JSON'unu uzantılı bir dosyaya kaydedin .importmanifest.json

Azure portalını kullanarak dışarı aktarma

İçeri aktarma bildiriminizi oluşturduktan sonra delta güncelleştirmesini içeri aktarmaya hazırsınız demektir. İçeri aktarmak için IoT Hub için Cihaz Güncelleştirmesi'ne güncelleştirme ekleme başlığındaki yönergeleri izleyin. İçeri aktarırken şu öğeleri eklemeniz gerekir:

Önceki adımda oluşturduğunuz içeri aktarma bildirimi .json dosyası.
DiffGen aracını çalıştırdığınızda oluşturulan yeniden sıkıştırılan hedef SWU görüntüsü.
DiffGen aracını çalıştırdığınızda oluşturulan delta dosyası.

Delta güncelleştirmesini cihazlarınıza dağıtma

Bir delta güncelleştirmesi dağıttığınızda, Azure portalındaki deneyim normal görüntü güncelleştirmesini dağıtma deneyimiyle aynı görünür. Güncelleştirmeleri dağıtma hakkında daha fazla bilgi için bkz . Azure IoT Hub için Cihaz Güncelleştirmesi'ni kullanarak güncelleştirme dağıtma.

Delta güncelleştirmeniz için dağıtımı oluşturduktan sonra Cihaz Güncelleştirmesi hizmeti ve istemcisi, dağıttığınız her cihaz için geçerli bir değişiklik güncelleştirmesi olup olmadığını otomatik olarak belirler. Geçerli bir delta bulunursa, delta güncelleştirmesi bu cihaza indirilir ve yüklenir. Geçerli bir değişiklik güncelleştirmesi bulunmazsa, geri dönüş olarak tam görüntü güncelleştirmesi (yeniden sıkıştırılan hedef SWU görüntüsü) indirilir. Bu yaklaşım, güncelleştirmeyi dağıttığınız tüm cihazların uygun sürüme ulaşabilmesini sağlar.

Delta güncelleştirme dağıtımı için üç olası sonuç vardır:

Delta güncelleştirmesi başarıyla yüklendi. Cihaz yeni sürümde.
Delta güncelleştirmesi kullanılamıyordu veya yüklenemedi, ancak bunun yerine tam görüntünün başarılı bir geri dönüş yüklemesi oluştu. Cihaz yeni sürümde.
Hem delta hem de tam görüntüye geri dönüş başarısız oldu. Cihaz hala eski sürümde.

Yukarıdaki sonuçlardan hangisinin gerçekleştiğini belirlemek için, başarısız durumdaki herhangi bir cihazı seçerek yükleme sonuçlarını hata kodu ve genişletilmiş hata koduyla görüntüleyebilirsiniz. Gerekirse birden çok başarısız cihazdan da günlük toplayabilirsiniz.

Delta güncelleştirmesi başarılı olursa, cihaz "Başarılı" durumunu gösterir.

Delta güncelleştirmesi başarısız olduysa ancak tam görüntüye başarılı bir geri dönüş yaptıysa, aşağıdaki hata durumunu gösterir:

resultCode: [0'dan büyük değer]
extendedResultCode: [sıfır olmayan]

Güncelleştirme başarısız olduysa, şu yönergeler kullanılarak yorumlanabilir bir hata durumu gösterir:

Result.h dosyasındaki Cihaz Güncelleştirme Aracısı hatalarıyla başlayın.

Değişiklik güncelleştirmeleri için kullanılan İndirme İşleyicisi işlevselliğine özgü Cihaz Güncelleştirme Aracısı hataları 0x9 ile başlar:

Bileşen	Ondalık	Onaltılık	Not
EXTENSION_MANAGER	0	0x00	Uzantı yöneticisi indirme işleyici mantığındaki hataları gösterir. Örnek: 0x900XXXXX
EKLENTİ	1	0x01	İndirme işleyicisi eklentisi paylaşılan kitaplıklarının kullanımıyla ilgili hataları gösterir. Örnek: 0x901XXXXX
SAKLI -DIR	2 - 7	0x02 - 0x07	İndirme işleyicisi için ayrılmıştır. Örnek: 0x902XXXXX
ORTAK	8	0x08	Delta İndirme İşleyicisi uzantısı üst düzey mantığındaki hataları gösterir. Örnek: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Delta İndirme işleyici uzantısı Kaynak Güncelleştirme Önbelleği'ndeki hataları gösterir. Örnek: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Delta işlemci API'sinden gelen hatalar için hata kodu. Örnek: 0x90AXXXXX

Hata kodu result.h dosyasında yoksa, büyük olasılıkla delta işlemci bileşeninde (Cihaz Güncelleştirmesi aracısından ayrı) bir hatadır. Öyleyse, extendedResultCode şu onaltılık biçimdeki negatif bir ondalık değerdir: 0x90AXXXXX
- 9, "Delta Tesisi"
- 0A, "Delta İşlemci Bileşeni" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX, FIT delta işlemcisinin 20 bit hata kodudur

Hata kodu bilgilerine göre sorunu çözemiyorsanız daha fazla yardım almak için bir GitHub sorunu oluşturun.

Sonraki adımlar

Yerel kümenizde sorun giderme

Aracılığıyla paylaş