community italiana di domotica personale
 
Integrare gratuitamente Home Assistant su Amazon Alexa (via haaska e AWS)

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

12 minuti di lettura
Scopi della guida:
Concetti affrontati:
  • Configurazione software
Componenti software utilizzate:
Prerequisiti:
  • Home Assistant configurato e funzionante
  • Home Assistant remotizzato via HTTPS (spiegato dopo)
  • Amazon Echo/Alexa configurato e funzionante e relativo account Amazon ad esso collegato
  • Un account personale Amazon
Dispositivi fisici utilizzati:
  • Il computer sul quale è in esecuzione 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 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 guida: 4.1

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 che quindi possono essere controllate “di fabbrica” da tale Smart Speaker – è 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, alcuni scenari evoluti 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 Alexa, 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:

  • alarm control panel (allarmi)
  • alert (avvisi di allarme)
  • automation (automazione) –  accensione/spegnimento
  • binary sensors (sensori binari)
  • camera (telecamere)
  • climate (climatizzatori e termostati) – impostazione della temperatura target.
  • cover (scuri)
  • fan (ventilatori) – accensione/spegnimento
  • group (gruppi)
  • input boolean (input booleani)
  • input_number (input numerici)
  • image processing (processamento immagini)
  • 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)
  • timer (cronometri)
  • vacuum (aspirapolvere)
N.b. Per integrare Amazon Alexa con Home Assistant 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.

AVVERTENZE DI INDOMUS

 Si parte

Prerequisiti

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

  • versione di Home Assistant maggiore o uguale alla 0.78;
  • 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. (vedi guida). Le guide disponibili per l’ottenimento di tale duplice prerequisito sono:

N.b. A differenza di altre, questa guida non prevede obbligatoriamente l’uso della porta 443 TCP “girata” verso la tradizionale TCP 8123 interna di Home Assistant, a meno che l’utente non abbia scelto proprio quella porta (esterna) per raggiungere l’HUB. L’apertura della porta 443 per altri scopi personali non ha, eventualmente, nulla a che vedere con la realizzazione della presente integrazione.

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

Tale indirizzo verrà usato dall’integrazione per interfacciare il cloud AWS con la nostra istanza di Home Assistant. Collegandosi ad esso (e se tutto è configurato correttamente) si otterrà la risposta:

405: Method not allowed

Si tratta di un errore perfettamente normale, che denota sia l’abilitazione delle API per Alexa che un corretto funzionamento. Si tratta infatti una request ad una risorsa che prevede il metodo POST, mentre collegandosi all’indirizzo tramite browser viene di default eseguita tramite il metodo GET – da qui l’errore.

INDIRIZZO RADICE

L’indirizzo “radice” presso il quale vengono esposte le API del proprio Home Assistant è invece il seguente:

https://il_tuo_dominio:porta/api

servirà più avanti.

Creazione TOKEN lunga vita

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

Nome utente su Lovelace UI Home Assistant

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.

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“. il 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” (o quel che si preferisce, è solo un nome descrittivo);
  • Descrizione del profilo di sicurezza: “HASSIO” (o quel che si preferisce, è solo una descrizione);
  • 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 accedere come “Root user” (creando un account, in caso non lo si possieda, alla voce “Create a new AWS account”) 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 “AWSLambdaBasicExecutionRole“; 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 “Europa (Irlanda)” (attenzione a non dimenticare questo fondamentale passaggio):

AWS Amazon Web Services - Lambda

N.b. Da aprile 2020 nella lista delle zone è disponibile anche “Europa (Milano)“, ma il funzionamento con le funzionalità Alexa non è ancora disponibile per quella zona. Va quindi ancora scelta la zona “Europa (Irlanda)“.

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, poi cliccare in alto su “Copy ARN“: tale codice verrà copiato negli appunti. Salvarlo da parte, come fatto in precedenza per lo Skill ID.

Nella schermata successiva relativa alla “Function Overview” cliccare su “Add trigger“: 

AWS Amazon Web Services - Lambda - Aggiungi trigger

selezionando poi “Alexa Smart Home“:

AWS Amazon Web Services - Lambda - Aggiungi trigger - Alexa Smart Home

N.b. Se la voce “Alexa Smart Home” è assente è perché precedentemente è stato impostato un profilo diverso da “Europa – Irlanda”.

Nel campo “ID Applicazione” della configurazione del Trigger inserire la “Skill ID” precedentemente ottenuta (eg. “amzn1.ask.skill.2e4e….“) e verificare che sia selezionato “Abilita trigger”.

Cliccare poi sul bottone “Aggiungi“.

Assicurarsi che le voci “Runtime” e “Gestore“, sotto “Impostazioni Runtime” (in basso), devono essere rispettivamente impostate “Python 3.6” e “haaska.event_handler“. In caso questi campi non fossero così impostati, correggerli come indicato.

ATTENZIONE: Non sbagliare questo passaggio! Indicando un handler diverso, l’integrazione non funzionerà.

Recarsi ora alla sezione “Codice della funzione“. Cliccare quindi il pulsante “Operazioni” e selezionare “Carica un file .zip” per provvedere ad inviare ad AWS il file haaska.zip scaricabile presso questo link.

Spostarsi su “Function code” (codice della funzione), cliccare sul file “config.json“.

Avere a questo punto cura di modificare il file inserendo:

Un JSON sarà, per esempio:

{
  "url": "https://il_tuo_dominio:8123/api",
  "bearer_token": "eyJ0eXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "debug": false,
  "ssl_verify": true,
  "ssl_client": []
}
N.b. Si noti – ed è un dettaglio importante – come l’indirizzo vari da “http” a “https“.

Al termine, cliccare su Deploy.

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:

  • Your Authorization URI: “https://www.amazon.com/ap/oa”
  • Access Token URI: “https://api.amazon.com/auth/o2/token”
  • Your Client ID: il valore del CLIENT ID ottenuto dalla pagina di recap del proprio profilo di sicurezza;
  • Your CLIENT Secret: il valore CLIENT SECRET ottenuto dalla pagina di recap del proprio profilo di sicurezza;
  • Your 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 i “Redirect URLs”

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"
      }
    }
  }
}
N.b. Se il JSON non risulta essere formattato in modo opportuno, cliccare su “FORMAT“.

Cliccare infine su “Save changes“.

A questo punto eseguire il test cliccando il bottone “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:

  • alarm control panel (allarmi)
  • alert (avvisi di allarme)
  • automation (automazione) –  accensione/spegnimento
  • binary sensors (sensori binari)
  • camera (telecamere)
  • climate (climatizzatori e termostati) – impostazione della temperatura target.
  • cover (scuri)
  • fan (ventilatori) – accensione/spegnimento
  • group (gruppi)
  • input boolean (input booleani)
  • input_number (input numerici)
  • image processing (processamento immagini)
  • 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)
  • timer (cronometri)
  • vacuum (aspirapolvere)

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.
Infine, dopo l’avvenuta modifica del file di configurazione di Home Assistant, ricordarsi di riavviare l’HUB.

N.b. Si consiglia caldamente di escludere di default tutti i domini caricati sull’HUB (qui scopri come esportare tale lista) tramite il campo “exclude_domains” e provvedere all’aggiunta delle singole entità da esporre ad Alexa. tramite il campo “include_entities“.

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, Home Assistant sarà totalmente integrato ad Alexa.

Questo slideshow richiede JavaScript.

Da qui in poi sarà possibile controllare le entità di Home Assistant esposte verso Alexa tramite comandi vocali. Ovviamente i comandi da dare varieranno molto in base alla tipologia di entità (i “domini” di cui sopra): per esempio, una lampadina si potrà accendere con un comando tipo “Alexa, accendi la luce della camera”, mentre un climatizzatore prevederà molti più comandi, come per esempio “Alexa, imposta il climatizzatore su 25”).

Un buon stratagemma, per comandi complessi, è quello di utilizzare script Home Assistant & routine Alexa, come spiegato in questa guida.


Per utilizzare invece Alexa come riproduttore multimediale – cosa molto diversa rispetto a quanto fatto con la presente guida – quella giusta è quella che segue:

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


Home Assistant Official Logo ATTENZIONE: 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.

   
Telegram News Channel