Utilizzo della distribuzione di file AWS IoT basata su MQTT nei dispositivi

Per avviare il processo di trasferimento dei dati, un dispositivo deve ricevere un set di dati iniziale, che includa almeno un ID di flusso. È possibile utilizzare un Processi per pianificare le attività di trasferimento dei dati per i dispositivi includendo il set di dati iniziale nel documento del processo. Quando un dispositivo riceve il set di dati iniziale, dovrebbe avviare l'interazione con la consegna di file basata su AWS IoT MQTT. Per scambiare dati con la distribuzione di file AWS IoT basata su MQTT, un dispositivo deve:

• Utilizzare il protocollo MQTT per effettuare la sottoscrizione a Argomenti di distribuzione dei file basati su MQTT.

• Invia richieste e attendi di ricevere le risposte utilizzando i messaggi MQTT.

Facoltativamente, è possibile includere un ID del file di flusso e una versione di flusso nel set di dati iniziale. L'invio di un ID del file di flusso a un dispositivo può semplificare la programmazione del firmware/software del dispositivo, poiché elimina la necessità di creare una richiesta DescribeStream dal dispositivo per ottenere questo ID. Il dispositivo può specificare la versione del flusso in una richiesta GetStream per applicare un controllo di coerenza nel caso in cui il flusso sia stato aggiornato in modo imprevisto.

Utilizzato DescribeStream per ottenere dati in streaming

AWS IoT La distribuzione di file basata su MQTT fornisce l'DescribeStreamAPI per inviare dati di streaming a un dispositivo. I dati del flusso restituiti da questa API includono l'ID del flusso, la versione del flusso, la descrizione del flusso e un elenco di file di flusso, ognuno dei quali ha un ID di file e la dimensione del file in byte. Con queste informazioni, un dispositivo può selezionare file arbitrari per avviare il processo di trasferimento dei dati.

Nota

Non è necessario utilizzare l’API DescribeStream se il dispositivo riceve tutti gli ID dei file di flusso richiesti nel set di dati iniziale.

Attenersi ai seguenti passaggi per effettuare una richiesta DescribeStream.

1. Iscriversi al filtro argomento $aws/things/ThingName/streams/StreamId/description/json “accettato”.

2. Iscriversi al filtro argomento $aws/things/ThingName/streams/StreamId/rejected/json “rifiutato”.

3. Pubblicare una richiesta DescribeStream inviando un messaggio a $aws/things/ThingName/streams/StreamId/describe/json.

4. Se la richiesta è stata accettata, il dispositivo riceve una risposta DescribeStream sul filtro argomento “accettato”.

5. Se la richiesta è stata rifiutata, il dispositivo riceve la risposta di errore nel filtro argomento “rifiutato”.

Nota

Se si sostituisce json con cbor negli argomenti e nei filtri degli argomenti mostrati, il dispositivo riceve messaggi nel formato CBOR, che è più compatto di JSON.

DescribeStream richiesta

Una tipica richiesta DescribeStream in JSON è simile a quella nell'esempio seguente.

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

• (Facoltativo) “c” è il campo token client.

  Il token client non può superare i 64 byte. Un token client di dimensioni superiori a 64 byte causerà una risposta di errore e un messaggio di errore InvalidRequest.

DescribeStream risposta

Una risposta DescribeStream in JSON è simile a quella nell'esempio seguente.

{
    "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” è il campo token client. Questo viene restituito se è stato dato nella richiesta DescribeStream. Utilizza il token client per associare la risposta alla sua richiesta.

• "s” è la versione del flusso come numero intero. È possibile utilizzare questa versione per eseguire un controllo di coerenza con le richieste GetStream.

• "r” contiene un elenco dei file nel flusso.

  • "f” è l'ID del file di flusso come numero intero.

  • "z” è la dimensione del file di flusso in numero di byte.

• “d” contiene la descrizione del flusso.

Ottieni blocchi di dati da un file di flusso

Puoi utilizzare l’API GetStream in modo che un dispositivo possa ricevere file di flusso in blocchi di dati di piccole dimensioni, in modo che possa essere utilizzato da quei dispositivi che hanno vincoli per l'elaborazione di blocchi di grandi dimensioni. Per ricevere un intero file di dati, potrebbe essere necessario inviare o ricevere più richieste e risposte fino a quando tutti i blocchi di dati non vengono ricevuti ed elaborati.

GetStream richiesta

Attenersi ai seguenti passaggi per effettuare una richiesta GetStream.

1. Iscriversi al filtro argomento $aws/things/ThingName/streams/StreamId/data/json “accettato”.

2. Iscriversi al filtro argomento $aws/things/ThingName/streams/StreamId/rejected/json “rifiutato”.

3. Pubblicare una richiesta GetStream all'argomento $aws/things/ThingName/streams/StreamId/get/json.

4. Se la richiesta è stata accettata, il dispositivo riceverà una o più risposte GetStream sul filtro argomento “accettato”. Ogni messaggio di risposta contiene informazioni di base e un payload di dati per un singolo blocco.

5. Ripetere i passaggi 3 e 4 per ricevere tutti i blocchi di dati. È necessario ripetere questi passaggi se la quantità di dati richiesti è superiore a 128 KB. È necessario programmare il dispositivo per utilizzare più richieste GetStream per ricevere tutti i dati richiesti.

6. Se la richiesta è stata rifiutata, il dispositivo riceverà la risposta di errore nel filtro argomento “rifiutato”.

Nota

• Se sostituisci “json” con “cbor” negli argomenti e nei filtri degli argomenti mostrati, il tuo dispositivo riceverà messaggi nel formato CBOR, che è più compatto di JSON.

• AWS IoT La consegna di file basata su MQTT limita la dimensione di un blocco a 128 KB. Se si effettua una richiesta per un blocco superiore a 128 KB, la richiesta non verrà eseguita correttamente.

• È possibile effettuare una richiesta per più blocchi la cui dimensione totale è superiore a 128 KB (ad esempio, se si effettua una richiesta di 5 blocchi da 32 KB ciascuno per un totale di 160 KB di dati). In questo caso, la richiesta non ha esito negativo, ma il dispositivo deve effettuare più richieste per ricevere tutti i dati richiesti. Il servizio invierà blocchi aggiuntivi man mano che il dispositivo effettua richieste aggiuntive. Si consiglia di continuare con una nuova richiesta solo dopo che la risposta precedente è stata correttamente ricevuta ed elaborata.

• Indipendentemente dalla dimensione totale dei dati richiesti, è consigliabile programmare il dispositivo per avviare i tentativi quando i blocchi non vengono ricevuti o non vengono ricevuti correttamente.

Una tipica richiesta GetStream in JSON è simile a quella nell'esempio seguente.

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

• [facoltativo] “c” è il campo token client.

  Il token client non può superare i 64 byte. Un token client di dimensioni superiori a 64 byte causerà una risposta di errore e un messaggio di errore InvalidRequest.

• [facoltativo] “s” è il campo della versione di flusso (un numero intero).

  La distribuzione dei file basata su MQTT applica un controllo di coerenza basato su questa versione richiesta e sulla versione più recente del flusso nel cloud. Se la versione del flusso inviata da un dispositivo in una richiesta GetStream non corrisponde alla versione più recente del flusso nel cloud, il servizio invia una risposta di errore e un messaggio di errore VersionMismatch. In genere, un dispositivo riceve la versione di flusso prevista (più recente) nel set di dati iniziale o nella risposta a DescribeStream.

• "f” è l'ID del file di flusso (un numero intero compreso tra 0 e 255).

  L'ID del file di stream è necessario quando crei o aggiorni uno stream utilizzando AWS CLI o SDK. Se un dispositivo richiede un file di flusso con un ID che non esiste, il servizio invia una risposta di errore e un messaggio di errore ResourceNotFound.

• "l” è la dimensione del blocco dati in byte (un numero intero compreso tra 256 e 131.072).

  Fare riferimento a Crea una bitmap per una richiesta GetStream per istruzioni su come utilizzare i campi bitmap per specificare quale parte del file di flusso verrà restituita nella risposta GetStream. Se un dispositivo specifica una dimensione di blocco fuori intervallo, il servizio invia una risposta di errore e un messaggio di errore BlockSizeOutOfBounds.

• [facoltativo] “o” è l'offset del blocco nel file di flusso (un numero intero compreso tra 0 e 98.304).

  Fare riferimento a Crea una bitmap per una richiesta GetStream per istruzioni su come utilizzare i campi bitmap per specificare quale parte del file di flusso verrà restituita nella risposta GetStream. Il valore massimo di 98.304 è basato su un limite di dimensioni del file di flusso di 24 MB e 256 byte per la dimensione minima del blocco. Se il valore non viene specificato, viene usato il valore predefinito 0.

• [facoltativo] “n” è il numero di blocchi richiesti (un numero intero compreso tra 0 e 98.304).

  Il campo “n” specifica (1) il numero di blocchi richiesti, o (2) quando viene utilizzato il campo bitmap (“b”), un limite al numero di blocchi che verranno restituiti dalla richiesta bitmap. Questo secondo utilizzo è facoltativo. Se non è definito, il valore predefinito è 131072/. DataBlockSize

• [facoltativo] “b” è una bitmap che rappresenta i blocchi richiesti.

  Utilizzando una bitmap, il dispositivo può richiedere blocchi non consecutivi, il che rende più comoda la gestione dei tentativi in seguito a un errore. Fare riferimento a Crea una bitmap per una richiesta GetStream per istruzioni su come utilizzare i campi bitmap per specificare quale parte del file di flusso verrà restituita nella risposta GetStream. Per questo campo, converti la bitmap in una stringa che rappresenta il valore della bitmap in notazione esadecimale. La bitmap deve essere inferiore a 12.288 byte.

Importante

Una delle opzioni "n" o "b" deve essere specificata. Se nessuna delle due opzioni è specificata, la richiesta GetStream potrebbe non essere valida quando la dimensione del file è inferiore a 131072 byte (128 KB).

GetStream risposta

Una risposta GetStream in JSON assomiglia a questo esempio per ogni blocco di dati richiesto.

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

• “c” è il campo token client. Questo viene restituito se è stato dato nella richiesta GetStream. Utilizza il token client per associare la risposta alla sua richiesta.

• “f” è l'ID del file di flusso a cui appartiene il payload del blocco di dati corrente.

• “l” è la dimensione del payload del blocco dati in byte.

• “i” è l'ID del blocco di dati contenuto nel payload. I blocchi di dati sono numerati a partire da 0.

• “p” contiene il payload del blocco dati. Questo campo è una stringa, che rappresenta il valore del blocco di dati in codifica Base64.

Crea una bitmap per una richiesta GetStream

È possibile utilizzare il campo bitmap (b) in una richiesta GetStream per ottenere blocchi non consecutivi da un file di flusso. Ciò aiuta i dispositivi con capacità RAM limitata a gestire i problemi di distribuzione della rete. Un dispositivo può richiedere solo i blocchi che non sono stati ricevuti o non sono stati ricevuti correttamente. La bitmap determina quali blocchi del file di flusso verranno restituiti. Per ogni bit impostato su 1 nella bitmap, verrà restituito un blocco corrispondente del file di flusso.

Di seguito è riportato un esempio di come specificare una bitmap e i relativi campi di supporto in una richiesta GetStream. Ad esempio, desideri ricevere un file di flusso in blocchi di 256 byte (la dimensione del blocco). Pensa a ogni blocco di 256 byte come a un numero che specifica la sua posizione nel file, a partire da 0. Quindi il blocco 0 è il primo blocco di 256 byte nel file, il blocco 1 è il secondo e così via. Desideri richiedere i blocchi 20, 21, 24 e 43 dal file.

Offset di blocco

Poiché il primo blocco è il numero 20, specifica l'offset (campo o) come 20 per risparmiare spazio nella bitmap.

Numero di blocchi

Per garantire che il dispositivo non riceva più blocchi di quelli in grado di gestire con risorse di memoria limitate, è possibile specificare il numero massimo di blocchi da restituire in ciascun messaggio inviato dalla distribuzione di file basata su MQTT. Nota che questo valore viene ignorato se la bitmap stessa specifica meno di questo numero di blocchi o se la dimensione totale dei messaggi di risposta inviati dalla distribuzione di file basata su MQTT supera il limite del servizio di 128 KB per la richiesta GetStream.

Bitmap di blocco

La bitmap stessa è una matrice di byte non firmati espressi in notazione esadecimale e inclusi nella richiesta GetStream come rappresentazione della stringa del numero. Ma per costruire questa stringa, iniziamo pensando alla bitmap come una lunga sequenza di bit (un numero binario). Se un bit in questa sequenza è impostato su 1, il blocco corrispondente dal file di flusso verrà inviato nuovamente al dispositivo. Per questo esempio, vogliamo ricevere i blocchi 20, 21, 24 e 43, quindi dobbiamo impostare i bit 20, 21, 24 e 43 nella nostra bitmap. Possiamo usare l'offset del blocco per risparmiare spazio, quindi dopo aver sottratto l'offset da ogni numero di blocco, vogliamo impostare i bit 0, 1, 4 e 23, come nell'esempio seguente.

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

Prendendo un byte (8 bit) alla volta, questo è convenzionalmente scritto come: “0b00010011”, “0b00000000” e “0b10000000”. Il bit 0 viene visualizzato nella nostra rappresentazione binaria alla fine del primo byte e il bit 23 all'inizio dell'ultimo. Questo può creare confusione a meno che non si conoscano le convenzioni. Il primo byte contiene i bit 7-0 (in questo ordine), il secondo byte contiene i bit 15-8, il terzo byte contiene i bit 23-16 e così via. Nella notazione esadecimale, questo si converte in “0x130080”.

Suggerimento

È possibile convertire il binario standard in notazione esadecimale. Prendi quattro cifre binarie alla volta e convertile nel loro equivalente esadecimale. Ad esempio, “0001” diventa “1”, “0011” diventa “3” e così via.

Mettendo tutto questo insieme, il JSON per la nostra richiesta GetStream avrà il seguente aspetto.

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

• "c” è il campo token client.

• "s" è la versione del flusso prevista.

• “l” è la dimensione del payload del blocco dati in byte.

• "f" è l'ID dell'indice del file di origine.

• "o" è l'offset del blocco.

• "n" è il numero di blocchi.

• "b" è la bitmap BlockId mancante a partire dall'offset. Questo valore deve essere codificato base64.

Gestione degli errori derivanti dalla consegna di file basata su MQTT AWS IoT

Una risposta di errore inviata a un dispositivo sia per DescribeStream sia per GetStream API contiene un token client, un codice di errore e un messaggio di errore. Una tipica risposta di errore è simile a quella nell'esempio seguente.

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

• “o” è il codice che indica il motivo dell’errore. Consulta i codici di errore più avanti in questa sezione per maggiori dettagli.

• “m” è il messaggio di errore che contiene i dettagli dell'errore.

• “c” è il campo token client. Questo può essere restituito se è stato dato nella richiesta DescribeStream. Utilizza il token client per associare la risposta alla sua richiesta.

  Il campo token client non è sempre incluso in una risposta di errore. Quando il token client fornito nella richiesta non è valido o non è corretto, non viene restituito nella risposta di errore.

Nota

Per compatibilità con le versioni precedenti, i campi nella risposta agli errori potrebbero essere in forma non abbreviata. Ad esempio, il codice di errore potrebbe essere designato da campi “codice” o “o” e il campo token client può essere designato dai campi “clientToken” o “c”. È consigliabile utilizzare il modulo abbreviazione mostrato sopra.

InvalidTopic

L'argomento MQTT del messaggio di flusso non è valido.

InvalidJson

La richiesta del flusso non è un documento JSON valido.

InvalidCbor

La richiesta del flusso non è un documento CBOR valido.

InvalidRequest

La richiesta è generalmente identificata come non corretta. Per ulteriori informazioni, vedere il messaggio di errore.

Non autorizzato

La richiesta non è autorizzata ad accedere ai file di dati di flusso nel supporto di archiviazione, come Amazon S3. Per ulteriori informazioni, vedere il messaggio di errore.

BlockSizeOutOfBounds

La dimensione del blocco è fuori intervallo. Fare riferimento alla sezione “Distribuzione di file basata su MQTT” in Service Quotas di AWS IoT Core.

OffsetOutOfBounds

L'offset è fuori intervallo. Fai riferimento alla sezione “Distribuzione di file basata su MQTT” in Service Quotas di AWS IoT Core.

BlockCountLimitExceeded

Il numero dei blocchi di richiesta è fuori intervallo. Fai riferimento alla sezione “Distribuzione di file basata su MQTT” in Service Quotas di AWS IoT Core.

BlockBitmapLimitExceeded

La dimensione della bitmap richiesta è fuori intervallo. Fai riferimento alla sezione “Distribuzione di file basata su MQTT” in Service Quotas di AWS IoT Core.

ResourceNotFound

Il flusso, i file, le versioni del file o i blocchi richiesti non sono stati trovati. Consulta il messaggio di errore per ulteriori dettagli.

VersionMismatch

La versione del flusso nella richiesta non corrisponde alla versione del flusso nella funzione della distribuzione dei file basata su MQTT. Ciò indica che i dati del flusso sono stati modificati da quando la versione del flusso è stata inizialmente ricevuta dal dispositivo.

E TagMismatch

L'ETag S3 nel flusso non corrisponde all'ETag dell'ultima versione dell'oggetto S3.

InternalError

Si è verificato un errore interno nella distribuzione dei file basata su MQTT.