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

Scopi della guida: Integrare gratuitamente Home Assistant all’ecosistema Amazon Alexa al fine di controllare, tramite comandi vocali, la propria domotica personale. Metodo alternativo al servizio a pagamento cloud (più semplice) Livello di difficoltà: Alto Categoria d’integrazione: Cloud Push Concetti affrontati: Configurazione software Componenti software utilizzate: Home Assistant haaska Amazon AWS App “Amazon” (per Android e/o iOS)	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 INDICATA A UTENTI CON ISTALLAZIONE:
NOTE E DISCLAIMER qualsiasi eventuale modifica agli impianti domestici dev'essere progettata e realizzata SOLO da personale qualificato; qualsiasi modifica non prevista attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno infatti puro scopo didattico) e fa decadere garanzia, omologazioni e certificazioni di qualità; dei dispositivi interessati; tutte le tecniche descritte si intendono applicate a software e firmware aggiornati alle ultime versioni disponibili; gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione; questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In caso di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat; se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 5.6

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.

Home Assistant, HUB personale re delle integrazioni, può a sua volta essere integrato con qualunque smart speaker che utilizzi Amazon Alexa. Quindi perché, dato che molte componenti domotiche dichiarano una diretta compatibilità con l’ecosistema Amazon Alexa (e che quindi possono essere controllate “di fabbrica” da tale Smart Speaker) è utile integrarle via Home Assistant e poi, tramite esso, con Amazon Alexa? 

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, oltre a essere in grado a integrare un insieme di componenti e servizi enormemente superiore rispetto all’ecosistema Alexa (leggi lo speciale sulle integrazioni Home Assistant).

Nel momento in cui si integra tale HUB personale (quindi Home Assistant nel caso specifico di questa guida) su Amazon Alexa, si potranno controllare tutti i componenti e le entità – quali scenari (ed altro) – in esso definiti tramite l’assistente vocale. È uno dei tanti motivi per adottare un HUB personale per la propria domotica: questo concetto, semplice ma importante, lo abbiamo spiegato in dettaglio qui.

Gli elementi (definiti domini) definiti in configurazione Home Assistant e controllabili tramite integrazione su Amazon Alexa sono:

• alarm control panel (allarmi)
• automation (automazione) –  accensione/spegnimento
• camera (telecamere)
• climate (climatizzatori e termostati)
• light (luci)
• lock (serrature)
• media_player (riproduttori multimediali)
• script – solo accensione/attivazione
• sensor (sensori)

e svariati altri, che vedremo sul finire di questa guida.

Infine, è bene sapere che anche Alexa può essere integrata a sua volta su Home Assistant come riproduttore multimediale e come sistema di notifica vocale/visiva, ovvero “facendola parlare” automaticamente al presentarsi di determinate condizioni in domotica oppure riproducendo contenuti visuali sugli Amazon Echo dotati di schermo.

 Si parte

• Prerequisiti
• Attivare API e Alexa
• Creazione TOKEN lunga durata
• Amazon Developer Console
• Alexa Developer Console
• Amazon Web Services (AWS)
• Completamento Skill
• TEST
• Definizione di domini ed entità 
• Aggiungere la Skill ad Alexa

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 protocollo HTTPS.

Il secondo punto prevede che la propria istanza Home Assistant sia raggiungibile da remoto e tramite protocollo HTTPS.
Le guide disponibili per l’ottenimento di tale prerequisito sono:

• guida per qualsiasi installazione di  Home Assistant, usando Reverse Proxy (gratuita e adatta alla stragrande maggioranza dei casi);
• guida per qualsiasi installazione di Home Assistant e qualsiasi tipo di connessione Internet, via Cloudflare (con un costo per l’acquisto del dominio, ma adatta a tutti e più affidabile).

Infine, è (ovviamente) necessario che su Home Assistant non sia operativa l’integrazione a pagamento tramite Nabu Casa., la quale eventualmente già permette di integrare Home Assistant su Alexa senza troppi mal di pancia. Eventualmente, disattivarla prima di cominciare con l’esecuzione della presente guida.

Attivare API e Alexa

In primis è necessario indicare a Home Assistant di attivare i componenti “API” e “Alexa“.
Per farlo, la configurazione del file configuration.yaml è banale. Aggiungere:

api:

alexa:
  smart_home:

Effettuata la modifica, riavviare Home Assistant.

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 alla nostra istanza di Home Assistant. Collegandosi ad esso tramite browser (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. In sostanza, per proseguire oltre è paradossalemente necessario riscontrare tale 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

Segnarselo: servirà più avanti.

Creazione TOKEN lunga durata

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

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

Cliccare ora su “CREA TOKEN” e, alla richiesta del nome del token da creare, inserire “haaska“.
A questo punto salvare da qualche parte la stringa che verrà prodotta da Home Assistant (attenzione: non sarà possibile recuperarla successivamente, quindi salvarsela subito da parte).

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 (le proprie credenziali di accesso di Amazon.com/.it) per entrare. Successivamente cliccare su “Login with Amazon” (in alto).

Il sito chiederà (qualora non sia stato già fatto in precedenza) di configurare il servizio “Login with 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“:

Una volta ottenuto l’accesso, impostare la lingua italiana (solitamente il selettore è in basso a sinistra), poi 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:

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

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

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” specifica per il nostro ambiente.

A questo punto, apertasi la pagina principale della “Console degli sviluppatori“, impostare la lingua italiana (anche qui solitamente in basso a destra) e cliccare su “Crea Skill“:

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

Nella pagina che seguirà lasciare selezionato “v3“.

Segnarsi da una parte la stringa sotto la voce “Your Skill ID” (servirà più avanti).

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“, perché su questo sito, a differenza dei precedenti, non si usano le stesse credenziali Amazon.com/.it) presso l’indirizzo https://console.aws.amazon.com/console/home.

IAM

Una volta autenticati cliccare sulla voce “Tutti i servizi” (in alto) e selezionare la voce “IAM” sotto “Sicurezza, identità, conformità“. Poi, sulla sinistra, cliccare su “Ruoli” e infine “Crea Ruolo“.

Nella pagina che si aprirà selezionare prima “AWS Service” e poi “Lambda“. Nell’elenco seguente, cercare “AWSLambdaBasicExecutionRole“; una volta trovato, selezionare la voce e infine cliccare in basso su “Successivo“:

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

LAMBDA

Cliccare sulla voce “Servizi” (in alto) e selezionare la voce “Lambda” sotto “Calcolo“.

In alto a destra selezionate “Europa (Irlanda)” (attenzione a non dimenticare questo fondamentale passaggio):

Cliccare ora sul bottone arancione “Crea una funzione“, poi “Crea funzione da zero“, compilando i campi che seguono come da seguenti indicazioni:

• Nome: “haaska“;
• Runtime: “Python 3.9“;
• Architettura: “x86_64“;
• Modifica del ruolo di esecuzione predefinito: “Selezionare un ruolo esistente“;
  • Ruolo esistente: “lambda_basic_execution“:

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 “Panoramica della funzione” cliccare su “Aggiungi trigger“: 

selezionando poi “Alexa Smart Home“:

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“. Spostarsi ora sul tab “Codice“, cliccare a destra su “Carica da…” per provvedere ad inviare ad AWS il file haaska.zip scaricabile presso questo link.

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

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

Avere a questo punto cura di modificare il file inserendo:

• nel campo “url“, l’indirizzo “radice” presso il quale Home Assistant espone le proprie API (come sopra spiegato – attenzione che sia https e non http);
• nel campo “bearen_token“, la stringa generata nello step relativo al TOKEN lunga durata.

Un JSON sarà, per esempio:

{
  "url": "https://il_tuo_dominio:8123/api",
  "bearer_token": "eyJ0eXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "debug": false,
  "ssl_verify": true,
  "ssl_client": []
}

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:user_id“.

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:

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 “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 di domini ed entità

Prima di concludere l’integrazione è buona regola specificare anticipatamente nella configurazione Home Assistant quali siano i domini e/o le entità da esporre verso Amazon Alexa.

Se le luci, diciamo, appartengono al dominio light, una singola entità luce appartenente a tale dominio potrebbe per esempio chiamarsi light.cucina.

I domini che Alexa è in grado di censire e controllare sono i seguenti:

• alarm_control_panel (allarmi)
• alert (avvisi di allarme)
• automation (automazione) –  accensione/spegnimento
• binary sensors (sensori binari)
• button
• camera (telecamere)
• climate (climatizzatori e termostati)
• cover (scuri)
• device_tracker
• event
• fan (ventilatori) – accensione/spegnimento
• group (gruppi)
• humidifier
• input boolean (input booleani)
• input_button
• input_datetime
• input_number (input numerici)
• input_select
• light (luci)
• lock (serrature)
• media_player (riproduttori multimediali)
• number
• person
• remote
• scene
• script – solo accensione/attivazione
• select
• sensor (sensori)
• siren
• switch
• timer (cronometri)
• vacuum (aspirapolvere)
• weather
• zone

Per indicare cosa Alexa debba “vedere”, è possibile:

• indicare interi domini da includere o escludere;
• indicare specifiche entità da includere o escludere.

Per esempio, l’utente potrebbe voler escludere tutte le luci e includere, invece, una sola, specifica. Oppure potrebbe voler includere un intero dominio, per escludere specificamente alcune entità – e così via.

Tali inclusioni/esclusioni si effettuano aggiungendo un blocco di configurazione YAML al file di configurazione di Home Assistant, sotto il blocco alexa, il quale può includere anche una sezione per configurare le speficiche entità in modo che Alexa le integri con delle specificità (per esempio, il nome).

Vediamo un esempio concreto:

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

Con questa configurazione d’esempio:

• sono inclusi nel dominio Amazon Alexa le entità relative alle luci di cucina e camera, sono inclusi tutti gli interruttori, tranne quello del terrazzo. Escluso in toto il dominio “light” (luci), tranne ovviamente quelle entità sopra incluse specificamente
• è 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.

alexa:
  smart_home:
    filter:
      exclude_domains:
        - alarm_control_panel
        - alert
        - automation
        - binary_sensor
        - button
        - camera
        - climate
        - cover
        - device_tracker
        - fan
        - group
        - humidifier
        - input_boolean
        - input_button
        - input_datetime
        - input_number
        - input_select
        - light
        - lock
        - media_player
        - number
        - person
        - remote
        - scene
        - script
        - select
        - sensor
        - siren
        - switch
        - timer
        - vacuum
        - weather
        - zone 
      include_entities:
        #includere progressivamente, in questa sezione, le entità da esporre ad Alexa
      include_domains:
        #includere progressivamente, in questa sezione, i domini da esporre ad 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 (anche semplicemente chiedendo “Alexa, cerca nuovi 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.

Terminata questa procedura, complimenti: 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, per sempio per “farla parlare” alla bisogna – cosa molto diversa rispetto a quanto fatto con la presente guida – quella giusta è quella che segue:

Integrare Amazon Alexa come “Media Player” su Home Assistant