Google Assistant FHEM Connect

Google Assistant FHEM Connect
Zweck / Funktion
	Anbindung von FHEM an Google Assistant
Allgemein
Typ	Inoffiziell
Details
Dokumentation	siehe Forum
Support (Forum)	Frontends/Sprachsteuerung
Modulname	39_gassistant
Ersteller	dominik
	Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Egal ob iOS, Android, Google Home oder WearOS, mit FHEM Connect kannst du deine FHEM Geräte per Google Assistant und Google Home App (Google PlayStore, Apple AppStore) von überall aus steuern.

NEWS: FHEM Connect ist ab sofort offiziell in der Google Home App verfügbar!

Ich würde mich über positive Bewertungen von FHEM Connect freuen:

https://assistant.google.com/services/a/uid/0000000062f42fd8?hl=de

Feedback und Anregungen zur Unterstützung neuer Geräte bitte ich euch hier zu posten:

https://forum.fhem.de/index.php/topic,96696.0.html

News

28.03.2019

FHEM Connect ist offiziell in der Google Home App verfügbar

17.03.2019

gassistant-fhem < 1.3.0 wird nicht mehr unterstützt
genericDeviceType contact, security wird als switch angelegt
ROOMMATE, GUEST wird als light unterstützt (als light deshalb, weil das in der Home App gruppiert angezeigt wird)
Rolläden werden ebenfalls ab sofort unterstützt, sind aber nicht über die App steuerbar (da muss Google noch nacharbeiten)

Hintergrundinfos

FHEM Connect basiert auf Google Firebase, welches die Plattform für die Kommunikation mit Google bietet. Der lokal installierte fhemconnect Client kommuniziert mit Google Firebase und übermittelt von dort die Daten an Google. Das hat 3 große Vorteile:

Keine Portfreigaben notwendig
Kommunikation läuft gesichert über HTTPS und die Authentifizierung über Auth0 mittels OAuth2
Neue Funktionalitäten, wie zum Beispiel die Unterstützung von neuen Devices, sind immer gleich verfügbar sobald diese im Firebase Projekt implementiert wurden. Man muss also nicht regelmäßig aktualisieren um in den Genuss von neuen Google Assistant Features zu kommen.
Aktuell wird die Installation von dominik betrieben. Nur Google und dominik haben administrative Berechtigungen auf Firebase und könnten daher theoretisch beliebige FHEM Kommandos schicken.
Jeder User agiert in einem eigenen Bereich der Firebase Datenbank.
europe-west1-fhem-ga-connector.cloudfunctions.net ist dominiks Firebase Cloud Functions Endpoint für die Aufrufe der Funktionen.

Unterstütze Geräte

Google unterscheidet zwischen Traits und Device Types. Traits sind Funktionen (on/off, dimmen, ...) die ein Geräte beliebigen Typs unterstützen kann. Device Types dienen nur zur Darstellung in der Home App und der Steuerung über den Gerätetyp per Sprache (z.B. "Schalte die Waschmaschine ein", der Name der Waschmaschine muss nicht genannt werden).

Die gesamte Liste der von Google bereitgestellten Traits findet man hier: https://developers.google.com/actions/smarthome/traits/

Folgende Traits werden durch Google Assistant FHEM Connect unterstützt:

Brightness
ColorSetting
Dock
FanSpeed (nur Englisch)
Locator
Modes (nur Englisch)
OnOff
Scene
StartStop
TemperatureSetting
Toggles (nur Englisch)

Die gesamte Liste der von Google unterstützten Device Types findet man hier: https://developers.google.com/actions/smarthome/guides/ Der Device Type muss im Normalfall nicht über genericDeviceType gesetzt werden, da FHEM Connect diesen in den meisten Fällen automatisch erkennt.

Um ein einfaches dummy Device in Google Assistant zu integrieren, benötigt es nur ein on,off Command (nicht webCmd, sondern setList!!).

Attribute

Folgende Attribute werden von Google Assistant FHEM Connect genutzt:

genericDeviceType
assistantName (Name des Devices bei Google, soll zukünftig auch von anderen Assistenten benutzt werden)
gassistantName (Name des Devices bei Google)
realRoom (Raum welcher beim ERSTEN Synchronisieren an Google übergeben wird)
homebridgeMapping (Bitte nur verwenden, wenn es ohne homebridgeMapping nicht funktioniert)

Installation

FHEM Connect in der Home App

ACHTUNG: gassistant-fhem < 1.3.0 wird nicht mehr unterstützt, bitte auf die aktuelle Version aktualisieren!

Vorraussetzung: Raspbian/Debian stretch mit installiertem nodejs, jessie wird nicht supported
FHEM mit update all auf den letzten Stand bringen. FHEM muss zwingend aktuell sein. Letztes Update sollte nicht älter als 03.02.2019 sein.
gassistant-fhem installieren und einrichten:
Dazu auf der Konsole folgenden Befehl ausführen
```
sudo npm install -g gassistant-fhem --unsafe-perm
```
Connector in FHEM definieren:
Dazu in FHEM folgenden Befehl ausführen
```
define gassistant gassistant
```
Ca. 30s warten bis ein Reading gassistantFHEM.loginURL erscheint. Sollte der Link nicht erscheinen so kann man ihn auch über die Weboberfläche im device gassistant im Attribut loginURL nachschauen.
Link öffnen und einloggen
Den erhaltenen authcode in FHEM hinterlegen (set gassistant authcode ............)
Falls ihr euren Webzugriff mit einer Authentifizierung sichert, dann ist noch das gassistantFHEM-auth Attribut auf username:passwort zu setzen
Ein Testgerät (es sollte on/off unterstützen) in den Raum GoogleAssistant hinzufügen
Home App öffnen und FHEM Connect auswählen

Wenn ihr danach neue Geräte dem Raum hinzufügt, werden diese automatisch von Google verarbeitet. Es dauert teilweise eine Minute bis die neuen Geräte in der Home App erscheinen.

Bitte achtet darauf, dass die Geräte bereits vor dem Hinzufügen in den Raum richtig benannt sind. Eine Namensänderung (alias) muss sonst über einen reload getriggert werden.

Update

Es wird nur in seltenen Fällen ein Update benötigt, da der größte Teil der Anwendung in Firebase konfiguriert ist. Sollte der Client dennoch aktualisiert werden müssen, dann kann das mit folgenden Befehlen durchgeführt werden:

sudo npm install -g gassistant-fhem --unsafe-perm

gassistant über FHEM neu starten

Architektur

fhemconnect Client

Lokale installierter Client der die Verbindung zu FHEM herstellt.

Auth0

Auth0 wird sowohl von fhemconnect Client als auch von Google Assistant genutzt um den User zu authentifizieren. Damit erhält der User eine eindeutigen User ID.

Firebase ("zentralerer Server", obwohl es Server-less betrieben wird)

Firebase Firestore

Datenbank in welcher die Geräteinformationen gespeichert werden.

Firebase Realtime DB

Datenbank in welcher der aktuelle Status der Geräte gespeichert wird.

Firebase Cloud Functions

Die Cloud Function stellt einen Webaufruf im Internet zur Verfügung. Google ruft direkt eine solche Cloud Function auf. Des Weiteren wird diese auch für die Kommunikation vom fhemconnect Client zum Firebase Projekt ("Server") genutzt.

Die Dienste auth0 und Google Firebase wurden beide als EU Instanzen konfiguriert. Eure Daten liegen daher im EU Raum und unterliegen damit auch den EU Datenschutzvorgaben.

Datenfluss

Der Datenfluss und die Arbeitsweise von FHEM Connect wird anhand des folgenden Beispiels erklärt:

Bei der Verknüpfung des Google Accounts mit FHEM Connect wird der Service von auth0 herangezogen. Dieser authentifiziert den User und generiert einen Access und Refresh Token mit welchem Google sich gegenüber FHEM Connect (“dem zentralen Service”) authentifiziert.
Bei der Installation des fhemconnect Clients wird ebenso auth0 herangezogen. Der User wird auch dort über auth0 authentifiziert und damit kann sich auch fhemconnect am zentralen Service anmelden.
Durch dieses Verfahren kann FHEM Connect die User ID aus dem fhemconnect Client und die User ID die über Google kommt matchen und damit Befehle dem richtigen User zuordnen. Ein Faken dieser User ID ist nicht möglich, da der übertragene Token (JSON Web Token) signiert ist und bei jeder Übertragung von auth0 verifiziert wird.
Durch die Verknüpfung des Accounts weiß Google, dass es FHEM Connect gibt und es dorthin Smart Home Befehle schicken kann.
Ein Befehl wie "Schalte das Nachtlicht ein" wird von Google interpretiert
FHEM Connect (der zentrale Service der auf Firebase läuft) erhält den Befehl das Nachtlicht einzuschalten. Durch den von Google übertragenen Access Token, welcher die User ID beinhaltet, wird der User identifiziert.
FHEM Connect weiß durch die User ID, welche es dem verifizierten Access Token entnommen hat, welchem User der Befehl zuzuordnen ist und schickt dieser über Firebase an den fhemconnect Client.
Der fhemconnect Client schickt den Befehl direkt an FHEM weiter wo der Befehl ausgeführt wird.

FAQs

FHEM Connect funktioniert bei mir nicht und ich weiß nicht weiter

Kein Problem, ich helfe gerne weiter. Bitte folgende Informationen in diesem Thread posten:

Logfile (links oben im gassistant Device zu finden) von Start bis zum Erreichen des Fehlers
Ersten 3 und letzten 3 Stellen des Readings gassistant-fhem-uid (...|AAA....BBB)
Name (Internals NAME) des betroffenen Gerätes

Ich kann in der Home App manche Geräte nicht steuern

Google entwickelt die Home App laufend weiter. Manche Funktionen, die zwar über Sprache funktionieren, sind in der Home App noch nicht steuerbar (z.B. Rollos).

Ich erhalte den Fehler Error: Rate limit reached - too many requests

Einfach 5 Minuten warten bis ihr das nächste Mal auf reload klickt.

Ich erhalte die Meldung, dass für mein Gerät ein Software Update nötig ist.

In diesem Fall ist ein Update für gassistant-fhem notwendig. Der Updateprozess ist im Abschnitt Update beschrieben.

Geräte werden in Google Home doppelt angezeigt oder der Sprachassistent fragt welches der Geräte verwendet werden soll.

Man erkennt den Fehler auch in dem man im gassistant-fhem Log die EXECUTE Logs ansieht. Erscheinen diese zu einem Befehl mehrfach, so liegt das Problem an doppelten Geräten bei Google. Lösung: Am Abend die Account Verknüpfung in der Google Home App auflösen. Am nächsten Tag kurz nach 9 Uhr die Account Verknüpfung wiederherstellen.

FHEM ist durch Username und Password gesichert (401: Authorization Required)

gassistant-fhem.cfg im fhem Installationsordner mit user/pass und wenn nötig SSL erweitern

"connections": [
   {
       "name": "FHEM",
       "server": "127.0.0.1",
       "auth": {"user": "fhemuser", "pass": "fhempassword"},
       "ssl": true,
       "port": "8083",
       "filter": "room=GoogleAssistant"
   }
]

"Method Not Allowed" Fehlermeldung bei der npm Installation?

sudo npm install -g npm

Geräte erneut an Google übertragen

"Hey Google, synchronisiere meine Geräte" sagen

Wie kann meine Familie auf die Geräte zugreifen?

In der Home App kann man mit den + Symbol auch Familienmitglieder hinzufügen. Damit haben dann die Familienmitglieder in deren Home App ebenfalls Zugriff auf die Geräte.

Beim Starten kommt ein Fehler in dem "async" hervorgehoben ist.

Stelle sicher, dass du die aktuelle nodejs Version hast. Es sollte zumindest >= 8 sein (node -v liefert dazu die Antwort).

sudo apt update && sudo apt install nodejs

Ich möchte den Raum meiner Geräte nicht ändern

Man kann die Ermittlung der über Google verfügbaren Geräte auch über die group durchführen. Dazu muss dann in den Verbindungseinstellungen der filter room=GoogleAssistant durch zB group=ghomeDevice ersetzt werden. Eine weiteren Möglichkeit ist das Zuordnen von zwei Räumen in FHEM für ein Gerät zB attr MediacenterKodi room Wohnzimmer,GoogleAssistant

Ich möchte gassistant-fhem nicht global installieren oder habe nicht die Berechtigung dazu

Um gassistant-fhem nur Änderungen am Ordner, in dem es installiert wurde, machen zu lassen muss der Installationsbefehl

npm install gassistant-fhem

sein. Gestartet wird es dann aus dem Installationsordner mit dem Befehl node_modules/gassistant-fhem/bin/gassistant-fhem Die Konfigurationsdatei für die FHEM-Verbindung ist dann unter ~/.fhemconnect/config.json

Kostenlos

Aktuell wird der Service kostenlos betrieben. Abhängig von der Auslastung, könnte es zukünftig der Fall sein, dass die freien Limits bei Firebase und Auth0 überstiegen werden und damit Kosten anfallen. Solange das nicht der Fall ist, wird der Service kostenlos zur Verfügung gestellt.