Integrate Alexa su Home Assistant tramite hasska

GUIDA AGGIORNATA QUI: https://www.domoticadiy.it/2021/01/integrare-alexa-su-home-assistant-tramite-hasska-aggiornamento-gennaio-2021/

Esistono 2 modi per integrare Amazon Alexa su Home Assistant:

• a pagamento (5 euro al mese) tramite il servizio Nabu Casa;
• gratis, tramite un servizio chiamato haaska

In questa guida andremo ovviamente a spiegare tutti i passaggi da effettuare per ottenere il servizio gratis. Armatevi di pazienza perchè la guida sarà lunghetta!

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.7
• Ruolo: Selezionare un ruolo esistente
• Ruolo esistente: lambda_basic_execution

E cliccate Crea funzione

Nella nuova pagina che appare, scendere a metà circa e trovare la sezione Codice della funzione

Nella colonna di sinistra, all’interno della cartella contenente il nome della vostra funzione, create un file (se non è già presente) di nome lambda_function.py

Selezionatelo e nell’editor di codice a destra copiate ed incollate il codice che potete trovare a questo indirizzo ma che per comodità riporto qui di seguito:

#!/usr/bin/env python3.7
# coding: utf-8

# Copyright (c) 2019 Unai Uribarri <unaiur@gmail.com>
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

import os
import json
import logging
import ssl
from http.client import HTTPSConnection, RemoteDisconnected

HOST = os.environ['HOST']
PORT = int(os.environ.get('PORT', default='443'))
BEARER_TOKEN = os.environ['BEARER_TOKEN']
AWS_REGION = os.environ.get("AWS_DEFAULT_REGION")

LOGGER = logging.getLogger()
if os.environ.get('DEBUG'):
        LOGGER.setLevel(logging.DEBUG)

SSL_CONTEXT = ssl.create_default_context()
if os.environ.get('SSL_VERIFY', default = True):
    SSL_CONTEXT.verify_mode = ssl.CERT_REQUIRED
    SSL_CONTEXT.check_hostname = True
else:
    SSL_CONTEXT.check_hostname = False
    SSL_CONTEXT.verify_mode = ssl.CERT_NONE

CONNECTION = HTTPSConnection(HOST, PORT, context = SSL_CONTEXT)
HEADERS = {
    'Authorization': f'Bearer {BEARER_TOKEN}',
    'content-type': 'application/json',
    'User-Agent': f"HAASKA-Lite in {AWS_REGION}"
}
URL = '/api/alexa/smart_home'
            

def handle_event(event, num_attempt = 1):
    try:
        LOGGER.debug(f'Received event: {event}')
        CONNECTION.request('POST', URL,
            body = json.dumps(event).encode('utf8'),
            headers = HEADERS)
        response = CONNECTION.getresponse()
        if response.status != 200:
            LOGGER.error(f'HomeAssistant error {response.status} {response.reason}')
            return None
        return json.loads(response.read())
    except RemoteDisconnected:
        LOGGER.info("HomeAssistant closed the connection.")
        CONNECTION.close()
        if num_attempt >= 3:
            return None
        LOGGER.debug(f"Attemp {num_attempt} failed. Retrying...")
        return handle_event(event, num_attempt + 1)


def event_handler(event, context):
    try:
        return handle_event(event)
    except Exception:
        # Allow response timeouts after request was sent
        LOGGER.exception('Internal error calling HomeAssistant')
        CONNECTION.close()
        return None

Assicuratevi che il campo Runtime sia settato su Python 3.7

Nel campo Gestore dovete scrivere lambda_function.event_handler

Cliccare quindi su Salva.

Ora spostatevi un po’ più in basso nella sezione Variabili di ambiente, cliccate Modifica ed inserite i seguenti campi:

HOST : lamiacasa.duckdns.org (sostituite lamiacasa con il vostro dominio duckdns)
PORT : 8123 (o in base alla vostra porta utilizzata se l’avete cambiata)
BEARER_TOKEN : (il vostro token di lunga vita generato in Home Assistant a inizio guida e vi siete segnati su un blocco note)

e salvare.

Spostarsi ancora più in basso in Ruolo di esecuzione, selezionare Utilizza un ruolo esistente e selezionare sotto lambda_basic_execution

Salvare di nuovo.

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 Configura eventi di 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 su Esegui il 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:
    filter: 
      include_domains:
        - switch
        - light
      exclude_domains:
        - automation

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