Integrare gratuitamente Amazon Echo (Alexa) con Home Assistant (via haaska e AWS)

11 minuti di lettura
Scopi della guida
Concetti affrontati:
  • Configurazione software
Componenti software utilizzate:
Prerequisiti
  • Home Assistant configurato e funzionante (minimo versione 0.62)
  • Home Assistant remotizzato su HTTPS (spiegato dopo)
  • Amazon Echo/Alexa configurato e funzionante e relativo account Amazon ad esso collegato
  • Un account personale Amazon
Dispositivi fisici utilizzati:
  • Il dispositivo sul quale risiede Home Assistant
  • Smartphone sul quale eseguire l’app Amazon Alexa (Android e/o iOS)
  • Amazon Echo (qualsiasi modello o qualsiasi modello di smart speaker che monti Amazon Alexa come software integrato)
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere effettuata da personale qualificato
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (la presente guida ha puro scopo didattico)
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere la garanzia.
Revisione guida: 1.5

Home Assistant Amazon-Echo-Plus

Abstract

L’avvento sul mercato degli Smart Speaker sta lentamente cambiando le abitudini di molti che, quotidianamente, prendono dimestichezza e familiarità con la possibilità di interagire con un vero e proprio assistente personale usando semplicemente voce e linguaggio naturale.

Amazon Echo è uno dei device di più ampio e riconosciuto successo. Come abbiamo spiegato tale smart speaker per funzionare utilizza il software Alexa, il quale è disponibile, anche per smart speaker prodotti da terze parti, oltre che come applicazione stand-alone per smartphone/tablet Android e iOS.

Qualunque smart speaker che utilizzi Amazon Alexa può esser facilmente integrato con Home Assistant.
Ma perché, dato che molte componenti domotiche dichiarano compatibilità con Amazon Echo – e quindi possono essere controllate “di fabbrica” – è utile integrarle con quest’ultimo tramite Home Assistant[Prima di rispondere alla domanda, chi legge abbia chiaro il concetto di integrazione in domotica.]

Semplice: perché tramite un HUB personale come Home Assistant siamo in grado di definire scenari, accessori virtuali, automazioni non definibili altrimenti con l’uso separato delle singoli componenti. Come spiegato anche in un episodio del nostro podcast, scenari come “buonanotte” (il quale magari quando evocato spenga tutte le luci, la tv, e attivi l’allarme perimetrale) semplicemente non possono essere realizzati senza l’ausilio di una piattaforma comune, ovvero un HUB personale.

Nel momento in cui si integra tale HUB personale (quindi Home Assistant nel caso specifico di questa guida) con Amazon Echo, si potranno controllare tutti i componenti e le entità – quali scenari (ed altro) – in esso definiti tramite il mio assistente personale. Uno dei tanti motivi per adottare un HUB personale per la propria domotica. Un focus su questo importante tema è disponibile qui.

Gli elementi (definiti domini) definiti in configurazione Home Assistant e controllabili tramite integrazione con Amazon Alexa (Amazon Echo e speaker compatibili) sono:

  • alert (avvisi di allarme)
  • automation (automazione) –  accensione/spegnimento
  • climate (climatizzatori e termostati) – impostazione della temperatura target.
  • cover (scuri)
  • fan (ventilatori) – accensione/spegnimento
  • group (gruppi)
  • input boolean (input booleani)
  • light (luci)
  • lock (serrature) – apertura e chiusura
  • media_player (riproduttori multimediali) – riproduzione, pausa, stop, imposta volume, aggiusta volume, traccia avanti/indietro)
  • scene
  • script – solo accensione/attivazione
  • sensor (sensori)
  • switch (interruttori)
N.b. Per integrare Home Assistant con Alexa esistono due strade:

La presente guida illustra come realizzare la seconda possibilità, quella gratuita.

Infine, è bene sapere che Alexa può essere integrata ad Home Assistant anche come riproduttore multimediale e come sistema di notifica vocale, ovvero “facendola parlare” automaticamente al presentarsi di determinate condizioni in domotica.

 Si parte

Prerequisiti

Come illustrato in testa, i pre-requisiti principali sono due:

  • versione di Home Assistant maggiore o uguale alla 0.62;
  • Home Assistant configurato per il controllo remoto tramite HTTPS.

Il secondo punto prevede che la propria istanza Home Assistant sia raggiungibile da remoto e tramite protocollo HTTPS. In caso si stia utilizzando Home Assistant installato su Raspberry (installazione manuale o HASSBIAN) è disponibile una guida dettagliata al procedimento.

Esistono inoltre dei pre-requisiti a corollario.

PRE-REQUISITI IN BASE ALL’INSTALLAZIONE HOME ASSISTANT
UTENTI RASPBIAN (o Linux)Gli utenti che utilizzino Home Assistant installato su Raspbian (anche modelità HASSBIAN) hanno la sola necessità di appurare di essere in grado di collegarsi al file system di Raspbian tramite SFTP (usando Filezilla o altri tool) per recuperare un file che verrà generato da Raspbian.
UTENTI HASSIOGli utenti che utilizzino HASSIO devono necessariamente avere installato SSHSamba server (HASSIO Add-on) per recuperare un file che verrà generato da HASSIO stesso.
UTENTI Windows Gli utenti che utilizzino Home Assistant installato su Windowsoltre al consiglio di cambiare ambiente operativo sul quale eseguirlo – è necessario si dotino di un computer con sistema operativo Raspbian/macOS/Linux, necessario per generare il file previsto in uno degli step seguenti.
UTENTI MACGli utenti che utilizzino Home Assistant installato su Mac devono appurare che, tramite “Terminale”, i seguenti comandi siano disponibili:

  • apt-get
  • wget
  • make

In caso non siano presenti, installarli. In alternativa, utilizzare un computer Linux/Raspbian, necessario per generare il file previsto in uno degli step seguenti.

Infine, è (ovviamente) necessario che su Home Assistant non sia operativa l’integrazione a pagamento tramite Nabu Casa.
Eventualmente, disattivarla prima di cominciare con l’esecuzione della presente guida.

Attivare API e Alexa

In primis è necessario indicare a Home Assistant di attivare il componente “API” e il componente “Alexa”.
La configurazione del file configuration.yaml è banale:

api:
alexa:
  smart_home:

Riavviare Home Assistant.
N.b. Si noti come si tratti di due blocchi distinti. Il primo attiva il componente “API“, il secondo “Alexa“.

A questo punto Home Assistant esporrà le proprie API all’indirizzo

https://il_tuo_dominio:porta/api/alexa/smart_home

Indirizzo che verrà usato dall’integrazione per interfacciare il cloud AWS con la nostra istanza di Home Assistant.
L’indirizzo che però andremo ad esporre verso AWS sarà solo la prima parte, ovvero:

https://il_tuo_dominio:porta/api

Creazione TOKEN lunga vita

A questo punto è necessario creare un “TOKEN a lunga vita“, ovvero una chiave valida per 10 anni.
Per far ciò, da interfaccia Home Assistant cliccare sul circolo colorato contenente la prima lettera del vostro username posta in alto a sinistra, nella colonna sinistra.

Una volta acceduto alla pagina, scollare sul fondo fino a trovare la seguente box:

Home Assistant - Token di accesso lunga vita

Cliccare ora su “CREA TOKEN” e, alla richiesta del nome del token da creare, inserire “haaska“.
A questo punto salvare la stringa che verrà prodotta da Home Assistant.

Creazione del package per AWS

A questo punto è necessario generare un package contenente “haaska” pre-configurato con il TOKEN appena creato (e relativo URL di connessione a Home Assistant).

Questo file può essere generato:

PER CHI HA A DISPOSIZIONE RASPBIAN/LINUX/MAC

da Terminale, eseguire:

sudo apt-get install python3 python3-venv python3-pip -y
cd ~
mkdir temp
cd temp
sudo wget https://github.com/mike-grant/haaska/archive/master.zip
unzip master.zip

In caso di errore sul comando wget e/o unzip, eseguire:

sudo apt-get update
sudo apt-get install zip wget -y

e successivamente ri-eseguire la wget.
Poi:

cd haaska-master/config
sudo cp config.json.sample config.json
sudo nano config.json

A questo punto ci si troverà davanti a una configurazione di questo tipo:

{
  "url": "http://localhost:8123/api",
  "bearer_token": "",
  "debug": false,
  "ssl_verify": true,
  "ssl_client": []
}

Avere a questo punto cura di modificare la configurazione inserendo:

N.b. Notare come l’indirizzo cambi da “http” a “https”.

Salvare e uscire (CTRL+X, Y, invio).
Infine:

cd ..
make

A questo punto verrà eseguita una procedura automatica che genererà un file chiamato haaska.zip. Recuperarlo tramite Filezilla (utilizzare SFTP) collegandolo all’IP del Raspberry.

UTENTI HASSIO

Stessa procedura di cui sopra, ma utilizzando i seguenti comandi alternativi da inserire tramite terminale SSH (il servizio dev’essere installato come add-on HASSIO):

mkdir temp
cd temp
apk add make
apk add zip
apk add wget
apk add nano
apk add py-pip
wget https://github.com/mike-grant/haaska/archive/master.zip
unzip master.zip
cd haaska-master/config
cp config.json.sample config.json
nano config.json

a questo punto effettuare le modifiche alla configurazione spiegata sopra, poi concludere con:

cd ..
make
cd /
cp ~/temp/haaska-master/haaska.zip /share

Infine, recuperare il file utilizzando “Configurator” (il file si troverà nella cartella “share“).

Amazon Developer Console

A questo punto è necessario iscriversi (se non lo si è già fatto) alla “Amazon Developer Console“, un sito satellite al classico Amazon.com/.it al quale è necessario essere già precedentemente iscritti.

Recarsi dunque presso https://developer.amazon.com/home.html e utilizzare il proprio username/password (di Amazon.com/.it) per entrare. Successivamente cliccare su “Login with Amazon”:

Amazon Developer Console - Login with AmazonIil sito chiederà (qualora non sia stato già fatto in precedenza) di configurare il servizio “Accedi con Amazon“, il quale permette di utilizzare la propria username/password di Amazon.com/.it (tra l’altro già usata per configurare il proprio ambiente Alexa) in tutti i siti “satellite” come, per l’appunto, “Amazon Developer Console“:

Amazon Developer Console - Login with Amazon

Una volta ottenuto l’accesso, cliccare su “Crea nuovo profilo di sicurezza“.
Nei campi che verranno richiesti, inserire:

  • Nome del profilo di sicurezza: “HASSIO”;
  • Descrizione del profilo di sicurezza: “HASSIO”;
  • URL del consenso della privacy: quello che si crede, è indifferente, dato che la Skill che prepareremo non sarà pubblica ma privata:

Amazon Developer Console - Nuovo profilo di sicurezza

Cliccare su “Salva“.
Nella finestra che si aprirà. cliccare sulla rotellina in basso a destra e selezionare “Impostazioni Web“:

Amazon Developer Console - Impostazioni Web Profilo di sicurezza

La pagina che segue contiene le coordinate del proprio profilo di sicurezza:

Amazon Developer Console - Impostazioni Web Profilo di sicurezza - Dettagli

Lasciare aperta la finestra e passare oltre.

Alexa Developer Console

Messa da parte la pagina precedente, aprire una nuova tab/pagina e collegarsi all’indirizzo https://developer.amazon.com/alexa/console/ask utilizzando poi la propria utenza Amazon.com/.it per autenticarsi. Lo scopo è quello di andare a definire una Skill ad hoc per il nostro ambiente.

A questo punto, apertasi la pagina principale della “Console degli sviluppatori“, cliccare su “Create Skill“:

Amazon Console degli sviluppatori - Create Skill

Nella pagina che seguirà indicare il nome della skill (“haaska” – o ciò che si preferisce) e “Smart Home” come tipologia:

Amazon Console degli sviluppatori - Nuova skill

Nella pagina che seguirà lasciare selezionato “v3“. Segnarsi da una parte la stringa sotto la voce “Your Skill ID” (servirà più avanti).
Amazon Console degli sviluppatori - Nuova skill - Payload Version e Skill ID

Lasciare aperta anche questa finestra e passare oltre.

Amazon Web Services (AWS)

Ora è necessario definire una risorsa Lambda presso AWS.

Aprire una nuova tab/finestra e autenticarsi (creando un account, in caso non lo si possieda) presso l’indirizzo https://console.aws.amazon.com/console/home.

N.b. L’eventuale creazione di un nuovo account prevede l’obbligatorio inserimento di una carta di credito valida,  alla quale non verrà però addebitato alcun costo (l’addebito di 1 dollaro post-inserimento è fittizio – è necessario ad AWS solo per verificare la validità della carta stessa). La configurazione dettata dalla presente guida non prevede alcuna spesa, salvo successive variazioni nel tempo dei termini d’uso di AWS la cui lettura e accettazione è a carico dell’utente che sottoscrive il servizio.

Inoltre, è chiaro che se l’utente dovesse successivamente implementare altre funzionalità che assorbano risorse a pagamento AWS, tale carta verrà utilizzata per gli addebiti. Se volete stare sereni, utilizzate una carta ricaricabile.

AWS Amazon Web Services - Accesso

IAM

Una volta autenticati cliccare sulla voce “Services” (in alto) e selezionare la voce “IAM” sotto “Security, Identity & Compliance“. Poi, sulla sinistra, cliccare su “Ruoli” e infine “Crea Ruolo“.

AWS Amazon Web Services - IAM

Nella pagina che si aprirà selezionare “AWS Service” e “Lambda“:

AWS Amazon Web Services - IAM - New role

In basso, cliccare su “Successivo: Autorizzazioni“.
Nella pagina seguente, cercare nella buca di ricerca “DatabaseAdministrator“; una volta trovato, selezionare la voce e infine cliccare su “Successivo: Tag“:

AWS Amazon Web Services - IAM - New role - 2

Nella pagina che segue, inserire “lambda_basic_execution” nel capo “Nome ruolo“; infine cliccare in basso “Crea ruolo“:

 

AWS Amazon Web Services - IAM - New role - 3

LAMBDA

Cliccare sulla voce “Services” (in alto) e selezionare la voce “Lambda” sotto “Compute“.

ATTENZIONE: Ricevendo in risposta un messaggio tipo “Your service sign-up is almost complete! Thanks for signing up with Amazon Web Services. Your services may take up to 24 hours to fully activate…“, la causa (9 su 10) è data dal non aver inserito una carta di credito valida all’atto della creazione dell’account.

In alto a destra selezionate “EU – Ireland” (attenzione a non dimenticare questo passaggio):

AWS Amazon Web Services - Lambda

 

Cliccare ora sul bottone arancione “Crea una funzione“.
I campi vanno compilati come segue:

  • Crea da zero;
  • Nome: “haaska”;
  • Runtime: “Python 3.6”;
  • Ruolo: “Selezionare un ruolo esistente”;
  • Ruolo esistente: “lambda_basic_execution”:

AWS Amazon Web Services - Lambda - Nuova funzione

Ciò fatto, cliccare su “Crea funzione“, in basso a destra.

Nella nuova pagina, scendere circa a metà e trovare il box “Codice della funzione“. Cliccare il menu a tendina “Tipo di voce del codice” e selezionare “Carica un file .zip“:

AWS Amazon Web Services - Lambda - Carica File

Le voci “Runtime” e “Gestore” dovrebbero essere rispettivamente impostate a “Python 3.6” e “haaska.event_handler“. In caso non fossero così impostati, correggerli come indicato.

A questo punto cliccare sull’icona rappresentante una freccia puntata verso l’alto per provvedere ad inviare ad AWS il file package .zip prodotto nella procedura iniziale.

Fatto questo, scendere ancora più in basso e trovare il riquadro “Ruolo di esecuzione“, il quale deve essere impostato come segue:

AWS Amazon Web Services - Lambda - Ruolo di esecuzione

Ora tornare in testa alla pagina, al riquadro “Designer” e selezionare la voce “Alexa Smart Home“:

AWS Amazon Web Services - Lambda - Designer

N.b. se la voce “Alexa Smart Homeè assente è perché precedentemente non è stato impostato il profilo a “EU (Ireland)“.

Scendere e trovare il box “Trigger“.
Nel campo editabile inserire la “Skill ID” precedentemente ottenuta (eg. “amzn1.ask.skill.2e4e….”)

AWS Amazon Web Services - Lambda - Trigger

Cliccare poi sul bottone “Aggiungi“.
Infine, salire in alto sulla pagina e premere il bottone arancione “Salva“.

Immediatamente sopra il bottone “Salva” c’è una stringa definita “arn“: segnarsela.

Lasciare aperta anche questa finestra e passare oltre.

Completamento Skill

Tornare al recap della skill e inserire nel campo “Default endpoint” il valore del campo “arn” copiato nel punto precedente.
Selezionare, sotto, la checkbox “Europe, India” (attenzione a non dimenticare questo passaggio). Anche qui copiare lo stesso “arn“.

In alto a destra nella pagina, cliccare su “Save“.

Ora cliccare sulla colonna di sinistra la voce “ACCOUNT LINKING“.
Nella pagina che si aprirà, inserire i seguenti valori:

  • Authorization URI: “https://www.amazon.com/ap/oa”
  • Access Token URI: “https://api.amazon.com/auth/o2/token”
  • Client ID: il valore del CLIENT ID ottenuto dalla pagina di recap del proprio profilo di sicurezza;
  • CLIENT Secret: il valore CLIENT SECRET ottenuto dalla pagina di recap del proprio profilo di sicurezza;
  • Client Authentication Scheme: HTTP BASIC (Recommended);
  • Cliccare su “+ Add Scope” e inserire “profile”.

In alto a destra nella pagina, cliccare su “Save“.

Lasciare aperta anche questa finestra: a breve ci serviranno i “Redirect URLs” apparsi in fondo a questa pagina.

Tornare alla pagina di recap del proprio profilo di sicurezza, cliccare su “Modifica” e inserire, alla voce “URL di ritorno consentiti“, tutti e tre gli URL ottenuti nel passo precedente.

Una volta completato, cliccare su “Salva“.

TEST

Tornare alla pagina di definizione della “Lambda” e cliccare su “Selezione eventi di test” e poi “Configura eventi di test“.
Si aprirà una finestra simile a questa:

AWS Amazon Web Services - Lambda - TEST

Nel campo “Nome evento” inserire “Test“.
Cancellare poi tutte le righe di test e sostituirle col testo che segue:

{
  "directive": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      }
    }
  }
}

Cliccare infine su “Salva“.

A questo punto eseguire il “Test” cliccando il bottone “Esegui test“: il responso dovrebbe essere positivo. Differentemente, ricontrollare tutti i passi sin qui attuati.

Definizione dei domini

Prima di concludere l’integrazione è buona regola specificare anticipatamente nella configurazione Home Assistant quali siano i domini da mettere a disposizione di Amazon Echo/Alexa, quindi quali accessori, scene, entità ecc.

L’elenco dei domini esportabili è il seguente:

  • alert (avvisi di allarme)
  • automation (automazione) –  accensione/spegnimento
  • climate (climatizzatori e termostati) – impostazione della temperatura target.
  • cover (scuri)
  • fan (ventilatori) – accensione/spegnimento
  • group (gruppi)
  • input boolean (input booleani)
  • light (luci)
  • lock (serrature) – apertura e chiusura
  • media_player (riproduttori multimediali) – riproduzione, pausa, stop, imposta volume, aggiusta volume, traccia avanti/indietro)
  • scene
  • script – solo accensione/attivazione
  • sensor (sensori)
  • switch (interruttori)

Aggiungere quindi un blocco analogo a quello che segue alla configurazione Home Assistant:

alexa:
  smart_home:
    filter:
      include_entities:
        - light.cucina
        - light.camera
      include_domains:
        - switch
      exclude_entities:
        - switch.terrazzo
      exclude_domains:
        - lock
    entity_config:
      light.cucina:
        name: Nome personalizzato per Alexa
        description: La luce della cucina
      switch.scale:
        display_categories: LIGHT

In questo blocco di esempio sono inclusi nel dominio Amazon Alexa le funzionalità di accensione luci di cucina e camera, sono inclusi tutti gli interruttori, tranne quello del terrazzo. Escluso in toto il dominio “lock” (serrature).
Inoltre, è stato personalizzato il comportamento/nome della luce di cucina e l’interruttore delle scale.

Il campo display_categories può essere personalizzato sulla base delle categorie disponibili in ambito Alexa.

Aggiungere la skill ad Alexa

Ci siamo: ora è possibile aggiungere la Skill appena creata al proprio profilo Alexa.

Dato che de facto abbiamo creato una Skill (privata) ad hoc, basterà aprire l’app (Mobile o Web) Alexa, sfogliare la sezione “Le tue skill” sotto la voce “Skill“. Una volta trovata la propria skill autoprodotta (chiamata “haaska“, o differentemente come si sia scelto di chiamarla), selezionarla e cliccare su “Abilita“. L’app chiederà di associare un account: utilizzare quello di Amazon.com/.it.

Al termine della procedura, eseguire la ricerca completa dei dispositivi. Questa nuova procedura provvederà ad effettuare la discovery automatica delle entità presenti su Home Assistant ed esposte ad Alexa in base alla configurazione del paragrafo precedente.

In caso di mancata personalizzazione, Alexa troverà tutte le entità (sconsigliato).

Terminata questa procedura, Alexa sarà totalmente integrata a Home Assistant.

Questo slideshow richiede JavaScript.


Home Assistant Official LogoATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica a Home Assistant, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.

🔻 Clicca QUI per commentare l'articolo. 🔻

“Far parlare” Amazon Alexa come sistema di notifica domotica su Home Assistant