Praten met je Home Assistant installatie via Google Home – deel 2

Tijd voor deel 2 van de serie berichten over het praten met je Home Assistant installatie via Google Home. Als je deel 1 van gisteren nog niet gelezen hebt, doe dat dan eerst even. Anders wordt het heel moeilijk om te volgen.

Als je deel 1 gelezen hebt, dan weet je inmiddels dat er een aantal manieren zijn waarom je een koppeling kunt hebben tussen je Google Home (Mini).

Home Assistant Cloud
Laat ik beginnen met Home Assistant Cloud, een dienst waar ik zelf (nog) geen ervaring mee heb. Dat maakt het wat ongemakkelijker voor me om er uitspraken over te doen, maar ik lees vooral dat het gewoon werkt en als ik de info lees dan lijkt het ook een stuk gemakkelijker qua setup dan de handmatige manier. Je kunt het gratis een maand testen, daarna €5,- per maand, dus als je denkt “ik zie al dat zelf installeren niet zitten” is het zeker iets om uit te proberen. In onderstaande video kun je zien hoe je Home Assistant Cloud kunt installeren en configureren:

https://www.youtube.com/watch?v=lAadTeTr-hI

Met de setup kun je standaard zaken doen: lampen of schakelaars aan/uit zetten en alle apparaten aansturen die standaard door het home automation deel van Google Assistant worden ondersteund.

Ik ben voor de handmatige setup gegaan en zoals gezegd die is wat ingewikkelder. In de rest van het bericht ga ik uit van die setup.

Handmatige setup – deel 1
 Ik heb de procedure die hier beschreven is gebruikt. Omdat het voor mij de eerste keer was ben ik gestart bij “First time setup”. Voordat ik er mee aan de slag kon moest ik zorgen voor een https:// verbinding met Home Assistant. Dat gaat heel gemakkelijk met de DuckDNS component. Daarna kon ik de beschreven stappen volgen.

Helaas werkt dat om niet duidelijke reden niet altijd voor iedereen. Ik vrees dat ik daar niet heel erg bij kan helpen.  Ik heb al een vraag binnen gekregen van iemand die mijn configuration.yaml wilde zien.

Die heb ik gedeeld maar dat hielp niet, want daar staat niet zo heel veel spannends in. En ik weet niet waarom het blijkbaar regelmatig niet werkt.  Sorry.
Met deze setup kun je ook nu de standaard dingen doen: in de Google Home app op iOS of Android kun je je schakelaars en lampen zien en deze schakelen.

Maar ik wilde meer. Ik wilde de luchtvochtigheid kunnen opvragen of vragen wie thuis is of niet (op basis van de aanwezigheid van ieders smartphone). En daarvoor moest ik een app ontwikkelen voor Google Assistent waarbij ik in vragen voor Home Assistent met behulp van Dialogflow kon beantwoorden.

Handmatige setup – deel 2
Ook voor Dialogflow staat een configuratiebeschrijving online. Je moet eerst de component activeren. Dat kan heel simpel door dialogflow: toe te voegen aan configuration.yaml en Home Assistant opnieuw op te starten. Dan volg je de stappen die hier staan.

Niet vergeten, aan de Home Assistant kant moet je de webhook nog configureren bij Instellingen > Integraties.

Die URL voor je webhook heb je straks nodig in Dialogflow om aan de omgeving te vertellen waar de variabelen naar toe doorgestuurd moeten worden. De URL  heb je straks nodig in het onderdeel Fulfillment in Dialogflow (zie de afbeelding hieronder). Daar komen we nog bij terug.

Ik kon niet zo snel vinden of ik de URL na het aanmaken nogmaals kon opvragen. Sla hem dus meteen even op, anders moet je een nieuwe aanmaken.
Let op! Het gaat hier dus niet of een url met het oude API-wachtwoord van Home Assistant er in.

In de config map van je Home Assistant server maak je een bestand aan met de naam intent.yaml. Hierin neem je uiteindelijk de code op die de variabelen vanuit Dialogflow ontvangen en de response in tekst terug geven.

Aan de slag in Dialogflow
Tijd om te gaan bouwen in Dialogflow. Maar daarvoor beginnen we niet in Dialogflow zelf maar bij de Actions console van Google die je kunt vinden op https://console.actions.google.com/
Ik kan niet meer eenvoudig achterhalen wat je exact de eerste keer moet doen als je daar toegang toe wilt hebben, meestal is het krijgen van toegang met een gmail-account eenvoudig.

Ik heb er al twee actions, voor dit bericht ga ik een nieuwe aanmaken zodat je mee kunt volgen. Klik dus op Add/import project.

Geef het project een logische naam. We gaan een app maken die je verteld hoe lang je moet reizen afhankelijk van het gekozen vervoermiddel. Ik kies als projectnaam “Mijn persoonlijke routeplanner” zodat ik straks kan zeggen “Hey Google, praat met mijn persoonlijke routeplanner”, maar je kunt zelf een naam kiezen. Zet de standaard taal op Nederlands en land op Nederland. Klik op Create Project.

Er wordt nu een nieuw project aangemaakt. Dat kan even duren. De eerste pagina die je dan ziet heeft als optie “Decide how your Action is invoked”. Klik op deze link.

Voeg als naam ook in “Mijn persoonlijke routeplanner” en klik op “Save”.

 
Kies nu aan de linkerkant “Actions” en dan “ADD YOUR FIRST ACTION”. We gaan voor de default, de CUSTOM action, dus klik meteen op BUILD.

Omdat ik al eerder ingelogd ben in Dialogflow, ga ik meteen door en wordt er een nieuwe “agent” aangemaakt “Mijn-persoonlijke-routeplanner”, het kan zijn dat jij nog meldingen krijgt om een account aan te maken. Verander default language naar Dutch – nl en klik op CREATE.

Boven in het scherm staat (op dit moment) een melding: Dialogflow API V1 will be deprecated on October 23rd, 2019. Learn how to migrate to API V2 here.

Die melding is voor ons relevant, maar klik hem met DISMISS voor nu toch  nog maar even weg.

Onze app is aangemaakt. Binnen deze applicatie hebben we te maken met drie belangrijke concepten: 

1. Entities: dit zijn de variabelen die je wilt doorgeven aan Home Assistant.
2. Intents: dit zijn de “bedoelingen” van de gebruiker. Of in beter Nederlands: de gebruiker wil wat van je
3. Context: zie het als een verzameling voor de variabelen die bij elkaar horen.

Voor deze eenvoudige test gebruiken we alleen 1 en 2, context laten we voor deel 3.

Een eenvoudige test
De eenvoudige test omvat een app met één intent die reageert als de gebruiker vraag hoe lang het reizen is als je een bepaald vervoersmiddel gebruikt. De intent gaat nog niets daadwerkelijk opzoeken, maar laat wel de dialoog zien. We willen dat de gebruiker aan de app kan vragen “Hoe lang doe ik er over met de auto?” of “Hoe lang reizen is het met de fiets?” waarbij dan in een echte situatie de app een antwoord zou geven met daarin de reistijd. Voor nu laten we de app alleen de keuze voor het vervoersmiddel herhalen.

Daarvoor hebben we een intent nodig en zullen we een variable voor het vervoersmiddel definiëren bij de entities.

De entities zijn de variabelen die ik in Dialogflow kan gebruiken om de gebruiker te antwoorden en die (in de volgende stap) naar mijn script op Home Assistant worden doorgestuurd en door de synoniemen kan ik de gebruiker veel vrijheid geven, terwijl ik toch maar een beperkt aantal opties aan de kant van Home Assistant hoef af te dekken. Neem dit voorbeeld van de reistijd. Stel, we willen de app de reistijd laten opzoeken met behulp van Google Maps, dan maakt het niet uit of ik zeg dat ik met de “bus” of “trein” kom, dan hebben we alleen de optie “openbaar vervoer”. Idem voor de fiets, Google Maps maakt geen verschil tussen reistijd met een “racefiets”, “ligfiets” of een gewone “fiets”. En in plaats van dat we ons script op de Home Assistant straks alle synoniemen hoeven te laten verwerken, kunnen we dat hier al meteen in Dialogflow doen.

Kijk naar de afbeelding hierboven en voeg een entity “Voertuig” toe met een aantal synoniemen. Vergeet niet op “Save” te drukken.

Het tweede onderdeel, de intents, bevatten de dialogen met de gebruiker. Een eenvoudige dialoog is de “Default Welcome Intent”, die doet niet heel veel. Hij geeft een statische tekst door, zoals “Hallo, wat wil je weten van Home Assistant?” of “Goedendag, Home Assistant is er klaar voor!” (Dialogflow kiest zelf welke). Een andere “Default Fallback Intent” bevat de standaard antwoorden (en vervolgacties) voor het geval Dialogflow niet begrijpt wat de gebruiker zegt.

De intent die wij gaan maken doet ook nog niet zoveel. Hij herhaalt de keuze van de gebruiker. Het eerste dat we invoeren zijn trainingszinnen, voorbeeldzinnen voor Dialogflow om te leren welke soort teksten de gebruiker zou kunnen gebruiken om dit intent te triggeren (“als je dit soort teksten binnenkrijgt van Google Assistant, dan moet je deze intent starten”).  Maak een intent en noem hem HoeLangIsDeReistijd. Voeg een eerste trainingszin in, “Hoe lang doe ik er over met de bus?”

Zodra je die zin invoert zie je dat DialogFlow twee van de woorden (“de” en “bus”) een kleur geeft. De eerste “de” is een ‘foutje’, wij bedoelen er het lidwoord mee, DialogFlow denkt dat we de taalafkorting voor Duits bedoelen. Maar de tweede (“bus”) is wel gewenst, DialogFlow heeft namelijk al meteen gezien dat dit verwijst naar de entity “Voertuig”.

Voeg nog een aantal extra trainingszinnen in (zie hierboven voor voorbeelden). Ook hier zie je steeds kleurtjes verschijnen als Dialogflow mogelijke variabelen herkent in je zinnen.

Als je iets omlaag scrolt op de pagina naar Actions and parameters dan zie je daar in ieder geval de parameter “Voertuig” die verwijs naar de entity “@Voertuig” en waarvan je de waarde in je eigen scripts kunt gebruiken door gebruik van “$Voertuig”. Laten we dat eens proberen. Scroll nog wat verder naar beneden naar de Responses.

Vul hier een paar antwoordzinnen in waarbij je gebruik maakt van $Voertuig om naar de herkende waarde te verwijzen (zie afbeelding), dus bijvoorbeeld “OK, je wilt weten hoe lang je er over doet om hier te komen met $Voertuig”. Sla de intent op en test hem in het venster aan de rechterkant van je scherm. Als het goed is krijg je nu al een antwoord terug op je vragen.

Zoals je ziet krijg je niet de exacte term terug die je gebruikt. In het voorbeeld vraag ik naar “de trein”. Dat was een synoniem voor “het openbaar vervoer” binnen de entity Voertuig. Dat is dan ook de waarde die Dialogflow gebruikt als je $Voertuig in je antwoord gebruikt.

Verplichte waarden
Voor ons gesprek is het noodzakelijk dat er een keuze voor een vervoersmiddel doorgegeven wordt. Als de gebruiker alleen vraagt “Wat is de reistijd?” dan willen we dat er een vervolgvraag gesteld wordt “Met welk vervoersmiddel wil je reizen?” of zoiets (ook hier kun je verschillende opties invoeren die willekeurig gekozen worden).

Om dit voor elkaar te krijgen moet je het vinkje aanzetten bij “Required” voor de parameter “Voertuig”. Er komt dan automatisch een nieuwe kolom bij voor de prompt. Klik daar op en voer een of enkele vragen in (zie hierboven) die je wilt stellen als er geen vervoersmiddel herkend is in de vraag. Klik op Close als je klaar bent

Variabele verwijderen
Nu we hier toch zijn kunnen we ook wel meteen de parameter voor taal verwijderen (bij mij herkende hij er zelfs twee  “language” en “language1”). Klik op de drie puntjes helemaal rechts op de rij van de parameter die je wilt verwijderen. Je krijgt een heftige waarschuwing, maar die kun je negeren.

Koppelen aan Home Assistant met een webhook

Als laatste stap van deel 2 gaan we de koppeling met Home Assistant testen. We willen dat het antwoord niet in Dialogflow samengesteld wordt, maar willen de ingevulde waarde doorgeven aan Home Assistant en dan van Home Assistant een antwoord terug krijgen dat we dan weer aan de gebruiker doorgeven. Dat stelt ons later (in deel 3) in staat om sensoren waar Home Assistant toegang toe heeft (en Google Assistant of Dialogflow niet) uit te lezen en de waarde terug te geven.

Om de webhook te kunnen gebruiken moeten we de url die we van Home Assistant gekregen hebben bij het configureren van Dialogflow toevoegen aan de app.  Klik daarvoor in het linkermenu op Fullfilment en plak de url in.

[11-12-2018] Versie 1 van de API !!!
Op dit moment kan Home Assistant nog niet overweg met Versie 2 van de API die door Dialogflow gebruikt wordt. Die versie is echter wel de default.

We moeten dat dus aanpassen. Klik op het tandwieltje naast de naam van je app en kies voor V1 van de API. Klik op Save.

Op de Home Assistant server moeten we er voor zorgen dat er een antwoord gegeven wordt als Dialogflow de waarde voor Voertuig doorgeeft. Dat doe je door in Dialogflow een Action op te geven die verwijst naar een reactie in het bestand intent.yaml
Wij zullen als naam voor de action de naam van de intent gebruiken “HoeLangIsDeReistijd”. Dat hoeft niet, maar ik vind het eenvoudiger om zo de juiste terug te vinden. In het bestand intent.yaml staan namelijk alle actions die je wilt gebruiken bij de verschillende intents of zelfs verschillende apps.

Hierboven zie je de structuur van de code in intent.yaml. Eerst wordt de naam van de action gegeven met een dubbele punt erachter (“HoeLangIsDeReistijd:”). Daaronder zie je de afhandeling van het antwoord. Hou er rekening mee dat in yaml de witruimte voor de tweede en derde regel belangrijk zijn. Je kunt naar de waarde van de parameter die door Dialogflow doorgegeven wordt verwijzen met (in dit geval) {{ Voertuig }} (hoofdlettergevoelig!)

Als je de intent.yaml aangepast hebt moet je Home Assistant opnieuw opstarten. Dat kan vanuit de browser via Instellingen > Algemeen

De laatste stap is het activeren van de webhook in de intent. Vul eerst de naam van Action in

Vul bij Action and parameters boven de tabel met de parameters in “HoeLangIsDeReistijd” (hoofdletter gevoelig), dus de naam die je in intent.yaml gebruikt hebt. Onder de opties voor het invullen van responses, staat een schuifje waarmee je het gebruik van de webhook aan kunt zetten “Enable webhook call for this intent”.

Sla de wijzigingen op en test de intent weer aan de rechterkant in de dialoog. Als het goed is krijg je daar nu een antwoord met de tekst zoals je die in intent.yaml gebruikt hebt:

Hoera! We hebben nu een functionerende maar nog steeds nutteloze intent geproduceerd die gebruik maakt van onze Home Assistant server om een (nutteloos) antwoord te geven op onze vraag.

Probeer nu ook eens de optie “See how it works in Google Assistant” (onder het vak waar je de tekst invoert).
Er wordt dan een nieuw venster geopend. Hier kun je met tekst of audio de dialoog uitproberen. Zie de gif hieronder.

Zet de “Surface” eerst op “Speaker”. Je ziet in het voorbeeld dat onze app al in staat is om verschillende antwoorden aan elkaar te koppelen. Vraag je gewoon alleen naar de afstand, dan krijg je de vraag naar het vervoersmiddel. Je hoeft dan niet de hele zin te herhalen om een antwoord te krijgen.

Het kan even duren voordat de app gesynchroniseerd is naar je andere devices, maar je moet de app dan ook op je telefoon in Google Assistant of op je Google Home Mini kunnen gebruiken. Omdat je de app niet gepubliceerd hebt is hij nog niet door anderen te gebruiken.

In deel 3 gaan we met contexten aan de slag om ingewikkeldere, samengestelde antwoorden te onthouden.
Ik verwacht dat dat gemakkelijker is voor je als deze eerste twee stappen want de basisbeginselen zouden nu helder moeten zijn.