Data Store

Trackle mette a disposizione di ogni dispositivo un contenitore di dati in cloud di tipo JSON. Pensa al Data Store come un database chiave-valore condiviso tra il firmware e le App, utile per sapere l'ultimo stato conosciuto di un dispositivo, per salvare le sue configurazioni oppure per aggregare informazioni di diversi dispositivi per esempio in un'applicazione di prodotto.

Il Data Store può essere scritto dalle App, attraverso le API REST, anche quando il dispositivo è offline. Per ogni modifica Trackle invia una notifica al dispositivo, immediata se è subito raggiungibile oppure nel momento in cui torna online. Questo meccanismo permette di costruire potenti logiche di sincronizzazione.

Un Data Store √® composto da una o pi√Ļ chiavi, che chiamiamo propriet√†, definite a livello di Prodotto. Ogni dispositivo pu√≤ leggere e scrivere solo le chiavi configurate nel Data Store attraverso la Console o tramite le API REST.

Trackle.writeStore()

write store(json, REPLACE | MERGE)

Il parametro della funzione deve essere un file json in cui ogni voce deve essere definita come proprietà nel prodotto trackle cloud.

La dimensione massima di una scrittura in put (mode REPLACE) o in patch (mode MERGE) dello store è di 4Kb.

// SINTASSI
typedef enum
{
    STORE_WRITE_REPLACE = 0, // sostituisci lo store corrente
    STORE_WRITE_MERGE        // aggiorna una o pi√Ļ attibuiti dello store
} Store_Write_Type

void trackleWriteStore(Trackle * v, const char* data, Store_Write_Type type) {

// ESEMPIO
trackleWriteStore(c, "{\"data\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit.\"}", STORE_WRITE_MERGE);
trackleWriteStore(c, "{\"data\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit.\", \"data2\":\"Morbi auctor tincidunt ipsum, et egestas felis posuere a\"}", STORE_WRITE_REPLACE);

Trackle.readStore()

Richiede il valore di una propriet√† dsllo store. √ą necessario passare come argomento la chiave della propriet√† che si desidera leggere.

La dimensione massima della proprietà che è possibile leggere è di 1KB.

I messaggi di lettura e scrittura dello store rientrano nel rate di invio degli eventi, di circa 1 evento / sec, con picchi fino a 4 messaggi al secondo.

Trackle.readStoreCallback()

La callback viene chiamata quando viene ricevuta una proprietà dal cloud, richiesta con il metodo readStore:

  • key: la chiave della propriet√†

  • data: il valore della propriet√†

void read_store_callback(const char* key, const char* data) {
    // handle data
}

trackleSetReadStoreCallback(c, read_store_callback);

Come documentato nel paragrafo precedente, la dimensione massima del valore della proprietà (data) è di 1KB

Trackle.changedStoreCallback()

Questa callback viene chiamata quando il valore di una o pi√Ļ propriet√† sullo store √® stato aggiornato sul Cloud ed √® quindi necessario che il firmware legga il nuovo valore della propriet√†:

  • keys: elenco delle chiavi delle propriet√† modificate, separate da virgola

void changed_store_callback(const char* keys) {
    // handle data
}

trackleSetChangedStoreCallback(c, changed_store_callback);

Se un software, attraverso le API REST, effettua una modifica allo store, se il dispositivo è online riceverà subito una notifica di change con il nome della proprietà e potrà decidere se eseguire una lettura con la funzione readStore() o ignorarla.

Se invece il device è offline, alla prima riconnessione riceverà la lista delle proprietà che sono state modificate nel periodo di disconnessione.

Se il dispositivo successivamente effettua una read dello store o una propriet√†, oppure fa una scrittura di una o pi√Ļ propriet√†, quelle propriet√† non verranno pi√Ļ notificate ai successivi riavvii (in quanto risulteranno sincronizzate con il dispositivo)

fare diagrammi di sequenza per spiegare il meccanismo di synch.

Se è necessario che il dispositivo riceva un comando in tempo reale, solamente se è online, è consigliabile utilizzare una Trackle POST.

Modalità di utilizzo dello store

In funzione delle necessità, è possibile utilizzare lo in diverse modalità:

  • SOLA SCRITTURA: se lo store √® utilizzato solamente per rendere disponibili dei dati in cloud attraverso le API REST ma non √® necessario leggerli / riceverli dal dispositivo, √® possibile creare e scrivere singolarmente le propriet√†. In questo modo ogni propriet√† pu√≤ avere una dimensione massima di 4KB ed √® possibile gestire store di grandi dimensioni.

  • SOLA LETTURA o LETTURA E SCRITTURA: nel caso in cui il dispositivo abbia la necessit√† di leggere lo store, √® imporante ricordare che la dimensione massima di una propriet√† in lettura √® di 1KB. Potrebbe quindi essere possibile scrivere pi√Ļ chiavi con una singola write, in quanto la dimensione della singola scrittura pu√≤ arrivare a 4KB, prestando sempre attenzione a non superare la dimensione di 1KB per la singola propriet√†.

Last updated