تحديثات دلتا (معاينة)

تسمح لك تحديثات دلتا بإنشاء تحديثات صغيرة تمثل فقط التغييرات بين تحديثين كاملين، صورة مصدر وصورة هدف. يعد هذا الأسلوب مثاليا لتقليل النطاق الترددي المستخدم لتنزيل تحديث إلى جهاز، خاصة إذا كانت هناك بعض التغييرات فقط بين التحديثات المصدر والهدف.

متطلبات استخدام تحديثات دلتا في تحديث الجهاز ل IoT Hub

• يجب أن تكون ملفات التحديث المصدر والهدف بتنسيق SWUpdate (SWU).
• داخل كل ملف SWUpdate، يجب أن تكون هناك صورة أولية تستخدم نظام ملفات Ext2 أو Ext3 أو Ext4.

تعيد عملية إنشاء دلتا ضغط تحديث SWU الهدف باستخدام ضغط gzip لإنتاج دلتا مثالية. يمكنك استيراد تحديث SWU الهدف المعاد ضغطه إلى خدمة Device Update مع ملف تحديث دلتا الذي تم إنشاؤه.

تكوين عامل تحديث الجهاز لمكون معالج دلتا

لتنزيل تحديثات دلتا وتثبيتها من خدمة Device Update، يحتاج جهازك إلى عامل Device Update مع وجود مكون معالج التحديث ومكون معالج دلتا وتكوينه.

عامل تحديث الجهاز

ينسق عامل Device Update عملية التحديث على الجهاز، بما في ذلك إجراءات التنزيل والتثبيت وإعادة التشغيل. لإضافة عامل تحديث الجهاز إلى جهاز وتكوينه للاستخدام، راجع توفير عامل تحديث الجهاز. استخدم إصدار العامل 1.0 أو أحدث.

معالج التحديث

يتكامل معالج التحديث مع عامل Device Update لتنفيذ تثبيت التحديث الفعلي. بالنسبة إلى تحديثات دلتا، ابدأ بمعالج microsoft/swupdate:2 التحديث إذا لم يكن لديك بالفعل معالج تحديث SWUpdate الخاص بك الذي تريد تعديله.

معالج دلتا

يعيد معالج دلتا في Azure/iot-hub-device-update-delta إنشاء ملف صورة SWU الأصلي على جهازك بعد تنزيل ملف دلتا، بحيث يمكن لمعالج التحديث تثبيت ملف SWU. لإضافة مكون معالج دلتا إلى صورة جهازك وتكوينه للاستخدام، يمكنك تنزيل حزمة Debian ل Ubuntu 20.04 والإصدارات الأحدث من https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

إذا كنت تستخدم توزيعة أخرى، فاتبع إرشادات README.md لاستخدام CMAKE لإنشاء معالج دلتا من المصدر بدلا من ذلك. من هناك، قم بتثبيت الكائن المشترك libadudiffapi.so مباشرة عن طريق نسخه إلى الدليل /usr/lib ، كما يلي:

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

إضافة ملف صورة SWU مصدر إلى جهازك

بعد تنزيل ملف تحديث دلتا إلى جهاز، تتم مقارنته بملفات صالحة <source_archive> مخزنة مؤقتا مسبقا على الجهاز. تمكن هذه العملية تحديث دلتا من إعادة إنشاء الصورة الهدف الكامل.

أبسط طريقة لملء هذه الصورة المخزنة مؤقتا هي استيراد ونشر تحديث كامل للصورة إلى الجهاز عبر خدمة Device Update. إذا تم تكوين الجهاز باستخدام إصدار عامل تحديث الجهاز 1.0 أو أحدث ومعالج دلتا، يقوم العامل بتخزين ملف SWU المثبت مؤقتا تلقائيا لاستخدام تحديث دلتا لاحقا.

إذا كنت تريد ملء الصورة المصدر مباشرة على جهازك بدلا من ذلك، فإن المسار الذي يتوقع الصورة فيه هو <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>. بشكل افتراضي، <BASE_SOURCE_DOWNLOAD_CACHE_PATH> هو المسار /var/lib/adu/sdc/<provider>. provider القيمة هي provider جزء من updateId لملف SWU المصدر.

ENCODED_HASH هو سلسلة سداسية 64 من SHA256 للثنائي، ولكن بعد الترميز إلى سلسلة سداسية عشرية base64، فإنه يقوم بترميز الأحرف كما يلي:

• + مرمز ك octets _2B
• / مرمز ك octets _2F
• = مرمز ك octets _3D

إنشاء تحديث دلتا باستخدام أداة DiffGen

يمكنك إنشاء تحديثات دلتا باستخدام أداة Diff Generation (DiffGen).

المتطلبات الأساسية للبيئة

قبل إنشاء دلتا مع DiffGen، تحتاج إلى تنزيل وتثبيت العديد من الأشياء على جهاز البيئة. من الناحية المثالية، استخدم بيئة Ubuntu 20.04 Linux، أو نظام Windows الفرعي لـ Linux إذا كنت تستخدم Windows.

يعرض الجدول التالي المحتوى المطلوب ومكان الحصول عليه والتثبيت الموصى به إذا لزم الأمر.

إنشاء تحديث دلتا باستخدام DiffGen

تعمل أداة DiffGen مع الوسيطات وبناء الجملة المطلوبة التالية:

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

يقوم الأمر السابق بتشغيل البرنامج النصي recompress_tool.py ، والذي ينشئ <recompressed_target_file>. ثم يستخدم <recompressed_target_file>DiffGen بدلا من <target_archive> كملف هدف لإنشاء diff. يتم ضغط ملفات الصور داخل <recompressed_target_archive> مع gzip.

إذا تم توقيع ملفات SWU الخاصة بك، فإنها تتطلب أيضا الوسيطة <signing_command> في الأمر DiffGen:

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

تقوم معلمة DiffGenTool مع سلسلة أوامر التوقيع بتشغيل البرنامج النصي recompress_and_sign_tool.py . ينشئ <recompressed_target_file>هذا البرنامج النصي . بالإضافة إلى ذلك، يوقع هذا البرنامج النصي أيضا ملف sw-description داخل الأرشيف لإنشاء ملف sw-description.sig .

يمكنك استخدام نموذج البرنامج النصي sign_file.sh من مستودع Azure/iot-hub-device-update-delta GitHub لإنشاء فرق بين ملف مصدر الإدخال وملف هدف تم إعادة ضغطه وإعادة توقيعه. افتح البرنامج النصي، وقم بتحريره لإضافة المسار إلى ملف المفتاح الخاص، واحفظه. راجع قسم الأمثلة لاستخدام العينة.

يصف الجدول التالي الوسيطات بمزيد من التفصيل:

أمثلة DiffGen

تعمل الأمثلة التالية من الدليل /mnt/o/temp في نظام Windows الفرعي لـ Linux.

تنشئ التعليمات البرمجية التالية فرقا بين ملف مصدر الإدخال وملف هدف تم إعادة ضغطه:

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 الخاص بك، يمكنك استخدام نموذج البرنامج النصي sign_file.sh المذكور سابقا. افتح البرنامج النصي، وقم بتحريره لإضافة المسار إلى ملف المفتاح الخاص بك، واحفظ البرنامج النصي، ثم قم بتشغيل DiffGen كما يلي.

تنشئ التعليمات البرمجية التالية فرقا بين ملف مصدر الإدخال وملف هدف تم إعادة ضغطه وإعادة توقيعه:

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

استيراد تحديث دلتا الذي تم إنشاؤه

العملية الأساسية لاستيراد تحديث دلتا إلى خدمة تحديث الجهاز هي نفسها لأي تحديث آخر. إذا لم تكن قد قمت بالفعل، فتأكد من مراجعة كيفية إعداد تحديث ليتم استيراده إلى Azure Device Update ل IoT Hub.

إنشاء بيان الاستيراد

لاستيراد تحديث إلى خدمة تحديث الجهاز، يجب أن يكون لديك ملف بيان استيراد أو أنشئه. لمزيد من المعلومات، راجع استيراد التحديثات إلى تحديث الجهاز.

يجب أن يشير استيراد ملفات البيان لتحديثات دلتا إلى الملفات التالية التي أنشأتها أداة DiffGen:

• <recompressed_target_file> صورة SWU
• الـ <delta file>

تستخدم ميزة تحديث دلتا إمكانية تسمى الملفات ذات الصلة التي تتطلب إصدار 5 أو أحدث من بيان الاستيراد. لاستخدام ميزة الملفات ذات الصلة، يجب تضمين العناصر relatedFiles و downloadHandler في بيان الاستيراد الخاص بك.

يمكنك استخدام relatedFiles الكائن لتحديد معلومات حول ملف تحديث دلتا، بما في ذلك اسم الملف وحجم الملف وتجزئة sha256. والأهم من ذلك، يجب عليك أيضا تحديد الخاصيتين التاليتين الفريدتين لميزة تحديث دلتا:

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

كلتا الخاصيتين خاصتان بالخاصية التي <source image file> استخدمتها كإدخال إلى أداة DiffGen عند إنشاء تحديث دلتا الخاص بك. يحتاج بيان الاستيراد إلى معلومات حول صورة SWU المصدر على الرغم من أنك لا تستورد الصورة المصدر فعليا. تستخدم مكونات دلتا على الجهاز بيانات التعريف هذه حول الصورة المصدر لتحديد موقع تلك الصورة على الجهاز بعد تنزيل تحديث دلتا.

downloadHandler استخدم الكائن لتحديد كيفية تنسيق عامل Device Update لتحديث دلتا باستخدام ميزة الملفات ذات الصلة. ما لم تقم بتخصيص الإصدار الخاص بك من عامل Device Update لوظيفة دلتا، استخدم ما يلي downloadHandler:

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

يمكنك استخدام الأمر Azure CLI 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>"}' 

احفظ بيان الاستيراد الذي تم إنشاؤه JSON مع ملحق الملف .importmanifest.json.

الاستيراد باستخدام مدخل Microsoft Azure

بمجرد إنشاء بيان الاستيراد الخاص بك، قم باستيراد تحديث دلتا باتباع الإرشادات الواردة في إضافة تحديث إلى تحديث الجهاز ل IoT Hub. يجب تضمين العناصر التالية في الاستيراد:

• ملف *importmanifest.json الذي قمت بإنشائه مسبقا في الخطوات السابقة
• <recompressed_target_file> صورة SWU التي أنشأتها أداة DiffGen
• <delta file> أداة DiffGen التي تم إنشاؤها

نشر تحديث دلتا إلى الأجهزة

تجربة نشر تحديث دلتا في مدخل Microsoft Azure هي نفسها نشر تحديث صورة عادي. لمزيد من المعلومات، راجع نشر تحديث باستخدام تحديث الجهاز.

بمجرد إنشاء النشر لتحديث دلتا الخاص بك، تحدد خدمة تحديث الجهاز والعميل تلقائيا ما إذا كان هناك تحديث دلتا صالح لكل جهاز تقوم بالنشر إليه. إذا وجدوا دلتا صالحة، فإنهم يقومون بتنزيل تحديث دلتا وتثبيته على هذا الجهاز.

إذا لم يعثروا على تحديث دلتا صالح، يتم تنزيل تحديث الصورة الكامل (صورة SWU الهدف المعاد ضغطها) بدلا من ذلك كتراجع. يضمن هذا الأسلوب أن جميع الأجهزة التي تقوم بنشر التحديث للوصول إلى الإصدار المناسب.

هناك ثلاث نتائج محتملة لنشر تحديث دلتا:

• تم تثبيت تحديث دلتا بنجاح والجهاز على الإصدار الجديد.
• لم يكن تحديث دلتا متوفرا أو فشل تثبيته، ولكن تم تثبيت احتياطي للصورة الكاملة بنجاح، والجهاز على الإصدار الجديد.
• فشل تثبيت كل من دلتا والنسخ الاحتياطي، ولا يزال الجهاز على الإصدار القديم.

لتحديد نتيجة الفشل التي حدثت، يمكنك عرض نتائج التثبيت مع رمز الخطأ ورمز الخطأ الموسع عن طريق تحديد أي جهاز في حالة فشل. يمكنك أيضا جمع السجلات من عدة أجهزة فاشلة إذا لزم الأمر.

• إذا نجح تحديث دلتا، يظهر الجهاز حالة Succeeded .

• إذا فشل تحديث دلتا ولكن نجح النسخ الاحتياطي للصورة الكاملة، يظهر الجهاز حالة الخطأ التالية:

  • resultCode: <قيمة أكبر من 0>
  • extendedResultCode: <قيمة غير صفرية>

استكشاف أخطاء التحديثات الفاشلة وإصلاحها

تعرض التحديثات غير الناجحة حالة خطأ يمكنك تفسيرها باستخدام الإرشادات التالية. ابدأ بأخطاء عامل تحديث الجهاز في result.h.

تبدأ الأخطاء من عامل Device Update الخاصة بوظيفة معالج تنزيل تحديثات دلتا ب 0x9:

إذا لم يكن رمز الخطأ موجودا في result.h، فمن المحتمل أن يكون خطأ في مكون معالج دلتا، منفصلا عن عامل Device Update. إذا كان الأمر كذلك، extendedResultCode تكون قيمة عشرية سالبة بالتنسيق 0x90AXXXXXالسداسي العشري .

• 9 هو "Delta Facility"
• 0A هو "Delta Processor Component" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
• XXXXX هو رمز الخطأ 20 بت من معالج دلتا أداة تثبيت الحقل (FIT)

إذا لم تتمكن من حل المشكلة استنادا إلى معلومات رمز الخطأ، فتحقق من مشكلة GitHub للحصول على مزيد من المساعدة.

المحتوى ذو الصلة

• تحديث جهاز Azure لمخطط بيان استيراد IoT Hub
• استكشاف المشكلات الشائعة وإصلاحها