community italiana di domotica personale
 
Integrare un lettore di impronte digitali a Home Assistant (via NodeMCU ed ESPHome)

Integrare un lettore di impronte digitali a Home Assistant (via NodeMCU ed ESPHome)

11 minuti di lettura
SCOPI DEL PROGETTO:
  • Definire un lettore di impronte digitali tramite vari componenti e, tramite firmware ESPHome, integrarlo a Home Assistant come strumento per l’identificazione biometrica nella propria domotica
  • Livello di difficoltà: medio/alto
  • Costo: basso
CONCETTI AFFRONTATI:
  • Assemblaggio hardware
  • Configurazione e installazione firmware
  • Configurazione integrazione Home Assistant
COMPONENTI SOFTWARE UTILIZZATE:
COMPONENTI FISICI UTILIZZATI:
PROGETTO MAGGIORMENTE INDICATO PER:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno puro scopo didattico);
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere garanzia, omologazioni e certificazioni di qualità.
Revisione progetto: 1.0

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

NodeMCU ESP32
un NodeMCU ESP32.

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:

  1. scegliere un lettore d’impronte;
  2. configurare il firmware ESPHome;
  3. installare il firmware su NodeMCU;
  4. assemblare assieme il NodeMCU e il lettore d’impronte;
  5. 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

R307/ZFM-20 Optical Fingerprint Reader

R503 Capacitive Fingerprint Reader with Bi-Color Aura LED

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:

Esempio installazione lettore impronte su placca
un esempio di installazione dell’R503 su placca.

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 dedicato; 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: GPIO14
  tx_pin: GPIO13
  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:
  password: "password_di_integrazione_esphome"
  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: GPIO14
  tx_pin: GPIO13
  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:
  password: "password_di_integrazione_esphome"
  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.

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:

R503 Pinout


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:

NodeMCU - Lettore d'impronte
lo schema delle connessioni.

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.

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:

Integrare componenti ESPHome a Home Assistant (via API)

Una volta effettuata l’integrazione, al di là dei servizi precedentemente elencati si otterranno entità analoghe alle seguenti:

Home Assistant - ESPHome ESP32 Grow Fingerprint Reader
rappresentazione grafica delle entità.

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:

Open your Home Assistant instance and show your service developer tools.

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.


NodeMCU ATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica ai dispositivi ESP8266, ESP32 e similari per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.

   
Telegram News Channel