RHASSPY: Unterschied zwischen den Versionen

Aus FHEMWiki
Zeile 129: Zeile 129:
{{Hinweis|RHASSPY führt jede Menge Daten aus unterschiedlichen Quellen zusammen um seine Funktion erfüllen zu können. Die endgültige Daten-Struktur, die RHASSPY verwendet, kann mittels des [[List|list]]-Kommandos angezeigt werden. Es wird empfohlen, sich diese Daten-Struktur auf jeden Fall anzusehen. Vor allem dann, wenn etwas nicht wie gewünscht funktioniert.}}
{{Hinweis|RHASSPY führt jede Menge Daten aus unterschiedlichen Quellen zusammen um seine Funktion erfüllen zu können. Die endgültige Daten-Struktur, die RHASSPY verwendet, kann mittels des [[List|list]]-Kommandos angezeigt werden. Es wird empfohlen, sich diese Daten-Struktur auf jeden Fall anzusehen. Vor allem dann, wenn etwas nicht wie gewünscht funktioniert.}}


==SET-Befehle==
==Set-Befehle (SET)==


;<code id="set-customslot">customSlot</code>
;<code id="set-customslot">customSlot</code>
Zeile 210: Zeile 210:


{{Hinweis|Bitte nicht vergessen, dass nach jeder Änderung an RHASSPY oder an einem von RHASSPY gesteuerten Gerät ein <code>update devicemap</code> ausgeführt werden muss!}}
{{Hinweis|Bitte nicht vergessen, dass nach jeder Änderung an RHASSPY oder an einem von RHASSPY gesteuerten Gerät ein <code>update devicemap</code> ausgeführt werden muss!}}
==Attribute (ATTR)==
Um RHASSPY zum Laufen zu bringen, müssen unterschiedliche Attribute gesetzt werden. Dabei gibt es
*Attribute, die im RHASSPY-Device selbst gesetzt werden müssen und
*Attribute, die in den Devices gesetzt werden müssen, die von RHASSPY kontrolliert werden sollen.
Letztere werden im Abschnitt [[#Tbd]] behandelt.
In diesem Abschnitt werden die Attribute behandelt, die auf das RHASSPY-Device selbst wirken.
;<code id="attr-iodev">IODev</code>
;<code id="attr-forcenext">forceNext</code>
;<code id="attr-languagefile">languageFile</code>
;<code id="attr-response">response</code>
;<code id="attr-rhasspyhotwords">rhasspyHotwords</code>
;<code id="attr-rhasspyintents">rhasspyIntents</code>
;<code id="attr-rhasspyshortcuts">rhasspyShortcuts</code>
;<code id="attr-rhasspytweaks">rhasspyTweaks</code>
==Readings / Events==
;<code>IODev</code>
;<code>intents</code>
;<code>lastIntentPayload</code>
:Content of the last command which was received by FHEM
;<code>lastIntentTopic</code>
;<code>listening_roomname</code>
:Changes to 1 if a wake-word was recognized and back to 0 if the Rhasspy-session has ended.
:There is one reading for every single satellite/master.
:Can for example be used to mute speakers while Rhasspy is listening to commands.
;<code>mute_roomname</code>
:Shows if a room/siteId is muted and doesn't execute any commands.
:There is one reading for every siteId.
:Default is 0.
;<code>responseType</code>
:Shows the type of the last response.
:Possible values are text or voice.
:voiceResponse and textResponse
:Response to the last voice- or text-command.
;<code>siteIds</code>
:Reading contains every available siteId.
:Can be updated with running fetchSiteIds.
;<code>state</code>
;<code>training</code>
:Contains the last response of the trainRhasspy command.
;<code>updateSentences</code>
:Contains the last response ot the updateSlots command.`
;<code>updateSlots</code>
:Contains the last response ot the updateSlots command.`
;<code>hotword</code>
:If activated, contains the last used hotword and siteId.
;<code>voiceResponse</code>


== Beispiele ==
== Beispiele ==

Version vom 1. Dezember 2021, 18:50 Uhr


Clock - Under Construction.svg An dieser Seite wird momentan noch gearbeitet.


RHASSPY
Zweck / Funktion
Anbindung von FHEM an den Rhasspy Sprachassistenten
Allgemein
Typ Contrib
Details
Dokumentation Thema
Support (Forum) Frontends/Sprachsteuerung
Modulname 10_RHASSPY.pm
Ersteller BetaUser (Forum /Wiki), drhirn (Forum /Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Rhasspy ist eine Open-Source Lösung für Spracherkennung und Sprachsteuerung. Es besteht aus einer Sammlung von Scripten, die unter einer einheitlichen Bedienoberfläche zusammengefasst sind, die sehr flexibel genutzt und erweitert werden können. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben wird. Es wir also keine Sprache zur Erkennung an einen Server im Internet geschickt, und für den Betrieb nur für FHEM werden nur moderate Hardwareanforderungen gestellt - ein aktueller Raspberry Pi ab Modell 3B+ sollte in der Regel genügen.

Die Anbindung weiterer Räume ist über sogenannte "Satelliten" möglich. Dies kann z.B. ein Pi Zero mit Mikro und Lautsprecher sein, ein ESP32 mit entsprechender Hardware oder ein Mobiltelefon mit Android und der entsprechenden App.

Rhasspy besteht aus vielen unterschiedlichen Modulen (Hot-Word Erkennung, Text to Speech, Speech to Text, Intent Erkennung, ...). Alle diese Module kommunizieren miteinander über das MQTT-Protokoll.


Das Modul RHASSPY prüft Teile des MQTT-Traffics, konvertiert diese JSON-Nachrichten in FHEM-Befehle und sendet Nachrichten zurück an Rhasspy um z.B. Antworten über TextToSpeech auszugeben.

RHASSPY verwendet das 00_MQTT2_CLIENT.pm Modul um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, ein MQTT2_CLIENT Device zu erstellen, bevor dieses Modul verwendet werden kann.

Hervorgegangen ist dieses Modul ursprünglich aus dem Snips-Modul, nachdem Snips an Sonos verkauft und somit eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!


Info blue.png
In diesem Artikel und der commandref werden folgende Schreibweisen verwendet:
  • RHASSPY bezieht sich auf das FHEM-Modul oder das FHEM-Device
  • Rhasspy bezeichnet die (zentrale) Installation bzw. das Web-Interface, unter dem die Scriptsammlung verwaltet werden kann.



Info blue.png
Was Dialoge betrifft, verlässt sich RHASSPY auf die Mechanismen, die hier beschrieben sind. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als RHASSPY eingestellt ist


Erste Schritte

Für Einsteiger in das Thema Rhasspy bzw. RHASSPY gibt es eine Schnellstart-Anleitung, die die ersten grundlegenden Schritte einfach erklärt: RHASSPY/Schnellstart

Es ist auf jeden Fall empfehlenswert, die Schnellstart-Anleitung zuerst durchzulesen, bevor man sich auf dieser Seite weiter in das Thema vertieft.

Installation des RHASSPY Moduls

Das Modul ist derzeit nicht in der "offiziellen" FHEM Distribution enthalten und muss daher manuell installiert werden. Dafür gibt es zwei Möglichkeiten.

FHEM SVN

Im SVN von FHEM ist die jeweils aktuelle "stable" Version des Moduls im contrib-Zweig zu finden. Diese kann mit folgendem Befehl, der im FHEM Befehls-Eingabefeld einzugeben ist, herunter geladen werden:

{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }

Genauere Informationen zu dieser Vorgangsweise finden sich unter Update#Einzelne_Dateien_aus_dem_SVN_holen.

Nach Installation des Moduls muss FHEM neu gestartet werden.


FHEM Update und GitHub

Im GitHub-Repository des Moduls gibt es zwei Branches main und dev. In main ist die stabile Version des Moduls, in dev die jeweils aktuelle Entwicklungsversion. Aus Gründen der Stabilität ist natürlich die aus main zu bevorzugen.

Um das Modul zu installieren beziehungsweise zu aktualisieren, kann der update-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repos aufgenommen werden:

update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:

update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt

Wählt man diesen Weg, wird das Modul auch automatisch aktualisiert, wenn ein Update von FHEM durchgeführt wird. Möchte man die Entwicklungsversion verwenden, muss in den beiden Befehlen main durch dev ersetzt werden.

Weitere Informationen zu dieser Vorgangsweise in der stehen in der CommandRef oder im FHEM-Wiki.

Nach Installation des Moduls muss FHEM neu gestartet werden.

Einrichtung MQTT2_CLIENT

Rhasspy kommuniziert hauptsächlich über das MQTT-Protokoll. Und zwar sowohl Rhasspy-intern, wie auch mit FHEM. Da dies auch für die übertragene Sprache und Audio-Dateien gilt und es daher zu sehr viel MQTT-Verkehr kommt, sollte der Rhasspy-interne MQTT-Server verwendet werden. Daher ist die Einrichtung eines MQTT2_CLIENT-Devices notwendig, um die für FHEM relevanten Daten zu beziehen.


Zuerst muss ein MQTT2_CLIENT Device erstellt werden, welches sich mit dem MQTT-Server (Mosquitto) von Rhasspy verbindet:

define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port>


Anschließend wird die clientOrder gesetzt, um die richtige Benachrichtigungsreihenfolge einzustellen. Wird das MQTT2_CLIENT Device nur für RHASSPY verwendet, reicht hier die Angabe RHASSPY. Ansonsten müssen noch alle anderen Devices (z.B. MQTT_GENERIC_BRIDGE, MQTT2_DEVICE) angegeben werden.

attr <deviceName> clientOrder RHASSPY [device2] [device3]


Um die Topics einzuschränken, die das Device abonniert, müssen diese angegeben werden. Wird der MQTT-Server nur für RHASSPY verwendet, reicht die Angabe setByTheProgram. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.

attr <deviceName> subscriptions setByTheProgram

bzw.

attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected


Beispiele
  • Rhasspy-interner MQTT-Server wird mit seinem Standard-Port verwendet. Rhasspy läuft auf der selben Maschine wie FHEM. MQTT2_CLIENT wird nur für RHASSPY verwendet.
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
  • Rhasspy läuft auf einem eigenen Server und verwendet einen externen MQTT Server mit eigener Port-Einstellung. MQTT2_CLIENT wird für RHASSPY, aber auch MQTT_GENERIC_BRIDGE und MQTT2_DEVICE verwendet.
defmod rhasspyMQTT2 MQTT2_CLIENT 192.168.1.122:1884
attr rhasspyMQTT2 clientOrder RHASSPY MQTT_GENERIC_BRIDGE MQTT2_DEVICE
attr rhasspyMQTT2 subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected [zusätzliche Subscriptions für andere MQTT-Module]


Definition von RHASSPY (DEF)

define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <encoding>
Info green.pngRHASSPY verwendet sehr oft <parseParams>. Nicht nur im Define, sondern z.B. auch, um Attribut-Werte auszuwerten. Es sollten also alle Parameter im Define in der Form key=value angegeben werden.).

Alle Parameter sind optional. Die meisten werden im Normalfall gar nicht benötigt (z.B. fhemId, prefix). Sollten sie aber verwendet und später geändert werden, kann es zu unvorhergesehenem Verhalten kommen. Speziell beim Einstieg in das Thema RHASSPY sollten nicht mehr, als die ersten drei verwendet werden. Ausgenommen eventuell noch language, möchte man eine andere Sprache als Englisch oder Deutsch verwenden.


baseUrl
Die URL zum Rhasspy-Webservice. Sollten eine Base und mehrere Satelliten verwendet werden, die URL zur Base. Bitte sicherstellen, dass die Adresse richtig ist (IP und Port)! Default ist baseUrl=http://127.0.0.1:12101.
devspec
devspec der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der genericDeviceType-Support aktiviert ist, ist der Default devspec=genericDeviceType=.+, sonst wird devspec=room=Rhasspy verwendet. Ohne ein passendes Match in der devspec wird kein Gerät mit dem Modul interagieren, egal, ob sonst irgendwelche RHASSPY-spezifischen Attribute beim Gerät gesetzt sind. Genauere Informationen, wie z.B. eine Liste von Geräten oder Kombinationen aus Geräten und Räumen (z.B. devspec=room=livingroom,room=bathroom,bedroomlamp) verwendet werden können, finden sich in der CommandRef.
defaultRoom
Der Name des Standard-Raumes, der verwendet wird, wenn im Sprachkommando kein Raum enthalten ist und auch kein passender für das Device gefunden werden kann. Default ist defaultRoom=default.
language
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom global-Device ab. Dieser ist standardmäßig language=en.
fhemId
Wird verwendet um auf MQTT-Seite zwischen mehreren Installationen des RHASSPY-Moduls zu unterscheiden. Ist auch ein Teil des Topic-Trees, auf den die jeweilige RHASSPY-Instanz hört. Default ist fhemId=fhem.
prefix
Wird verwendet um auf FHEM-Seite zwischen mehreren Installationen des RHASSPY-Moduls zu unterscheiden. Praktisch, wenn man mehrere Instanzen von RHASSPY auf einer FHEM Installation laufen hat und z.B. verschiedene Bezeichner für Gruppen und Räume haben möchte (z.B. unterschiedliche Sprachen). Default ist prefix=rhasspy.
useGenericAttrs
Üblicherweise verwendet RHASSPY - wie auch einige andere FHEM Module für Sprachassistenten - das Attribut genericDeviceType um Schaltmöglichkeiten von Geräten automatisch zu erkennen. Dieser Parameter fügt das Attribut genericDeviceType zur globalen Attributliste hinzu. Der Wert 0 verhindert dieses hinzufügen. Default ist useGenericAttrs=1.
encoding
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist encoding=utf8.
handleHotword
Triggert das Reading hotword, wenn ein Hotword erkannt wurde (und erstellt das Reading, falls noch nicht vorhanden). Weitere Informationen dazu stehen beim Attribut rhasspyHotwords. Default ist handleHotword=0


Info blue.png
Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. attr <deviceName> IODev <m2client>.


Beispiele

Läuft Rhasspy auf der selben Maschine wie FHEM, die Sprache ist im global-Device bereits richtig eingestellt und der Standardraum entspricht der siteID, die in Rhasspy vergeben wurde:

define Rhasspy RHASSPY

Läuft Rhasspy auf einem anderen System wie FHEM, der Standard-Raum enspricht nicht dem, was Rhasspy liefert, die Sprache soll auch anders sein und es sollen sowohl Geräte mit vorhandenem genericDeviceType Attribut, als auch die Geräte device_a1 und device_xy gesteuert werden:

define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1


Info blue.png
RHASSPY führt jede Menge Daten aus unterschiedlichen Quellen zusammen um seine Funktion erfüllen zu können. Die endgültige Daten-Struktur, die RHASSPY verwendet, kann mittels des list-Kommandos angezeigt werden. Es wird empfohlen, sich diese Daten-Struktur auf jeden Fall anzusehen. Vor allem dann, wenn etwas nicht wie gewünscht funktioniert.


Set-Befehle (SET)

customSlot
Creates a new - or overwrites an existing slot - in Rhasspy
Provide slotname, slotdata and (optional) info, if existing data shall be overwritten and training shall be initialized immediately afterwards.
First two arguments are required, third and fourth are optional.
overwrite defaults to true, setting any other value than true will keep existing Rhasspy slot data.
Examples:
set <rhasspyDevice> customSlot mySlot a,b,c overwrite training
set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false
fetchSiteIds
Fetch all available siteIds from Rhasspy-Base and create a reading siteIds. Used for e.g. to determine on which Rhasspy satellite the user gets informed that a timer has ended.
Has to be executed everytime a new satellite is installed or a new siteId is added to Rhasspy. Example: set <rhasspyDevice> fetchSiteIds
play
Sendet eine WAV Datei an Rhasspy.
siteId und <path> sind verpflichtend!
Optional kann die Anzahl der Wiederholungen (Default: 1) und die Dauer der Pause zwischen den jeweiligen Wiederholungen (Default: 15) angeben werden.
Beispiele:
set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"
set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20
speak
Voice output over TTS.
Both arguments (siteId and text) are required!
Example: set <rhasspyDevice> speak siteId="default" text="This is a test"
textCommand
Send a text command to Rhasspy.
Example: set <rhasspyDevice> textCommand turn the light on
trainRhasspy
Sends a train-command to the HTTP-API of the Rhasspy base.
Example: set <rhasspyDevice> trainRhasspy
update
devicemap
When the configuration work to RHASSPY and all subordinated devices is finished or there had been changes, issuing a devicemap-update is mandatory, to get the RHASSPY data structure updated, inform Rhasspy on changes that may have occured (update slots) and initiate a training on updated slot values etc. Has to be executed after changes to the attributes of a Rhasspy-controlled devices or the RHASSPY device itself.
Example: set <rhasspyDevice> update devicemap
devicemap_only
Used to check whether attribute changes have found their way to the data structure. This will neither update slots nor initiate any training towards Rhasspy.
Example: set <rhasspyDevice> update devicemap_only
slots
Sends a command to the HTTP-API of the Rhasspy master to update all slots on Rhasspy with actual FHEM-devices, rooms, etc.
Updated/Created Slots are for example (note: the first two parts en.fhem. correspond to the settings in DEF):
  • de.fhem.AllKeywords
  • de.fhem.Device
  • de.fhem.Device-genericDeviceType
  • de.fhem.Group
  • de.fhem.Room
  • de.fhem.MediaChannels
  • de.fhem.Color
  • de.fhem.NumericType
Example: set <rhasspyDevice> update slots
slots_no_training
Same as slots without starting a training after updating.
Example: set <rhasspyDevice> update slots_no_training
language
Reinitialization of language file.
Be sure to execute this command after changing something in the language-configuration file or the attribute languageFile!
Example: set <rhasspyDevice> update language
intent_filter
Reset intent filters used by Rhasspy dialogue manager. See intentFilter in rhasspyTweaks attribute for details.
all
Update devicemap and language.
Example: set <rhasspyDevice> update all
volume
Sets volume of given siteId between 0 and 1 (float)
Both arguments (siteId and volume) are required!
Example: set <rhasspyDevice> siteId="default" volume="0.5"


Info blue.png
Bitte nicht vergessen, dass nach jeder Änderung an RHASSPY oder an einem von RHASSPY gesteuerten Gerät ein update devicemap ausgeführt werden muss!



Attribute (ATTR)

Um RHASSPY zum Laufen zu bringen, müssen unterschiedliche Attribute gesetzt werden. Dabei gibt es

  • Attribute, die im RHASSPY-Device selbst gesetzt werden müssen und
  • Attribute, die in den Devices gesetzt werden müssen, die von RHASSPY kontrolliert werden sollen.

Letztere werden im Abschnitt #Tbd behandelt.

In diesem Abschnitt werden die Attribute behandelt, die auf das RHASSPY-Device selbst wirken.

IODev
forceNext
languageFile
response
rhasspyHotwords
rhasspyIntents
rhasspyShortcuts
rhasspyTweaks


Readings / Events

IODev
intents
lastIntentPayload
Content of the last command which was received by FHEM
lastIntentTopic
listening_roomname
Changes to 1 if a wake-word was recognized and back to 0 if the Rhasspy-session has ended.
There is one reading for every single satellite/master.
Can for example be used to mute speakers while Rhasspy is listening to commands.
mute_roomname
Shows if a room/siteId is muted and doesn't execute any commands.
There is one reading for every siteId.
Default is 0.
responseType
Shows the type of the last response.
Possible values are text or voice.
voiceResponse and textResponse
Response to the last voice- or text-command.
siteIds
Reading contains every available siteId.
Can be updated with running fetchSiteIds.
state
training
Contains the last response of the trainRhasspy command.
updateSentences
Contains the last response ot the updateSlots command.`
updateSlots
Contains the last response ot the updateSlots command.`
hotword
If activated, contains the last used hotword and siteId.
voiceResponse

Beispiele

Links