Alexa su Home Assistant con Haaska (aprile 2021)

Questa guida si propone come alternativa alle ultime guide che si possono trovare in rete ultimamente, dove si utilizza un codice aggiornato di Haaska ma dove sfortunatamente, si è impossibilitati al collegamento della Skill al proprio account Alexa e di fatto rende inutile il lavoro svolto.

Questa guida serve per realizzare correttamente tutta la procedura di integrazione di Alexa con Home Assistant.

REQUISITI

Per poter procedere correttamente all’implementazione di Alexa su Home Assistant, è necessario che abbiate attivato l’ HTTPS. Se non lo avete ancora fatto, seguite prima questa guida. Inoltre sarà necessario caricare diversi file sul Raspberry, è quindi consigliabile abilitare il servizio SAMBA sul Raspberry, oppure procurarvi un programma FTP come Filezilla.

INTEGRAZIONE SU HOME ASSISTANT

Per prima cosa apriamo il nostro file di configurazione configuration.yaml presente nella directory d’installazione di Home Assistant e aggiungiamo le seguenti stringhe:

api:

e ancora:

alexa:
  smart_home:

Salviamo e riavviamo Home Assistant da interfaccia grafica oppure con il comando SSH:

sudo reboot

GENERAZIONE TOKEN DI LUNGA VITA

Entriamo ora in Home Assistant e creiamoci un token di lunga vita (10 anni): cliccate sul vostro nome dal menu di sinitra:

E successivamente cliccare Crea token ed inserire come nome: haaska

Verrà generata una stringa. Copiatevela da parte in un blocco note, ci servirà più avanti.

AMAZON DEVELOPER CONSOLE

Registriamoci sul sito https://developer.amazon.com/home.html effettuando il login con le stesse credenziali che utilizzare con amazon.it e cliccate su Login with Amazon

Nel caso ve lo chiedesse, configurate il servizio Accedi con Amazon.

Successivamente cliccate su Crea nuovo profilo di sicurezza e compilate i campi:

• Nome del profilo di sicurezza: (scegliete un nome a piacere)
• Descrizione del profilo di sicurezza: (scegliete un nome a piacere)
• URL del consenso all’Informativa sulla privacy: (scegliete un indirizzo a piacere)

Cliccate su Salva

Ora dal profilo appena creato, utilizzando il simbolo ingranaggio, selezioniamo Impostazioni web

Si aprirà la seguente finestra. Lasciatela aperta perchè servirà più tardi.

ALEXA DEVELOPER CONSOLE

Apriamo una nuova finestra del browser e colleghiamoci a https://developer.amazon.com/alexa/console/ask con le stesse credenzioni del nostro amazon.it

Clicchiamo su Create skill

Dare un nome a piacere, selezionare Smart Home e cliccare Create skill

Nella nuova pagina lasciare spuntato v3 nel Payload version e appuntarsi da parte Your Skill ID. Mantenere aperta la finestra perchè ci servirà più avanti.

AMAZON WEB SERVICE (AWS)

Aprire una nuova finestra del browser e collegarsi al sito: https://console.aws.amazon.com/console/home e registrarsi.

Nota bene: vi verrà richiesto di inserire i dati della vostra carta di credito per procedere. Potete tranquillamente farlo in quanto serve ad Amazon per addebitarvi eventuali costi se sforate il limite di chiamate del servizio. Siccome il servizio è usato esclusivamente da voi, è impossibile sforare tale limite. Questa opzione è stata pensata per addebitare i costi delle chiamate AWS nel caso steste creando un’applicazione commerciale distribuita a centinaia/migliaia di utenti dove sicuramente il limite sarebbe raggiunto. Quindi, essendo una vostra app personale, potete stare sereni!

Una volta loggati, selezionate il menu Servizi in alto e cercate il servizio IAM sotto Sicurezza, identità, conformità.

Nella nuova pagina che si apre, selezionate Ruoli e poi Crea ruolo

Nella nuova pagina selezionare Servizio AWS, poi Lambda e cliccare Successivo: Autorizzazioni

Nella pagina che si apre, inserire nell’input di ricerca: DatabaseAdministrator
Selezionare il checkbox e cliccare Successivo: Tag

Ignorare la configurazione della pagina TAG e andare avanti.

Nella prossima pagina inserire nel campo Nome ruolo: lambda_basic_execution e cliccare Crea ruolo

Creato il ruolo, tornare nel menu Servizi e selezioniamo Lambda sotto la voce “Calcolo”

Selezioniamo ora dal menu in alto a destra Irlanda e clicchiamo Crea funzione

Nota bene: la selezione Irlanda è importantissima, non selezionate altri paesi!

Nella prossima schermata selezionate Crea da zero e compilate i campi:

• Nome: haaska
• Runtime: Python 3.8
• Ruolo: Selezionare un ruolo esistente
• Ruolo esistente: lambda_basic_execution

E cliccate Crea funzione

Nella nuova pagina che appare, scendere fino alla sezione Codice

A destra, utilizzare il bottone Carica da -> File .zip

Utilizzate il seguente file, scaricabile da qui.

Per salvare, utilizzare il bottone DEPLOY

Nella sezione sotto Impostazioni di runtime assicurarsi di settare il campo Gestore in: haaska.event_handler

Ora fate doppio click su config.json presente nella colonna di sinistra e modificate come richiesto:

url: https://lamiacasa.duckdns.org:443/api (sostituite lamiacasa con il vostro dominio duckdns). Utilizzate 443 oppure 8123 in base al portforwarding effettuato sul vostro router

bearer_token: (il vostro token di lunga vita generato in Home Assistant a inizio guida e vi siete segnati su un blocco note)

ssl_verify: false

e cliccate DEPLOY.

Tornare ad inizio pagina nella sezione Designer ed aggiungere il trigger Alexa Smart Home

Nel campo ID applicazione inserite l’ ID (Your Skill ID) che avete recuperato qui.

Cliccare infine su Aggiungi

Salvare di nuovo con il pulsante Salva in alto a destra della pagina.

Sempre in alto del pulsante Salva è presente una stringa denominata ARN simile a questa:

arn:aws:lambda:eu-west-1:xxxxxxxxxxxx:function:haaska

Copiatevi la vostra personalizzata in un blocco note perchè servirà più avanti. Lasciate infine aperta anche questa finestra del browser.

Riapriamo la scheda del browser a cui eravamo fermi con questa schermata:

Copiamo quindi nei campi Default endpoint* e nel campo Europe, India la stessa stringa ARN segnata in precedenza.

Cliccare quindi su Save

Clicchiamo ora dal menu di sinistra ACCOUNT LINKING e compilare i campi:

• 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 del proprio profilo di sicurezza qui
• CLIENT Secret: il valore CLIENT SECRET del proprio profilo di sicurezza qui
• Client Authentication Scheme: HTTP BASIC (Recommended)
• Cliccare su + Add Scope e inserire profile

Cliccare su Save

A fondo pagina appariranno 3 indirizzi alla voce Alexa Redirect URLs, copiateveli in un blocco note e lasciate aperta questa finestra.

Tornate quindi alla pagina aperta del vostro profilo di sicurezza, cliccare Modifica ed inserire nella sezione URL di ritorno consentiti i 3 Alexa Redirect URLs appena recuperati dal punto precedente.

Salvate.

TESTIAMO IL TUTTO

Aprire di nuovo la scheda del browser dove avete configurato la funzione lambda e clicchiamo su TEST

Nella finestra che si apre diamo un nome Test e nel campo del codice cancelliamo il testo presente e incolliamo:

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

Clicchiamo su Crea e nella pagina principale clicchiamo di nuovo su TEST

Se tutto è andato a buon fine dovreste ricevere una schermata sotto il codice, simile a questa:

Se invece ricevete qualche errore del tipo “HomeAssistant 500 Internal Server Error” è molto probabile che ci sia qualche script/automazione/entità o altro all’interno del vostro Home Assistant che sia incompatibile con Haaska o malconfigurata (caso tipico con i componenti climate). A questo punto è consigliato procedere a step ed includere solo i dispositivi di cui abbiamo veramente bisogno. Possiamo quindi andare a modificare il nostro configuration.yaml in:

alexa:
  smart_home:
    locale: it-IT
    endpoint: https://api.eu.amazonalexa.com/v3/events
    client_id: IL_VOSTRO_CLIEND_ID
    client_secret: IL_VOSTRO_CLIENT_SECRET
    filter: 
      include_domains:
        - switch
        - light
      exclude_domains:
        - automation

IL_VOSTRO_CLIEND_ID e IL_VOSTRO_CLIENT_SECRET sono quelli recuperati dal profilo sicurezza

Come vedere è stata aggiunta l’opzione filter che permette appunto di filtrare ciò che vogliamo che Alexa possa vedere:

• include_entities: elenco di ID degli unici device da esporre alla Skill
• include_domains: elenco dei domini (light, switch, sensors, ecc…) da esporrre alla Skill
• exclude_entities: elenco di ID degli unici device da NON esporre alla Skill
• exclude_domains: elenco dei domini (light, switch, sensors, ecc…) da NON esporre alla Skill

Nell’esempio ho escluso tutte le automazioni, e incluso solamente gli interruttori e le luci.

E’ inoltre possibile configurare i nomi di alcune entità in modo da far apparire un “nome amichevole” direttamente da app Alexa durante il discovery dei dispositivi, senza quindi che lo mettiate voi in manuale dentro l’app Alexa.

Come si fa? Aggiugendo l’opzione entity_config sullo stesso livello (indentazione) di filter:

filter:
  ...
# configurazioni opzionali per entità
entity_config:
  switch.pulsante_camera_main:
  name: Pulsante cameretta
  description: Pulsante principale della cameretta

ABILITAZIONE DELLA SKILL

Terminato il test, ora possiamo aprire l’app Alexa dal nostro telefono e nella sezione Skill -> Le mie skill selezionare ed abilitare la vostra Skill appena creata (haaska).

Fatto ciò potete fare Ricerca dispositivi e in 45 secondi appariranno tutte le entità presenti su Home Assistant