Amazon Alexa Smart Home Skill

01

Požadavky

Než začnete, připravte si vlastní Amazon účet používaný na zařízeních Echo nebo v aplikaci Alexa. Se stejným účtem vytvoříte Amazon Developer skill. Dále budete potřebovat vlastní AWS účet pro Lambda funkci, která předává požadavky z Alexy do RichPear Home.

RichPear Home musí být z internetu dostupný přes HTTPS na portu 443 s důvěryhodným certifikátem. Samopodepsaný certifikát nestačí. Lokálně můžete RichPear Home dál otevírat na http://rphome.local:8123, případně http://IP-ADRESA:8123, ale pro Alexu použijte veřejnou HTTPS adresu bez koncové lomítka.

02

Vytvoření Amazon Alexa Smart Home skillu

1. Otevřete Alexa Developer Console a přejděte na stránku Alexa Skills.
2. Zvolte Create Skill, vyplňte název a vyberte výchozí jazyk skillu.
3. Jako model zvolte Smart Home a jako hostování Provision your own.
4. Po vytvoření zkontrolujte, že je vybraná verze payloadu v3, a poznamenejte si Skill ID. Budete ho potřebovat v AWS Lambda.

Výchozí jazyk skillu musí odpovídat tomu, jak používáte Alexu. Volba jazyka ovlivňuje i region AWS Lambda, který vyberete v dalším kroku.

03

Vytvoření AWS Lambda funkce

V AWS vytvořte nejdřív IAM roli pro Lambda běh. Pro základní zápis do CloudWatch logů stačí spravovaná politika AWSLambdaBasicExecutionRole. Potom v konzoli Lambda založte novou funkci z volby Author from scratch, runtime nastavte na aktuální Python 3 a jako execution role vyberte právě vytvořenou roli.

Region Lambda zvolte podle jazyka skillu, ne podle fyzické polohy serveru:

• US East (N. Virginia): Arabic (SA), English (CA), English (US), French (CA), Portuguese (BR), Spanish (MX), Spanish (US).
• EU (Ireland): Dutch (NL), English (IN), English (UK), French (FR), German (DE), Hindi (IN), Italian (IT), Spanish (ES).
• US West (Oregon): English (AU), Japanese.

Do funkce přidejte trigger Alexa Smart Home a vložte Skill ID z Developer Console. Kód Lambda funkce má přijmout Alexa Smart Home direktivu, připojit autorizační token a předat požadavek na veřejnou adresu RichPear Home endpointu /api/alexa/smart_home.

V nastavení prostředí Lambda funkce doplňte proměnné:

• BASE_URL: veřejná HTTPS adresa RichPear Home bez koncového lomítka.
• DEBUG: nastavte na True jen při ladění.
• LONG_LIVED_ACCESS_TOKEN: používejte pouze dočasně pro ladění Lambda volání a po dokončení ho odstraňte.
• NOT_VERIFY_SSL: nepoužívejte v běžném provozu; Alexa pro propojení účtu vyžaduje důvěryhodný certifikát.

Po uložení nasaďte kód tlačítkem Deploy a zkopírujte ARN funkce. ARN vložíte zpět do nastavení skillu jako výchozí endpoint.

04

Nastavení endpointu a propojení účtu

V Alexa Developer Console otevřete vytvořený skill, přejděte do části Smart Home a do pole Default endpoint vložte ARN Lambda funkce.

V části Account Linking ponechte vypnutou volbu pro propojení z vlastní aplikace nebo webu a nastavte OAuth údaje pro veřejnou adresu RichPear Home:

Authorization URI: https://VAŠE-DOMÉNA/auth/authorize
Access Token URI: https://VAŠE-DOMÉNA/auth/token
Client ID pro Evropu: https://layla.amazon.com/
Client ID pro USA a Brazílii: https://pitangui.amazon.com/
Client ID pro Japonsko a Austrálii: https://alexa.amazon.co.jp/
Client Secret: libovolná vlastní hodnota
Authentication Scheme: Credentials in request body
Scope: smart_home

Lomítko na konci hodnoty Client ID je důležité. Pole Domain List a výchozí expiraci access tokenu můžete nechat prázdné.

Po uložení otevřete v aplikaci Alexa nabídku More → Skills & Games → Your Skills → Dev, vyberte vytvořený skill a zapněte ho. Přihlaste se do RichPear Home účtem, který má přístup k ovládaným entitám. Po úspěšném přihlášení spusťte vyhledání zařízení v Alexa aplikaci nebo hlasovým příkazem „Alexa, discover devices“.

05

Konfigurace v RichPear Home

Minimální konfigurace zpřístupní podporované entity Alexe. V praxi je bezpečnější začít úzkým filtrem a přidávat jen zařízení, která opravdu chcete ovládat hlasem.

alexa:
  smart_home:
    locale: en-GB
    filter:
      include_entities:
        - light.kitchen
        - switch.coffee_machine
      exclude_entities:
        - switch.outside
    entity_config:
      light.kitchen:
        name: Kitchen light
        description: Light in the kitchen
      cover.garage_door:
        display_categories: GARAGE_DOOR

Hodnota locale má odpovídat jazyku a regionu vašich Alexa zařízení. Podporované hodnoty jsou de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, it-IT, ja-JP, nl-NL a pt-BR.

Filtr podporuje konkrétní entity, domény i vzory s * a ?. Pokud definujete jen zahrnutí, vše ostatní se skryje. Pokud definujete jen vyloučení, vše ostatní zůstane dostupné. U zámků, garážových vrat, kamer a alarmů ponechte správnou kategorii zařízení, jinak Alexa nemusí nabídnout všechny funkce nebo bezpečnostní potvrzení.

06

Podporované entity a omezení

Alexa umí pracovat hlavně s běžnými ovládacími prvky domácnosti: světla, vypínače, scény, skripty, klimatizace a termostaty, ventilátory, zvlhčovače, rolety a garážová vrata, zámky, kamery, mediální přehrávače, vysavače, číselné hodnoty, časovače, ventily, alarmové panely a vybrané senzory.

Některé funkce vyžadují přesný typ entity nebo další vlastnosti. Teplotní senzory lze číst hlasem, světla mohou podporovat jas, barvu a teplotu bílé, ventilátory rychlost nebo oscilaci, rolety pozici a náklon. Odemknutí zámku a otevření garážových vrat vyžaduje čtyřmístný hlasový PIN nastavený v Alexa aplikaci.

Pro rutiny, oznámení zvonku, změny stavu senzorů a některé živé stavové informace je potřeba zapnout proaktivní události. V konfiguraci se k tomu používá endpoint podle regionu skillu:

• https://api.amazonalexa.com/v3/events pro Severní Ameriku.
• https://api.eu.amazonalexa.com/v3/events pro Evropu.
• https://api.fe.amazonalexa.com/v3/events pro Dálný východ a Austrálii.

07

Řešení problémů

Pokud propojení účtu selže, zkontrolujte veřejnou HTTPS adresu, port 443, certifikát, přesné OAuth adresy /auth/authorize a /auth/token, správný Client ID včetně koncového lomítka a volbu Credentials in request body.

Pokud Lambda vrací chybu autorizace, ověřte, že je skill v Alexa aplikaci znovu propojený s platným účtem RichPear Home. Dočasný dlouhodobý token v Lambda funkci používejte jen při ladění a po dokončení ho odstraňte.

Když Alexa nenajde zařízení, zkontrolujte filtr entit, názvy zařízení, podporované domény, region Lambda funkce, ARN ve skillu a logy v AWS CloudWatch. U binárních senzorů používaných v rutinách musí typ odpovídat podporované třídě, například dveře, okno, pohyb, garážová vrata nebo otevření.

Po změně konfigurace restartujte RichPear Home, potom v Alexa aplikaci zakažte a znovu povolte vlastní skill a spusťte nové vyhledání zařízení.