Descripción y uso de actualizaciones diferenciales en Device Update for IoT Hub (versión preliminar)

Artículo
03/10/2024

Las actualizaciones diferenciales permiten generar una pequeña actualización que representa solo los cambios entre dos actualizaciones completas: una imagen de origen y una imagen de destino. Este enfoque es ideal para reducir el ancho de banda usado para descargar una actualización en un dispositivo, especialmente si solo se han producido algunos cambios entre las actualizaciones de origen y destino.

Nota:

La característica de actualización diferencial actualmente está en versión preliminar pública.

Requisitos para usar actualizaciones diferenciales en Device Update for IoT Hub

Los archivos de actualización de origen y destino deben tener el formato SWUpdate (SWU).
Dentro de cada archivo SWUpdate, debe haber una imagen sin procesar que use el sistema de archivos Ext2, Ext3 o Ext4. Esa imagen se puede comprimir con gzip o zstd.
El proceso de generación diferencial vuelve a comprimir la actualización SWU de destino mediante la compresión zstd para generar un diferencial óptimo. Importará esta actualización SWU de destino que se ha vuelto a comprimir en el servicio Device Update junto con el archivo de actualización diferencial generado.
En el archivo SWUpdate del dispositivo, también se debe habilitar la descompresión zstd.
- Este proceso requiere el uso de SWUpdate 2019.11 o posterior.

Configuración de un dispositivo con el agente de Device Update y el componente de procesador diferencial

Para que el dispositivo descargue e instale actualizaciones diferenciales desde el servicio Device Update, necesita varios componentes presentes y configurados.

Agente de Device Update

El agente de Device Update organiza el proceso de actualización en el dispositivo, incluidas las acciones de descarga, instalación y reinicio. Agregue el agente de Device Update a un dispositivo y configúrelo para su uso. Use la versión 1.0, o una posterior, del agente. Para obtener instrucciones, consulte Aprovisionamiento del agente de Device Update.

Controlador de actualización

Se integra un controlador de actualización con el agente de Device Update para realizar la instalación de la actualización real. Para las actualizaciones diferenciales, comience con el controlador de actualización microsoft/swupdate:2 si aún no tiene su propio controlador de actualización de SWUpdate que quiere modificar. Si usa su propio controlador de actualización, asegúrese de habilitar la descompresión zstd en SWUpdate.

Procesador diferencial

El procesador diferencial vuelve a crear el archivo de imagen SWU original en el dispositivo después de descargar el archivo diferencial, por lo que el controlador de actualización puede instalar el archivo SWU. El código del procesador diferencial está disponible en el repositorio de GitHub Azure/iot-hub-device-update-delta.

Para agregar el componente de procesador diferencial a la imagen del dispositivo y configurarlo para su uso, siga las instrucciones de README.md para usar CMAKE para compilar el procesador diferencial desde el origen. Desde allí, instale el objeto compartido (libadudiffapi.so) directamente copiándolo en el directorio /usr/lib:

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

Adición de un archivo de imagen SWU de origen al dispositivo

Después de descargar una actualización diferencial en un dispositivo, debe compararse con un archivo SWU de origen válido que se haya almacenado previamente en caché en el dispositivo. Este proceso es necesario para que la actualización diferencial vuelva a crear la imagen de destino completa. La manera más sencilla de rellenar esta imagen almacenada en caché es implementar una actualización de imagen completa en el dispositivo mediante el servicio Device Update (mediante los procesos de importación e implementación existentes). Siempre que el dispositivo esté configurado con el agente de Device Update (versión 1.0 o posterior) y el procesador diferencial, el agente de Device Update almacena en caché el archivo SWU instalado automáticamente para su uso posterior de la actualización diferencial.

Si en su lugar desea rellenar previamente la imagen de origen en el dispositivo, la ruta de acceso en la que se espera la imagen es:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

De forma predeterminada, BASE_SOURCE_DOWNLOAD_CACHE_PATH es la ruta de acceso de /var/lib/adu/sdc/[provider]. El valor de [provider] es la parte del proveedor del elemento updateId del archivo SWU de origen.

ENCODED_HASH es la cadena hexadecimal en base 64 del SHA256 del archivo binario, pero después de codificarse en cadena hexadecimal en base 64, codifica los caracteres de la siguiente manera:

+ codificado como octets _2B
/ codificado como octets _2F
= codificado como octets _3D

Generación de actualizaciones diferenciales mediante la herramienta DiffGen

Requisitos previos del entorno

Antes de crear diferenciales con DiffGen, es necesario descargar e instalar varios elementos en la máquina del entorno. Se recomienda un entorno de Linux y específicamente Ubuntu 20.04 (o el subsistema de Windows para Linux si se usa de forma nativa en Windows).

En la tabla siguiente, se proporciona una lista del contenido necesario, dónde recuperarlo y la instalación recomendada si es necesario:

Nombre del archivo binario	Dónde conseguirlo	Cómo instalar
DiffGen	Repositorio de GitHub Azure/iot-hub-device-update-delta	En la carpeta raíz, seleccione Microsoft.Azure.DeviceUpdate.Diffs.[version].nupkg. Obtenga más información sobre los paquetes NuGet.
Versión 6.00 del entorno de ejecución de .NET Core	Mediante el terminal o administradores de paquetes	Instrucciones para Linux. Solo se requiere el entorno de ejecución.

Dependencias

Se usa zstd_compression_tool para descomprimir los archivos de imagen de un archivo y volver a comprimirlos con zstd. Este proceso garantiza que todos los archivos de archivado usados para la generación de diferencias tengan el mismo algoritmo de compresión para las imágenes dentro de los archivos.

Comandos para instalar los paquetes y bibliotecas necesarios:

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

Creación de una actualización diferencial mediante DiffGen

La herramienta DiffGen se ejecuta con varios argumentos. Todos los argumentos son necesarios y la sintaxis general es la siguiente:

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

El script recompress_tool.py se ejecuta para crear el archivo [recompressed_target_archive], que se usa en lugar de [target_archive] como archivo de destino para crear la diferencia.
Los archivos de imagen de [recompressed_target_archive] se comprimen con zstd.

Si los archivos SWU están firmados (es probable), necesitará otro argumento también:

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

Además de usar [recompressed_target_archive] como archivo de destino, al proporcionar un parámetro de cadena de comando de firma se ejecuta recompress_and_sign_tool.py para crear el archivo [recompressed_target_archive] y tener el archivo sw-description dentro del archivo firmado (es decir, está presente un archivo sw-description.sig). Puede usar el script sign_file.sh de ejemplo del repositorio de GitHub Azure/iot-hub-device-update-delta. Abra el script, edítelo para agregar la ruta de acceso al archivo de clave privada y guárdelo. Consulte la sección de ejemplos para ver un uso de ejemplo.

En la tabla siguiente, se describen los argumentos con más detalle:

Argumento	Descripción
[source_archive]	Esta es la imagen en la que se basa el diferencial al crear el diferencial. Importante: esta imagen debe ser idéntica a la imagen que ya está presente en el dispositivo (por ejemplo, almacenada en caché de una actualización anterior).
[target_archive]	Esta es la imagen a la que el diferencial actualiza el dispositivo.
[output_path]	Ruta de acceso (incluido el nombre deseado del archivo diferencial que se va a generar) en la máquina host donde se coloca el archivo diferencial después de la creación. Si la ruta de acceso no existe, la herramienta la crea.
[log_folder]	Ruta de acceso en la máquina host donde se crean los registros. Se recomienda definir esta ubicación como una subcarpeta de la ruta de acceso de salida. Si la ruta de acceso no existe, la herramienta la crea.
[working_folder]	Ruta de acceso en la máquina donde se colocan los archivos auxiliares y otros archivos de trabajo durante la generación diferencial. Se recomienda definir esta ubicación como una subcarpeta de la ruta de acceso de salida. Si la ruta de acceso no existe, la herramienta la crea.
[recompressed_target_archive]	Ruta de acceso en la máquina host donde se crea el archivo de destino recomprimido. Se usa este archivo en lugar de <target_archive> como archivo de destino para la generación de diferencias. Si esta ruta de acceso existe antes de llamar a DiffGenTool, se sobrescribe la ruta de acceso. Se recomienda definir esta ruta de acceso como un archivo en la subcarpeta de la ruta de acceso de salida.
"[signing_command]" (opcional)	Comando personalizable que se usa para firmar el archivo sw-description dentro del archivo de archivado recomprimido. El archivo sw-description del archivo recomprimido se usa como parámetro de entrada para el comando de firma; DiffGenTool espera que el comando de firma cree un nuevo archivo de firma con el nombre de la entrada con `.sig` anexado. Es necesario rodear el parámetro entre comillas dobles para que todo el comando se pase como un único parámetro. Además, evite colocar el carácter "~" en una ruta de acceso de clave usada para firmar y use la ruta de acceso principal completa en su lugar (por ejemplo, use /home/USER/keys/priv.pem en lugar de ~/keys/priv.pem).

Ejemplos de DiffGen

En estos ejemplos, estamos trabajando fuera del directorio /mnt/o/temp (en WSL):

Creación de diferencias entre el archivo de origen de entrada y el archivo de destino recomprimido:

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]

Si también usa el parámetro de firma (necesario si el archivo SWU está firmado), puede usar el script sign_file.sh de ejemplo al que se hizo referencia anteriormente. En primer lugar, abra el script y edítelo para agregar la ruta de acceso al archivo de clave privada. Guarde el script y, a continuación, ejecute DiffGen como se indica a continuación:

Creación de diferencias entre el archivo de origen de entrada y el archivo de destino recomprimido y vuelto a firmar:

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

Importación de la actualización diferencial generada

El proceso básico de importación de una actualización en el servicio Device Update no cambia para las actualizaciones diferenciales, por lo que, si aún no lo ha hecho, asegúrese de revisar esta página: Preparación de una actualización para importarla a Device Update for IoT Hub

Generación del manifiesto de importación

El primer paso para importar una actualización en el servicio Device Update siempre es crear un manifiesto de importación si aún no tiene uno. Para obtener más información sobre los manifiestos de importación, consulte Importación de actualizaciones a Device Update for IoT Hub. En el caso de las actualizaciones diferenciales, el manifiesto de importación debe hacer referencia a dos archivos:

La imagen SWU de destino recomprimida creada al ejecutar la herramienta DiffGen.
El archivo diferencial creado al ejecutar la herramienta DiffGen.

La característica de actualización diferencial usa una nueva funcionalidad llamada archivos relacionados, que requiere un manifiesto de importación con la versión 5 o posterior.

Para crear un manifiesto de importación para la actualización diferencial mediante la característica de archivos relacionados, deberá agregar objetos relatedFiles y downloadHandler al manifiesto de importación.

Use el objeto relatedFiles para especificar información sobre el archivo de actualización diferencial, incluido el nombre de archivo, el tamaño de archivo y el hash sha256. También es importante mencionar que debe especificar dos propiedades que son únicas para la característica de actualización diferencial:

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

Ambas propiedades son específicas del archivo de imagen SWU de origen que usó como entrada para la herramienta DiffGen al crear la actualización diferencial. La información sobre la imagen SWU de origen es necesaria en el manifiesto de importación, aunque realmente no importa la imagen de origen. Los componentes diferenciales del dispositivo usan estos metadatos sobre la imagen de origen para buscar la imagen en el dispositivo una vez descargado el diferencial.

Use el objeto downloadHandler para especificar cómo organiza el agente de Device Update la actualización diferencial mediante la característica de archivos relacionados. A menos que vaya a personalizar su propia versión del agente de Device Update para la funcionalidad diferencial, solo debe usar este elemento downloadHandler:

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

Puede usar la interfaz de la línea de comandos (CLI) de Azure para generar un manifiesto de importación para la actualización diferencial. Si no ha usado la CLI de Azure para crear un manifiesto de importación antes, consulte Creación de un manifiesto de importación básico.

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

Guarde el archivo JSON del manifiesto de importación generado en un archivo con la extensión .importmanifest.json.

Importación mediante Azure Portal

Una vez que haya creado el manifiesto de importación, estará listo para importar la actualización diferencial. Para la importación, siga las instrucciones que se indican en Importación de una actualización a Device Update for IoT Hub. Debe incluir estos elementos al realizar la importación:

El archivo .json del manifiesto de importación que creó en el paso anterior.
La imagen SWU de destino recomprimida creada al ejecutar la herramienta DiffGen.
El archivo diferencial creado al ejecutar la herramienta DiffGen.

Implementación de la actualización diferencial en los dispositivos

Al implementar una actualización diferencial, la experiencia de Azure Portal es idéntica a la implementación de una actualización de imagen normal. Para obtener más información sobre la implementación de actualizaciones, consulte Implementación de una actualización mediante Device Update for Azure IoT Hub.

Una vez creada la implementación de la actualización diferencial, el servicio Device Update y el cliente identifican automáticamente si hay una actualización diferencial válida para cada dispositivo en el que se va a implementar. Si se encuentra un diferencial válido, la actualización diferencial se descargará e instalará en ese dispositivo. Si no se encuentra ninguna actualización diferencial válida, la actualización de imagen completa (la imagen SWU de destino recomprimida) se descargará en su lugar como reserva. Este enfoque garantiza que todos los dispositivos en los que va a implementar la actualización obtengan la versión adecuada.

Hay tres posibles resultados para una implementación de actualizaciones diferenciales:

Actualización diferencial instalada correctamente. El dispositivo está en una nueva versión.
La actualización diferencial no estaba disponible o no se pudo instalar, pero se produjo una instalación de reserva correcta de la imagen completa. El dispositivo está en una nueva versión.
Error tanto de la actualización diferencial como la de reserva en la imagen completa. El dispositivo todavía está en la versión anterior.

Para determinar cuál de los resultados anteriores se produjo, puede ver los resultados de instalación con el código de error y el código de error extendido seleccionando cualquier dispositivo que esté en estado de error. También puede recopilar registros de varios dispositivos con errores si es necesario.

Si la actualización diferencial se realizó correctamente, el dispositivo muestra un estado "Correcto".

Si se produjo un error en la actualización delta pero se realizó correctamente una de reserva en la imagen completa, se muestra el siguiente estado de error:

resultCode: [valor mayor que 0]
extendedResultCode: [distinto de cero]

Si la actualización no se realizó correctamente, se muestra un estado de error que se puede interpretar mediante estas instrucciones:

Comience con los errores del agente de Device Update del archivo result.h.

Los errores del agente de Device Update que son específicos de la funcionalidad del controlador de descargas que se usa para las actualizaciones diferenciales comienzan por 0x9:

Componente	Decimal	Hex	Nota
EXTENSION_MANAGER	0	0x00	Indica errores de la lógica del controlador de descargas del administrador de extensiones. Ejemplo: 0x900XXXXX
PLUGIN	1	0x01	Indica errores con el uso de las bibliotecas compartidas del complemento del controlador de descargas. Ejemplo: 0x901XXXXX
RESERVED	2 - 7	0x02 a 0x07	Reservado para el controlador de descargas. Ejemplo: 0x902XXXXX
COMMON	8	0x08	Indica errores en la lógica de nivel superior de la extensión del controlador de descargas diferenciales. Ejemplo: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Indica errores en la memoria caché de actualización de origen de la extensión del controlador de descargas diferenciales. Ejemplo: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Código de error para los errores de la API del procesador diferencial. Ejemplo: 0x90AXXXXX

Si el código de error no está presente en el archivo result.h, es probable que se produzca un error en el componente del procesador diferencial (independiente del agente de Device Update). Si es así, el elemento extendedResultCode es un valor decimal negativo del siguiente formato hexadecimal: 0x90AXXXXX
- 9 es "Utilidad diferencial"
- 0A es "Componente del procesador diferencial" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX es el código de error de 20 bits del procesador diferencial FIT.

Si no puede resolver el problema en función de la información del código de error, abra un problema en GitHub para obtener más ayuda.

Pasos siguientes

Solución de problemas comunes

Share via