Il tutorial di oggi nasce da una richiesta di Martin: realizzare uno sketch per accedere ad un’area protetta (con username e password) di un sito web.

Basic Authentication

Il metodo di autenticazione più semplice che il protocollo HTTP supporta è chiamato basic authentication.

Se proviamo ad accedere ad un’area sicura, il server risponderà alla nostra richiesta con il codice 401, indicando al browser la necessità di specificare nome utente e password validi. Normalmente in questo caso il browser mostrerà un messaggio chiedendoci di inserire i dati richiesti:

Nome utente e password vengono quindi uniti in un’unica stringa, separati da due punti (utente:password). La stringa viene quindi codificata in base64 ed inviata al server all’interno di un header HTTP:

Authorization: Basic stringa_base64

Se ad esempio il nostro nome utente è luca e la password è MyS3cr3t, possiamo utilizzare un convertitore online per trovare la codifica base64 da inserire nell’header:

Configurazione server

E’ necessario effettuare una configurazione lato server per attivare la basic authentication su una cartella del nostro sito. La maggior parte dei server web sono configurabili tramite files .htaccess salvati all’interno della cartella stessa.

Per prima cosa, dobbiamo preparare un file contenente gli utenti (e le relative password); questo file per convenzione si chiama .htpasswd. Utilizziamo uno strumento online per codificare i dati e inseriamo la stringa ottenuta all’interno del file .htpasswd; carichiamo infine questo file all’interno della cartella da proteggere:

Prepariamo ora il file .htaccess con il seguente contenuto:

AuthType Basic
AuthName "Secure folder"
AuthUserFile /htdocs/demo/secure/.htpasswd
Require valid-user

Con AuthType indichiamo la modalità (“basic”) di autenticazione, mentre con AuthName possiamo specificare un nome per l’area protetta.

Dobbiamo quindi specificare la posizione del file .htpasswd, indicando il suo path assoluto. Per conoscere questo percorso possiamo sfruttare un semplice script php.

Infine possiamo indicare di accettare qualsiasi utente presente nel file (“valid-user”) o, in alternativa, indicare il nome degli utenti validi (Require user username).

Anche il file .htaccess va caricato nella cartella da proteggere:

Arduino

Lo sketch completo è disponibile nel repository GitHub.

Viene definita come costante la stringa (già codificata in base64) di autenticazione:

char authorization[] PROGMEM = "bHVjYTpNeVMzY3Izdb==";

La richiesta (GET) al server web contiene anche l’header Authorization:

Stash::prepare(PSTR("GET /demo/secure/ HTTP/1.1" "\r\n"
    "Host: $F" "\r\n" 
    "Authorization: Basic $F" "\r\n"
    "\r\n"), website, authorization);

Viene quindi controllato se la risposta del server contiene il valore 401 (che indica una richiesta di autenticazione, quindi il rifiuto delle credenziali) o 200 (ok):

if(strstr(reply, "HTTP/1.1 401") != 0)
  Serial.println("Authorization required :(");
else if(strstr(reply, "HTTP/1.1 200") != 0)
  Serial.println("Access granted! :)");

Infine due screenshots dello sketch in azione…

Sto sviluppando una applicazione che utilizzerà dei caratteri (fonts) particolari; è possibile evitare di installare tali caratteri nel PC dell’utente includendoli all’interno dell’applicazione e caricandoli in memoria a runtime: questo tutorial spiega come fare…

Font

Inseriamo il file del font all’interno della cartella del progetto:

Nell’esempio ho scelto il font Always Forever di Brittney Murphy.

Aggiungiamo il file al nostro progetto selezionando Add - Existing Item… e selezionando il nostro font:

Configuriamo come Build Action Embedded Resource:

Codice

Per prima cosa configuriamo il progetto abilitando il codice unsafe:

Creiamo una istanza dell’oggetto PrivateFontCollection che conterrà il font una volta caricato in memoria:

private PrivateFontCollection pfc = new PrivateFontCollection();

Leggiamo il contenuto del file e memorizziamolo nel byte array fontdata:

Stream fontStream = this.GetType().Assembly.GetManifestResourceStream("EmbeddingFontDemo.always_forever.ttf");
byte[] fontdata = new byte[fontStream.Length];
fontStream.Read(fontdata, 0, (int)fontStream.Length);
fontStream.Close();

Infine aggiungiamo il font all’oggetto PrivateFontCollection; dovendo usare i puntatori dobbiamo includere la chiamata in un blocco unsafe:

unsafe
  {
    fixed (byte* pFontData = fontdata)
    {
      pfc.AddMemoryFont((System.IntPtr)pFontData, fontdata.Length);
    }
  }

Per poter utilizzare il font all’interno di un controllo, è necessario impostare a true la proprietà del controllo UseCompatibleTextRendering:

E’ ora possibile applicare il nuovo font al controllo:

label1.Font = new Font(pfc.Families[0], 30, FontStyle.Regular);

Demo

Ho preparato un progetto che dimostra quando spiegato sopra, disponibile nel mio repository GitHub.

Le strisce di led (led strips in inglese) sono diventate molto comuni per vari utilizzi: dall’illuminazione interna ed esterna, ai giochi di luce, alle decorazioni… Oggi vi spiegherò i vari tipi di strisce disponibili e vi mostrerò un esempio pratico di controllo usando Arduino e C#.

Strisce di led

Una striscia di led è formata da un numero variabile di led (solitamente SMD) saldati su un circuito flessibile. I led possono essere di un solo colore oppure RGB, ovvero in grado di emettere tutti i colori dello spettro.

Le strisce di led possono inoltre essere waterproof, ovvero resistenti all’acqua e quindi utilizzabili anche all’esterno.

Le strisce normalmente includono anche le resistenze necessarie al funzionamento dei led; la loro tensione di alimentazione è di solito 5 o 12V.

Strisce indirizzabili (digitali)

Alcune strisce di led sono dette “indirizzabili” (addressable) o digitali: queste strisce comprendono – oltre a led e resistenze – dei chip di controllo che consentono di comandare in maniera indipendente i vari led. I chip di controllo possono essere visibili sulla striscia o, talvolta, direttamente inclusi nei led:

Molto importante distinguere le strisce in base al numero di led indipendenti: le più economiche infatti utilizzano un chip solo per comandare 3 led. Nelle schede dei produttori a volte si parla di numero di pixel: una striscia indicata da 30 led/metro e 10 pixel/metro indica proprio che ogni chip comanda 3 led e che quindi la striscia è separabile minimo ogni 3 led.

I chip di controllo più diffusi sono: WS2801, WS2811, LPD8803, HL1606… la libreria che ho scelto per Arduino li supporta tutti!

Arduino

La maggior parte delle strisce di led digitali funzionano con un semplice protocollo seriale: basta un PIN di Arduino per inviare i dati e la massa che viene collegata con la massa dell’alimentatore.

Tra le varie librerie disponibili, ho scelto di utilizzare fastspi (sito ufficiale) perché supporta molti chip di controllo, è di facile utilizzo e molto efficente nell’utilizzo delle risorse hardware di Arduino. Nella prossima pagina vi spiegherò lo sketch e la GUI in C#…

Ultra Librarian è un tool di Accelerated Designs per gestire librerie di componenti elettronici (disegni CAD, modelli per simulazioni…). Molti produttori di circuiti integrati forniscono files Ultra Librarian (.bxl) dei propri prodotti: in questo tutorial vedremo come importare tali modelli in Eagle…

Per prima cosa dobbiamo installare nel nostro PC la versione free di Ultra Librarian, scaricabile dal sito di Texas Instruments (il link è alla riga Step 1).

Prendiamo quindi un modello .bxl; per questo tutorial ho scelto il driver motori DRV8801, sempre di TI. Nella pagina relativa al prodotto, è disponibile il download del file in formato Ultra Librarian:

Lanciamo Ultra Librarian e clicchiamo Load Data, quindi selezioniamo il file scaricato:

Selezioniamo Eagle come CAD verso cui esportare il componente e clicchiamo Export to Selected Tools:

Nel log visualizzato al termine dell’esportazione, prendiamo nota del percorso in cui è stato salvato il file:

In Eagle, apriamo la nostra libreria o creiamone una nuova:

Scegliamo File - Script…:

Selezioniamo il file esportato da Ultra Librarian:

Il componente verrà creato:

A volte è necessario qualche aggiustamento… ma è veramente comodo trovare i modelli già pronti sui siti dei diversi produttori!

Inizio con questo post una serie di tutorial sul nuovo Arduino Yun per raccontare la mia esperienza con questa scheda e illustrarne le potenzialità attraverso esempi concreti… oggi vedremo come collegarlo alla nostra rete wifi!

Yun e wifi

Una delle caratteristiche più interessanti di Arduino Yun è la possibilità, senza shield esterni, di collegarlo ad una rete, sia via cavo (Ethernet) che wifi.

Ho deciso di alimentare il mio Yun tramite un alimentatore micro USB (quello dei più recenti telefoni cellulari va benissimo):

Di default, Arduino Yun funziona come access point, pubblicando una rete wifi non protetta con SSID Arduino Yun-xx:

Una volta collegati, il nostro PC prenderà un indirizzo della rete 192.168.240.0/24:

L’interfaccia di amministrazione di Arduino Yun è raggiungibile tramite browser all’indirizzo http://192.168.240.1. La password di default è arduino:

Una volta effettuato l’accesso, clicchiamo configure:

Possiamo modificare il nome della scheda (nell’esempio ho scelto Yun-Luca), cambiare la password, il timezone e collegare Yun ad una rete wireless tra quelle rilevate e visualizzate in un menu a tendina:

Dopo il riavvio, la scheda sarà collegata alla nostra rete!

Upload via wifi

Possiamo ora sfruttare una comoda caratteristica di Arduino Yun: la possibilità di effettuare l’upload di un nuovo sketch tramite rete, senza bisogno di collegare la scheda al nostro PC via USB.

Apriamo l’IDE (attenzione: dobbiamo scaricare l’ultima versione disponibile, ora 1.5.4r2) e selezioniamo come board Arduino Yun.

L’IDE effettuerà una scansione della rete e, sotto port, sarà visualizzata la scheda con il suo indirizzo IP:

Sarà quindi possibile compilare e caricare uno sketch come abbiamo imparato a fare per gli altri Arduino… al momento di effettuare l’upload ci verrà chiesta la password di Yun:

Terminale SSH

Ci possiamo collegare a Yun anche in modalità terminale, usando un client SSH (es. PuTTY per Windows)… nei prossimi post vedremo a cosa può essere utile questo collegamento:

Lavorando con Arduino Yun, è consigliato l’uso di una memoria SD esterna per ospitare i propri files: questo a causa del limitato numero di scritture della memoria interna. In questo tutorial vedremo come fare…

Per prima cosa inseriamo la nostra SD card nello slot di Arduino Yun:

Colleghiamoci ora allo Yun in SSH: se abbiamo un PC Windows, possiamo utilizzare il programma gratuito PuTTY. Inseriamo l’indirizzo IP della scheda e selezioniamo SSH come protocollo:

Inseriamo root come account e la password del nostro Yun:

Digitiamo il comando dmesg che visualizza tutti i messaggi di sistema. Se la SD card è stata correttamente riconosciuta, saranno presenti dei messaggi simili a quelli dello screenshot. Il “nome” della scheda in Linino sarà sda1:

Dobbiamo ora creare due cartelle all’interno della SD: la cartella arduino e, al suo interno, la cartella www; possiamo usare il comando mkdir. Infine creiamo un file contenente la scritta Hello World:

Smontiamo la scheda SD (umount /dev/sda1), quindi estraiamo e reinseriamo la scheda. Possiamo ora visualizzarne il contenuto tramite un browser web, all’indirizzo http://yun_ip/sd; ad esempio per visualizzare il file creato in precedenza:

Come funziona

Il webserver uHTTPd ha come document root (ovvero come cartella “principale”, dove è memorizzata l’interfaccia web di Yun) la cartella /www. Quando viene inserita una scheda SD, se questa contiene il path /arduino/www, viene creato automaticamente un link simbolico all’interno della /www:

WinSCP

Possiamo gestire i files presenti in Arduino Yun, inclusi quelli memorizzati sulla memoria SD, anche tramite una comoda interfaccia grafica. Per Windows è disponibile gratuitamente l’applicativo WinSCP. Inseriamo sempre l’indirizzo IP di Yun e selezioniamo come protocollo SCP:

Nella finestra di sinistra, sarà possibile navigare all’interno delle varie cartelle:

Il tutorial di oggi, diviso in due parti, vi spiegherà come utilizzare una webcam con il vostro Arduino Yun.

Scegliamo la webcam

La distribuzione Linux (Linino) in esecuzione su Arduino Yun è in grado di gestire le webcam supportate dal driver UVC: un elenco completo di tali webcam è disponibile sulla pagina ufficiale.

Non è invece attualmente supportato il driver Gspca; un supporto per tale driver è previsto nel prossimo futuro.

Ho scelto – dopo aver letto i test positivi di altri utenti – la webcam Microsoft LifeCam HD-3000, acquistabile per circa 20 euro:

Installiamo il software

Prima di collegare la webcam, dobbiamo installare qualche pacchetto software su Arduino Yun. L’installazione può essere fatta sia da riga di comando (collegandoci in SSH), sia da interfaccia grafica… per questo tutorial ho scelto la seconda modalità.

Colleghiamoci con un browser all’interfaccia grafica di Arduino e, dopo aver inserito la password, clicchiamo Configure; quindi advanced configuration panel:

Dal menu selezioniamo System, Software:

Premiamo il pulsante Update lists per aggiornare la lista dei software disponibili:

Cerchiamo il pacchetto kmod-video-uvc, spostiamoci nel tab Available packages e installiamolo:

Facciamo lo stesso per il pacchetto fswebcam:

Colleghiamo ora la webcam. Per essere sicuri che Linino la abbia riconosciuta, visualizziamo il log di sistema:

Le ultime righe del log dovrebbero indicare che la webcam è stata correttamente configurata:

Scattiamo una fotografia

Colleghiamoci ora via SSH ad Arduino Yun: utilizzeremo fswebcam per catturare una immagine dalla webcam e salvarla sulla SD, in modo che sia poi visibile tramite browser.

Spostiamoci sulla SD (cd /www/sd) e digitiamo il comando

fswebcam --no-banner --save photo.jpg

Con questo comando catturiamo una immagine dalla webcam e la salviamo, senza scritte aggiuntive (–no-banner) con nome photo.jpg:

Possiamo ora utilizzare un browser per visualizzare l’immagine catturata:

Nella prima parte di questo tutorial abbiamo visto come configurare la nostra webcam e come catturare immagini statiche; oggi vedremo come modificare la risoluzione e come visualizzare il video in realtime…

Immagini “rovinate”

Usando fswebcam mi è capitato a volte che l’immagine catturata sia “rovinata”:

E’ possibile risolvere questo problema con l’opzione –skip n che indica al programma di scartare le prime n immagini provenienti dalla webcam prima di catturarne una:

Risoluzione

Ogni webcam supporta un numero fisso di possibili risoluzioni (= il numero di pixel che compongono l’immagine).

Possiamo conoscere le risoluzioni supportate dalla nostra webcam con alcuni comandi Linux:

• otteniamo l’identificativo numerico (VID e PID) della webcam con lsusb:

• ora possiamo visualizzare i dettagli di tale device con lsusb -d 045e:0779 -v (cambiate l’ID con il vostro). Ogni sezione VideoStreaming Interface Descriptor riporta una risoluzione supportata:

• Con un semplice grep possiamo estrarre il solo elenco di risoluzioni:

fswebcam supporta l’opzione -r per specificare la risoluzione dell’immagine (widthxheight):

Ecco il risultato:

Nella prossima pagina vedremo come visualizzare video in realtime…

Il microcontrollore ATmega32u4 utilizzato su Arduino Yun ha una porta seriale (PIN 0 e 1) internamente connessa al chip AR9331 che esegue la distribuzione Linux Linino:

Come in Arduino Leonardo, anche Arduino Yun emula la porta seriale tramite USB (connettore micro USB). A volte però può essere necessario disporre di una porta seriale fisica, ad esempio per collegarsi a devices che non sono in grado di supportarne una virtuale (console di apparati di rete…).

Yun mette a disposizione una porta USB host, alla quale è possibile collegare periferiche USB quali tastiere, webcam… e anche un adattatore USB->seriale:

Scegliamo un adattatore che utilizzi un chip della FTDI, ad esempio il famoso FT232R:

Colleghiamoci in SSH al nostro Yun e installiamo il modulo kernel relativo:

opkg install kmod-usb-serial-ftdi

Se ora colleghiamo l’adattatore e visualizziamo i messaggi di sistema (comando dmesg) vedremo che questo sarà correttamente riconosciuto e il nome della nuova porta seriale (nello screenshot ttyUSB0):

Se avete visto qualche mio progetto (dashboard, grafici web…), sicuramente avrete notato come prediligo l’uso del linguaggio PHP quando si tratta di programmare pagine/siti dinamici. Possiamo utilizzare PHP anche con il nostro Yun, ecco come fare…

Per prima cosa dobbiamo installare i pacchetti software. Ho scelto di installare la versione 5, includendo il modulo CLI, che consente di lanciare script PHP dalla riga di comando (vedremo che sarà utile quando impareremo a lanciare comandi tramite Bridge!):

Modifichiamo ora il file di configurazione (/etc/config/uhttpd) del webserver, decommentando (= togliendo il simbolo # ad inizio riga) l’uso dell’interprete php:

Riavviamo il webserver:

Per verificare che tutto funzioni, prepariamo una pagina con il comando phpinfo().

Spostiamoci sulla SD (cd /www/sd) e creiamo la pagina:

Apriamo ora il browser e controlliamo che la pagina venga correttamente interpretata:

Dopo qualche mese di assenza, riprendo questa serie di tutorial per qualche nuovo progetto… oggi però vi voglio parlare di una libreria un po’ particolare…

Tutti gli esempi che vi ho mostrato si basano sulla libreria Ethercard di JeeLabs - nel primo post vi ho anche spiegato come installarla all’interno dell’IDE.

Questa libreria ha dato prova di essere molto ben realizzata, stabile e supportata dagli sviluppatori.

Ho trovato una diversa libreria, sempre per il controller enc28j60, chiamata UIPEthernet (pagina ufficiale su Github). Questa libreria ha il grosso vantaggio di essere compatibile con gli sketch scritti per la libreria ufficiale.

L’unica modifica necessaria è modificare tutti gli include, sostituendo Ethernet.h con UIPEthernet.h.

Come esempio, carichiamo lo sketch WebServer ed effettuiamo la modifica sopra descritta:

Con questa piccola modifica, lo sketch ora viene correttamente compilato e funziona con il nostro shield:

Nell’utilizzarla, dobbiamo però tenere conto delle differenze hardware tra i due controller (W5100 e enc28j60), ricordando in particolare che il secondo utilizza delle risorse del chip ATMega e che quindi ha sicuramente dei limiti maggiori.

In particolare ho riscontrato che alcuni sketch non funzionano (Arduino continua a resettarsi) perché viene saturata la memoria RAM del microcontrollore… è il caso ad esempio della libreria per collegarsi a database MySQL.

Dopo aver introdotto, in un precedente articolo, le strisce di led e avervi illustrato come controllare una striscia digitale, vediamo oggi un semplice progetto che nasce da una richiesta di un amico: far lampeggiare una striscia di led ad una frequenza variabile.

Cosa mi serve

Vista la semplicità del progetto, ho deciso di realizzarlo su una breadboard, usando i seguenti componenti:

• un Arduino Mini Pro
• un potenziometro da 4.7Kohm
• un transistor MOSFET STP16NF06 (datasheet)
• una striscia di led a 12V e il relativo alimentatore

Collegamenti

I vari elementi del progetto vanno collegati secondo questo schema:

Arduino

Lo sketch Arduino è disponibile nel mio repository su Github.

Vediamo il suo funzionamento:

#define ledPin        13
#define stripPin      2
#define analogInPin   A0

Per prima cosa definiamo alcune costanti: i PIN a cui sono collegati il led (on board), la striscia di led e il potenziometro (usiamo un PIN analogico per leggere il suo valore).

int outState = LOW;
long previousMillis = 0;
long interval = 1000;

Quindi inizializziamo le variabili che mantengono lo stato dell’uscita, il tempo trascorso e la frequenza di lampeggio (inizialmente di 1 secondo).

pinMode(ledPin, OUTPUT);
pinMode(stripPin, OUTPUT);

All’interno del setup(), configuriamo come OUTPUT i PIN a cui sono collegati led e striscia.

int potValue = analogRead(analogInPin);
interval = map(potValue, 0, 1023, 50, 2000);

Nel loop principale leggiamo il valore del potenziometro (tra 0 e 1023) e scaliamo tale valore, attraverso la funzione map, nell’intervallo 50-2000. Questo consente di regolare il periodo di lampeggio tra 50 e 2000ms.

if(currentMillis - previousMillis > interval) {

Se è trascorso un intervallo di tempo…

if (outState == LOW) outState = HIGH;
else outState = LOW;

… invertiamo lo stato dell’uscita…

digitalWrite(ledPin, outState);
digitalWrite(stripPin, outState);

… e accendiamo/spegnamo led e striscia.

Demo

Breve filmato che illustra il funzionamento dello sketch:

In alcuni tutorial precedenti, avete già imparato a realizzare semplici pagine web per comandare a distanza led, relay… oggi vi mostrerò come rendere queste pagine sicure grazie ad una password.

Form web

La pagina web pubblicata da Arduino contiene una semplice form, composta da due pulsanti e da un campo di input per la password:

Alla pressione del pulsante, viene inviato ad Arduino un comando POST contenente – oltre ad informazioni del browser – i dati della form:

Dallo screenshot si può notare come i dati siano concatenati dal carattere & e il valore del campo password sia specificato dopo l’etichetta pwd=.

Sketch

Il codice in esecuzione su Arduino (lo trovate nel repository Github), alla ricezione di una nuova richiesta, esegue le seguenti operazioni:

• verifica se la richiesta è di tipo POST
• in questo caso, estrae dalla richiesta il valore della password e la confronta con quella memorizzata
• se la password è corretta, estrae dalla richiesta il pulsante (ON|OFF) premuto
• modifica lo stato dell’uscita
• restituisce la pagina HTML

Vediamolo nel dettaglio:

char* led_password = "SesamE";

la password è inserita hardcoded nello sketch, di default sarà SesamE

pinMode(led_pin, OUTPUT);
digitalWrite(led_pin, LOW);
led_status = false;

all’interno del setup() avviene l’inizializzazione del PIN e dello stato dell’uscita (di default spenta)

if(strstr((char *)Ethernet::buffer + pos, "POST /") != 0) {

lo sketch verifica – tramite la funzione strstr() – se il pacchetto ricevuto contiene il comando POST /

char* password_position = strstr((char *)Ethernet::buffer + pos, "&pwd=");
if(password_position != 0) {
  strcpy(password, password_position + 5);
  if(strcmp(password, led_password) == 0) Serial.println("Valid password :)");

lo sketch cerca la stringa &pwd= nel pacchetto; se la trova estrae la password e la memorizza nella variabile password. Le due password sono quindi confrontate

if(strstr((char *)Ethernet::buffer + pos, "OFF=") != 0) {
digitalWrite(led_pin, LOW);
led_status = false;

se la password è corretta e il pacchetto contiene il comando OFF=, l’uscita viene spenta. Lo stesso controllo avviene per il comando ON=

if(led_status == true) bfill.emit_p(PSTR(
[...]

infine viene generata la pagina HTML, resa dinamica da due if:

• in base allo stato dell’uscita, uno dei due pulsanti viene disabilitato (aggiungendo l’attributo disabled)
• se la password non è corretta, viene visualizzato un messaggio di errore

Funzionamento

Ecco due screenshot relativi all’inserimento di una password valida e una sbagliata:

Come ormai sapete, Arduino Yun esegue una distribuzione Linux chiamata Linino. A volte può essere necessario eseguire un factory reset di tale distribuzione, ovvero tornare all’immagine base di una scheda appena acquistata.

Procedura

Scarichiamo l’immagine di Linino dal sito web di Arduino:

L’immagine è in formato ZIP, estraiamo il contenuto (un file binario .BIN) sul disco fisso del nostro computer:

Copiamo il file .BIN nella root di una scheda SD, quindi inseriamo la scheda nel nostro Yun.

Accediamo al pannello web di Arduino e inseriamo la password (quella di default è arduino). Scorrendo la pagina principale, ci verrà indicato che l’immagine è stata rilevata e che è possibile operare un reset:

Confermiamo quindi di voler procedere al reset:

Il LED WLAN di Yun (colore blu) lampeggerà durante il processo…

Al termine, la nostra scheda Yun sarà come appena tolta dalla scatola!

Un progetto a cui sto lavorando prevede il controllo tramite Android; ho quindi pensato che fosse l’occasione giusta per scrivere un tutorial su come utilizzare la connettività bluetooth in applicazioni Android…

Prerequisiti

Questo tutorial prevede che abbiate una minima conoscenza di come sviluppare una applicazione Android: in rete si possono trovare delle ottime guide, iniziando da quella ufficiale di Google. Potete scegliere l’IDE che più preferite: personalmente mi trovo bene con Eclipse + ADT plugin.

Sorgenti

Tutte le applicazioni di esempio verranno pubblicate in un repository su Github.

Application permissions

Perché la nostra applicazione possa utilizzare la connettività bluetooth del telefono, è necessario dichiarare di utilizzare tale funzionalità. Avrete infatti notato che quando si installa una nuova applicazione, Android chiede se si accetta di concedere a tale applicazione i permessi necessari al suo funzionamento.

Apriamo il file AndroidManifest.xml

Spostiamoci sul tab Permissions, quindi clicchiamo Add…

Selezioniamo Uses Permission

Infine selezioniamo android.permission.BLUETOOTH e salviamo il file

BluetoothAdapter

L’oggetto che consente di interfacciarsi con il modulo bluetooth del telefono è BluetoothAdapter.

Possiamo ottenere l’instanza di default tramite il metodo statico getDefaultAdapter():

mBluetoothAdapter = BluetoothAdapter.getDefaultAdapter();

Se il telefono non ha il modulo bluetooth, il metodo restituisce null; in questo caso possiamo visualizzare un messaggio di errore (Toast) e chiudere l’applicazione:

Toast.makeText(this, "This app requires a bluetooth capable phone", Toast.LENGTH_SHORT).show();
finish();

Dobbiamo quindi verificare che il modulo bluetooth sia abilitato, tramite il metodo isEnabled():

mBluetoothAdapter.isEnabled()

In caso non sia abilitato, possiamo richiederne l’abilitazione tramite una Intent. Definiamo una costante per identificare la nostra richiesta; quindi creiamo una Intent e sottomettiamola al sistema Android:

private final int REQUEST_ENABLE_BT = 1;
[...]
Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT);

La nostra applicazione viene messa in secondo piano e all’utente appare un popup con la richiesta di abilitare il bluetooth:

Una volta che l’utente ha confermato (o negato) la richiesta di attivazione, viene chiamato il metodo onActivityResult, dove possiamo verificare se la richiesta ha avuto o meno esito positivo:

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
 if(requestCode == REQUEST_ENABLE_BT)
 if(resultCode == RESULT_OK) listPairedDevices();

Paired devices

In questo primo esempio, andremo ad elencare i dispositivi già accoppiati (paired) al telefono. Un dispositivo bluetooth deve essere infatti accoppiato (eventualmente inserendo una password numerica) prima di poter stabilire la connessione.

Il metodo getBondedDevices() restituisce un Set di oggetti di tipo BluetoothDevice:

Set pairedDevices = mBluetoothAdapter.getBondedDevices();

Ogni dispositivo bluetooth ha un nome e un indirizzo (univoco); possiamo visualizzare in una TextArea i dati dei dispositivi accoppiati con un loop:

for(BluetoothDevice pairedDevice : pairedDevices) {
 textView2.append(Html.fromHtml("<strong>" + pairedDevice.getName() + "</strong>"));
 textView2.append(" (" + pairedDevice.getAddress() + ")\n");
}

Ecco l’applicazione in esecuzione:

Next

Nella prossima parte di questo tutorial vedremo come effettuare lo scan e il pairing di nuovi dispositivi…

Nel precedente tutorial, ho introdotto gli oggetti principali per interagire con il modulo bluetooth di uno smartphone Android e vi ho mostrato come elencare i dispositivi associati al telefono. Oggi vedremo invece come chiedere ad Android di cercare nuovi dispositivi…

Discovery e permessi

Per poter utilizzare la funzionalità di discovery di nuovi dispositivi bluetooth, è necessario dichiarare un nuovo permesso per la nostra app: BLUETOOTH_ADMIN

Per eseguire una nuova discovery è sufficiente invocare il metodo startDiscovery dell’oggetto BluetoothAdapter:

mBluetoothAdapter.startDiscovery();

Questo metodo è asincrono: sottomette la richiesta di iniziare una nuova scansione al S.O. Android e ritorna. Perché la nostra app sia informata di quando un dispositivo viene rilevato e di quando il processo di discovery termina, è necessario utilizzare i BroadcastReceiver.

Receivers e Intent filters

Una app può chiedere ad Android di essere informata di particolari eventi; ad esempio della ricezione di un SMS o del fatto che la carica della batteria sia in esaurimento. Questo tipo di eventi sono notificati alle app tramite dei messaggi broadcast: le app possono ricevere i messaggi creando degli oggetti di tipo BroadcastReceiver.

Una volta creato l’oggetto, è necessario indicare ad Android di quali eventi l’app deve essere informata. Per ogni evento è necessario creare il relativo filtro (IntentFilter); infine tramite il metodo registerReceiver() è possibile chiedere al SO di chiamare, per l’evento indicato nell’IntentFilter, il BroadcastReceiver specificato:

Nel nostro caso, dobbiamo ricevere due eventi:

• BluetoothDevice.ACTION_FOUND quando un nuovo dispositivo è rilevato
• BluetoothAdapter.ACTION_DISCOVERY_FINISHED quando il processo di discovery termina

Creiamo i relativi IntentFilter e registriamo il Receiver:

IntentFilter deviceFoundFilter = new IntentFilter(BluetoothDevice.ACTION_FOUND);
IntentFilter discoveryFinishedfilter = new IntentFilter(BluetoothAdapter.ACTION_DISCOVERY_FINISHED);
registerReceiver(mReceiver, deviceFoundFilter);
registerReceiver(mReceiver, discoveryFinishedfilter);

Il BroadcastReceiver deve implementare il metodo onReceive(), chiamato da Android per notificare l’evento:

mReceiver = new BroadcastReceiver() {
  public void onReceive(Context context, Intent intent) {
    String action = intent.getAction();

La stringa action consente di identificare l’evento che viene notificato e agire di conseguenza:

if (BluetoothDevice.ACTION_FOUND.equals(action)) {
  // visualizzo il nuovo dispositivo
}
if (BluetoothAdapter.ACTION_DISCOVERY_FINISHED.equals(action)) {
  // abilito nuovamente il pulsante che attiva la scansione
}

App

Anche l’app di questo esempio è molto semplice: attiva la scansione e visualizza l’elenco dei dispositivi trovati.

I suoi sorgenti sono disponibili su Github.

Riprendiamo il corso relativo alla programmazione di app Android con funzionalità Bluetooth per un piccolo tutorial che spiega come rilevare il cambio di stato del modulo Bluetooth.

Android è un sistema operativo multitasking: mentre la nostra applicazione è in esecuzione, è possibile che l’utente o un’altra applicazione cambino lo stato del modulo Bluetooth, ad esempio disattivandolo.

Nel primo tutorial abbiamo già visto come chiedere ad Android di attivare le funzionalità Bluetooth; in maniera simile possiamo chiedere sempre ad Android di notificare alla nostra app ogni cambio di stato.

Per prima cosa creiamo un BroadcastReceiver che riceverà i messaggi dal S.O.

mReceiver = new BroadcastReceiver() {

all’interno del metodo onReceive() del nostro Receiver verifichiamo se il messaggio ricevuto è relativo al cambio di stato del modulo Bluetooth:

public void onReceive(Context context, Intent intent) {
  String action = intent.getAction();
  if (BluetoothAdapter.ACTION_STATE_CHANGED.equals(action)) {

otteniamo quindi lo stato attuale dagli extra parameters dell’Intent. Lo stato è un valore di tipo int, utilizziamo quindi il metodo getIntExtra, indicando il nome del parametro da ottenere e specificando un valore di default, che ci verrà restituito se non viene trovato un parametro con il nome specificato:

int actualState = intent.getIntExtra(BluetoothAdapter.EXTRA_STATE, 
 BluetoothAdapter.STATE_OFF);

infine registriamo il nostro Receiver come abbiamo già imparato:

IntentFilter stateChangedfilter = 
 new IntentFilter(BluetoothAdapter.ACTION_STATE_CHANGED);
registerReceiver(mReceiver, stateChangedfilter);

Il modulo Bluetooth può avere quattro diversi stati:

• BluetoothAdapter.STATE_ON
• BluetoothAdapter.STATE_OFF
• BluetoothAdapter.STATE_TURNING_ON
• BluetoothAdapter.STATE_TURNING_OFF

Ho preparato una app di esempio che visualizza in maniera grafica lo stato attuale, aggiornandosi automaticamente se questo cambia:

I sorgenti della app sono come sempre disponibili su Github!

Nel tutorial di oggi, finalmente vedremo come effettuare un collegamento con un dispositivo Bluetooth e inviare dei dati…

Profili e UUID

Lo standard Bluetooth definisce una serie di profili, ovvero di funzionalità che i dispositivi Bluetooth offrono.

Per semplificare, i profili Bluetooth corrispondono a “cosa” un dispositivo può fare; ad esempio, un auricolare Bluetooth implementerà sicuramente il profilo HSP (Headset Service Profile) che specifica come ricevere/trasmettere audio e come inviare semplici comandi (“rispondi”, “alza il volume…”) al telefono associato. Alcuni auricolari più avanzati implementano anche il profilo A2DP (Advanced Audio Distribution Profile), consentendo all’utente anche di ascoltare musica trasmessa dal telefono.

Nello stabilire una connessione tra due dispositivi, il dispositivo che inizia la connessione può utilizzare il protocollo SDP (Service Discovery Protocol) per scoprire quali servizi sono offerti dall’altro, ovvero quali profili questo implementa.

Ogni servizio è definito da un identificativo numerico (UUID) da 128 bit. Normalmente si utilizza una versione corta (short form) di tale identificativo:

• si parte da un UUID base di 128 bit, 0×00000000-0000-1000-8000-00805F9B34FB
• si inserisce la versione corta dell’UUID al posto dei primi 8 zeri
• si ottiene quindi l’UUID completo del servizio

Ad esempio il servizio HSP ha UUID breve 0×1108, quindi il suo UUID completo sarà

0×00001108-0000-1000-8000-00805F9B34FB

SPP

Il profilo più semplice e più utilizzato per comunicare con dispositivi embedded è sicuramente il Serial Port Profile (SPP), che ha UUID breve 0×1101.

Questo profilo emula tra i due dispositivi una connessione seriale:

Android

Negli scorsi tutorial abbiamo visto come ottenere l’elenco dei dispositivi associati al nostro smartphone.

Ogni dispositivo è una istanza dell’oggetto BluetoothDevice; tale oggetto mette a disposizione due metodi per aprire un canale di comunicazione:

• createRfcommSocketToServiceRecord(UUID)
• createInsecureRfcommSocketToServiceRecord(UUID)

Entrambi i metodi accettano l’UUID del profilo da utilizzare e si distinguono solo perché il primo cerca di effettuare una connessione cifrata. I più comuni moduli Bluetooth che si usano nei sistemi embedded non supportano tale modalità, quindi sarà necessario usare il secondo.

Se la connessione va a buon fine, i metodi restituiscono un oggetto di tipo BluetoothSocket che rappresenta il canale di comunicazione tra lo smartphone e il dispositivo associato; in caso di errore invece viene sollevata una eccezione.

Vediamo come inviare dati ad un dispositivo che implementa il profilo SSP.

Per prima cosa definiamo l’UUID del profilo:

UUID SPP_UUID = java.util.UUID.fromString("00001101-0000-1000-8000-00805F9B34FB");

Quindi otteniamo il canale di comunicazione con il dispositivo:

BluetoothSocket btSocket = null;	
try {
  btSocket = targetDevice.createInsecureRfcommSocketToServiceRecord(SPP_UUID);
} catch (IOException e) {
  Toast.makeText(this, "Unable to open a serial socket with the device", 
    Toast.LENGTH_SHORT).show();
}

Il canale non è ancora aperto, dobbiamo utilizzare il metodo connect() per collegarci al dispositivo:

try {
  btSocket.connect();
} catch (IOException e) {
  Toast.makeText(this, "Unable to connect to the device", 
    Toast.LENGTH_SHORT).show();
}

Una volta connessi, l’oggetto BluetoothSocket mette a disposizione due Stream, uno per inviare (OutputStream) e uno per ricevere (InputStream) dati. Per comodità, possiamo utilizzare un oggetto OutputStreamWriter che rende più facile inviare sequenze di caratteri attraverso uno stream:

try {
  OutputStreamWriter writer = new OutputStreamWriter(btSocket.getOutputStream());
  writer.write("Hello World!\r\n");
  writer.flush();
} catch (IOException e) {
  Toast.makeText(this, "Unable to send message to the device", 
    Toast.LENGTH_SHORT).show();
}

Il nostro writer mantiene un buffer locale: per essere sicuri che i dati vengano effettivamente inviati, ricordatevi sempre di effettuare il flush().

Al termine della connessione, il socket deve essere chiuso:

try {
  btSocket.close();
} catch (IOException e) {
  Toast.makeText(this, "Unable to close the connection to the device", 
    Toast.LENGTH_SHORT).show();
}

Nella prossima pagina, vi mostrerò una app che implementa quando spiegato sopra…

Se avete provato l’app presentata nel tutorial precedente, forse vi sarete accorti di un difetto: mentre viene stabilita la connessione Bluetooth con il dispositivo e viene inviato il messaggio, l’interfaccia grafica dell’applicazione non risponde. Il motivo è semplice: molti metodi utilizzati sono blocking, ovvero fermano l’esecuzione del processo che li chiama finché non ottengono un risultato (o un timeout).

Se ad esempio utilizziamo il metodo read() per leggere dati da un socket, tale metodo fermerà l’esecuzione del processo finché un dato non è disponibile!

Per risolvere il problema, dobbiamo creare una applicazione multitasking, ovvero formata da più processi con esecuzione indipendente.

Threads e GUI

Per semplificare, una applicazione può essere formata da uno o più processi (thread), eseguiti dal S.O. Android in parallelo. Le applicazioni più semplici, come quelle degli esempi precedenti, hanno un unico thread, chiamato main thread. Questo thread ha, tra gli altri, il compito di gestire i componenti (testo, immagini, pulsanti…) che compongono l’interfaccia (GUI) dell’applicazione.

La prima regola da tenere sempre in mente quando si lavora ad applicazioni multithread è infatti che solo il main thread può modificare l’intefaccia grafica:

Questa regola da spesso problemi ai programmatori: pensate al caso in cui un secondo thread riceve dati dal socket Bluetooth: probabilmente alla ricezione di determinati comandi, l’interfaccia grafica deve essere aggiornata di conseguenza…

La soluzione normalmente suggerita è di chiedere al thread principale di effettuare tale aggiornamento… io invece voglio mostrarvi un approccio alternativo, che si basa sull’uso dell’oggetto AsyncTask.

AsyncTask

L’oggetto AsyncTask è stato pensato per gestire in maniera semplice dei tasks che devono eseguiti in background e che devono interagire con l’intefaccia grafica dell’applicazione.

Il suo vantaggio è che, in maniera trasparente per il programmatore, ha alcuni metodi che vengono eseguiti nel GUI (main) thread e altri che invece vengono eseguiti in un thread separato.

Il programmatore può quindi sfruttare i metodi eseguiti nel GUI thread per aggiornare l’interfaccia e quelli nel secondo thread per le operazioni in background (ad es. per ricevere/inviare dati attraverso il socket):

Vediamo i metodi nel dettaglio:

• onPreExecute() – GUI – eseguito appena prima dell’inizio delle attività in background, può essere utile per visualizzare un avviso (animazione, messaggio…) che l’operazione richiesta è in esecuzione
• doInBackground() – background – metodo principale che viene eseguito in un thread separato
• publishProgress() – background – metodo, normalmente chiamato da doInBackground(), che serve per notificare un “progresso” nell’esecuzione del task
• onProgressUpdate() – GUI – metodo, chiamato da publishProgress(), che può aggiornare l’intefaccia grafica ricevendo il “progresso” del task in background
• onPostExecute() e onCancelled() – GUI – metodi eseguiti alla fine del task (o alla sua cancellazione)

Nella prossima pagina vedremo come mettere tutto questo in pratica in una applicazione Android…

Grazie a Jun Chun, il mio tutorial relativo allo sviluppo di applicazioni Android con funzionalità Bluetooth è stato tradotto in coreano.

I cinque articoli sono disponibili in due post sul sito di Jon, ArsViator:

http://arsviator.blogspot.kr/2014/06/bluetooth-programming-in-android-12.html
http://arsviator.blogspot.kr/2014/06/bluetooth-programming-in-android-22.html