FCGF : Libraria Google Moduli per micro controllori Wi-Fi e GSM.

FCGF 0.0.4 sta arrivando!

Abbiamo lavorato molto per rendere la connessione a Google Moduli dalla tua board Wi-Fi o GSM il più semplice e veloce possibile, al contempo ci siamo preoccupati di offrirti una documentazione adeguatamente completa.

Controllo del traffico

E’ possibile usare FCGF per monitorare il traffico a 360°. L’uso della libreria riduce i tempi e i costi per la realizzazione di sistemi di monitoraggio.

Centralizzazione dei dati

Puoi inviare diversi dati, provenienti da diverse board, allo stesso modulo di Google, favorendo cosi la centralizzazione dei dati.

Totem sondaggi automatici

La libreria si presta benissimo alla realizzazione di sistemi automatici per la raccolta di sondaggi.

A cosa serve il ToolKit e come si usa ?

Quando crei un modulo di Google, questo può avere al suo interno varie tipologie di campi, nello specifico la libreria accetta i campi di tipo “Risposta breve” e/o “Paragrafo” e ogni campo ha un identificativo che fino a qualche tempo fa poteva essere prelevato andando a spulciare nel codice html del modulo, ma ora non è più possibile farlo e il ToolKit online della libreria permette di generare lo sketch andando a scandagliare il tuo modulo e inserendo automaticamente tutti gli identificativi nello sketch in una frazione di secondo. 

Gli identificativi dei campi validi sono simili a quello indicato di seguito : 

entry.xxxxxxxxxxx

Dove “xxxxxxxxxxx” indica una serie di caratteri univoca.

La procedura per la generazione dello sketch ti richiede veramente pochissimo tempo ed è completamente guidata.

1. Inizio

Aprendo il ToolKit usando il pulsante presente in questa pagina o il menu del sito, viene visualizzata una pagina simile a quella indicata nella figura seguente. Basta fare click sul pulsante Start per iniziare :


2. Seleziona il tipo di board in tuo possesso

La libreria è compatibile con quasi tutte le board in commercio che integrano la connettività Wi-Fi e GSM, nella schermata seguente è possibile scegliere su quale board lavorare : 

3. Inserimento link modulo

Nel terzo passaggio puoi inserire i link del tuo modulo. Devi inserire il link dell’editor del modulo e il link dell’anteprima del modulo, i link in questione devono essere simili a questi :

 

https://docs.google.com/forms/d/xxxxxxxxxxxxxxxx/edit
https://docs.google.com/forms/d/e/xxxxxxxxxxxxxxxx/viewform

I link devono essere corretti in modo tale che il ToolKit possa interrogare il tuo modulo e prelevare le informazioni che serviranno per completare lo sketch :

4. Informazioni non obbligatorie

In questa sezione puoi aggiungere le informazioni di connessione alla tua rete Wi-Fi o GSM, in base alla board che hai selezionato nel secondo passaggio e altre informazioni non obbligatorie che verranno riempite automaticamente con i valori predefiniti. Nel caso in cui non inserisci i dati di accesso alla connessione utilizzata, ricordati che questi dati andranno inseriti manualmente nel codice :

Per quanto riguarda il Submit interval il valore predefinito è “0” e va a indicare una pausa, espressa in minuti, tra un invio di dati e l’altro. Il Variables prefix è solamente un’impostazione cosmetica del codice e va ad aggiungere un prefisso personalizzato alle variabili predefinite usate nello sketch, di default questo valore è impostato come “myform_”

5. Generazione dello sketch

Concluse le impostazioni di settaggio è il momento di generare il codice con il pulsante “Process now!” :

Successivamente è possibile scaricare il codice tramite il pulsante “Download sketch” presente ai piedi dello sketch appena generato : 


Come si popola l'Array values ?

Nello sketch generato è stata creata una variabile in Array la quale dovrebbe essere simile alla seguente : 

String myform_values[] = {"yourval_0","yourval_1"...};

L’Array in questione ha N elementi al suo interno quanti sono i campi compatibili analizzati dal ToolKit, mettendo il caso che tu sia in possesso di un modulo con 4 campi, gli elementi in questo Array saranno 4. I valori all’interno dell’Array possono essere solo valori String e quindi qualsiasi variabile numerica deve essere convertita in String, considerando un sensore DHT11 una soluzione ottimale all’invio dei suo valori è la seguente :

int temperatura = DHT.readTemperature();
int umidita = DHT.readHimidity();
String myform_values[] = {String(temperatura),String(umidita)};

L’Array values verrà successivamente processato dalla funzione submit che invierà i tuoi dati al modulo. E’ importante ricordare che gli elementi dell’Array seguono esattamente l’ordine dei campi partendo dal primo elemento dell’Array a sinistra (primo campo) :

campo1
campo2
campo3
String myform_values[] = {campo1, campo2, campo3};

Changelog

  1. Compatibilità con Arduino Uno Wi-Fi Rev.2
  2. Il ToolKit online è compatibile con i nuovi parametri di generazione moduli di Google.
  3. Risolti alcuni problemi minori.

  1. Compatibilità con Arduino MKR GSM 1400.
  2. Compatibilità con Arduino Nano 33 IoT.
  3. Aggiunta funzione di delay nel submit che non blocca il programma.
  4. Aggiunto contatore interno per conteggiare gli invii e le connessioni corrette e/o fallite.
  5. Aggiunta funzione che converte i punti in virgole per adattare il separatore decimale alle impostazioni internazioni italiane.

  1. Risolto un problema che impediva l’invio di valori contenenti i caratteri speciali ( | ! “£ $% & / () =? ^ * + [] {} -_;:,. <>)
  2. Inserita una variabile di callback, utile per testare il corretto inserimento dei valori all’interno del tuo modulo.

Prima Alpha con ToolKit online.

Funzioni

Funzione che converte gli elementi di una stringa e li rende compatibili per essere inseriti all’interno di un URL.

Uso

String testo_originale = "ciao questo è un testo con caratteri e simboli";
String testo_convertito = FCGF_URL_ENCODE(testo_originale);

Risultato

 ciao%20questo%20%C3%A8%20un%20testo%20con%20caratteri%20e%20simboli

Funzione che permette di convertire un valore IPAddress in un valore String.

Uso

IPAddress ip(192,168,1,30);
String stringa_ip = FCGF_IP_TO_STRING(ip);

Risultato

192.168.1.30

Begin per la libreria compatibile solo con ESP8266 ed ESP32. Questa funzione di begin permette di inizializzare la libreria sfruttando le funzionalità di connettività Wi-Fi di client secondari come ad esempio Blynk.

Uso

void setup() {
gf.dummyBegin();
}

Questa funzione di begin permette di inizializzare la libreria, il client sicuro per la connessione SSL e la connettività Wi-Fi delle seguenti board : 

Arduino UNO Wi-Fi Rev.2
Arduino MKR W-Fi 1010
Arduino Nano 33 Iot
Board con ESP8266
Board con ESP32

Per inizializzare correttamente il Wi-Fi della board è necessario inserire il nome della connessione Wi-Fi e la password di quest’ultima, entrambi i valori devono essere in const char.

Uso

const char* mia_rete = "casa";
const char* mia_password = "segreto";
void setup() {
   gf.beginWiFi(mia_rete, mia_password);
}

Funzione di inizializzazione del client sicuro e della connessione dati tramite sim. Questa funzione è compatibile solo con Arduino MKR GSM 1400 e permette di usare la libreria in assenza di Wi-Fi sfruttando una sim dati di qualsiasi gestore.

Uso

const char* apn = "apn_sim";
const char* pin = "0000";
const char* user = "sim";
const char* passwd = "segreto";
void setup() {
  gf.beginGSM(apn, pin, user, passwd);
}

Una volta inizializzata la libreria con uno dei tre begin disponibili in base alla tua board, è possibile inviare i dati sul tuo modulo con la funzione submit.

Uso

int numero_campi = 3;
int timer_invii = 1; //1 minuto
String id_modulo = "xxxxxxxxxxxxxxxxxxxxxxxxxx";
String campi_modulo[] = {"entry.xxxxxxxx","entry.xxxxxxxx","entry.xxxxxxxx"};
void loop() {
String miei_valori[] = {"valore1","valore2","valore3"};
gf.submit(id_modulo, campi_modulo, miei_valori, numero_campi, timer_invii);
}

L’id del modulo è l’id dell’editor del modulo e permette alla libreria di capire a quale modulo inviare la richiesta HTTP con il metodo POST.

La funzione gestisce due array, il primo è l’array che contiene i nomi di tutti i campi disponibili all’interno del tuo modulo (di tipo “Risposta breve” e/o “Paragrafo”) e il secondo array contiene i valori che andranno a riempire i campi del primo array, entrambi gli array sono di tipo String.

Il numero di campi identifica il numero di campi presenti nel tuo modulo, tutti i campi (di tipo “Risposta breve” e/o “Paragrafo”) che sono presenti nel tuo modulo.

Il timer invio (espresso in minuti) è un delay che non blocca la normale esecuzione della funzione loop, ma allo stesso tempo permette di indicare ogni quanto tempo si deve procedere con un nuovo invio di dati. Questo parametro è di default impostato su 0 (senza ritardi), tuttavia, esiste un ritardo logico dovuto alla connessione a internet e ad altri fattori legati a latenze hardware.

Funzione che trasforma un numero con separatore decimale indicato dal punto “.” in un numero con separatore decimale indicato da una virgola “,”.  Questa funzione è stata inserita poiché il metodo di separazione dei decimali delle board è con un punto, la gestione dei decimali sui servizi Google, sopratutto sui fogli di calcolo e le impostazioni internazionali sono impostate su “Italia”, è usata una virgola. La funzione è in grado di fare una conversione del separatore decimale solo nelle variabili String.

Uso 

float numero_decimale = 2.5;
String numero_decimale_string = String(numero_decimale);
String numero_decimale_con_virgola = gf.commaForDot(numero_decimale_string);

Risultato

2,5

La funzione permette di estrarre il numero di errori e successi delle connessioni al server e dell’invio dei dati. Ogni volta che si verifica un errore o un successo viene incrementato un counter interno. 

Uso

int numero_invii_corretti = gf.counter(0);
int numero_invii_falliti = gf.counter(1);
int numero_connessioni_google_fallite = gf.counter(2);

Parametri

La funzione accetta parametri di tipo int (numerico) che vanno da 0 a 2 e che permettono di selezionare il tipo di contatore da interrogare in base alle tue esigenze.

0 = Numero di invii corretti
1 = Numero di invii falliti
2 = Numero di connessioni al server Google fallite

Funzione assimilabile al classico delay di Arduino e board simili ma che permette di mettere in pausa il codice per 1 o più minuti.

Uso

gf.delayMinute(1); //attendi un minuto

Attenzione : Questa funzione mette in pausa tutto il processo della board in uso, rendendola inutilizzabile per tutto il periodo impostato. Se hai bisogno di creare una sorta di time per mettere in pausa il prossimo invio di dati leggi le informazioni legate alla funzione delayMinute inclusa nella funzione submit.

Funzione che permette di settare la lingua del webAgent che andrà a fare le richieste HTTP al servizio di Google, di default è “it”.

Uso

gf.setLanguage("en"); //imposta la lingua in inglese

Funzione che permette di settare il nome del webAgent che andrà a fare richieste HTTP ai servizi di Google, di default è “FCGFIotDevice”.

Uso

gf.setWebAgent("nome"); //imposta il nome del webAgent come "nome"

Variabili

Variabile booleana che permette di intercettare il risultato di un’invio della funzione submit, questa variabile può essere usata affiancata a un costrutto “if” per capire se il tuo invio di dati è stato effettuato correttamente o meno.

Uso

gf.submit(...);
if(FCGF_SUBMIT_CALLBACK) {
   //invio corretto
} else {
   //invio fallito
}

Risoluzione dei problemi

In tal caso è necessario verificare che i dati inseriti per la tua connessione Wi-Fi o l’APN dell’operatore utilizzato sulla SIM siano corretti e nel caso di una connessione Wi-Fi che il modem/router centrale riesca a configurare gli ip in modo automatico e che quindi il DHCP sia attivo.

La libreria ha la necessità di connettersi a  Google e nello specifico al server “docs.google.com” prima di poter “parlare” con il tuo modulo, se ricevi sul Monitor Seriale la scritta “#HOST UNAVAILABLE” vuol dire che il server ha rigettato la tua richiesta di connessione, questo può succedere solo nel caso in cui la tua SIM non ha ancora completato l’inizializzazione della connessione dati, in questo caso ti basterà tentare di nuovo la connessione al server, o nel caso in cui mancano i certificati per connetterti a Google. La mancanza di certificati può riscontrarsi maggiormente con Arduino MKR Wi-Fi 1010 ed è un problema risolvibile aggiungendo alla board il certificato “google.com:443”, qui trovi la guida per effettuare questa operazione : https://www.filoconnesso.it/consigli-su-arduino-mkr-wifi-1010-aggiornamento-firmware-aggiunta-certificati-e-correggere-gli-errori-comuni/.

Quando la libreria non riesce a inviare i dati di solito il problema è imputabile al modulo di Google e ai dati che stai cercando di inviare. Accertati sempre che tutti i campi del modulo di Google siano di tipo “Risposta breve” e/o “Paragrafo”, inoltre invia sempre dati stringa e cioè inseriti all’interno delle virgolette “esempio”. Un secondo fattore molto importante da non sottovalutare è che ogni campo del tuo modulo non deve avere convalide impostate e questo vuol dire che non deve avere controlli per appurare che il dato sia un numero o meno e non deve avere un controllo sulla lunghezza dei caratteri.