Se usa DescribeStream para obtener datos de transmisión Obtener bloques de datos de un archivo de transmisión Gestión de errores derivados de la entrega de archivos AWS IoT basada en MQTT

Uso de la entrega de archivos AWS IoT basada en MQTT en los dispositivos

Para iniciar el proceso de transferencia de datos, el dispositivo debe recibir un conjunto de datos inicial, que incluya como mínimo un ID de transmisión. Puede utilizar un Trabajos para programar tareas de transferencia de datos para sus dispositivos incluyendo el conjunto de datos inicial en el documento de trabajo. Cuando un dispositivo recibe el conjunto de datos inicial, debería iniciar la interacción con la entrega de archivos basada en AWS IoT MQTT. Para intercambiar datos con la entrega de archivos AWS IoT basada en MQTT, el dispositivo debe:

Utilizar el protocolo MQTT para suscribirse al Temas relacionados con la entrega de archivos basada en MQTT.
Enviar las solicitudes y esperar a recibir las respuestas mediante mensajes MQTT.

Si lo desea, puede incluir un ID de archivo de transmisión y una versión de la transmisión en el conjunto de datos inicial. El envío de un ID de archivo de transmisión a un dispositivo puede simplificar la programación del firmware/software del dispositivo, ya que elimina la necesidad de realizar una solicitud DescribeStream desde el dispositivo para obtener este ID. El dispositivo puede especificar la versión de la transmisión en una solicitud GetStream para aplicar una comprobación de coherencia en caso de que la transmisión se actualice de forma inesperada.

Se usa DescribeStream para obtener datos de transmisión

AWS IoT La entrega de archivos basada en MQTT proporciona la DescribeStream API para enviar datos de transmisión a un dispositivo. Los datos de transmisión devueltos por esta API incluyen el ID de la transmisión, la versión de la transmisión, la descripción de la transmisión y una lista de archivos de transmisión, cada uno de los cuales tiene un ID de archivo y el tamaño del archivo en bytes. Con esta información, un dispositivo puede seleccionar archivos arbitrarios para iniciar el proceso de transferencia de datos.

nota

No es necesario utilizar la API DescribeStream si el dispositivo recibe todos los ID de los archivos de transmisión necesarios en el conjunto de datos inicial.

Siga estos pasos para realizar una solicitud DescribeStream.

Suscríbase al filtro de temas “aceptados” $aws/things/ThingName/streams/StreamId/description/json.
Suscríbase al filtro de temas “rechazados” $aws/things/ThingName/streams/StreamId/rejected/json.
Publique una solicitud DescribeStream enviando un mensaje a $aws/things/ThingName/streams/StreamId/describe/json.
Si la solicitud se ha aceptado, el dispositivo recibirá una respuesta DescribeStream en el filtro de temas “aceptados”.
Si la solicitud se rechazó, el dispositivo recibirá la respuesta de error en el filtro de temas “rechazados”.

nota

Si sustituye json con cbor en los temas y filtros de temas mostrados, su dispositivo recibirá los mensajes en el formato CBOR, que es más compacto que JSON.

DescribeStream solicitud

Una solicitud DescribeStream típica en JSON se parece al siguiente ejemplo.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039"
}

(Opcional) “c” es el campo del token del cliente.

El token de cliente no puede ser superior a 64 bytes. Un token de cliente que supere los 64 bytes provoca una respuesta de error y un mensaje de error InvalidRequest.

DescribeStream respuesta

Una respuesta DescribeStream en JSON se parece al siguiente ejemplo.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039",
    "s": 1,
    "d": "This is the description of stream ABC.",
    "r": [
        {
            "f": 0,
            "z": 131072
        },
        {
            "f": 1,
            "z": 51200
        }
    ]
}

“c” es el campo de token del cliente. Esto se devuelve si se especificó en la solicitud DescribeStream. Use el token del cliente para asociar la respuesta a su solicitud.
“s” es la versión de transmisión en forma de número entero. Puede utilizar esta versión para comprobar la coherencia de sus solicitudes GetStream.
“r” contiene una lista de los archivos de la transmisión.
- “f” es el ID del archivo de transmisión en forma de número entero.
- “z” es el tamaño del archivo de transmisión en número de bytes.
“d” contiene la descripción de la transmisión.

Obtener bloques de datos de un archivo de transmisión

Puede usar la API GetStream para que un dispositivo pueda recibir archivos de transmisión en bloques de datos pequeños, de modo que puedan utilizarla aquellos dispositivos que tienen limitaciones a la hora de procesar bloques de gran tamaño. Para recibir un archivo de datos completo, es posible que un dispositivo deba enviar o recibir varias solicitudes y respuestas hasta que se reciban y procesen todos los bloques de datos.

GetStream solicitud

Siga estos pasos para realizar una solicitud GetStream.

Suscríbase al filtro de temas “aceptados” $aws/things/ThingName/streams/StreamId/data/json.
Suscríbase al filtro de temas “rechazados” $aws/things/ThingName/streams/StreamId/rejected/json.
Publique una GetStream solicitud sobre el tema$aws/things/ThingName/streams/StreamId/get/json.
Si la solicitud ha sido aceptada, su dispositivo recibirá una o varias respuestas GetStream en el filtro de temas “aceptados”. Cada mensaje de respuesta contiene información básica y una carga de datos para un solo bloque.
Repita los pasos 3 y 4 para recibir todos los bloques de datos. Debe repetir estos pasos si la cantidad de datos solicitada es superior a 128 KB. Debe programar el dispositivo para que utilice varias solicitudes GetStream a fin de recibir todos los datos solicitados.
Si la solicitud ha sido rechazada, su dispositivo recibirá la respuesta de error en el filtro de temas “rechazados”.

nota

Si sustituye “json” por “cbor” en los temas y filtros de temas mostrados, su dispositivo recibirá mensajes en el formato CBOR, que es más compacto que JSON.
AWS IoT La entrega de archivos basada en MQTT limita el tamaño de un bloque a 128 KB. Si realiza una solicitud de un bloque que supere los 128 KB, la solicitud fallará.
Puede realizar una solicitud para varios bloques cuyo tamaño total sea superior a 128 KB (por ejemplo, si solicita 5 bloques de 32 KB cada uno para un total de 160 KB de datos). En este caso, la solicitud no falla, pero el dispositivo debe realizar varias solicitudes para recibir todos los datos solicitados. El servicio enviará bloques adicionales a medida que tu dispositivo realice solicitudes adicionales. Le recomendamos que continúe con una nueva solicitud sólo después de haber recibido y procesado correctamente la respuesta anterior.
Independientemente del tamaño total de los datos solicitados, debe programar su dispositivo para que inicie reintentos cuando no se reciban bloques, o no se reciban correctamente.

Una solicitud GetStream típica en JSON se parece al siguiente ejemplo.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "s": 1,
    "f": 0,
    "l": 4096,
    "o": 2,
    "n": 100,
    "b": "..."
}

[opcional] “c” es el campo del token del cliente.

El token de cliente no puede ser superior a 64 bytes. Un token de cliente que supere los 64 bytes provoca una respuesta de error y un mensaje de error InvalidRequest.
[opcional] “s” es el campo de versión de la transmisión (un entero).

La entrega de archivos basada en MQTT aplica una comprobación de coherencia basada en esta versión solicitada y en la última versión de la transmisión en la nube. Si la versión de transmisión enviada desde un dispositivo en una solicitud GetStream no coincide con la última versión de transmisión en la nube, el servicio envía una respuesta de error y un mensaje de error VersionMismatch. Normalmente, un dispositivo recibe la versión esperada (más reciente) de la transmisión en el conjunto de datos inicial o en la respuesta a DescribeStream.
“f” es el ID del archivo de transmisión (un número entero comprendido entre 0 y 255).

El ID del archivo de transmisión es obligatorio para crear o actualizar una transmisión mediante el SDK AWS CLI o el SDK. Si un dispositivo solicita un archivo de transmisión con un ID que no existe, el servicio envía una respuesta de error y un mensaje de error ResourceNotFound.
“l” es el tamaño del bloque de datos en bytes (un entero comprendido entre 256 y 131 072).

Consulte Crea un mapa de bits para una solicitud GetStream para obtener instrucciones sobre cómo usar los campos de mapa de bits para especificar qué parte del archivo de transmisión se devolverá en la respuesta GetStream. Si un dispositivo especifica un tamaño de bloque que está fuera del rango, el servicio envía una respuesta de error y un mensaje de error BlockSizeOutOfBounds.
[opcional] “o” es el desplazamiento del bloque en el archivo de transmisión (un número entero en el rango de 0 a 98.304).

Consulte Crea un mapa de bits para una solicitud GetStream para obtener instrucciones sobre cómo usar los campos de mapa de bits para especificar qué parte del archivo de transmisión se devolverá en la respuesta GetStream. El valor máximo de 98.304 se basa en un límite de tamaño de archivo de transmisión de 24 MB y 256 bytes para el tamaño mínimo de bloque. El valor por defecto es 0 si no se especifica.
[opcional] “n” es el número de bloques solicitados (un número entero comprendido entre 0 y 98 304).

El campo “n” especifica (1) el número de bloques solicitados o (2) cuando se utiliza el campo de mapa de bits (“b”), un límite en el número de bloques que devolverá la solicitud de mapa de bits. Este segundo uso es opcional. Si no está definido, el valor predeterminado es DataBlockSize131072/.
[opcional] “b” es un mapa de bits que representa los bloques que se solicitan.

Con un mapa de bits, el dispositivo puede solicitar bloques no consecutivos, lo que facilita la gestión de los reintentos tras un error. Consulte Crea un mapa de bits para una solicitud GetStream para obtener instrucciones sobre cómo usar los campos de mapa de bits para especificar qué parte del archivo de transmisión se devolverá en la respuesta GetStream. Para este campo, convierta el mapa de bits en una cadena que represente el valor del mapa de bits en notación hexadecimal. El mapa de bits debe tener menos de 12.288 bytes.

importante

Debe especificarse “n” o “b”. Si no se especifica ninguno de ellos, es posible que la solicitud GetStream no sea válida cuando el tamaño del archivo sea inferior a 131072 bytes (128 KB).

GetStream respuesta

Una respuesta GetStream en JSON tiene el aspecto que se muestra en este ejemplo para cada bloque de datos que se solicite.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "f": 0,
    "l": 4096,
    "i": 2,
    "p": "..."
}

“c” es el campo de token del cliente. Esto se devuelve si se especificó en la solicitud GetStream. Use el token del cliente para asociar la respuesta a su solicitud.
“f” es el ID del archivo de transmisión al que pertenece la carga útil del bloque de datos actual.
“l“ es el tamaño de la carga útil del bloque de datos en bytes.
“i” es el ID del bloque de datos contenido en la carga útil. Los bloques de datos se enumeran a partir de 0.
“p” contiene la carga útil del bloque de datos. Este campo es una cadena que representa el valor del bloque de datos en la codificación Base64.

Crea un mapa de bits para una solicitud GetStream

Puede usar el campo de mapa de bits (b) en una GetStream solicitud para obtener bloques no consecutivos de un archivo de transmisión. Esto ayuda a los dispositivos con una capacidad de RAM limitada a solucionar los problemas de entrega de la red. Un dispositivo solo puede solicitar aquellos bloques que no se hayan recibido o que no se hayan recibido correctamente. El mapa de bits determina qué bloques del archivo de transmisión se devolverán. Para cada bit, que se establece en 1 en el mapa de bits, se devolverá el bloque correspondiente del archivo de transmisión.

A continuación, se muestra un ejemplo de cómo especificar un mapa de bits y sus campos de soporte en una solicitud GetStream. Por ejemplo, desea recibir un archivo de transmisión en fragmentos de 256 bytes (el tamaño del bloque). Imagine que cada bloque de 256 bytes tiene un número que especifica su posición en el archivo, empezando por 0. Así, el bloque 0 es el primer bloque de 256 bytes del archivo, el bloque 1 es el segundo y, así, sucesivamente. Desea solicitar los bloques 20, 21, 24 y 43 del archivo.

Desplazamientos de bloques

Como el primer bloque es el número 20, especifique el desplazamiento (campo o) como 20 para ahorrar espacio en el mapa de bits.

Número de bloques

Para garantizar que el dispositivo no reciba más bloques de los que puede gestionar con recursos de memoria limitados, puede especificar el número máximo de bloques que se deben devolver en cada mensaje enviado mediante un sistema de entrega de archivos basado en MQTT. Tenga en cuenta que este valor no se tiene en cuenta si el propio mapa de bits especifica menos de este número de bloques o si el tamaño total de los mensajes de respuesta enviados mediante la entrega de archivos basada en MQTT supera el límite de servicio de 128 KB por solicitud GetStream.

Mapa de bits de bloques

El mapa de bits en sí es una matriz de bytes sin signo expresados en notación hexadecimal e incluidos en la solicitud GetStream como una representación en cadena del número. Pero para construir esta cadena, empecemos por pensar en el mapa de bits como una secuencia larga de bits (un número binario). Si un bit de esta secuencia se establece en 1, el bloque correspondiente del archivo de transmisión se devolverá al dispositivo. En nuestro ejemplo, queremos recibir los bloques 20, 21, 24 y 43, por lo que debemos establecer los bits 20, 21, 24 y 43 en nuestro mapa de bits. Podemos usar el desplazamiento del bloque para ahorrar espacio, así que después de restar el desplazamiento de cada número de bloque, queremos establecer los bits 0, 1, 4 y 23, como en el siguiente ejemplo.


 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1

Si se toma un byte (8 bits) a la vez, se escribe convencionalmente como: “0b00010011”, “0b00000000” y “0b10000000”. El bit 0 aparece en nuestra representación binaria al final del primer byte y el bit 23 al principio del último. Esto puede resultar confuso a menos que conozca las convenciones. El primer byte contiene los bits 7-0 (en ese orden), el segundo byte contiene los bits 15-8, el tercer byte contiene los bits 23-16, y así sucesivamente. En notación hexadecimal, se convierte en “0x130080”.

sugerencia

Puede convertir la notación binaria estándar en hexadecimal. Tome cuatro dígitos binarios a la vez y conviértalos a su equivalente hexadecimal. Por ejemplo, “0001” pasa a ser “1”, “0011” pasa a ser “3” y así sucesivamente.

Desglose en bloques del mapa de bits para construir una cadena en la GetStream solicitud.

Al juntar todo esto, el JSON de nuestra solicitud GetStream tiene el siguiente aspecto.


{
    "c" : "1",       
    "s" : 1,         
    "l" : 256,       
    "f" : 1,         
    "o" : 20,        
    "n" : 32,       
    "b" : "130080"
}

“c” es el campo de token del cliente.
“s” es la versión de transmisión esperada.
“l“ es el tamaño de la carga útil del bloque de datos en bytes.
“f” es el identificador del índice del archivo fuente.
“o” es el desplazamiento de los bloque.
“n” es el número de bloques.
“b” es el mapa de bits de BlockID que falta a partir del desplazamiento. Este valor debe estar codificado con based64.

Gestión de errores derivados de la entrega de archivos AWS IoT basada en MQTT

Una respuesta de error que se envía a un dispositivo para las API de DescribeStream y GetStream contiene un token de cliente, un código de error y un mensaje de error. Una respuesta de error típica se parece al siguiente ejemplo.


{
    "o": "BlockSizeOutOfBounds", 
    "m": "The block size is out of bounds", 
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380" 
}

“o” es el código de error que indica la razón por la que se ha producido un error. Consulte los códigos de error más adelante en esta sección para obtener más información.
“m” es el mensaje de error que contiene los detalles del error.
“c” es el campo de token del cliente. Esto se puede devolver si se especificó en la solicitud DescribeStream. Puede utilizar el testigo del cliente para asociar la respuesta a su solicitud.

El campo del token del cliente no siempre se incluye en una respuesta de error. Cuando el token de cliente proporcionado en la solicitud no es válido o tiene un formato incorrecto, no se devuelve en la respuesta al error.

nota

Por motivos de compatibilidad con versiones anteriores, es posible que los campos de la respuesta al error no estén abreviados. Por ejemplo, el código de error puede designarse mediante los campos “code” u “o” y el campo token de cliente puede designarse mediante los campos “clientToken” o “c”. Le recomendamos que utilice la forma de abreviatura que se muestra arriba.

InvalidTopic: El tema MQTT del mensaje de transmisión no es válido.
InvalidJson: La solicitud de transmisión no es un documento JSON válido.
InvalidCbor: La solicitud de transmisión no es un documento CBOR válido.
InvalidRequest: Por lo general, la solicitud se identifica como incorrecta. Para más información, consulte el mensaje de error.
Unauthorized: La solicitud no está autorizada para acceder a los archivos de datos de transmisión en el medio de almacenamiento, como Amazon S3. Para más información, consulte el mensaje de error.
BlockSizeOutOfBounds: El tamaño del bloque está fuera de los límites. Consulte la sección Entrega de archivos basada en MQTT” en Service Quotas AWS IoT Core.
OffsetOutOfBounds: El desplazamiento está fuera de los límites. Consulte la sección Entrega de archivos basada en MQTT” en Service Quotas AWS IoT Core.
BlockCountLimitExceeded: El número de bloques de solicitudes está fuera de los límites. Consulte la sección Entrega de archivos basada en MQTT” en Service Quotas AWS IoT Core.
BlockBitmapLimitExceeded: El tamaño del mapa de bits de solicitud está fuera de los límites. Consulte la sección Entrega de archivos basada en MQTT” en Service Quotas AWS IoT Core.
ResourceNotFound: No se encontraron el flujo, los archivos, las versiones de archivos o los bloques solicitados. Consulte el mensaje de error para obtener más información.
VersionMismatch: La versión de transmisión de la solicitud no coincide con la versión de transmisión de la característica de entrega de archivos basada en MQTT. Esto indica que los datos de la transmisión se han modificado desde que el dispositivo recibió inicialmente la versión de transmisión.
E TagMismatch: La ETag de S3 de la transmisión no coincide con la ETag de la última versión de la cosa de S3.
InternalError: Se ha producido un error interno en la entrega de archivos basada en MQTT.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Administrar una transmisión en la nube AWS

Un ejemplo de caso de uso en Freertos OTA