Delta güncelleştirmeleri (Önizleme)

Delta güncelleştirmeleri, yalnızca iki tam güncelleştirme, bir kaynak görüntü ve hedef görüntü arasındaki değişiklikleri temsil eden küçük güncelleştirmeler 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.

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.

Delta oluşturma işlemi, en iyi deltayı oluşturmak için gzip sıkıştırmasını kullanarak hedef SWU güncelleştirmesini yeniden sıkıştırıyor. Yeniden sıkıştırılan hedef SWU güncelleştirmesini, oluşturulan delta güncelleştirme dosyasıyla birlikte Cihaz Güncelleştirmesi hizmetine aktarırsınız.

Delta işlemci bileşeni için Cihaz Güncelleştirmesi aracı yapılandırması

Cihaz Güncelleştirme hizmetinden değişiklik güncelleştirmelerini indirip yüklemek için, cihazınızın güncelleştirme işleyicisi ve delta işlemci bileşeninin mevcut ve yapılandırılmış olduğu Cihaz Güncelleştirmesi aracısına ihtiyacı vardır.

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 eklemek ve kullanmak üzere yapılandırmak için bkz . Cihaz Güncelleştirmesi aracısı sağlama. Aracı sürüm 1.0 veya üzerini kullanın.

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.

Delta işlemci

Azure/iot-hub-device-update-delta konumundaki delta işlemcisi , değişiklik 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 bileşenini cihaz görüntünüze eklemek ve kullanmak üzere yapılandırmak için adresinden Ubuntu 20.04 ve üzeri https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0için bir Debian paketi indirebilirsiniz.

Başka bir dağıtım kullanıyorsanız, bunun yerine kaynaktan delta işlemcisi oluşturmak için CMAKE'yi kullanmak için README.md yönergelerini izleyin. Buradan, paylaşılan nesneyi /usr/lib dizinine aşağıdaki gibi kopyalayarak doğrudan libadudiffapi.so yükleyin:

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

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

Delta güncelleştirme dosyası bir cihaza indirildikten sonra, daha önce cihazda önbelleğe alınmış geçerli <source_archive> bir dosyayla karşılaştırılır. Bu işlem, delta güncelleştirmesinin tam hedef görüntüyü yeniden oluşturmasını sağlar.

Bu önbelleğe alınmış görüntüyü doldurmanın en basit yolu, Cihaz Güncelleştirme hizmeti aracılığıyla cihaza tam görüntü güncelleştirmesi içeri aktarmak ve dağıtmaktır. Cihaz, Cihaz Güncelleştirme aracısı sürüm 1.0 veya üzeri ve delta işlemcisi ile yapılandırılmışsa aracı, yüklü SWU dosyasını daha sonra delta güncelleştirme kullanımı için otomatik olarak önbelleğe alır.

Bunun yerine doğrudan cihazınızdaki kaynak görüntüyü önceden doldurmayı istiyorsanız, görüntünün beklendiği yol şeklindedir <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>. Varsayılan olarak, <BASE_SOURCE_DOWNLOAD_CACHE_PATH> /var/lib/adu/sdc/<provider yoludur>. provider değeri, provider kaynak SWU dosyasının updateId değeridir.

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ştirme oluşturma

Fark Oluşturma (DiffGen) aracını kullanarak delta güncelleştirmeleri oluşturabilirsiniz.

Ortam önkoşulları

DiffGen ile deltalar oluşturmadan önce, ortam makinesine birkaç şey indirip yüklemeniz gerekir. İdeal olarak bir Ubuntu 20.04 Linux ortamı kullanın veya Windows kullanıyorsanız Linux için Windows Alt Sistemi.

Aşağıdaki tabloda gereken içerik, nereden alınacağı ve gerekirse önerilen yükleme gösterilmektedir.

DiffGen kullanarak delta güncelleştirme oluşturma

DiffGen aracı aşağıdaki gerekli bağımsız değişkenler ve söz dizimi ile çalışır:

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

Yukarıdaki komut, dosyasını oluşturan <recompressed_target_file>recompress_tool.py betiğini çalıştırır. DiffGen daha sonra fark oluşturmak için hedef dosya olarak yerine <target_archive> öğesini kullanır<recompressed_target_file>. içindeki <recompressed_target_archive> görüntü dosyaları gzip ile sıkıştırılır.

SWU dosyalarınız imzalıysa, DiffGen komutunda bağımsız değişkeni de gerektirir <signing_command> :

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

İmzalama komut dizesi parametresine sahip DiffGenTool, recompress_and_sign_tool.py betiğini çalıştırır. Bu betik, oluşturur <recompressed_target_file>. Ayrıca bu betik, sw-description.sig dosyası oluşturmak için arşivdeki sw-description dosyasını da imzalar.

Giriş kaynak dosyası ile yeniden sıkıştırılmış ve yeniden imzalanmış bir hedef dosya arasında fark oluşturmak için Azure/iot-hub-device-update-delta GitHub deposundaki örnek sign_file.sh betiğini 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:

DiffGen örnekleri

Aşağıdaki örnekler Linux için Windows Alt Sistemi'de /mnt/o/temp dizininde çalışır.

Aşağıdaki kod, giriş kaynak dosyası ile yeniden sıkıştırılan hedef dosya arasında bir fark oluşturur:

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

SWU dosyanız imzalıysa kullanmanız gereken imzalama parametresini de kullanıyorsanız, daha önce bahsedilen örnek sign_file.sh betiğini kullanabilirsiniz. Betiği açın, özel anahtar dosyanıza yol eklemek için düzenleyin, betiği kaydedin ve DiffGen'i aşağıdaki gibi çalıştırın.

Aşağıdaki kod, giriş kaynak dosyası ile yeniden sıkıştırılmış ve yeniden imzalanan hedef dosya arasında fark oluşturur:

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

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

Cihaz Güncelleştirme hizmetine delta güncelleştirmesini içeri aktarmanın temel işlemi, diğer güncelleştirmeler ile aynıdır. Henüz yapmadıysanız, IoT Hub için Azure Cihaz Güncelleştirmesi'ne aktarılacak güncelleştirmeyi hazırlama makalesini gözden geçirmeyi unutmayın.

İçeri aktarma bildirimini oluşturma

Bir güncelleştirmeyi Cihaz Güncelleştirmesi hizmetine aktarmak için bir içeri aktarma bildirim dosyasına sahip olmanız veya oluşturmanız gerekir. Daha fazla bilgi için bkz . Güncelleştirmeleri Cihaz Güncelleştirmesi'ne aktarma.

Delta güncelleştirmeleri için içeri aktarma bildirim dosyaları, DiffGen aracının oluşturduğu aşağıdaki dosyalara başvurmalıdır:

• <recompressed_target_file> SWU görüntüsü
• <delta file>

Delta güncelleştirme özelliği, sürüm 5 veya sonraki bir içeri aktarma bildirimi gerektiren ilgili dosyalar olarak adlandırılan bir özellik kullanır. İlgili dosyalar özelliğini kullanmak için, içeri aktarma bildiriminize relatedFiles ve downloadHandler nesnelerini eklemeniz gerekir.

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

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

Her iki özellik de delta güncelleştirmenizi oluştururken DiffGen aracına giriş olarak kullandığınız özelliklere özeldir <source image file> . İçeri aktarma bildirimi, kaynak görüntüyü içeri aktarmasanız bile kaynak SWU görüntüsüyle ilgili bilgilere ihtiyaç duyar. Cihazdaki delta bileşenleri, delta güncelleştirmesini indirdikten sonra bu görüntüyü cihazda bulmak için kaynak görüntüyle ilgili bu meta verileri kullanır.

downloadHandler Cihaz Güncelleştirmesi aracısının delta güncelleştirmesini ilgili dosyalar özelliğini kullanarak nasıl düzenleneceğini belirtmek için nesnesini kullanın. Değişiklik işlevselliği için Cihaz Güncelleştirmesi aracısının kendi sürümünü özelleştirmediğiniz sürece aşağıdakileri downloadHandlerkullanın:

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

Delta güncelleştirmeniz için bir içeri aktarma bildirimi oluşturmak için Azure CLI az iot du update init v5 komutunu kullanabilirsiniz. Daha fazla bilgi için bkz . Temel içeri aktarma bildirimi oluşturma.

--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 dosyasını dosya uzantısı .importmanifest.json kaydedin.

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

İçeri aktarma bildiriminizi oluşturduktan sonra IoT Hub için Cihaz Güncelleştirmesi'ne güncelleştirme ekleme başlığı altında yer alan yönergeleri izleyerek delta güncelleştirmesini içeri aktarın. İçeri aktarma işlemine aşağıdaki öğeleri eklemeniz gerekir:

• Önceki adımlarda daha önce oluşturduğunuz *importmanifest.json dosyası
• <recompressed_target_file> DiffGen aracının oluşturduğu SWU görüntüsü
• Oluşturulan <delta file> DiffGen aracı

Cihazlara delta güncelleştirme dağıtımı

Azure portalındaki delta güncelleştirmesi dağıtım deneyimi, normal bir görüntü güncelleştirmesi dağıtmakla aynıdır. Daha fazla bilgi için bkz . Cihaz Güncelleştirmesini kullanarak güncelleştirme dağıtma.

Delta güncelleştirmeniz için dağıtımı oluşturduktan sonra Cihaz Güncelleştirme 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 bulurlarsa delta güncelleştirmesini indirip bu cihaza yüklerler.

Geçerli bir değişiklik güncelleştirmesi bulamazsa, tam görüntü güncelleştirmesi (yeniden sıkıştırılan hedef SWU görüntüsü) geri dönüş olarak 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 ve cihaz yeni sürümde.
• Delta güncelleştirmesi kullanılamıyordu veya yüklenemedi, ancak tam görüntünün geri dönüş yüklemesi başarılı oldu ve cihaz yeni sürümde.
• Hem delta hem de geri dönüş yüklemeleri başarısız oldu ve cihaz hala eski sürümde.

Hangi hata sonucunun oluştuğuna karar vermek için, başarısız durumdaki herhangi bir cihazı seçerek hata kodu ve genişletilmiş hata koduyla yükleme sonuçlarını 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 geri dönüş başarılı olduysa, cihaz aşağıdaki hata durumunu gösterir:

  • resultCode: <0'dan büyük değer>
  • extendedResultCode: <sıfır olmayan değer>

Başarısız güncelleştirme sorunlarını giderme

Başarısız güncelleştirmeler, aşağıdaki yönergeleri kullanarak yorumlayabileceğiniz bir hata durumu görüntüler. Result.h dosyasındaki Cihaz Güncelleştirme aracısı hatalarıyla başlayın.

Cihaz Güncelleştirmesi aracısından delta güncelleştirmeleri indirme işleyicisi işlevine özgü hatalar ile 0x9başlar:

Hata kodu result.h dosyasında yoksa, büyük olasılıkla Cihaz Güncelleştirmesi aracısından ayrı olarak delta işlemci bileşeninde bir hatadır. Öyleyse, extendedResultCode onaltılık biçimdeki 0x90AXXXXXnegatif ondalık değeridir.

• 9 "Delta Tesisi"
• 0A is "Delta processor component" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
• XXXXX , Alan Yükleme Aracı (FIT) delta işlemcisinden alınan 20 bit hata kodudur

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

İlgili içerik

• IoT Hub için Azure Cihaz Güncelleştirmesi içeri aktarma bildirimi şeması
• Yerel kümenizde sorun giderme