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 MQTT basada en archivos

Uso de la entrega de archivos AWS IoT MQTT basada en 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 AWS IoT Empleos 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 AWS IoT MQTT basada en datos. Para intercambiar datos con la entrega de archivos AWS IoT MQTT basada en archivos, el dispositivo debe:

Utilice el MQTT protocolo para suscribirse alMQTTtemas basados en la entrega de archivos.
Envíe las solicitudes y espere a recibir las respuestas mediante MQTT mensajes.

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 MQTTLa entrega basada en archivos permite DescribeStream API enviar datos de transmisión a un dispositivo. Los datos de transmisión que devuelve 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 los archivos de la 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 que lo utilices DescribeStream API si tu dispositivo recibe todos los archivos IDs de transmisión necesarios del 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 lo json cbor sustituyes por uno de los temas y filtros de temas que se muestran, tu dispositivo recibirá los mensajes en el CBOR formato, que es más compacto queJSON.

DescribeStream solicitud

Una DescribeStream solicitud típica se JSON parece a la del 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 DescribeStream respuesta 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 usarlo GetStream API para que un dispositivo pueda recibir archivos de flujo en bloques de datos pequeños, de modo que pueda ser utilizado por 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 sustituyes «json» por «cbor» en los temas y filtros de temas que se muestran, tu dispositivo recibirá los mensajes en el CBOR formato, que es más compacto queJSON.
AWS IoT MQTTLa entrega de archivos basada en archivos 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 GetStream solicitud típica se JSON parece a la del 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).

MQTTla entrega de archivos basada en archivos aplica una comprobación de coherencia basada en la versión solicitada y en la última versión de streaming 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 AWS CLI oSDK. 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 Cree 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 Cree 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 131072/DataBlockSize.
[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 Cree 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 GetStream respuesta se JSON parece a este ejemplo para cada bloque de datos que se solicita.


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

Cree 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 RAM capacidad limitada a resolver 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 la entrega de archivos MQTT basada en archivos. Tenga en cuenta que este valor no se tiene en cuenta si el propio mapa de bits especifica un número inferior a este número de bloques o si hace que el tamaño total de los mensajes de respuesta enviados mediante la entrega de archivos MQTT basada en archivos supere el límite de servicio de 128 KB por GetStream solicitud.

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.

Bloque el desglose del mapa de bits para crear una cadena en la solicitud. GetStream

Juntando todo esto, el aspecto JSON de nuestra GetStream solicitud es el siguiente.


{
    "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 blockId mapa de bits 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 MQTT basada en archivos

Una respuesta de error que se envía a un dispositivo para ambos DescribeStream y GetStream APIs 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 con los campos «código» u «o» y el campo del token del cliente puede designarse con los campos «clientToken» o «c». Le recomendamos que utilice la forma de abreviatura que se muestra arriba.

InvalidTopic: El MQTT tema del mensaje de transmisión no es válido.
InvalidJson: La solicitud de transmisión no es un JSON documento válido.
InvalidCbor: La solicitud de Stream no es un CBOR documento 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 MQTT basada» en AWS IoT Core Service Quotas.
OffsetOutOfBounds: El desplazamiento está fuera de los límites. Consulte la sección «Entrega de archivos MQTT basada» en AWS IoT Core Service Quotas.
BlockCountLimitExceeded: El número de bloques de solicitudes está fuera de los límites. Consulte la sección «Entrega de archivos MQTT basada» en AWS IoT Core Service Quotas.
BlockBitmapLimitExceeded: El tamaño del mapa de bits de solicitud está fuera de los límites. Consulte la sección «Entrega de archivos MQTT basada» en AWS IoT Core Service Quotas.
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 función de entrega de archivos MQTT basada en archivos. Esto indica que los datos de la transmisión se han modificado desde que el dispositivo recibió inicialmente la versión de transmisión.
ETagMismatch: La S3 ETag de la transmisión no coincide con la versión más reciente ETag del objeto de S3.
InternalError: Se ha producido un error interno en la entrega de archivos MQTT basados.

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

Administra una transmisión

Un ejemplo de caso de uso en Free RTOS OTA