FCGF 0.0.4 è qui!
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
- Compatibilità con Arduino Uno Wi-Fi Rev.2
- Connessione al server Google migliorata.
- Risolto un problema che impediva la connessione al server se veniva impostato un valore superiore a 0 nelle impostazioni di delay del submit.
- Risolti alcuni problemi minori.
- Compatibilità con Arduino MKR GSM 1400.
- Compatibilità con Arduino Nano 33 IoT.
- Aggiunta funzione di delay nel submit che non blocca il programma.
- Aggiunto contatore interno per conteggiare gli invii e le connessioni corrette e/o fallite.
- Aggiunta funzione che converte i punti in virgole per adattare il separatore decimale alle impostazioni internazioni italiane.
- Risolto un problema che impediva l’invio di valori contenenti i caratteri speciali ( | ! “£ $% & / () =? ^ * + [] {} -_;:,. <>)
- 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 Wi-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 paragonabile 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 timer 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"
Uso :
void setup() { FCGF_DEBUG = true/false; }
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.
Il tuo modulo creato su Google Moduli è vuoto, non esiste (controlla che gli url siano corretti) e/o non ha campi compatibili.
I campi compatibili sono di tipo “Risposta Breve” e/o “Paragrafo”.
FAQ
FCGF è un progetto opensource e consiste in una libreria (quindi un gruppo di funzioni dedicate per un singolo scopo) che implementata in Arduino IDE permette di integrare i moduli di Google all’interno dei tuoi progetti IoT e allo stesso tempo di farlo in modo semplice e veloce. La libreria sfrutta una caratteristica dei moduli Google, la quale permette di inviare richieste HTTP al modulo e inserire i dati inseriti nei vari campi senza avere il modulo effettivamente visibile ed editabile. Grazie a questa libreria potrai effettuare raccolta di dati per uso statistico in modo automatizzato utilizzando i più comuni micro controllori in commercio che permettono la connettività Wi-Fi e GSM. Questa libreria è adatta ai professionisti e agli hobbisti che hanno la necessità di automatizzare la raccolta di dati in un unico posto, successivamente il tuo modulo Google può essere convertito in un foglio di calcolo e avere tutte le potenzialità che un foglio di calcolo offre (media, grafici, calcoli complessi e cosi via).
Si, Google Moduli è gratuito. Google Moduli fa parte della stessa suite office al quale fa parte anche Google Fogli, puoi accedere al servizio da qui per creare il tuo modulo di Google : https://docs.google.com/forms/. L’operazione di creazione di un modulo di Google è semplicissima e ti richiederà pochi minuti di configurazione.
No, la libreria funziona tramite richieste HTTP di tipo POST consentite da Google, queste richieste verranno ricevute dal tuo modulo ed elaborate in automatico.
La libreria è stata sviluppata per essere integrata nell’IDE di Arduino e funziona perfettamente su tutti i micro controllori con base ESP8266 e ESP32, oltre a questi è compatibile anche con Arduino UNO Wi-Fi Rev.2, Arduino MKR 1010, Arduino Nano 33 Iot e può funzionare in modalità GSM con Arduino MKR GSM 1400.
I dati che possono essere inviati sono di tipo stringa e numerici, il tuo modulo deve essere configurato in modo tale che nessun campo abbia una convalida o in caso sia necessaria una convalida devi accertarti che tu la possa soddisfarla al momento dell’invio dei dati dalla tua board. Le tipologie di campo compatibili e che il ToolKit riesce a processare in fase di generazione dello sketch sono “Risposta breve” o “Paragrafo”.
Certamente, in fase di generazione dello sketch dal ToolKit utilizza la procedura con il dummyBegin per creare un “begin stupido” che non gestisce l’avvio del Wi-Fi, ma sfrutta il client Wi-Fi di Blynk.
Il ToolKit Online è uno strumento indispensabile per la generazione dello sketch, poichè con gli ultimi aggiornamenti Google è stata diventata difficoltosa la ricerca dei campi con un’analisi manuale del codice HTML del tuo modulo. Il ToolKit va ad analizzare in una frazione di secondo il tuo modulo pubblico ed elabora un codice compatibile con la libreria da poter caricare sulla tua board, implementando in pochissimo tempo i moduli di Google nel tuo progetto IoT.
ASSOLUTAMENTE NO! Il ToolKit effettua tutte le operazioni per l’utente a lato client, noi non abbiamo accesso alle informazioni che inserisci nei campi ma non ci riteniamo minimamente responsabili nel caso in cui, utenti terzi con una cerca esperienza nel settore, possano intercettare il vostro processo di generazione dello Sketch. In ogni caso i dati come il nome della tua connessione GSM/Wi-Fi ed eventuale password/PIN di quest’ultime, sono dati inseribili manualmente nel codice e non necessariamente devono essere inseriti nel ToolKit. Infine, tutte le operazioni che esegue il ToolKit dai nostri server ai server di Google sono protette da un certificato SSL e viaggiano su protocollo HTTPS.
In informatica nulla è veramente al sicuro, tuttavia i dati vengono inviati tramite richieste HTTP (consentite da Google) e cifrate tramite certificato SSL. In ogni caso, come specificato nei punti precedenti, non ci riteniamo responsabili di un uso inappropriato e malevolo che potrebbero intraprendere utenti terzi sfruttando le debolezze della trasmissione dati, ove siano presenti.
Si è possibile. Come succede normalmente con i moduli Google pubblici, possiamo chiedere a più utenti di accedere al nostro modulo Google e rispondere ai campi disponibili, allo stesso modo possiamo programmare più board in modo che inviino più dati (magari di differente natura) ad un singolo modulo, favorendo cosi la centralizzazione dei dati. Questa caratteristica permette effettuare statistiche territoriali dettagliate e funzionanti in pochi e semplici passi.
La libreria è a codice sorgente aperto, quindi puoi modificare la libreria purché tu non vada a cancellare i riferimenti del creatore e dei contribuitori del progetto, puoi aggiungere il tuo nome ai contribuitori, modificare la libreria in base alle tue esigenze e al momento della ridistribuzione del progetto dovrai seguire le stesse linee guida del progetto originale :
1. Devi rilasciare modifiche e derivate in licenza opensource.
2. Non puoi vendere il tuo progetto senza aver acquistato una licenza commerciale della libreria.
3. Non devi cancellare il nome dell’autore originale della libreria.
4. Cita sempre la fonte al momento della condivisione della tua realizzazione.
DEVI CHIEDERE AIUTO SE NE HAI BISOGNO. Questo progetto è strutturato in modo tale che sia portato avanti anche dalla community di Filo Connesso, l’aiuto può arrivare in modo diretto grazie agli appassionati e agli sviluppatori che offrono un po del loro tempo per sviluppare correzioni e funzionalità nuove di FCGF o può arrivare anche da chi chiede aiuto, grazie alle richieste di aiuto e ai feedback noi riusciamo a scovare nuovi problemi e a correggerli. Per ogni domanda può fare riferimento al gruppo pubblico su Telegram “Bar Filo Connesso” : https://t.me/filoconnessogroup
Puoi scaricare la libreria da questa pagina o nel nostro profilo GitHub : https://github.com/filoconnesso/FCGF.
Puoi installare la libreria scaricando il file .zip da questa pagina o dal nostro profilo di GitHub e aggiungerla all’IDE di Arduino dal menu Sketch->include Libreria->Aggiungi da file .ZIP.
Dalla versione Alpha 0.0.3 tutte le volte che la board esegue il begin della libreria nel monitor seriale verrà visualizzato un messaggio di benvenuto con la versione corrente della libreria installata nell’IDE di Arduino.
Supporta il progetto
Lavoriamo molto per offrirti degli strumenti gratuiti e super semplici da usare per agevolarti nella realizzazione dei tuoi progetti, puoi dare una mano al nostro lavoro supportando il progetto come indicato nella pagina di sostegno di Filo Connesso.
Licenza
Questa libreria è rilasciata in licenza d’uso opensource GNU v3.0, qui i dettagli : https://github.com/filoconnesso/FCGF/blob/main/LICENSE
Crediti e ringraziamenti
Questa libreria è stata realizzata con la pazienza e il supporto speciale di Ubi De Feo, Manuel Penna, Edoardo Sassi e Mirko Pacioni.