SCOPI DEL PROGETTO:
CONCETTI AFFRONTATI:
|
COMPONENTI SOFTWARE UTILIZZATE:
COMPONENTI FISICI UTILIZZATI:
|
PROGETTO INDICATO a UTENTI CON ISTALLAZIONE: |
|
NOTE E DISCLAIMER
|
|
| Revisione progetto: 1.2 | |
Abstract
Introdurre la biometria nella propria domotica personale può essere uno strumento estremamente semplice e al contempo potente per gestire un numero enorme di scenari e funzionalità.
Nello specifico, in questo progetto vedremo come configurare in proprio un lettore di impronte digitali (in grado inoltre di distinguere da persona a persona) così da integrarlo all’interno della propria domotica basata su Home Assistant. Tale integrazione consentirà all’utente di dotarsi di strumenti utili per attivare automazioni, scenari, cambiare stati ad altre entità e ancora molto altro.
Per esempio, il lettore che andremo a realizzare consentirà di autenticare una o più persone e, per esempio, armare o disarmare un sistema d’allarme integrato su Home Assistant (vedi focus sulle varie modalità), oppure attivare delle automazioni e/o degli script, e molto altro ancora.
Questo progetto guiderà l’utente dall’assemblaggio delle necessarie componenti hardware, alla configurazione del firmware necessario e, infine, all’integrazione e l’uso su Home Assistant
Si parte
- Assunti
- Spiegazione del progetto per punti
- Scelta del lettore d’impronte
- Configurare il firmware ESPHome
- Installazione su NodeMCU
- Assemblare l’hardware
- Integrazione con Home Assistant
- Uso
Assunti
Si assume, per la realizzazione del presente progetto, di possedere un NodeMCU oppure un NodeMCU basato su ESP32 (si consiglia di valutare anche questo modello, particolarmente prestante dal punto di visto ricezione Bluetooth, un domani lo si volesse usare anche come BRIDGE/Gateway Bluetooth) e di avere a disposizione la suite di tool relativa al firmware ESPHome (installata in una delle modalità previste).
Si assume inoltre di avere a disposizione un cavo USB/Micro-USB per collegare il NodeMCU da riprogrammare al computer ospitante i tool ESPHome (a meno che il NodeMCU non ospiti già ESPHome a bordo – in tal caso non serve, in quanto la riprogrammazione avverrà in modalità OTA via Wi-Fi).
Infine, si dà ovviamente per scontato di avere già a disposizione una propria istanza di Home Assistant in una qualsiasi delle modalità operative.
Spiegazione del progetto per punti
Il progetto sostanzialmente prevede, in ordine, di:
- scegliere un lettore d’impronte;
- configurare il firmware ESPHome;
- installare il firmware su NodeMCU;
- assemblare assieme il NodeMCU e il lettore d’impronte;
- integrare il tutto con Home Assistant.
I passi verranno descritti sequenzialmente e nel dettaglio, quindi si consiglia di leggere con attenzione tutta la sequenza.
Scelta del lettore d’impronte
Prima cosa da fare è scegliere un lettore d’impronte digitali in modo che, ovviamente, esso sia compatibile con l’uso fisico con NodeMCU e con quello logico tramite il firmware ESPHome.
Noi abbiamo testato con successo questi due modelli:
R307/ZFM-20 Optical Fingerprint Reader
R503 Capacitive Fingerprint Reader con LED circolare
Abbiamo prediletto il secondo, l’R503, in quanto è installabile a vite in un qualunque foro: banalmente, in presenza di una classica cassetta murale 503 (quella dei comuni interruttori, per capirci) è possibile installare una classica placca di copertura, forarla, installare il lettore, l’alimentatore e NodeMCU nella scatola, e il gioco è fatto:
Il primo modello, l’R307, è meno comodo da installare, in quanto ha forma di barilotto. Inoltre, l’R503 presenta anche un elegante LED circolare che comunica gli stati in fase di lettura (si accende in blu quando l’impronta viene riconosciuta, in rosso quando non viene riconosicuta):
Configurare il firmware ESPHome
ESPHome è un firmware “modulare” che consente, appunto, di installare sui dispositivi target (in questo caso un NodeMCU) le componenti utili agli scopi prefissi “assemblate” in un unico compilato.
| N.b. Se non si conosce questo firmware è necessario dare una veloce lettura alla scheda ad esso dedicata; diversamente non si comprenderanno gli aspetti che verranno spiegati in seguito e, fatalmente, si fallirà. |
Nel caso di questo specifico progetto il componente utile allo scopo è ESP32 Grow Fingerprint Reader, il quale consente per l’appunto la gestione dei lettori di impronte digitali.
Per attivarlo, è semplicemente necessario aggiungere, nella configurazione YAML di ESPHome (la “ricetta” del nostro firmware):
fingerprint_grow:
La presenza di questa voce aggiunge, in compilazione del firmware, tale componente, attivando le funzioni di cui sopra. Sempre che, ovviamente, si stia utilizzando una versione di ESPHome uguale o superiore alla 0.18.0.
Inoltre, è necessario attivare anche il componente UART Bus, il quale consente di far dialogare il componente che ospita il firmware (il NodeMCU) con il lettore d’impronte. Per attivarlo, è necessario aggiunge alla configurazione YAML di ESPHome:
uart:
| N.b. In caso il lettore che andremo a realizzare non venga poi utilizzato con un HUB per domotica in grado utilizzare le API di interfacciamento ESPHome (come per esempio Home Assistant – vedi guida), è possibile attivare, nella configurazione ESPHome, la piattaforma MQTT (non approfondita nel presente progetto) in alternativa alla piattaforma API. |
CONFIGURAZIONE SPECIFICA
Ora, ovviamente, è necessario indicare al firmware ESPHome una parte di configurazione specifica al lettore d’impronte da integrare. La configurazione ovviamente varia in base a come il lettore viene collegato al NodeMCU: noi proporremo una configurazione tipo successivamente personalizzabile dall’utente.
Descriveremo la configurazione in tre distinti blocchi per una maggiore chiarezza.
UART
Il primo, semplicissimo blocco da configurare è quello che spiegherà al NodeMCU come comunicare col lettore d’impronte. Sono necessari due pin digitali del NodeMCU da collegare ai poli TX/RX del lettore: noi abbiamo scelto GPIO13 e GPIO14.
Il blocco è da configurare quindi come segue:
uart: rx_pin: GPIO13 tx_pin: GPIO14 baud_rate: 57600
LETTORE IMPRONTE
Ora è il momento di dichiarare le specifiche funzionalità del lettore sfruttando il sopracitato componente ESP32 Grow Fingerprint Reader. Nelle varie caratteristiche è necessario indicare su quale pin digitale del NodeMCU sia collegato il contatto proveniente dal lettore d’impronte che segnala al NodeMCU l’attivazione della rilevazione. Noi abbiamo scelto GPIO12.
Definiamo quindi un blocco come segue:
fingerprint_grow:
sensing_pin: GPIO12
on_finger_scan_matched:
- text_sensor.template.publish:
id: fingerprint_state
state: "Impronta autorizzata"
- delay: 3000ms
- text_sensor.template.publish:
id: fingerprint_state
state: "Attesa"
- fingerprint_grow.aura_led_control:
state: BREATHING
speed: 200
color: BLUE
count: 1
on_finger_scan_unmatched:
- text_sensor.template.publish:
id: fingerprint_state
state: "Impronta non autorizzata"
- fingerprint_grow.aura_led_control:
state: FLASHING
speed: 25
color: RED
count: 2
on_enrollment_scan:
- text_sensor.template.publish:
id: fingerprint_state
state: "Impronta acquisita"
- text_sensor.template.publish:
id: fingerprint_state
state: "Impronta acquisita"
- fingerprint_grow.aura_led_control:
state: FLASHING
speed: 25
color: BLUE
count: 2
- fingerprint_grow.aura_led_control:
state: ALWAYS_ON
speed: 0
color: PURPLE
count: 0
on_enrollment_failed:
- text_sensor.template.publish:
id: fingerprint_state
state: "Acquisizione impronta fallita"
- fingerprint_grow.aura_led_control:
state: FLASHING
speed: 25
color: RED
count: 4
SERVIZI HOME ASSISTANT
Ora aggiungiamo un blocco che consenta di creare, lato Home Assistant, i servizi utili a pilotare il comportamento del lettore d’impronte, come per esempio l’attivazione della procedura di registrazione di una nuova impronta digitale, oppure la cancellazione.
Per farlo sfrutteremo la sezione “api:” del file di configurazione:
api:
encryption:
key: "metterequidentrounachiavepersonalequalunque"
services:
- service: enroll
variables:
finger_id: int
num_scans: int
then:
- fingerprint_grow.enroll:
finger_id: !lambda 'return finger_id;'
num_scans: !lambda 'return num_scans;'
- service: cancel_enroll
then:
- fingerprint_grow.cancel_enroll:
- service: delete
variables:
finger_id: int
then:
- fingerprint_grow.delete:
finger_id: !lambda 'return finger_id;'
- service: delete_all
then:
- fingerprint_grow.delete_all:
Questo blocco definisce, lato Home Assistant (una volta effettuata l’integrazione, ovviamente) i seguenti servizi:
- esphome.NOMEDEVICE_enroll
- esphome.NOMEDEVICE_cancel_enroll
- esphome.NOMEDEVICE_delete
- esphome.NOMEDEVICE_delete_all
Spiegheremo più avanti funzionalità e uso degli stessi.
Entità Home Assistant
Infine, andiamo a definire delle entità che verranno create lato Home Assistant (sempre una volta effettuata l’integrazione) e che saranno sostanzialmente le “leve” che utilizzeremo poi in domotica per sfruttare a pieno il lettore d’impronte.
text_sensor: - platform: template id: fingerprint_state name: "Stato impronta" binary_sensor: - platform: fingerprint_grow id: fingerprint_enrolling name: "Acquisendo impronta" sensor: - platform: fingerprint_grow fingerprint_count: name: "Conta impronte" last_finger_id: name: "Ultimo ID impronta" last_confidence: name: "Affidabilità ultima impronta" status: name: "Stato impronta" capacity: name: "Capacità impronta" security_level: name: "Livello di sicurezza"
Questa configurazione crea una serie di sensori:
- binary_sensor.acquisendo_impronta
- sensor.affidabilita_ultima_impronta
- sensor.capacita_impronta
- sensor.conta_impronte
- sensor.livello_di_sicurezza
- sensor.stato_impronta
- sensor.stato_impronta_2
- sensor.ultimo_id_impronta
Come dei servizi, anche di queste entità parleremo più avanti.
Esempio di configurazione completa
Una volta completata la propria “ricetta” ESPHome, apparirà all’incirca come segue. La primissima parte “esphome:” può variare in base al modello di NodeMCU (nell’esempio, la configurazione testata per un NodeMCU ESP32), così come le varie password (OTA, di failback, di integrazione) e le credenziali di accesso alla propria Wi-Fi.
esphome:
name: lab
platform: ESP32
board: nodemcu-32s
wifi:
ssid: "mia_wifi"
password: "password_wifi"
# Enable fallback hotspot (captive portal) in case wifi connection fails
ap:
ssid: "Finger Reader Fallback"
password: "password_fallback"
captive_portal:
# Enable logging
logger:
ota:
password: "password_ota"
uart:
rx_pin: GPIO13
tx_pin: GPIO14
baud_rate: 57600
fingerprint_grow:
sensing_pin: GPIO12
on_finger_scan_matched:
- text_sensor.template.publish:
id: fingerprint_state
state: "Impronta autorizzata"
- delay: 3000ms
- text_sensor.template.publish:
id: fingerprint_state
state: "Attesa"
- fingerprint_grow.aura_led_control:
state: BREATHING
speed: 200
color: BLUE
count: 1
on_finger_scan_unmatched:
- text_sensor.template.publish:
id: fingerprint_state
state: "Impronta non autorizzata"
- fingerprint_grow.aura_led_control:
state: FLASHING
speed: 25
color: RED
count: 2
on_enrollment_scan:
- text_sensor.template.publish:
id: fingerprint_state
state: "Impronta acquisita"
- text_sensor.template.publish:
id: fingerprint_state
state: "Impronta acquisita"
- fingerprint_grow.aura_led_control:
state: FLASHING
speed: 25
color: BLUE
count: 2
- fingerprint_grow.aura_led_control:
state: ALWAYS_ON
speed: 0
color: PURPLE
count: 0
on_enrollment_failed:
- text_sensor.template.publish:
id: fingerprint_state
state: "Acquisizione impronta fallita"
- fingerprint_grow.aura_led_control:
state: FLASHING
speed: 25
color: RED
count: 4
api:
encryption:
key: "metterequidentrounachiavepersonalequalunque"
services:
- service: enroll
variables:
finger_id: int
num_scans: int
then:
- fingerprint_grow.enroll:
finger_id: !lambda 'return finger_id;'
num_scans: !lambda 'return num_scans;'
- service: cancel_enroll
then:
- fingerprint_grow.cancel_enroll:
- service: delete
variables:
finger_id: int
then:
- fingerprint_grow.delete:
finger_id: !lambda 'return finger_id;'
- service: delete_all
then:
- fingerprint_grow.delete_all:
# Optional template text sensor for visual feedback
text_sensor:
- platform: template
id: fingerprint_state
name: "Stato impronta"
# Optional sensors
binary_sensor:
- platform: fingerprint_grow
id: fingerprint_enrolling
name: "Acquisendo impronta"
sensor:
- platform: fingerprint_grow
fingerprint_count:
name: "Conta impronte"
last_finger_id:
name: "Ultimo ID impronta"
last_confidence:
name: "Affidabilità ultima impronta"
status:
name: "Stato impronta"
capacity:
name: "Capacità impronta"
security_level:
name: "Livello di sicurezza"
Ovviamente si tratta solo di un esempio assolutamente personalizzabile.
| N.b. A prescindere, su qualsiasi configurazione ESPHome consigliamo sempre di includere alcuni componenti secondo noi sempre utili, come quelli illustrati su questa scheda. |
Installazione su NodeMCU
A questo punto si è pronti per la compilazione e la successiva installazione sul NodeMCU.
Le tecniche per farlo sono le più disparate – tutto dipende ovviamente da dove si ha installato e in che modalità la suite ESPHome.
CON NODEMCU VERGINE
Se il NodeMCU è vergine, l’unica possibilità di installare il compilato ESPHome è utilizzando cavo USB/Micro-USB a collegare il computer che monta ESPHome e NodeMCU. Collegare i due tramite il cavo e poi premere sul tasto BOOT/FLASH: questo imposterà il NodeMCU in modalità di riprogrammazione.
A questo punto eseguire la compilazione del firmware seguendo una delle guide dedicate al tema in base alla propria modalità d’uso di ESPHome e alla propria installazione.
CON NODEMCU GIÀ DOTATO DI ESPHOME
In caso NodeMCU sia già dotato di firmware ESPHome, la quale precedente compilazione prevedesse il codice:
ota:
password: "password_ota"
e avesse lo stesso “name“, allora non sarà necessario il cavo, ma basterà avviare la compilazione del firmware provvedendo all’accensione del NodeMCU il quale, entrando nella stessa rete LAN (tramite Wi-Fi) del computer sul quale viene eseguito ESPHome, verrà aggiornato.
Assemblare l’hardware
Arrivati a questo punto è necessario assemblare le varie componenti per creare un’unicum hardware. Per farlo è necessario assemblare:
- alimentatore
- NodeMCU
- lettore d’impronte.
L’alimentatore può ovviamente essere quello suggerito, così come un comune alimentatore USB che alimenti la porta del NodeMCU tramite cavo Micro-USB. Nello schema che proporremo, comunque, ipotizzeremo l’uso dell’alimentatore suggerito da noi, in quanto testato.
Il pinout preso in considerazione è quello del lettore d’impronte R503, ma ovviamente usandone un altro basterà prendere il riferimento del pinout specifico per il modello. Quello dell’R503 è il seguente:
Quel che è necessario fare è:
- collegare i poli + e – in uscita dall’alimentatore all’alimentazione del NodeMCU (3/5v testati ok);
- collegare i vari GPIO12/13/14 (o quelli comunque indicati personalmente nella propria configurazione di ESPHome);
- collegare un’alimentazione 3-5 volt al lettore d’impronte.
Lo schema finale, realizzabile magari su basetta Breadboard per effettuare preliminarmente i propri test, è il seguente:
Completato lo schema, alimentare il tutto: il NodeMCU dovrebbe entrare sulla rete Wi-Fi e rendersi quindi disponibile all’intergrazione con Home Assistant offrendo i servizi del lettore d’impronte come da progetto.
| NOTA IMPORTANTE: un eventuale sesto cavo dal lettore d’impronte (solitamente bianco) va collegato anch’esso al polo 3.3v, assieme al rosso come nello schema di cui sopra. |
Integrazione con Home Assistant
A questo punto basterà accendere il NodeMUC e provvedere all’integrazione delle sue funzionalità sul proprio HUB personale. Dato che stiamo ragionando su Home Assistant, la guida è la seguente:
Una volta effettuata l’integrazione, al di là dei servizi precedentemente elencati si otterranno entità analoghe alle seguenti:
Uso
Sostanzialmente, quel che è necessario fare una tantum è registrare una o più impronte digitali (questi sensori ne possono collezionare centinaia), dopodiché sfruttare i riconoscimenti all’interno dell’HUB. Per farlo – o comunque, in linea di massima, per gestire le registrazioni delle impronte – si utilizzano i servizi visti in precedenza, servizi che appaiono su Home Assistant una volta integrato il NodeMCU con ESPHome all’HUB.
Gestione impronte
Ogni impronta registrata dispone di un identificativo, o ID. Per registrare una nuova impronta recarsi presso la voce “Strumenti per gli sviluppatori” > “Servizi” di Home Assistant, oppure direttamente usando il link che segue:
dove è possibile indicare quale tra i vari servizi evocare.
Per registrare una nuova impronta, selezionare il servizio esphome.NOMEDEVICE_enroll, indicare l’ID prescelto (ipotizziamo “1“) e il numero di digitalizzazioni (consigliato “10“). Una volta cliccato su “Chiama il servizio”, posizionare il dito sul lettore finché l’entità sensor.stato_impronta_2 non abbia acquisito il valore “Impronta acquisita“. A quel punto, l’impronta con ID “1” sarà stata registrata localmente sul lettore. E così via per tutte le altre da acquisire.
Per cancellare un’impronta utilizzare il servizio esphome.NOMEDEVICE_delete; per cancellarle tutte, usare il servizio esphome.NOMEDEVICE_delete_all.
Uso in automazione e altro
Come detto in precedenza, le entità generate dall’integrazione sono svariate (tutte abbastanza comprensibili), ma noi ci concentreremo su alcune, specifiche:
- sensor.affidabilita_ultima_impronta
- sensor.stato_impronta_2
- sensor.ultimo_id_impronta
La prima entità sensore (sensor.affidabilita_ultima_impronta) contiene lo stato, numerico, dell’affidabilità dell’ultima lettura. Quando tale valore è superiore a 100, la lettura può considerarsi pienamente valida e non frutto di un falso positivo.
La seconda, sensor.stato_impronta_2, contiene l’etichetta intelleggibile dello stato di lettura. Quando varia in “Impronta autorizzata“, significa che ha riconosciuto un’impronta registrata in memoria.
Infine la terza, sensor.ultimo_id_impronta, contiene l’ID dell’ultima impronta riconosciuta.
Va da se che scrivere un’automazione che “faccia qualcosa” (disattivare un allarme? attivare un impianto? è personale) quando un’impronta sia stata riconosciuta sia quantomai semplice:
automation: - alias: "Automazione su base riconoscimento generico" trigger: platform: state entity_id: sensor.stato_impronta_2 to: 'Impronta autorizzata' condition: - condition: numeric_state entity_id: sensor.affidabilita_ultima_impronta above: 100 action: []
Questa automazione scatta quando viene riconosciuta una qualsiasi impronta con livello di affidabilità maggiore di 100. Com’è facile intuire, nel blocco action andranno poi inserite le azioni da fare in caso di effettivo riconoscimento dell’impronta.
Ma se volessi indicare anche una specifica impronta? Semplice:
automation:
- alias: "Automazione su base riconoscimento specifico"
trigger:
platform: state
entity_id: sensor.stato_impronta_2
to: 'Impronta autorizzata'
condition:
condition: and
conditions:
- condition: state
entity_id: sensor.ultimo_id_impronta
state: '1'
- condition: numeric_state
entity_id: sensor.affidabilita_ultima_impronta
above: 100
action: []
Ipotizziamo infine aver definito un sistema d’allarme in proprio su Home Assistant (o comunque di averne uno integrato in una delle tante modalità) e di volerlo disarmare ogni qual volta viene riconosciuta una specifica impronta digitale.
L’automazione tipo potrebbe essere:
automation:
- alias: "Automazione su base riconoscimento specifico"
trigger:
platform: state
entity_id: sensor.stato_impronta_2
to: 'Impronta autorizzata'
condition:
condition: and
conditions:
- condition: state
entity_id: sensor.ultimo_id_impronta
state: '1'
- condition: numeric_state
entity_id: sensor.affidabilita_ultima_impronta
above: 100
action:
- service: alarm_control_panel.alarm_disarm
entity_id: alarm_control_panel.home
e così via. Il limite, come sempre, è la fantasia.
| Questa pagina è redatta, manutenuta e aggiornata dallo staff di inDomus, un gruppo di persone molto diverse tra loro che trovi, per domande e supporto, sul forum e sulla chat del sito. Alcuni link sono taggati in qualità di affiliati Amazon e riceviamo un compenso dagli acquisti idonei, utile al sostenimento del sito, ma le nostre recensioni sono tutte indipendenti e non sponsorizzate. Se ti sei perso, a tua disposizione c'è la mappa. |