Как понять и использовать разностные обновления в обновлении устройств для Центр Интернета вещей (предварительная версия)

  • Статья

Разностные обновления позволяют создавать небольшое обновление, представляющее только изменения между двумя полными обновлениями — исходного образа и целевого образа. Этот подход идеально подходит для уменьшения пропускной способности, используемой для скачивания обновления на устройство, особенно если между исходным и целевым обновлениями есть только несколько изменений.

Примечание.

Функция разностного обновления в настоящее время доступна в общедоступной предварительной версии.

Требования к использованию разностных обновлений в обновлении устройств для Центр Интернета вещей

  • Исходные и целевые файлы обновления должны иметь формат SWUpdate (SWU).
  • В каждом файле SWUpdate должен быть необработанный образ, использующий файловую систему Ext2, Ext3 или Ext4. Это изображение можно сжать с помощью gzip или zstd.
  • Процесс создания разностного поколения повторно сжимает целевое обновление SWU с помощью сжатия zstd, чтобы обеспечить оптимальную разностную дельту. Импортируйте это повторное обновление целевого swU в службу обновления устройств вместе с созданным файлом разностного обновления.
  • В SWUpdate на устройстве также должен быть включен zstd decompression.
    • Для этого процесса требуется использование SWUpdate 2019.11 или более поздней версии.

Настройка устройства с помощью агента обновления устройств и компонента разностного процессора

Чтобы устройство скачать и установить разностные обновления из службы обновления устройств, вам потребуется несколько компонентов, присутствующих и настроенных.

Агент Обновления устройств

Агент обновления устройств управляет процессом обновления на устройстве, включая скачивание, установку и перезапуск действий. Добавьте агент обновления устройств на устройство и настройте его для использования. Используйте агент версии 1.0 или более поздней. Инструкции см. в разделе "Подготовка агента обновления устройств".

Обработчик обновления

Обработчик обновлений интегрируется с агентом обновления устройства для выполнения фактической установки обновления. Для разностных обновлений начните с обработчика обновлений microsoft/swupdate:2 , если у вас еще нет собственного обработчика обновления SWUpdate, который вы хотите изменить. Если вы используете собственный обработчик обновления, обязательно включите zstd decompression в SWUpdate.

Разностный процессор

Разностный обработчик повторно создает исходный файл образа SWU на устройстве после скачивания разностного файла, чтобы обработчик обновлений смог установить SWU-файл. Код разностного процессора доступен в репозитории GitHub Azure/iot-hub-device-update-delta GitHub.

Чтобы добавить компонент разностного процессора в образ устройства и настроить его для использования, следуйте README.md инструкциям по использованию CMAKE для создания разностного процессора из источника. После этого установите общий объект (libadudiffapi.so), скопировав его /usr/lib в каталог:

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

Добавление исходного файла образа SWU на устройство

После скачивания разностного обновления на устройство его необходимо сравнить с допустимым исходным SWU-файлом , который ранее кэшировался на устройстве. Этот процесс необходим для повторного создания полного целевого образа. Самый простой способ заполнения кэшированного образа — развертывание полного обновления образа на устройстве с помощью службы обновления устройств (с помощью существующих процессов импорта и развертывания ). Если устройство настроено с помощью агента обновления устройств (версии 1.0 или более поздней версии) и разностного процессора, агент обновления устройств кэширует установленный ФАЙЛ SWU автоматически для последующего использования разностного обновления.

Если вы хотите напрямую предварительно заполнить исходный образ на устройстве, путь, в котором ожидается изображение:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

По умолчанию BASE_SOURCE_DOWNLOAD_CACHE_PATH — это путь /var/lib/adu/sdc/[provider]. Значением [provider] является часть поставщика идентификатора updateId для исходного SWU-файла.

ENCODED_HASH — это строка шестнадцатеричной строки SHA256 двоичного файла, но после кодирования в шестнадцатеричную строку base64 кодирует символы следующим образом:

  • + закодированное как octets _2B
  • / закодированное как octets _2F
  • = закодированное как octets _3D

Создание разностных обновлений с помощью средства DiffGen

Предварительные требования среды

Прежде чем создавать разностные значения с помощью DiffGen, необходимо скачать и /или установить на компьютере среды. Мы рекомендуем среду Linux и, в частности, Ubuntu 20.04 (или подсистема Windows для Linux, если изначально в Windows).

В следующей таблице приведен список необходимого содержимого, где их получить, и рекомендуемую установку при необходимости:

Двоичное имя Где получить Как установить
DiffGen Репозиторий GitHub azure/iot-hub-device-update-delta GitHub В корневой папке выберите Microsoft.Azure.DeviceUpdate.Diffs.[ version].nupkg-файл . Дополнительные сведения о пакетах NuGet.
. Среда выполнения NETCore, версия 6.0.0 Через терминал / диспетчер пакетов Инструкции для Linux. Требуется только среда выполнения.

Зависимости

Zstd_compression_tool используется для распаковки файлов изображений архива и их повторного сжатия с помощью zstd. Этот процесс гарантирует, что все архивные файлы, используемые для создания диффа, имеют один и тот же алгоритм сжатия для образов в архивах.

Команды для установки необходимых пакетов и библиотек:

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

Создание разностного обновления с помощью DiffGen

Средство DiffGen выполняется с несколькими аргументами. Все аргументы обязательны, и общий синтаксис выглядит следующим образом:

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

  • Скрипт recompress_tool.py запускается для создания файла [recompressed_target_archive], который затем используется вместо [target_archive] в качестве целевого файла для создания диффа.
  • Файлы изображений в [recompressed_target_archive] сжимаются с помощью zstd.

Если файлы SWU подписаны (скорее всего), вам потребуется еще один аргумент:

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

  • Помимо использования [recompressed_target_archive] в качестве целевого файла, при условии, что параметр строки командной строки подписи выполняется recompress_and_sign_tool.py для создания файла [recompressed_target_archive] и файла sw-description в архиве с подписью (то есть файл sw-description.sig). Пример sign_file.sh скрипта можно использовать из репозитория GitHub Azure/iot-hub-device-update-delta GitHub. Откройте скрипт, измените его, чтобы добавить путь к файлу закрытого ключа, а затем сохраните его. Ознакомьтесь с разделом примеров использования.

В следующей таблице подробно описаны аргументы:

Аргумент Description
[source_archive] Это изображение, на которое основано разностное значение при создании разностной области. Важно: этот образ должен совпадать с изображением, которое уже присутствует на устройстве (например, кэшированное из предыдущего обновления).
[target_archive] Это изображение, на которое разностное обновление устройства.
[output_path] Путь (включая требуемое имя создаваемого разностного файла) на хост-компьютере, где размещается разностный файл после создания. Если путь не существует, средство создает его.
[log_folder] Путь на хост-компьютере, где создаются журналы. Мы рекомендуем определить это расположение как вложенную папку выходного пути. Если путь не существует, средство создает его.
[working_folder] Путь к компьютеру, в котором хранятся материалы и другие рабочие файлы во время разностного создания. Мы рекомендуем определить это расположение как вложенную папку выходного пути. Если путь не существует, средство создает его.
[recompressed_target_archive] Путь на хост-компьютере, в котором создается повторножатый целевой файл. Этот файл используется вместо <target_archive> в качестве целевого файла для создания диффа. Если этот путь существует перед вызовом DiffGenTool, путь перезаписан. Мы рекомендуем определить этот путь как файл в подпапке выходного пути.
"[signing_command]" (необязательно) Настраиваемая команда, используемая для подписывания файла sw-description в повторножатом архивном файле. Файл sw-description в повторном архиве используется в качестве входного параметра для команды подписывания; DiffGenTool ожидает, что команда подписи создаст новый файл подписи, используя имя входных данных с .sig добавленным. Вокруг параметра в двойных кавычках требуется, чтобы вся команда передавалась в виде одного параметра. Кроме того, не помещайте символ "~" в путь ключа, используемый для подписывания, и используйте полный путь дома (например, используйте /home/USER/keys/priv.pem вместо ~/keys/priv.pem).

Примеры DiffGen

В этих примерах мы работаем из каталога /mnt/o/temp (в WSL):

Создание диффа между входным исходным файлом и повторно сжатым целевым файлом:

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]

Если вы также используете параметр подписывания (необходимо, если файл 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 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

Импорт созданного разностного обновления

Базовый процесс импорта обновления в службу обновления устройств не изменяется для разностных обновлений, поэтому если вы еще не сделали этого, обязательно просмотрите эту страницу: как подготовить обновление для импорта в обновление устройств Azure для Центр Интернета вещей

Создание манифеста импорта

Первым шагом для импорта обновления в службу обновления устройств всегда является создание манифеста импорта, если у вас еще нет. Дополнительные сведения о манифестах импорта см. в разделе "Импорт обновлений в обновление устройства". Для разностных обновлений манифест импорта должен ссылаться на два файла:

  • Повторно сформированный целевой образ SWU, созданный при запуске средства DiffGen.
  • Разностный файл, созданный при запуске средства DiffGen.

Функция разностного обновления использует функцию, называемую связанными файлами, для которой требуется манифест импорта версии 5 или более поздней.

Чтобы создать манифест импорта для разностного обновления с помощью функции связанных файлов, необходимо добавить связанные файлы и объекты downloadHandler в манифест импорта.

relatedFiles Используйте объект, чтобы указать сведения о разностном файле обновления, включая имя файла, размер файла и хэш sha256. Важно также указать два свойства, уникальные для функции разностного обновления:

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

Оба этих свойства относятся к исходному файлу образа SWU, который вы использовали в качестве входных данных для средства DiffGen при создании разностного обновления. Сведения об исходном образе SWU необходимы в манифесте импорта, даже если вы фактически не импортируете исходный образ. Разностные компоненты на устройстве используют эти метаданные о исходном изображении, чтобы найти изображение на устройстве после скачивания разностного изображения.

downloadHandler Используйте объект, чтобы указать, как агент обновления устройств оркеструет разностное обновление с помощью функции связанных файлов. Если вы не настраиваете собственную версию агента обновления устройств для разностной функциональности, следует использовать только этот downloadHandler:

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

Интерфейс командной строки Azure (CLI) можно использовать для создания манифеста импорта для разностного обновления. Если вы еще не использовали 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

Импорт с помощью портала Azure

После создания манифеста импорта вы будете готовы импортировать разностное обновление. Чтобы импортировать, следуйте инструкциям в разделе "Добавление обновления в обновление устройства" для Центр Интернета вещей. При импорте необходимо включить следующие элементы:

  • Манифест импорта .json файл, созданный на предыдущем шаге.
  • Повторно сформированный целевой образ SWU, созданный при запуске средства DiffGen.
  • Разностный файл, созданный при запуске средства DiffGen.

Развертывание разностного обновления на устройствах

При развертывании разностного обновления интерфейс в портал Azure выглядит идентично развертыванию регулярного обновления образа. Дополнительные сведения о развертывании обновлений см. в статье "Развертывание обновления с помощью обновления устройств для Центр Интернета вещей Azure".

После создания развертывания для разностного обновления служба обновления устройств и клиент автоматически определяют наличие допустимого разностного обновления для каждого развернутого устройства. Если найдено допустимое разностное значение, то разностное обновление загружается и устанавливается на этом устройстве. Если нет допустимого разностного обновления, то полное обновление образа (повторножатый целевой образ SWU) загружается вместо этого в качестве резервного восстановления. Этот подход гарантирует, что все устройства, которые вы развертываете обновление, чтобы получить соответствующую версию.

Существует три возможных результата развертывания разностного обновления:

  • Разностное обновление успешно установлено. Устройство находится в новой версии.
  • Разностное обновление было недоступно или не удалось установить, но вместо этого произошла успешная резервная установка полного образа. Устройство находится в новой версии.
  • Сбой разностного и резервного размещения до полного изображения. Устройство по-прежнему находится в старой версии.

Чтобы определить, какие из указанных выше результатов произошли, можно просмотреть результаты установки с кодом ошибки и расширенным кодом ошибки, выбрав любое устройство, которое находится в состоянии сбоя. При необходимости можно также собирать журналы с нескольких неудачных устройств.

Если разностное обновление выполнено успешно, устройство отображает состояние "Успешно".

Если разностное обновление завершилось сбоем, но успешно откатился к полному изображению, он отображает следующее состояние ошибки:

  • resultCode: [значение больше 0]
  • extendedResultCode: [ненулевая]

Если обновление не выполнено, отображается состояние ошибки, которое можно интерпретировать с помощью следующих инструкций:

  • Начните с ошибок агента обновления устройства в result.h.

    • Ошибки агента обновления устройств, относящиеся к функциям обработчика загрузки, используемым для разностных обновлений, начинаются с 0x9:

      Компонент Десятичное число Hex Примечание.
      EXTENSION_MANAGER 0 0x00 Указывает ошибки из логики обработчика загрузки диспетчера расширений. Пример: 0x900XXXXXX
      ПЛАГИН 1 0x01 Указывает ошибки при использовании общих библиотек подключаемых модулей обработчика загрузки. Пример: 0x901XXXXXX
      RESERVED 2–7 0x02 — 0x07 Зарезервировано для обработчика загрузки. Пример: 0x902XXXXXX
      СТАНДАРТНЫЕ 8 0x08 Указывает ошибки в логике верхнего уровня расширения обработчика загрузки Delta. Пример: 0x908XXXXX
      SOURCE_UPDATE_CACHE 9 0x09 Указывает ошибки в кэше исходного обновления модуля загрузки Delta Download. Пример: 0x909XXXXX
      DELTA_PROCESSOR 10 0x0A Код ошибки из API разностного процессора. Пример: 0x90AXXXXXX

    • Если код ошибки отсутствует в result.h, скорее всего, ошибка в компоненте разностного процессора (отдельно от агента обновления устройства). Если да, расширенныйResultCode является отрицательным десятичным значением следующего шестнадцатеричного формата: 0x90AXXXXXXX

      • 9 — Delta Facility
      • 0A — "Компонент разностного процессора" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
      • XXXXX — это 20-разрядный код ошибки из разностного процессора FIT

  • Если вы не можете решить проблему на основе сведений об коде ошибки, отправьте проблему GitHub, чтобы получить дополнительную помощь.

Следующие шаги

Устранение общих проблем