Ejecutar actualizaciones OTA - IoT Platform - Centro de documentación de Alibaba Cloud

IoT Platform admite la función over-the-air (OTA). Puede utilizar esta función para actualizar dispositivos. Este tema describe cómo usar la función OTA para actualizar dispositivos cuando se utiliza Message Queuing Telemetry Transport (MQTT) para conectarlos a IoT Platform. También se describen los topics y formatos de datos que se emplean durante el reenvío de datos en las actualizaciones OTA.

Proceso

La siguiente figura muestra el proceso para ejecutar una actualización OTA mediante MQTT.

Process

Notas

Para ejecutar una actualización diferencial, el dispositivo debe enviar el número de versión de un módulo OTA. Para una actualización completa, no es necesario enviar dicho número. Si no se envía el número de versión, no podrá especificar una versión de origen al configurar una actualización por lotes. Para obtener más información, consulte Create an update batch.

El dispositivo solo necesita enviar el número de versión una vez durante el inicio previo a la primera actualización. Una vez instalada la actualización en el dispositivo, este debe enviar inmediatamente el número de versión actual.
Al iniciar la actualización de varios dispositivos desde la consola de IoT Platform, cada dispositivo queda en estado Pending Update.

Cuando IoT Platform recibe el progreso de actualización enviado por un dispositivo, el estado del dispositivo cambia a Updating.

Nota
Después de recibir una notificación de actualización de IoT Platform, el dispositivo puede descargar el paquete de actualización y ejecutarla de inmediato o durante horas de baja demanda.
IoT Platform comprueba si una actualización OTA fue exitosa según el número de versión que envía el dispositivo.
Un dispositivo sin conexión no puede recibir notificaciones de actualización de IoT Platform.

Cuando el dispositivo se conecta, IoT Platform verifica si requiere actualización. Si es así, le envía una notificación; de lo contrario, no se envía ninguna notificación.

Formatos de mensaje

Para obtener más información sobre cómo usar SDK específicos por lenguaje con el fin de implementar actualizaciones OTA en dispositivos, consulte la documentación del Link SDK.

Los siguientes pasos describen el proceso para ejecutar una actualización OTA.

Opcional. Conecte un dispositivo al servicio OTA de IoT Platform y envíe el número de versión.

El número de versión se envía al siguiente topic mediante MQTT: /ota/device/inform/${productKey}/${deviceName}. Mensaje de ejemplo:

{
    "id": "123",
    "params": {
        "version": "1.0.1",
        "module": "MCU"
    }
}

Tabla 1. Descripción de parámetros
Parámetro	Tipo	Descripción
id	String	ID del mensaje. Número de tipo cadena. El valor debe ser único para el dispositivo y puede oscilar entre 0 y 4294967295.
version	String	Versión del módulo OTA.
module	String	Nombre del módulo OTA. Nota El parámetro module es opcional al reportar el número de versión del módulo predeterminado. El número de versión del módulo predeterminado representa la versión de firmware de todo el dispositivo.

En la consola de IoT Platform, agregue un paquete de actualización, verifíquelo e inicie una actualización por lotes.

Para obtener más información, consulte Overview.

Tras iniciar una actualización en la consola de IoT Platform, el dispositivo recibe la URL del paquete de actualización desde un topic.

El mensaje que incluye la URL se envía desde el servicio OTA de IoT Platform al siguiente topic: /ota/device/upgrade/${productKey}/${deviceName}. Cuando IoT Platform envía una solicitud de actualización OTA al dispositivo, este recibe la URL del paquete de actualización desde dicho topic.

Mensaje de ejemplo:

Para un paquete de actualización OTA que contiene un solo archivo:

Si el protocolo de descarga del paquete de actualización es HTTPS:

{
    "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\":\"Upgrade the underlying camera driver to fix the blurry video issue.\"}"
        }
    }
}

Si el protocolo de descarga del paquete de actualización es MQTT:

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

Los paquetes de actualización OTA con múltiples archivos solo admiten el protocolo de descarga HTTP. El formato de datos es el siguiente:

{
    "id": "123",
    "code": 200,
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***",
                "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                "fileSign":"93230c3bde425a9d7984a594ac55****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d7984a594ac56ea1f",
                "fileSign":"93230c3bde425a9d7984a594ac56****"
           }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Upgrade the underlying camera driver to fix the blurry video issue.\"}"
        }
    }
}

Tabla 2. Descripción de parámetros
Parámetro	Tipo	Descripción
id	Long	ID del mensaje. Debe ser único para el dispositivo.
message	String	Información del resultado.
code	String	Código de estado.
version	String	Versión del paquete de actualización del dispositivo.
size	Long	Tamaño del archivo del paquete de actualización en bytes. Este parámetro solo se incluye cuando el paquete de actualización OTA contiene un solo archivo.
url	String	Dirección de almacenamiento del paquete de actualización en Object Storage Service (OSS). Este parámetro solo se incluye cuando el paquete de actualización OTA contiene un solo archivo y el protocolo de descarga es HTTPS.
dProtocol	String	Protocolo de descarga del paquete de actualización. Este parámetro solo se incluye cuando el protocolo de descarga es MQTT.
streamId	Long	Identificador único para descargar el paquete de actualización OTA mediante MQTT. Este parámetro solo se incluye cuando el protocolo de descarga es MQTT.
streamFileId	Integer	Identificador único para un archivo individual del paquete de actualización. Este parámetro solo se incluye cuando el protocolo de descarga es MQTT.
isDiff	Long	Este parámetro solo se incluye cuando el tipo de paquete es actualización delta. Un valor de 1 indica que el paquete solo contiene las diferencias entre la nueva versión y la anterior. El dispositivo debe ejecutar una reversión delta.
digestsign	String	Firma del archivo del paquete de actualización OTA tras una actualización segura. Este parámetro solo se incluye si la función de actualización segura está habilitada para el paquete. Para habilitarla, consulte Secure upgrade.
sign	String	Firma del archivo del paquete de actualización OTA. Este parámetro solo se incluye cuando el paquete de actualización OTA contiene un solo archivo.
signMethod	String	Método de firma. Valores válidos: `SHA256` `MD5` Para paquetes de actualización delta 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 solo se incluye cuando el paquete de actualización OTA contiene un solo archivo.
module	String	Nombre del módulo al que pertenece el paquete de actualización. Nota Si el nombre del módulo es default, IoT Platform no envía el parámetro module.
extData	Object	Lista de etiquetas para el lote de actualización e información personalizada enviada al dispositivo. El campo _package_udi indica información personalizada. El formato para una sola etiqueta es `"key":"value"`.
files	Array	Lista de información para múltiples 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: Tamaño del archivo del paquete de actualización. fileName: Nombre del archivo del paquete de actualización. fileUrl, fileMd5 y fileSign tienen el mismo significado que url, md5 y sign.

Opcional. Descargue el paquete de actualización dentro de las 24 horas posteriores a la recepción de la URL por parte del SDK del dispositivo; de lo contrario, la URL caducará. El dispositivo puede solicitar una nueva tarea de actualización a IoT Platform enviando un mensaje al siguiente topic:

/sys/${productKey}/${deviceName}/thing/ota/firmware/get. Mensaje de ejemplo:

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

Tabla 4. Descripción de parámetros
Parámetro	Tipo	Descripción
id	String	ID del mensaje. Número de tipo cadena. El valor debe ser único para el dispositivo y puede oscilar entre 0 y 4294967295.
version	String	Versión del protocolo. El valor fijo es 1.0.
params	Object	Parámetros de la solicitud.
module	String	Nombre del módulo al que pertenece el paquete de actualización. Nota Si no se especifica este parámetro, el dispositivo solicita la información del paquete de actualización para el módulo predeterminado.
method	String	Método de la solicitud. El valor es `thing.ota.firmware.get`.

Una vez que IoT Platform recibe la solicitud, envía la información del paquete de actualización al siguiente topic: /sys/${productKey}/${deviceName}/thing/ota/firmware/get_reply.

IoT Platform envía al dispositivo la información sobre el paquete de actualización más reciente. Respuestas de ejemplo:

Para un paquete de actualización OTA que contiene un solo archivo:

Si el protocolo de descarga del paquete de actualización es HTTPS:

{
    "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\":\"Upgrade the underlying camera driver to fix the blurry video issue.\"}"
        }
    }
}

Si el protocolo de descarga del paquete de actualización es MQTT:

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

Los paquetes de actualización OTA con múltiples archivos solo admiten el protocolo de descarga HTTP. El formato de datos es el siguiente:

{
    "id": "123",
    "code": 200,
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***",
                "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                "fileSign":"93230c3bde425a9d7984a594ac55****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d7984a594ac56ea1f",
                "fileSign":"93230c3bde425a9d7984a594ac56****"
           }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Upgrade the underlying camera driver to fix the blurry video issue.\"}"
        }
    }
}

Tabla 1. La siguiente tabla describe los parámetros.
Parámetro	Tipo	Descripción
id	String	ID del mensaje. Valores válidos: 0 a 4294967295. Cada ID de mensaje debe ser único para el dispositivo. El ID del mensaje en la respuesta coincide con el de la solicitud. Puede consultar el parámetro `id` en los datos enviados al topic /sys/${productKey}/${deviceName}/thing/ota/firmware/get.
code	Integer	Código de estado. Un valor de 200 indica que la solicitud fue exitosa.
data	String	Información sobre el paquete de actualización. Para obtener más información, consulte Push OTA update package information to a device.

Si no hay ningún paquete de actualización disponible, se devuelven los siguientes datos:
```
{
    "id": "123",
    "code": 200,
    "data": {
    }
}
```

Una vez que el SDK del dispositivo recibe la URL del paquete de actualización, el dispositivo llama a una operación API del SDK para descargarlo.Overview

Por ejemplo, para descargar el paquete de actualización mediante el protocolo HTTPS, el SDK de C proporciona la interfaz

aiot_download_send_request

.

Para obtener más información, consulte

.

Nota
El dispositivo no puede descargar automáticamente el paquete de actualización. Debe llamar a la operación correspondiente en el SDK para realizar la descarga. Si el dispositivo no logra descargar el paquete desde la URL dentro de 24 horas, la URL caducará.

Para obtener más información sobre los registros generados al descargar el paquete de actualización, consulte los siguientes temas:

Durante una actualización, el dispositivo envía el progreso al siguiente topic:/ota/device/progress/${productKey}/${deviceName}.

Nota

Configure la frecuencia de reporte de progreso en el dispositivo con un máximo de una vez cada 3 segundos. Si el dispositivo reporta el progreso con demasiada frecuencia, es posible que no pueda visualizar todos los reportes en la

Batch Details

página del paquete de actualización OTA en la consola de IoT Platform.

Mensaje de ejemplo:

{
    "id": "123",
    "params": {
        "step": "-1",
        "desc": "OTA upgrade failed. Could not request the upgrade package information.",
        "module": "MCU"
    }
}

Tabla 3. Descripción de parámetros
Parámetro	Tipo	Descripción
id	String	ID del mensaje. Número de tipo cadena. El valor debe ser único para el dispositivo y puede oscilar entre 0 y 4294967295.
step	String	Progreso de la actualización OTA. Valores válidos: Entero de 1 a 100: Porcentaje de progreso de la actualización. `-1`: Error en la actualización. `-2`: Error en la descarga. `-3`: Error en la verificación. `-4`: Error en la grabación de firmware. Configure los valores de progreso y sus descripciones en el dispositivo según el escenario real de actualización. Para obtener información sobre cómo configurarlos, consulte OTA upgrades for Link SDK on devices.
desc	String	Descripción del paso actual. La descripción puede tener hasta 128 caracteres. Si ocurre un error, este campo puede contener el mensaje de error.
module	String	Nombre del módulo al que pertenece el paquete de actualización. Para obtener más información sobre módulos, consulte Add an upgrade package. Nota El parámetro module es opcional al reportar el progreso de actualización OTA del módulo predeterminado.

Al finalizar la actualización OTA de un dispositivo, este envía la versión actual del firmware al siguiente topic:/ota/device/inform/${productKey}/${deviceName}. Si la versión enviada coincide con la que el servicio OTA publicó en el topic, la actualización OTA se considera exitosa; de lo contrario, se considera fallida.

Nota
IoT Platform verifica si una actualización OTA fue exitosa basándose en la versión de firmware enviada. Por ejemplo, un dispositivo puede reportar un progreso de actualización del 100%. Sin embargo, si no envía la versión actual del firmware dentro de un periodo de tiempo de espera determinado, IoT Platform considerará que la actualización falló.

Se recomienda reiniciar el dispositivo inmediatamente después de completar la actualización OTA. Una vez que el dispositivo esté en línea, envíe el número de versión actual. El intervalo entre la solicitud de conexión del dispositivo a IoT Platform y la solicitud para enviar el número de versión actual no debe exceder los 2 segundos.

Errores comunes

La firma no es válida. Este error ocurre si la URL de un paquete de actualización es inválida o ha sido modificada, como se muestra en la siguiente figura.
Acceso denegado. El error se produjo porque la URL caducó. Cada URL tiene una validez de 24 horas.

Referencia de API

OTA update APIs