Compartir vía

Actualizaciones diferenciales (versión preliminar)

  • Artículo

Las actualizaciones diferenciales permiten generar pequeñas actualizaciones que representan 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 de Azure Device Update for IoT Hub se encuentra actualmente 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 estar en formato SWUpdate (SWU).
  • Dentro de cada archivo SWUpdate, debe haber una imagen sin procesar que use el sistema de archivos Ext2, Ext3 o Ext4.

El proceso de generación diferencial vuelve a comprimir la actualización de SWU de destino mediante la compresión gzip 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.

Configuración del agente de Device Update para el componente de procesador diferencial

Para descargar e instalar actualizaciones diferenciales desde el servicio Device Update, el dispositivo necesita el agente de Device Update con el controlador de actualizaciones y el componente de procesador diferencial 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. Para agregar el agente de Device Update a un dispositivo y configurarlo para su uso, consulte Aprovisionamiento del agente de Device Update. Use la versión 1.0, o una posterior, del agente.

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.

Procesador diferencial

El procesador diferencial en Azure/iot-hub-device-update-delta volver a crear el archivo de imagen SWU original en el dispositivo después de que se descargue el archivo diferencial, por lo que el controlador de actualizaciones puede instalar el archivo SWU. Para agregar el componente de procesador diferencial a la imagen del dispositivo y configurarlo para su uso, puede descargar un paquete Debian para Ubuntu 20.04 y versiones posteriores desde https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Si usa otra distribución, siga las instrucciones de README.md para usar CMAKE para compilar el procesador diferencial desde el origen en su lugar. Desde allí, instale el objeto compartido libadudiffapi.so directamente copiándolo en el directorio /usr/lib, como se indica a continuación:

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 que el archivo de actualización diferencial se descargue en un dispositivo, se compara con un <source_archive> válido almacenado en caché previamente en el dispositivo. Este proceso permite 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 importar e implementar una actualización de imagen completa en el dispositivo a través del servicio Device Update. Si el dispositivo está configurado con la versión 1.0 o posterior del agente de Device Update y el procesador diferencial, el agente almacena en caché el archivo SWU instalado automáticamente para su uso posterior de la actualización diferencial.

Si desea rellenar directamente la imagen de origen en el dispositivo en su lugar, la ruta de acceso donde 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 /var/lib/adu/sdc/<provider>. El valor provider es la parte de provider de updateId para el 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

Puede crear actualizaciones diferenciales mediante la herramienta Diff Generation (DiffGen).

Requisitos previos del entorno

Antes de crear actualizaciones diferenciales con DiffGen, debe descargar e instalar varias cosas en la máquina del entorno. Lo ideal es usar un entorno de Ubuntu 20.04 Linux o subsistema de Windows para Linux si está en Windows.

En la tabla siguiente se muestra el contenido necesario, dónde obtenerlo y la instalación recomendada si es necesario.

Nombre del binario Dónde conseguirlo Cómo instalar
DiffGen Repositorio de GitHub Azure/iot-hub-device-update-delta Descargue la versión que coincida con el sistema operativo o la distribución en la máquina que se usará para generar actualizaciones diferenciales.
Runtime de .NETCore, versión 8.0.0 A través de terminales o administradores de paquetes Instalación de .NET en Linux. Solo se requiere el runtime.

Creación de actualizaciones diferenciales mediante DiffGen

La herramienta DiffGen se ejecuta con los siguientes argumentos y sintaxis necesarios:

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

El comando anterior ejecuta el script de recompress_tool.py, que crea <recompressed_target_file>. Después, DiffGen usa <recompressed_target_file> en lugar de <target_archive> como archivo de destino para crear la diferencial. Los archivos de imagen en <recompressed_target_archive> se comprimen con gzip.

Si los archivos SWU están firmados, también requieren el argumento <signing_command> en el comando DiffGen:

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

El parámetro DiffGenTool con la cadena de comandos de firma ejecuta el script recompress_and_sign_tool.py. Este script crea <recompressed_target_file>. Además, este script también firma el archivo sw-description dentro del archivo para crear un archivo sw-description.sig.

Puede usar el script de sign_file.sh de ejemplo del repositorio de GitHub azure/iot-hub-device-update-delta para crear la diferencia entre el archivo de origen de entrada y un archivo de destino recomprimido y firmado. Abra el script, edítelo para agregar la ruta de acceso al archivo de clave privada y guárdelo. Consulte la sección Ejemplos para ver un uso de ejemplo.

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

Argumento Descripción
<source_archive> Imagen base que DiffGen usa como punto de partida para crear la 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> Imagen a la que la diferencial actualiza el dispositivo.
<output_path> Ruta de acceso en el equipo host en la que se va a colocar el archivo diferencial después de la creación, incluido el nombre deseado del archivo diferencial generado. Si la ruta de acceso no existe, la herramienta la crea.
<log_folder> Ruta de acceso de la máquina host en la que se van a crear registros. Es mejor 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> La ruta de acceso de la máquina para colocar los materiales adjuntos y otros archivos de trabajo en durante la generación diferencial. Es mejor 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 de la máquina host en la que se va a crear <recompressed_target_file>. <recompressed_target_file> se usa 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 la herramienta DiffGen, se sobrescribe. Es mejor definir este archivo en una subcarpeta de la ruta de acceso de salida.
"<signing_command>" (opcional) Un comando personalizable para firmar el archivo sw-description en <recompressed_target_archive>. El archivo sw-description en el archivo recomprimido se usa como parámetro de entrada para el comando de firma. DiffGen espera que el comando de firma cree un nuevo archivo de firma con el nombre de la entrada con .sig anexado.

Debe rodear el parámetro con comillas dobles para pasar todo el comando como un único parámetro. Evite también usar el carácter ~ en una ruta de acceso de clave que se usa para firmar y, en su lugar, use la ruta de acceso principal completa. Por ejemplo, use /home/USER/keys/priv.pem en lugar de ~/keys/priv.pem.

Ejemplos de DiffGen

Los ejemplos siguientes funcionan desde el directorio /mnt/o/temp en Subsistema de Windows para Linux.

El código siguiente crea una diferencia entre el archivo de origen de entrada y un archivo de destino recomprimido:

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

Si también usa el parámetro de firma (algo que debe hacer si el archivo SWU está firmado) puede usar el script de ejemplo sign_file.sh mencionado anteriormente. Abra el script, 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.

El código siguiente crea una diferencia entre el archivo de origen de entrada y un archivo de destino recomprimido y firmado:

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

Importación de actualización diferencial generada

El proceso básico de importación de una actualización diferencial en el servicio Device Update es el mismo que para cualquier otra actualización. Si aún no lo ha hecho, asegúrese de revisar Preparación de una actualización que se va a importar en Azure Device Update for IoT Hub.

Generación del manifiesto de importación

Para importar una actualización en el servicio Device Update, debe tener o crear un archivo de manifiesto de importación. Para obtener más información, consulte Importación de actualizaciones en Device Update.

Importar archivos de manifiesto para actualizaciones diferenciales debe hacer referencia a los siguientes archivos creados por la herramienta DiffGen:

  • Imagen de SWU de <recompressed_target_file>
  • El <delta file>

La característica de actualización diferencial usa una funcionalidad denominada archivos relacionados que requiere un manifiesto de importación de versión 5 o posterior. Para usar la característica de archivos relacionados, debe incluir los objetos relatedFiles y downloadHandler en el 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. Lo más importante es que también debe especificar las dos propiedades siguientes que son exclusivas de la característica de actualización diferencial:

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

Ambas propiedades son específicas de <source image file> que usó como entrada para la herramienta DiffGen al crear la actualización diferencial. El manifiesto de importación necesita la información sobre la imagen de SWU de origen aunque realmente no importe la imagen de origen. Los componentes diferenciales del dispositivo usan estos metadatos sobre la imagen de origen para buscar esa imagen en el dispositivo después de descargar la actualización 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 personalice su propia versión del agente de Device Update para la funcionalidad diferencial, use el siguiente downloadHandler:

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

Puede usar el comando az iot du update init v5 de la CLI de Azure para generar un manifiesto de importación para la actualización diferencial. Para obtener más información, consulte Creación de un manifiesto de importación básico.

--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 json del manifiesto de importación generado con la extensión de archivo .importmanifest.json.

Importación mediante Azure Portal

Una vez creado el manifiesto de importación, importe la actualización diferencial siguiendo las instrucciones de Agregar una actualización a Azure Device Update for IoT Hub. Debe incluir los siguientes elementos en la importación:

  • Archivo *importmanifest.json que creó en los pasos anteriores
  • Imagen de SWU <recompressed_target_file> creada por la herramienta DiffGen
  • La herramienta DiffGen <delta file> creada

Implementación de actualizaciones diferenciales en dispositivos

La experiencia de implementación de actualizaciones diferenciales en Azure Portal es la misma que la implementación de una actualización de imagen normal. Para obtener más información, consulte Implementación de una actualización mediante Device Update.

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 encuentran una actualización diferencial válida, descargan e instalan la actualización diferencial en ese dispositivo.

Si no encuentran una actualización diferencial válida, la actualización de imagen completa (la imagen de SWU de destino recomprimida) se descarga 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:

  • La actualización diferencial se instaló correctamente y el dispositivo está en la nueva versión.
  • La actualización diferencial no estaba disponible o no se pudo instalar, pero una instalación de reserva de la imagen completa se realizó correctamente y el dispositivo tiene la nueva versión.
  • Se produjo un error en las instalaciones diferenciales y de reserva y el dispositivo todavía está en la versión anterior.

Para determinar qué resultado de error se ha producido, puede ver los resultados de la instalación con código de error y el código de error extendido si selecciona cualquier dispositivo que esté en estado de error. También puede recopilar registros de varios dispositivos con errores si es necesario.

  • Si una actualización diferencial se realizó correctamente, el dispositivo mostrará un estado de Correcto.

  • Si se produjo un error en una actualización diferencial, pero la reserva de la imagen completa se realizó correctamente, el dispositivo mostrará el siguiente estado de error:

    • resultCode: <valor mayor que 0>
    • extendedResultCode: <valor distinto de cero>

Solución de problemas de actualizaciones con errores

Las actualizaciones incorrectas muestran un estado de error que puede interpretar mediante las instrucciones siguientes. 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 descarga de 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
COMÚN 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í, extendedResultCode es un valor decimal negativo en el 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 de la Herramienta de instalación de campos (FIT)

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

Contenido relacionado