IoT Platform:Descripción general de las actualizaciones OTA

Límites

Los dispositivos que utilizan OTA deben conectarse a IoT Platform mediante MQTT. Los dispositivos pueden descargar paquetes de actualización a través de MQTT o HTTPS.

• Cada cuenta de Alibaba Cloud admite hasta 500 paquetes de actualización. Todos los usuarios RAM bajo la misma cuenta comparten esta cuota.

• Se aplican los siguientes límites a la cantidad, tamaño, formato y región de los paquetes de actualización.

  • Descarga por HTTPS: Una actualización puede incluir uno o varios archivos. Un solo archivo puede tener un tamaño máximo de 1,000 MB. Solo se admiten archivos con los siguientes formatos: .bin, .dav, .tar, .gz, .zip, .gzip, .apk, .tar.gz, .tar.xz y .pack.

  • Descarga por MQTT: Solo se admiten archivos individuales de hasta 16 MB, y únicamente en las regiones China (Shanghai), China (Beijing) y China (Shenzhen). Utilice el C Link SDK para desarrollar descargas de archivos por MQTT. Sample code.

Funcionamiento

Requisitos previos

• Conecte su dispositivo a IoT Platform. Usuarios de Link SDK: Obtain C Link SDK y Device connection guide. Usuarios de chips AliOS Things: Documentación de AliOS Things.

Procedimiento de actualización OTA

Paso 1: Reportar el número de versión

1. Configure la función OTA.

   1. Connect the device to IoT Platform. En la consola de IoT Platform, seleccione la instancia objetivo y luego vaya a Device Management > Devices. Compruebe que el estado del dispositivo sea Online.

   2. Initialize the OTA feature.

   3. Configure the OTA feature.

2. Report the current version number. El dispositivo debe reportar su versión antes de la primera actualización. Reporte la versión una vez al inicio, no de manera periódica. Solo se puede reportar la versión de un módulo por llamada. Tema y formato de mensaje: consulte Formatos de mensaje al final de este tema.

Paso 2: Enviar información del paquete de actualización

1. Add an update package: Agregue un módulo OTA y un paquete de actualización para el producto.

   • Módulo: Un módulo actualizable definido por el usuario para dispositivos del mismo producto, como firmware, software o un controlador. El módulo predeterminado representa el firmware completo del dispositivo.

   • Paquete completo: Un archivo de actualización completo. Puede agregar uno o varios paquetes. Adding multiple sample packages requiere el C Link SDK. El dispositivo no necesita reportar la versión del módulo OTA antes de una actualización completa, pero sin una versión reportada no podrá dirigirse a una versión específica en una actualización por lotes. Create a batch update job.

   • Paquete diferencial: Contiene solo las diferencias entre la versión actual y la versión objetivo. El dispositivo realiza una restauración diferencial local para reconstruir el paquete completo antes de actualizar. Las actualizaciones diferenciales reducen la cuota de actualizaciones OTA consumida y el tráfico de descarga. El dispositivo debe reportar la versión del módulo OTA antes de una actualización diferencial.

     • Para chips AliOS Things, Alibaba Cloud proporciona generación de paquetes diferenciales y un algoritmo de restauración diferencial. Guía de usuario de OTA Diff Tools.

     • Para otros dispositivos, usted debe generar el paquete diferencial y desarrollar el algoritmo de restauración diferencial por su cuenta.

2. Optional: Verify the update package: Si establece Verify update package en Yes al agregar un paquete, debe realizar pruebas en dispositivos seleccionados antes del despliegue por lotes. El paquete estará disponible solo después de que los dispositivos de prueba se actualicen correctamente.

   Puede requerir confirmación de la aplicación antes de que proceda una actualización OTA:

   1. Desarrolle la aplicación usted mismo. La plataforma no envía mensajes de actualización al dispositivo; la aplicación debe consultarlos.

   2. La aplicación llama a ListOTAUnfinishedTaskByDevice para consultar trabajos de actualización de dispositivos pendientes.

   3. La aplicación llama a ConfirmOTATask para confirmar el trabajo de actualización. La plataforma envía el mensaje de actualización al dispositivo solo después de la confirmación.

3. Create a batch update job: IoT Platform envía información de actualización (URL del paquete, versión, tamaño) a los dispositivos en lotes. El estado del dispositivo cambia a To Be Updated o To Be Confirmed, y luego a Updating cuando el dispositivo reporta progreso.

Paso 3: Descargar el paquete de actualización

1. Obtain update package information. Los dispositivos sin conexión no pueden recibir mensajes de actualización. Cuando un dispositivo se conecta, IoT Platform comprueba si hay actualizaciones pendientes y envía el mensaje si es necesario.

   • IoT Platform envía información del paquete de actualización. El dispositivo se suscribe a: /ota/device/upgrade/${YourProductKey}/${YourDeviceName}. El dispositivo recibe información de actualización en este tema en dos escenarios:

     • El dispositivo está en línea cuando se crea el trabajo: IoT Platform envía la información de actualización inmediatamente.

     • El dispositivo está fuera de línea cuando se crea el trabajo: IoT Platform envía la información de actualización una vez que el dispositivo se conecta.

   • El dispositivo obtiene activamente información del paquete de actualización. El dispositivo publica una solicitud en un tema, e IoT Platform devuelve la información del paquete de actualización en el tema de respuesta. Temas y formatos de mensaje: consulte Formatos de mensaje al final de este tema.

   • Formatos de mensaje de descarga por HTTPS y MQTT: consulte Formatos de mensaje al final de este tema.

2. El dispositivo descarga el paquete de actualización mediante el protocolo HTTPS o MQTT.

   • Download a single file over HTTPS.

   • Download multiple files over HTTPS.

   • Download a single file over MQTT.

3. Report the update progress. Tema y formato de mensaje: consulte Formatos de mensaje al final de este tema.

   Importante

   Si el dispositivo reporta progreso con una frecuencia mayor a cada 3 segundos, es posible que algunas entradas de progreso no aparezcan en la pestaña Batch Details de la consola.

4. Report the new version number. Reinicie el dispositivo inmediatamente después de la actualización. Reporte la nueva versión dentro de los 2 segundos posteriores a la conexión.

   Importante

   IoT Platform considera la actualización como exitosa solo cuando la versión reportada coincide con la versión objetivo. Incluso si el progreso reportado alcanza el 100%, la actualización falla si no se reporta el nuevo número de versión antes de que expire el período de Device update timeout.

   • Tema: /ota/device/inform/${YourProductKey}/${YourDeviceName}

   • Formato de mensaje

     {
       "id": 1,
       "params": {
         "version": "2.0.0"
       }
     }

Paso 4: Consultar el resultado de la actualización

1. View the update status: Consulte el estado de actualización del dispositivo objetivo, la información del paquete de actualización y más detalles.

2. View update package versions and success rates: Consulte estadísticas sobre la distribución de versiones y tasas de éxito después de la actualización. Analice las causas de los errores en actualizaciones OTA para mejorar la tasa de éxito.

Referencias

• Solución de problemas de actualizaciones fallidas: How do I troubleshoot a failed device OTA update?.

• Consulte IoT Platform logs para ver registros de comunicación entre IoT Platform, dispositivos y aplicaciones.

• Códigos de error del lado del dispositivo: Error codes for devices.

• Reenvíe información de actualización de dispositivos a su servidor: Configure a server-side subscription using AMQP. Formatos de datos de temas OTA después del reenvío: Data formats.

Formatos de mensaje

Reporte del número de versión

• Topic: /ota/device/inform/${YourProductKey}/${YourDeviceName}

• Formato del mensaje

  {
    "id": 1,
    "params": {
      "version": "1.0.0",
      "module":"mcu"      // If this parameter is not specified, the default version number is used.
    }
  }

  Parámetro	Tipo	Descripción
  id	String	El ID del mensaje. Puede ser una cadena o un entero largo. Rango de valores: de 0 a 4294967295. Debe ser único por dispositivo.
  version	String	La versión del módulo OTA.
  module	String	El nombre del módulo OTA. Déjelo vacío cuando reporte la versión del módulo predeterminado. El módulo predeterminado representa el firmware general del dispositivo.

Obtención activa de un paquete de actualización

1. El dispositivo publica un mensaje en el topic: /sys/{productKey}/{deviceName}/thing/ota/firmware/get.

   • Formato del mensaje

     {
         "id": "123",
         "version": "1.0",
         "params": {
             "module": "MCU"
         },
         "method": "thing.ota.firmware.get"
     }

   • Descripción de parámetros

     Parámetro	Tipo	Descripción
     id	String	El ID del mensaje. El valor debe ser una cadena que contenga un número de 0 a 4294967295 y debe ser único para el dispositivo actual.
     version	String	La versión del protocolo. El valor está fijo en 1.0.
     params	Object	Los parámetros de la solicitud.
     module	String	El nombre del módulo al que pertenece el paquete de actualización. Si no especifica este parámetro, se solicita la información del paquete de actualización del módulo predeterminado.
     method	String	El método de la solicitud. El valor es thing.ota.firmware.get.

2. Después de que IoT Platform recibe la solicitud, devuelve la información del paquete de actualización al dispositivo en el topic de respuesta: /sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply.

Descarga mediante HTTPS

Descarga de un paquete de archivo único

{
    "id": "123",
    "code": 200,
    "data": {
        "size": 93796291,
        "sign": "f8d85b250d4d787a9f483d89a974***",
        "version": "10.0.1.9.20171112.1432",
        "isDiff": 1,
        "url": "https://the_firmware_url",
        "signMethod": "MD5",
        "md5": "f8d85b250d4d787a9f48***",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Update the underlying camera driver to resolve the issue of blurry video images.\"}"
        }
    }
}

Descarga de un paquete de varios archivos

{
    "code": "1000",
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***XJEH0qAKU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d***",
                "fileSign":"93230c3bde425a9d****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://***/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***qAKU%3D&security-token=***q6Ft5B2y***",
                "fileMd5":"93230c3bde425a92***",
                "fileSign":"93230c3bde425a92****"
            }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Update the underlying camera driver to resolve the issue of blurry video images.\"}"
        }
    },
    "id": 1626969597470,
    "message": "success"
}

Descarga mediante protocolo MQTT

Cuando descarga un paquete de actualización mediante MQTT, solo se admiten paquetes de archivo único. Después de que el dispositivo obtiene la información del paquete de actualización OTA, puede elegir realizar una full download o una sharded download.

1. Full download

   • Formato del mensaje

     {
         "id": "123",
         "code": 200,
         "data":{
             "size":432945,
             "digestsign":"A4WOP***SYHJ6DDDJD9***",
             "version":"2.0.0",
             "isDiff":1,
             "signMethod":"MD5",
             "dProtocol":"mqtt",
             "streamId":1397345,
             "streamFileId":1,
             "md5":"93230c3bde***",
             "sign":"93230c3bde42***",
             "module":"MCU",
             "extData":{
                 "key1":"value1",
                 "key2":"value2"
             }
         }
     }

   • Descripción de parámetros

     Parámetro	Tipo	Descripción
     id	Long	El ID del mensaje. El ID debe ser único para el dispositivo actual.
     message	String	La información del resultado.
     code	String	El código de estado.
     version	String	La versión del paquete de actualización del dispositivo.
     size	Long	El tamaño del archivo del paquete de actualización en bytes. Este parámetro se incluye únicamente cuando el paquete de actualización OTA contiene un solo archivo.
     url	String	La dirección de almacenamiento del paquete de actualización en Object Storage Service (OSS). Este parámetro se incluye únicamente cuando el paquete de actualización OTA contiene un solo archivo y se descarga mediante HTTPS.
     dProtocol	String	El protocolo para descargar el paquete de actualización. Este parámetro se incluye únicamente cuando el paquete de actualización se descarga mediante MQTT.
     streamId	Long	El identificador único para descargar el paquete de actualización OTA mediante MQTT. Este parámetro se incluye únicamente cuando el paquete de actualización se descarga mediante MQTT.
     streamFileId	Integer	El identificador único de un solo archivo del paquete de actualización. Este parámetro se incluye únicamente cuando el paquete de actualización se descarga mediante MQTT.
     isDiff	Long	Este parámetro se incluye únicamente cuando el paquete de actualización es un paquete diferencial. Un valor de 1 indica que el paquete contiene solo las diferencias entre la nueva versión y la versión anterior, y el dispositivo debe realizar una restauración diferencial.
     digestsign	String	La firma del archivo del paquete de actualización OTA para actualizaciones seguras. Se incluye únicamente cuando la actualización segura está habilitada. Habilite esta función en Add an update package.
     sign	String	La firma del archivo del paquete de actualización OTA. Este parámetro se incluye únicamente cuando el paquete de actualización OTA contiene un solo archivo.
     signMethod	String	El método de firma. Valores válidos: SHA256 MD5 Para paquetes de actualización diferencial de Android, solo se admite el método de firma MD5.
     md5	String	Si el método de firma es MD5, se asigna un valor tanto al parámetro sign como al md5. Este parámetro se incluye únicamente cuando el paquete de actualización OTA contiene un solo archivo.
     module	String	El nombre del módulo al que pertenece el paquete de actualización. Si el nombre del módulo es default, IoT Platform no envía el parámetro module.
     extData	Object	La lista de etiquetas del lote de actualización y la información personalizada enviada al dispositivo. El campo _package_udi indica información personalizada. El formato de una sola etiqueta es: "key":"value".
     files	Array	La lista de información sobre varios archivos del paquete de actualización. Este parámetro se incluye cuando el paquete de actualización OTA contiene varios archivos. La información de cada archivo es la siguiente: fileSize: El tamaño del archivo del paquete de actualización. fileName: El nombre del archivo del paquete de actualización. fileUrl, fileMd5 y fileSign: Estos parámetros tienen el mismo significado que url, md5 y sign.

2. Optional: Sharded download. Después de obtener la información anterior del paquete de actualización, el dispositivo descarga el archivo del paquete de actualización OTA en fragmentos mediante los siguientes topics.

   • Topic de solicitud: /sys/${productKey}/${deviceName}/thing/file/download

   • Topic de respuesta: /sys/${productKey}/${deviceName}/thing/file/download_reply

   • Formato del mensaje de solicitud

     {
      "id": "123456",
      "version": "1.0",
      "params": {
      "fileToken":"1bb8***",
      "fileInfo":{
      "streamId":1234565,
      "fileId":1
      },
      "fileBlock":{
      "size":256,
      "offset":2
      }
      }
     }

   • Descripción de parámetros del mensaje de solicitud

     Parámetro	Tipo	Descripción
     id	String	El ID del mensaje. El valor debe ser una cadena que contenga un número de 0 a 4294967295 y debe ser único para el dispositivo actual.
     version	String	La versión del protocolo. El valor está fijo en 1.0.
     params	Object	Los parámetros de la solicitud.
     fileToken	String	El token único del archivo. Este parámetro no es obligatorio. Admite dígitos, letras, guiones bajos (_) y puntos (.). El valor puede tener hasta 16 caracteres de longitud. Notas de uso: Si especifica este parámetro, IoT Platform lo devuelve en la respuesta a la solicitud del dispositivo. Esto le ayuda a confirmar el archivo descargado correspondiente en el mensaje de respuesta en escenarios de descarga de varios archivos. Si el dispositivo no necesita iniciar solicitudes de descarga para otros archivos durante el ciclo de solicitud y respuesta del archivo actual, puede dejar este parámetro vacío.
     fileInfo	Object	La información del archivo del paquete de actualización OTA.
     streamId	Long	El identificador único para descargar el paquete de actualización OTA mediante MQTT.
     fileId	Integer	El identificador único de un solo archivo del paquete de actualización.
     fileBlock	Object	La información del fragmento de archivo.
     size	Integer	El tamaño del fragmento de archivo solicitado para descargar, en bytes. El valor debe estar en el rango de 256 a 131072. Para el último fragmento de archivo, el valor debe estar en el rango de 1 a 131072.
     offset	Integer	La dirección de inicio del byte que corresponde al fragmento de archivo. El valor debe estar en el rango de 0 a 16777216.

   • Estructura del mensaje de respuesta

     

     Elemento de estructura	Descripción
     JSON Bytes Length	La longitud de la matriz de bytes que corresponde a la cadena JSON en los datos de respuesta. Debe ocupar 2 bytes, con el byte de mayor orden primero (big-endian). Por ejemplo, si la longitud de la matriz de bytes convertida desde la cadena JSON de respuesta usando codificación UTF-8 es 87 en decimal (57 en hexadecimal), el byte de mayor orden es 0x00 y el byte de menor orden es 0x57.
     JSON String Bytes	La matriz de bytes UTF-8 de la cadena JSON en los datos de respuesta. Detalles del formato: "Formato de datos JSON de respuesta" a continuación.
     File Block Bytes	La matriz de bytes del fragmento de archivo actual. Los bytes están ordenados ascendentemente según su desplazamiento desde el encabezado del archivo.
     CRC16/IBM	La suma de comprobación del fragmento de archivo. Solo se admite CRC16/IBM. Debe ocupar 2 bytes, con el byte de menor orden primero (little-endian). Por ejemplo, si la suma de comprobación del fragmento de archivo es 0x0809, el byte de menor orden es 0x09 y el byte de mayor orden es 0x08.

   • Formato del mensaje de respuesta

     {
      "id": "123456",
      "code":200,
      "msg":"file size has exceeded the limit 16 MB",
      "data": {
      "fileToken":"1bb8***",
      "fileLength":1238848,
      "bSize":1491,
      "bOffset":2
      }
     }

   • Descripción de parámetros del mensaje de respuesta

     Parámetro	Tipo	Descripción
     id	String	El ID del mensaje. El valor debe ser una cadena que contenga un número de 0 a 4294967295 y debe ser único para el dispositivo actual. El ID de mensaje devuelto es el ID de mensaje de la solicitud del dispositivo, que es el id en los datos del topic de solicitud /sys/${productKey}/${deviceName}/thing/file/download.
     code	Integer	El código de estado. Un valor de 200 indica éxito.
     msg	String	El mensaje de error que se devuelve si la solicitud falla.
     data	Object	Los datos devueltos al dispositivo.
     fileToken	String	El token único del archivo. Este parámetro se devuelve si se pasó el valor de fileToken en los parámetros de la solicitud.
     fileLength	Integer	El tamaño total del archivo en bytes.
     bSize	Integer	El tamaño del fragmento de archivo actual en bytes.
     bOffset	Integer	La dirección de inicio del byte que corresponde al fragmento de archivo actual. Este valor es el mismo que el valor de offset en los datos de la solicitud. La unidad es byte.

Reporte del progreso de actualización

• El dispositivo publica un mensaje en el topic: /ota/device/progress/${YourProductKey}/${YourDeviceName}.

• Formato del mensaje

  {
      "id": "123",
      "params": {
          "step": "-1",
          "desc": "OTA update failed. Failed to request the update package information.",
          "module": "MCU"
      }
  }

• Formato

  Parámetro	Tipo	Descripción
  id	String	El ID del mensaje. El valor debe ser una cadena que contenga un número de 0 a 4294967295 y debe ser único para el dispositivo actual.
  step	String	El progreso de la actualización OTA. Configure los valores de progreso y las descripciones según su escenario de actualización. Configuración del lado del dispositivo: Sample code. Un entero de 1 a 100: El porcentaje de progreso de la actualización. -1: La actualización falló. -2: La descarga falló. -3: La verificación falló. -4: La programación falló.
  desc	String	La descripción del paso actual. El valor puede tener hasta 128 caracteres de longitud. Si ocurre una excepción, este campo puede contener el mensaje de error.
  module	String	El nombre del módulo para el paquete de actualización OTA. Detalles del módulo: Add an update package. Cuando reporta el progreso de la actualización OTA para el módulo predeterminado, puede dejar vacío el parámetro module.