Arancino Library è una libreria realizzata per le board arancino.cc, scritta in linguaggio di programmazione Arduino Code, che può essere importata nell’ambiente di sviluppo Arduino IDE.
La libreria Arancino è scritta per funzionare anche nei microcontrollori SAMD21, attraverso la piattaforma SAMD di Arduino.
Utilizza la connessione seriale (mediante la libreria SerialUSB ) per comunicare con Arancino Module, ed attraverso la libreria Serial permette di eseguire le operazioni di debug.
Arancino Module è un demone (programma eseguito in background) che gira sul lato linux delle board arancino, che funge da interfaccia tra i microcontrollori connessi tramite porta seriale alla board arancino.cc, e può gestire più connessioni contemporaneamente. È progettato per funzionare sul sistema operativo Arancino OS, ma può anche essere eseguito su sistemi basati su Unix. Gestisce di default le connessioni seriali, ma può essere esteso ad altri canali di comunicazione. Ogni connessione deve implementare il protocollo Arancino Cortex.
La libreria Arancino consente di esportare/importare dati da e verso l’ambiente Linux utilizzando il datastore Redis come cache del database. Le API Arancino infatti, sono modellate sui comandi standard di Redis: arancino module interpreta i comandi API ( begin(), get(), set(),…) provenienti dai microcontrollori ad esso connessi e li invia al datastore Redis in attesa della loro esecuzione (vedi fig. 1)
Getting Started in Arduino IDE
Per utilizzare la libreria Arancino è necessario scaricarne l’ultima versione dal repository arancino-library, dalla sezione SmartMe.IO Repository Management Site; è possibile scegliere tra due versioni di librerie, la versione base “0.x.x”, e la versione più completa “1.x.x”, che supporta il multitasking con FreeRTOS. Effettuato il download della versione scelta, (file compresso “arancino-library-x.x.x.zip), per poter utilizzare Arancino Library in Arduino IDE è necessario aggiungerla alle librerie già presenti in esso (fig.2), dalla voce di menu: “Sketch → #include libreria → Aggiungi libreria da file ZIP… ”
Ultimata l’installazione, Arancino Library sarà presente come voce di menu in: “Sketch → #include libreria → Fornita da terze librerie → Arancino “
La libreria Arancino mette a disposizione una raccolta di esempi (file .ino scritti in Arduino IDE), per Arancino e per Arancino FreeRTOS, disponibili alla voce di menu “Esempi da librerie personalizzate” in: “File→ Esempi → Arancino “, come mostrato in fig.4:
Arancino API
La Arancino API (acronimo di Application Programming Interface) sono costituite da un set di comandi e protocolli che permettono alle board arancino.cc di comunicare agevolmente con i dispositivi ad esse connessi. La tabella 1 mostra i principali comandi utilizzati per la comunicazione seriale tra arancino.cc ed i microcontrollori ad essa connessi.
| begin | get | set | del | keys | hget |
| hset | hdel | hkeys | hvals | flush | publish |
Una descrizione dettagliata di tutti i comandi di Arancino API è disponibile nella nostra pagina git.smartme.io, nella sezione Arancino Library.
Arancino Cortex Protocol
Arancino Library utilizza un semplice protocollo, Arancino Cortex Protocol, per comunicare con Arancino Module tramite connessione seriale. Il protocollo Cortex è progettato per essere facile da leggere ed elaborare. Arancino Library, arancino Module ed arancino Cortex Protocol sono progettati per essere monodirezionali e sincroni. In questo scenario la libreria Arancino all’interno del microcontrollore funge da master, mentre il modulo Arancino funge da slave.
Ogni comando inviato utilizzando Cortex Protocol è composto da un identificatore di comando e da uno o più parametri. Gli identificatori e i parametri dei comandi sono separati da un carattere separatore (il codice ASCII del carattere “30” – RS – Record Separator) . Ogni comando inviato riceve una risposta, formata da un Codice Risposta e uno o più valori restituiti. Tutti i comandi inviati e le risposte ricevute terminano sempre con lo stesso carattere finale (codice ASCII del carattere “4” – EOT – End of Transmission) di fine trasmissione. In alcuni comandi ( come MGET o MSET) è possibile inviare o ricevere parametri multipli (array di valori), i cui elementi devono essere separati dal codice ASCII del carattere “16” (DLE – Data Link Escape). Il codice ASCII del carattere “25” (EM – End of Medium), è invece utilizzato per indicare un valore di ritorno NULL per una specifica operazione di lettura.
E’ quindi di fondamentale importanza NON utilizzare i codici ASCII di questi quattro caratteri speciali all’interno delle stringhe passate come parametri ai comandi API. I comandi ricevono la risposta entro un intervallo di timeout di 100 ms. Se non viene ricevuta alcuna risposta, il comando verrà ignorato. In fig. 5 sono mostrati le API arancino con i relativi identificatori di comandi Cortex ed alcuni esempi:
All’interno di REDIS esistono 2 tipi diversi di datastore: uno volatile ed uno persistente; per alcune operazioni (set o get) si dà priorità prima al volatile e poi al persistente.
Di seguito sono riportate alcune note relative all’utilizzo delle funzioni get ed mget:
- per ogni funzione di tipo get (get, hget, mget, hkeys, hvals, hgetall,..) si effettua la ricerca inizialmente nel database volatile, e nel caso non venisse trovato il dato richiesto, si cerca nel datastore persistente.
- se si desidera inserire un valore nel datastore con una funzione di tipo set singolo (set, hset), l’operazione sarà effettuata solo se il valore non esiste già nel dastore alternativo (cioè se si sta applicando una set standard sul dastore volatile, si controlla che la stessa chiave non esista già sul database persistente, e viceversa).
- nella funzione mset, non è necessario effettuare i controlli previsti per la funzione set; se la funzione mset venisse chiamata in entrambe le modalità ( persistente e standard) con le stesse chiavi, queste finirebbero su entrambi i datastore, ma in fase di lettura (mget) sarebbe acquisito di default il valore presente nel datastore volatile.
La tabella seguente mostra i possibili Codici di Risposta ricevuti:
| Codice di Risposta | Descrizione |
| 100 | OK – Generica operazione completata con successo |
| 101 | OK – Valore settato nel nuovo campo |
| 102 | OK – Settato il valore in un campo esistente |
| 200 | KO – Errore generico |
| 201 | KO – Valore ricevuto nullo |
| 202 | KO – Errore nell’esecuzione del comando SET |
| 203 | KO – Comando non trovato |
| 204 | KO – Comando non ricevuto |
| 205 | KO – Numero del parametro non valido |
| 206 | KO – Errore generico di Redis |
N.B.: tutte le funzioni di tipo *SET devono prevedere il charset UTF-8.