Modul Babble: Unterschied zwischen den Versionen

Aus FHEMWiki
Zeile 183: Zeile 183:
  {speakEG(ReadingsVal('wunderground','fc'.(('$VALUE' eq 'übermorgen')?'2':(('$VALUE' eq 'morgen')?'1':'0')).'_message',' '))}
  {speakEG(ReadingsVal('wunderground','fc'.(('$VALUE' eq 'übermorgen')?'2':(('$VALUE' eq 'morgen')?'1':'0')).'_message',' '))}
Für das Beispiel verwenden wir eine Perl-Funktion namens ''speak(<speechdevice>,<text>)'', die nichts weiter macht, als auf einem der dazu fähigen Devices (hier ''speechdevice'') die zuständige TTS (Text-to-Speech) Funktion aufzurufen. Der Parameter ''$PARM0'' wird dabei durch denjenigen ersten Parameter ersetzt, den die Erkennungsfunktion mitgeliefert bekommen hat (siehe oben).
Für das Beispiel verwenden wir eine Perl-Funktion namens ''speak(<speechdevice>,<text>)'', die nichts weiter macht, als auf einem der dazu fähigen Devices (hier ''speechdevice'') die zuständige TTS (Text-to-Speech) Funktion aufzurufen. Der Parameter ''$PARM0'' wird dabei durch denjenigen ersten Parameter ersetzt, den die Erkennungsfunktion mitgeliefert bekommen hat (siehe oben).
[[Datei:Babble_Wetter.png|800px|]]

Version vom 19. Januar 2018, 19:07 Uhr

Babble
Zweck / Funktion
Das Modul stellt eine komfortable Oberfläche bereit, um per Webinterface ein 'Natural Language User Interface' (NLUI) zu konfigurieren
Allgemein
Typ Hilfsmodul
Details
Dokumentation EN / DE
Support (Forum) Unterstuetzende Dienste
Modulname 95_Babble.pm
Ersteller Prof. Dr. Peter A. Henning
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 95_Babble.pm.

Allgemeines

Das Modul 95_Babble.pm stellt eine komfortable Oberfläche bereit, um per Webinterface ein Natural Language User Interface (NLUI) zu konfigurieren.

Funktionsweise

Dieses Modul überprüft einen empfangenen natürlichsprachlichen Satz auf einen darin enthaltenen Orts-Identifikator, sowie auf eine Liste von vordefinierten Verben und Verbteilen. Ein weiteres darin enthaltenes Nomen wir je nach Artikeln und Verben als gerät identifiziert. Beispielsweise resultieren die beiden Eingabesätze

  • Schalte die Beleuchtung in der Sitzgruppe an
  • Beleuchtung in der Sitzgruppe anschalten

jeweils im gleichen Ergebnis:

Gerät=licht Ort=sitzgruppe Verb=schalten Ziel=ein

Der Gerätename (auch als Babble-Device bezeichnet) ist ein von der FHEM-Bezeichung unabhängiger Begriff, der aber eindeutig mit einem FHEM-Device verbunden sein muss. also z.B. Licht für eine Lightscene.

In einem mehrfach geschachtelten Daten-Hash wird anschließend unter der Adresse

$hash->{DATA}{"command"}{"licht"}{"sitzgruppe"}{"schalten"}{"ein"}

nachgesehen, ob dort ein FHEM-Kommando hinterlegt wurde. Dieses lautet im Beispiel set WZ.Scene scene Sitzgruppe und schaltet eine entsprechende Lightscene an.

Geräte

Die Verbindung von (Babble-)Gerätenamen mit real existierenden FHEM-Devices erfolgt im unteren Bereich des Web-Frontends. Solche Geräte können entweder lokal sein, (also derselben FHEM-Instanz angehören, wie das Babble-Device). Oder sie sind entfernte Geräte (remote).

  • Lokale Geräte sind dadurch gekennzeichnet, dass in ihrem FHEM-Device das Attribut babbleDevice auf den Wert des gewünschten Gerätenamens gesetzt wird (siehe Abschnitt Vorarbeiten).
    • Solche lokalen Geräte werden automatisch (d.h. ohne weitere nötige Vorarbeiten) in der Babble-Übersicht angezeigt.
  • Entfernte Geräte liegen in einer anderen FHEM-Instanz. Sie müssen im Attribut babbleDevices des Babble-Devices angegeben werden.
    • In der gegenwärtigen ersten Fassung des Moduls können drei solche anderen FHEM-Instanzen angegeben werden, dazu müssen die Attribute remoteFHEM(1|2|3) remoteFunc(1|2|3) gesetzt werden. Bei der tatsächlichen Ausführung eines Befehls (siehe Abschnitt Nutzung) werden diese Attribute berücksichtigt

Nutzung

Zur Nutzung durch beliebige andere FHEM-Module muss nur das Perl-Unterprogramm

 Babble_DoIt("Babble","<zu analysierender Satz>"[,parm0,parm1,...])

aufgerufen werden (Babble ist duch den tatsächlichen Device-Namen zu ersetzen). Die Anzahl der Parameter beim Aufruf ist nicht festgelegt, es kann eine beliebige Anzahl von Parametern im Aufruf angegeben werden.

Bei der semantischen Analyse werden identifiziert

  • ein (Babble-)Gerätename device
  • eine Ortsangabe place, diese darf auch leer bleiben (abgespeichert als Wert none)
  • ein Verb verb in der Infinitiv-Form
  • eine Zielvariable, ggf. ein Reading target
  • ein Zielwert value

Wird ein natürlichsprachlicher Satz korrekt interpretiert und ein dazu hinterlegtes Kommando (gespeichert im Babble-Hash $hash->{DATA}{"command"}) gefunden, werden in diesem Substitutionen durchgeführt.

  • der String $VALUE wird durch den Zielwert value ersetzt.
  • ein String $PARM[0|1|2..] wird durch den beim Aufruf übergebenen Wert parm0, parm1,... ersetzt.

Durch diesen Mechanismus kann man den auszuführenden Kommandos verschiedene Parameter mitgeben.

Anschließend wird dieses Kommando ausgeführt. Vor der Ausführung

  • Bei lokalen (Babble-)Geräten wird im Modul einfach
fhem(<Kommando>)

ausgeführt.

  • Bei entfernten (Babble-)Geräten gibt es zwei Möglichkeiten:
    • Wurde nur die IP-Adresse der entfernten FHEM-Instanz (im Attribut remoteFHEM(1|2|3)) angegeben, erfolgt die Ausführung durch den HTTP-Request
 http://<IP-Adresse:Port>/fhem?XHR=1&cmd.<FHEM-Device>=<Kommando>
    • Wurde zusätzlich zu IP-Adresse der entfernten FHEM-Instanz ein Funktionsname (im Attribute remoteFunc(1|2|3)) angegeben, erfolgt die Ausführung durch den Aufruf der Funktion
<remoteFunc(1|2|3)>("<Kommando>")

Babble-Device

Vorarbeiten

Will man lokale (d.h. in derselben FHEM-Instanz befindliche) Devices per Babble ansteuern, muss man vorher im Device global dem Attribut userAttr ein neues global verfügbares Attribut babbleDevice hinzufügen. Dieses wird damit für jedes FHEM-Device setzbar.

Installation

Dieser Abschnitt bleibt nur hier so lange wie Babble noch nicht per Update verteilt wird

WICHTIG: Nicht nur das Modul 95_Babble.pm installieren, sondern auch die Datei babble.js in /fhem/www/pgm2 !!!

Definition

Das Babble-Device - hier mit dem Namen Babble versehen - selbst wird über

define Babble Babble

definiert. Diese Definition legt einen versteckten Raum "babbleRoom" an, welcher über einen Weblink im oberen Menü des Webinterfaces erreichbar ist.

  • Der Name dieses Raumes kann durch das Attribut hiddenRoom geändert werden.
  • Dieses Modul verwendet das globale Attribut language zur Bestimmung der Anzeigedaten (Standard: EN=english). Für deutsche Ausgabedaten muss in FHEM das Attribut
attr global language DE

gesetzt werden. Für dieses Wiki werden die deutschen Ausgabedaten verwendet.

Beim Anklicken des Begriffes Babble (eben der genannte Weblink) im oberen Menü des Webinterfaces wird dieser versteckte Raum angezeigt. Er enthält an erster Stelle das Babble-Device. Für die Konfiguration dieses Devices siehe den nächsten Abschnitt, für die Bedienung siehe den Abschnitt [Bedienung].

Set-Befehle

Das Babble-Device kennt die folgenden Set-Befehle (Babble ist duch den tatsächlichen Device-Namen zu ersetzen):

set Babble locked | unlocked

Sperre oder entsperre das Überschreiben der persistenten Daten, siehe Sperrung.

set Babble save | restore

Speichere die Daten persistent, oder hole sie aus der betreffenden Datei babbleFile (Achtung für Nutzer der configdb: Das File wird in der Datenbank abgelegt, nicht im Dateisystem).

Get-Befehle

Das Babble-Device kennt die folgenden Get-Befehle (Babble ist duch den tatsächlichen Device-Namen zu ersetzen):

 get Babble version

Gibt die Versionsnummer des Moduls zurück

Attribute

Das Babble-Device benötigt zum Funktionieren unbedingt ein paar wichtige Attribute. Bei der ersten Definition sollten diese automatisch belegt werden, können aber jederzeit geändert werden.

  • babbleDevices ist eine durch Leerzeichen separierte Liste von Device-Identifikatoren in der Form
 <Babble Devicename>:<FHEM-Devicename>:<Ziffer> <Babble Devicename>:<FHEM-Devicename>:<Ziffer> ... <Babble Devicename>:<FHEM-Devicename>:<Ziffer>

Als Ziffer sind die Werte 1,2,3 erlaubt, sie teile Babble mit, um welche der gegenwärtig möglichen drei verschiedenen entfernten FHEM-Instanzens es sich handelt

  • babblePlaces ist eine durch Leerzeichen separierte Liste von Orts-Identifikatoren, die in der Sprachsteuerung erkannt werden sollen. Die in FHEM bekannten Rooms=Räume werden ebenfalls als Ortsbezeichnungen zur Verfügung gestellt und brauchen nicht in dieser Liste aufzutauchen.
  • babbleStatus ist eine durch Leerzeichen separierte Liste von Status-Identifikatoren, also Nomen, die den Status eines Untersystems wiedergeben. Beispiel: Status Wert Wetter Zeit
  • babblePrepos ist eine durch Leerzeichen separierte Liste von Präpositionen. Beispiel: von vom des der in im auf bei am
  • babbleTimes ist eine durch Leerzeichen separierte Liste von Zeit-Adverbien, die eine Zeitangabe eines Untersystems signalisieren. Beispiel: heute morgen übermorgen nacht
  • babbleQuests ist eine durch Leerzeichen separierte Liste von Frage-Adverbien. Beispiel: wie wo wann
  • babbleArticles ist eine durch Leerzeichen separierte Liste von Artikeln. Beispiel: der die das den des dem zur
  • babbleVerbs ist eine durch Leerzeichen separierte Liste von Verbengruppen, die jeweils aus kommagetrennten Variationen und Konjugationen sowie einem davon per ':' getrennten Infinitiv bestehen. Beispiel: schalt,schalte:schalten mach,machs,mache:machen öffne:öffnen schließe,schließ:schließen
  • babbleVerbParts ist eine durch Leerzeichen separierte Liste von Verbteilen, die den durch das grundlegende Tun (beschrieben durch ein Verb, z.B. schließen) erreichten Zustand festlegen (z.B. zu in zuschließen und auf in aufschließen). Beispiel für diese Liste: zu auf ent wider ein an aus ab um
  • babbleWrites ist eine durch Leerzeichen separierte Liste, die spezielle Verben enthält, die mit Schreiboperationen befasst sind. Beispiel: sagen senden hinzufügen entfernen ändern löschen
  • remoteFHEM(1|2|3) ist die IP-Adresse (+ Port) einer entfernten FHEM-Instanz.
  • remoteFunc(1|2|3) ist der Name einer Funktion, die aufgerufen wir, um die entfernte FHEM-Instanz anzusprechen. Hier kann beispielsweise das Modul RFHEM oder das Modul FHEM2FHEM eingesetzt werden.
  • linkname ist der Name für den Link im FHEM-Menü. Default: Babble.
  • hiddenroom ist der Name für den versteckten Raum, der das Babble-Device enthält. Default: babbleRoom
  • lockstate ist der Sperrzustand für das Device, siehe Sperrung

Webinterface

In diesem Abschnitt wird die Bedienung des Webinterfaces und damit die Konfiguration des NLUI beschrieben. Um sie zu erreichen, klickt man auf den Begriff Babble im oberen Menü des Webinterfaces.

Babble Test

In diesem Teil des Webinterfaces kann ein Testsatz eingegeben werden. Durch anklicken des Buttons Test wird dieser analysiert und das Resultat der Analyse unmittelbar darunter angezeigt. Ist bereits ein FHEM-Kommando dafür definiert (siehe übernächsten Abschnitt), wird dieses ebenfalls angezeigt. Wenn man vorher die Checkbox Ausführung setzt, wird dieses FHEM-Kommando auch ausgeführt.

Babble Test.png

Babble Orte und Babble Verben

Hier können im oberen Bereich zusätzliche Orts-Identifikatoren angegeben und mit Hilfe des Buttons Hinzufügen dem Attribut babblePlaces hinzugefügt werden. Wählt man stattdessen einen bereits definierten Orts-Identifikator aus, verändert sich der Button in einen Entfernen-Button, zusätzlich erscheint ein Button zum Abbruch.

Hier können im unteren Bereich zusätzliche Verbengruppen angegeben und mit Hilfe des Buttons Hinzufügen dem Attribut babbleVerbs hinzugefügt werden. Wählt man stattdessen ein bereits definiertes Verb aus, verändert sich der Button in einen Entfernen-Button, zusätzlich erscheinen ein Button zum Ändern und zum Abbruch.

Babble Places.png

Babble Devices

In diesem Bereich können mit Dropdown-Listen die bekannten Orte, Verben, und Zielzustände ausgewählt werden, die in der semantischen Analyse erkannt werden. Zusätzliche Zeilen können mit dem Button Hinzufügen gewonnen werden, alle bis auf die erste Zeile für jedes Device können entfernt werden.

In der ersten Zeile sollte ein Hilfetext eingetragen werden - dieser wird ausgegeben, wenn für dieses Device keine Kombination aus Raum, Verb und Ziel erkannt worden ist. Für neue Devices wird ein Vorschlag geliefert.

Im rechten Feld wird dann das auszuführende FHEM-Kommando eingetragen.

  • Perl-Aufrufe werden dabei wie üblich in {..} Klammern eingeschlossen.
  • Achtung: Derzeit noch doppelte Anführungszeichen vermeiden, nur einfache Anführungszeichen sind erlaubt.

Babble Devices.png

Anwendungsbeispiele

Temperatur abfragen

Im Beispiel gehen wir davon aus, dass es ein dummy-Device tempProfileC mit verschiedenen userReadings gibt, z.B. steht WZ.T für die Temperatur im Wohnzimmer.

Babble Temperatur.png

Dieses dummy-Device erhält nun den Attributwert

attr tempProfileC babbleDevice Temperatur

Damit erscheint dieses Device mit FHEM-Devicename tempProfileC und Babble-Devicename Temperatur in der Liste der Babble-Devices. Im nächsten Schritt müssen dafür Kommandos angelegt werden. Für das Beispiel wollen wir die Temperatur im Schlafzimmer und im Wohnzimmer abfragen. Dazu müssen diese beiden Orte der Liste babblePlaces hinzugefügt werden, das geht im Webfrontend von Babble.

Als erstes wollen wir die Frage stellen: Wie ist die Temperatur im Schlafzimmer. Babble ist derzeit intern so konfiguriert, dass eine Frage "wie ist" mit dem Verb sagen assoziiert wird. Weil ein konkretes Ziel nicht genannt wurde, setzt Babble als Ziel der Abfrage den Status des Gerätes ein. Nötig sind also die beiden Einträge

$hash->{DATA}{"command"}{"temperatur"}{"schlafzimmer"}{"sagen"}{"status"} = <1. Kommando zur Ausgabe>
$hash->{DATA}{"command"}{"temperatur"}{"wohnzimmer"}{"sagen"}{"status"} = <2. Kommando zur Ausgabe>

Alternativ kann man auch den Befehl erteilen Sage den Wert der Temperatur im Schlafzimmer. Hier wird spezifisch der Wert abgefragt, sinnvoll sind also zwei weitere Einträge mit denselben Ausgaben

$hash->{DATA}{"command"}{"temperatur"}{"schlafzimmer"}{"sagen"}{"wert"} = <1. Kommando zur Ausgabe>
$hash->{DATA}{"command"}{"temperatur"}{"wohnzimmer"}{"sagen"}{"wert"} = <2. Kommando zur Ausgabe>

Auch diese beiden Einträge lassen sich komfortabel über das Webfrontend von Babble machen. Für das Beispiel verwenden wir eine Perl-Funktion namens speak(<speechdevice>,<text>), die nichts weiter macht, als auf einem der dazu fähigen Devices (hier speechdevice) die zuständige TTS (Text-to-Speech) Funktion aufzurufen.

<1. Kommando zur Ausgabe> = {speak($PARM0,'Die Temperatur im Schlafzimmer beträgt '.ReadingsVal('tempProfileC','SZ.T',).' Grad')}
<2. Kommando zur Ausgabe> = {speak($PARM0,'Die Temperatur im Wohnzimmer beträgt '.ReadingsVal('tempProfileC','WZ.T',).' Grad')}

Der Parameter $PARM0 wird dabei durch denjenigen ersten Parameter ersetzt, den die Erkennungsfunktion mitgeliefert bekommen hat (siehe oben).

Babble Temperatur2.png

Nach dem Sichern steht das zur Verfügung. Übergibt man an Babble den Textstring Wie ist die Temperatur im Schlafzimmer, wird auf den Sprachausgabedevices z.B. der Text ausgegeben Die Temperatur im Schlafzimmer beträgt 21 Punkt 4 Grad. Schönheitsfehler ist noch, dass der englische Dezimalpunkt mit ausgegeben wird. Das lässt sich aber problemlos beheben, indem die Perl-Funktion speakEG etwas aufgebohrt wird. Durch einen einfachen regulären Ausdruck kann man jeden Punkt zwischen Ziffern durch ein Komma ersetzen lassen.

Weckzeit setzen

Im Beispiel gehen wir davon aus, dass es ein FHEM-dummy-Device Weckzeit gibt, dieses dummy-Device erhält nun den Attributwert

attr Weckzeit babbleDevice Wecker

Damit erscheint dieses Device mit FHEM-Devicename Weckzeit und Babble-Devicename Wecker in der Liste der Babble-Devices. Im nächsten Schritt müssen dafür Kommandos angelegt werden.

Als Sprachbefehl soll verwendet werden Wecken um 18 Uhr 27. Babble ist derzeit intern so konfiguriert, dass eine dem Teilstring weck versehene Sprachnachricht automatisch mit dem Device Wecker und dem Verb stellen assoziiert wird. Nötig ist also erstens der Eintrag des Verbs stellen in die Liste der Verben (geht mit dem Webfrontend) sowie ein Eintrag

$hash->{DATA}{"command"}{"wecker"}{"none"}{"stellen"}{"auf"} = <Kommando zum Stellen>

Auch dieser Eintrag lässt sich komfortabel über das Webfrontend von Babble machen. Als Kommando zum Stellen trägt man nun ein

set Weckzeit $VALUE

Der String $VALUE wird bei der Ausführung durch den Value-Parameter ersetzt, den Babble bei der semantischen Analyse herausfiltert, also im Beispiel 18:27 Uhr. Aus dem Weckzeit-Dummy kann man nun diese Weckzeit mit einem einfachen notify auf den "echten" Wecker übertragen (natürlich ein FHEM-Device...)

Wetter abfragen

In diesem Beispiel gehen wir davon aus, das in dem FHEM-Device wunderground drei Readings vorliegen:

  • fc0_message ist die Wettervorhersage für heute
  • fc1_message ist die Wettervorhersage für morgen
  • fc2_message ist die Wettervorhersage für übermorgen

Das Device erhält nun den Attributewert

attr wunderground babbleDevice Wetter

Damit erscheint dieses Device mit FHEM-Devicename wunderground und Babble-Devicename Wetter in der Liste der Babble-Devices. Im nächsten Schritt müssen dafür Kommandos angelegt werden. Da bei der Analyse der Zeitwert (heute,morgen oder übermorgen) in der Variablen $VALUE abgelegt wird, reichen zwei Kommands aus, indem die Fallunterscheidung untergebracht wird:

$hash->{DATA}{"command"}{"wetter"}{"none"}{"sagen"}{"wetter"} = <Kommando zur Abfrage>
$hash->{DATA}{"command"}{"wetter"}{"none"}{"sagen"}{"status"} = <Kommando zur Abfrage>

Auch dieser Eintrag lässt sich komfortabel über das Webfrontend von Babble machen. Als Kommando zur Abfrage trägt man nun in beide Felder ein:

{speakEG(ReadingsVal('wunderground','fc'.(('$VALUE' eq 'übermorgen')?'2':(('$VALUE' eq 'morgen')?'1':'0')).'_message',' '))}

Für das Beispiel verwenden wir eine Perl-Funktion namens speak(<speechdevice>,<text>), die nichts weiter macht, als auf einem der dazu fähigen Devices (hier speechdevice) die zuständige TTS (Text-to-Speech) Funktion aufzurufen. Der Parameter $PARM0 wird dabei durch denjenigen ersten Parameter ersetzt, den die Erkennungsfunktion mitgeliefert bekommen hat (siehe oben).

Babble Wetter.png