FHEMWiki - Benutzerbeiträge [de]

MQTT

2025-03-24T14:33:45Z

Beta-User: /* Installation in FHEM */

[[MQTT]] ist ein Protokoll ("Message Queue Telemetry Transport"), mit dem Daten und Befehle zwischen verschiedenen Geräten ausgetauscht werden. Die Kommunikation erfolgt dabei über einen zentralen MQTT-Server, in alter Nomenklatur auch ''Broker'' genannt.

MQTT wurde entwickelt, um möglichst effizient, sicher und mit wenig Datenlast zu kommunizieren. MQTT ist nachrichtenorientiert, daher muss ein Client nicht beständig beim Server anfragen, ob neue Daten vorliegen. Heute findet sich MQTT vor allem im Bereich des ''Internet of Things'' (IoT). MQTT kann leicht mit FHEM verbunden werden, ohne dass dabei größerer CPU- oder Datenverbrauch entsteht.

== Schnellstart für Ungeduldige ==
define m2s MQTT2_SERVER 1883 global

Am MQTT-Endgerät den FHEM-Server angeben wie in der Dokumentation des Endgeräts angegeben, danach das Endgerät neu starten.
Das Endgerät ist dann im Raum ''MQTT2_DEVICE'' zu finden.

Schau mal in attrTemplate des neu angelegten MQTT2_DEVICE, ob was passendes für Dich dabei ist.

Für die meisten ggf. hierzu auftretenden Fragen sollten Hinweise in den [[MQTT2-Module - Praxisbeispiele|Praxisbeispielen zu den MQTT2-Modulen]] enthalten sein.

== Eine sehr kurze Einführung in MQTT ==
Die folgende Einführung kann eine vollwertige Einleitung wie beispielsweise [https://github.com/mqtt/mqtt.github.io/wiki diese Wikieinträge] nicht ersetzen.

Bei MQTT findet die nachrichtenbasierte Kommunikation zwischen einzelnen Teilnehmern<ref>Teilnehmer in diesem Sinne kann ein Stück Hardware mit einer MQTT-fähigen firmware sein, ein auf einem Computer laufendes Script (einschließlich eines MQTT-Server-Dienstes wie ''mosquitto'' oder ''MQTT2_SERVER'', kurz: alles mögliche sein. Dadurch kann auch ein einzelner Computer unter mehreren ClientID's am MQTT-Datenaustausch beteiligt sein.</ref> in der Regel nicht direkt statt. Stattdessen werden alle Nachrichten von einem Teilnehmer an einen Serverdienst, den MQTT-Server (früher ''Broker'' genannt) übergeben, der dann dafür sorgt, dass die Nachricht an alle (berechtigten) anderen Teilnehmer verteilt wird, die sich für derartige Nachrichten "interessieren". Wenn also ein Teilnehmer ohne Server-Funktion (Client) Daten von einem bestimmten anderen Teilnehmer (anderer Client) empfangen will, muss es vorher dem MQTT-Server (Broker) mitteilen, dass er die Nachrichten dieses anderen Teilnehmers abonniert (deshalb wird dieser Vorgang als ''subscribe'' bezeichnet). Im IoT ist besonders interessant, dass Sender und Empfänger von Nachrichten durch den MQTT-Server vollständig entkoppelt werden können - jemand, der Daten bereit stellt, muss sich also nicht darum kümmern, wer diese Daten empfängt<ref>Aufgrund dieser Funktionsweise sollte allerdings darauf geachtet werden, die Möglichkeiten des jeweiligen Servers zur Sicherung der Daten gegen unberechtigten Zugriff zu nutzen, insbesondere wenn die Art der Daten oder die sich hierdurch ergebenden Möglichkeiten, z.B. Schaltvorgänge in der realen Welt auszulösen, dies notwendig macht!</ref>.

Eine Nachricht besteht im Wesentlichen aus den folgenden Elementen:
*'''ClientID''' - das ist die Kennung des Senders einer Nachricht<ref>Diese kann sich bei der Weitergabe der Nachricht ändern: Zunächst sendet ein Client eine Nachricht unter seiner ClientID, der MQTT-Server wird diese dann in der Regel durch seine Kennung ersetzten, wenn er die Nachricht an einen Abonnenten - der auch ein weiterer MQTT-Server sein kann - weitergibt.</ref>
*Topic - das ist die Adresse, an die eine Nachricht gesendet wird, bzw. von wo sie abgeholt werden kann (so ähnlich wie ein Postfach in der realen Welt). Topics sind einfache Strings, die mit Schrägstrichen getrennt werden (keine Leerzeichen und nur sehr wenige Sonderzeichen erlaubt). Ein Topic könnte beispielhaft so lauten: <code>zuHause/1OG/Kueche/Licht/state</code>. Diese Topics beinhalten also eine Hierarchie der Objekte - hier im Beispiel sind sie zuerst danach sortiert, ob sie sich zu Haus befinden, dann wird nach Stockwerken sortiert und im ersten Stock schaut man auf die Küche sowie das dort vorhandene Licht.
*'''Payload''' - das ist der Inhalt der Nachricht, oft handelt es sich um Befehle oder Daten, gelegentlich auch ''message'' genannt.
*'''Quality of Service''' - soll geprüft werden, ob die Nachricht zugestellt wurde und wenn ja, mit welcher "Tiefe"?
*'''Retained Message'''.
Details bitte in der oben genannten Einführung nachlesen.

Das Protokoll ''MQTT'' kommuniziert üblicherweise über Port 1883, es können aber unter derselben Netzwerkadresse an unterschiedlichen Ports auch mehrere Serverdienste bereitstehen.

== Installation in FHEM ==
Um ''MQTT'' in FHEM zu nutzen, benötigt man (mindestens) einen MQTT-Server. Es gibt zwei Möglichkeiten: man kann FHEM-externe Server-Software (oder auch einen oder mehrere im Internet bereitstehende MQTT-Server) verwenden oder man kann die MQTT-Serverkomponente aktivieren, die mit {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} in FHEM direkt bereitsteht. Hier werden kurz beide Installationswege erläutert, zwingend ist nur einer, da eben mindestens ein MQTT-Serverdienst aktiv sein muß.

Die nachfolgenden Schaubilder zeigen schematisch die in FHEM zur Verfügung stehenden Wege der Einbindung von Hard- und/oder Softwarekomponenten, die über das MQTT-Protokoll Daten austauschen.
<gallery>
Datei:Mqtt2 server.png|Datenaustausch mit MQTT-Geräten, wenn ''MQTT2_SERVER'' als internem MQTT-Serverdienst verwendet wird
Datei:Mqtt2 client v extern server.png|Datenaustausch mit MQTT-Geräten, wenn ''MQTT2_CLIENT'' iVm. mosquitto als externem MQTT-Serverdienst verwendet wird
Datei:00 mqtt pm.png|Datenaustausch mit MQTT-Geräten, wenn das Modul ''MQTT'' (00_MQTT.pm) iVm. ''mosquitto'' als externem MQTT-Serverdienst verwendet wird
</gallery>
{{Hinweis|Neueinsteigern in das MQTT-Protokoll wird '''dringend empfohlen''', '''''MQTT2_SERVER''''', oder - sofern unbedingt ein externer Server zum Einsatz kommen soll - ''MQTT2_CLIENT'' zu verwenden.}}

=== FHEM als MQTT-Server ===
Die mit dem Modul {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} bereitstehende Serverkomponente kann z.B. wie folgt aktiviert werden:
defmod myBroker MQTT2_SERVER 1883 global
Dieses [[Gerät]] übernimmt dann die Kommunikation mit den externen Clients (und wird von diesen behandelt, wie jeder andere MQTT-Server auch<ref>Bitte beachten Sie, dass (Stand: Janar 2021) ''MQTT2_SERVER'' nicht alle features des MQTT-Protokolls unterstützt.</ref>) und verteilt die eingehenden Nachrichten als IO-Device<ref>im Sinne des [[DevelopmentModuleIntro#Zweistufiges Modell für Module|2-stufigen Modulkonzepts]]</ref> für die Client-Module [[MQTT2_DEVICE]]<ref>Die Zahl 2 in den Modulnamen verweist nur darauf, dass es sich um eine neuere Modulfamilie handelt; die Kommunikation mit den externen Komponenten unterscheidet sich nicht zu den älteren Modulen, die vor dem Jahr 2018 genutzt werden konnten.</ref> und [[MQTT_GENERIC_BRIDGE]].
Ein weiterer Vorteil dieser Lösung besteht darin, dass man ein ''MQTT2_SERVER''-Device mit Hilfe von [[allowed]] absichern kann, was auch SSL-verschlüsselte Kommunikation ermöglicht. '''Hinweis:''' In diesem Fall muss User bzw. Passwort auch in den entsprechenden Geräten eingetragen werden.

{{Hinweis|Wenn Sie beabsichtigen, diese Variante zu verwenden, sollten Sie als nächstes die [[MQTT2-Module - Praxisbeispiele|Praxisbeispiele zu den MQTT2-Modulen]] lesen, und ggf. später wieder hierher zurückkehren. Dort findet sich auch ein Abschnitt zu dem auf den Grafiken zu den MQTT2-IO-Modulen enthaltenen [[MQTT2-Module_-_Praxisbeispiele#bridgeRegexp|bridgeRegexp]]-Attribut.}}
{{Hinweis|Falls Sie neben Anweisungen aus FHEM selbst heraus andere Software nutzen wollen, um Befehle über den ''MQTT2_SERVER'' an die darüber eingebundenen Geräte zu senden, beachten Sie bitte auch den Abschnitt zum [[MQTT2_CLIENT#ignoreRegexp|ignoreRegexp]]-Attribut bei ''MQTT2_CLIENT''.}}

=== FHEM-externer Broker ===
==== Beispiel: mosquitto ====
Eine gern verwendete MQTT-Server-Software ist [http://mosquitto.org Mosquitto]. Sie kann ohne weiteres auf dem Raspberry Pi, der bereits eine FHEM-Installation besitzt, installiert werden und wird keine größere CPU- oder Netzwerklast verursachen.

Im wesentlichen beschränkt sich die Installation eines MQTT Servers aber auf wenige Arbeitsschritte. Seit ''stretch'' ist ''Mosquitto'' bereits in der Distribution enthalten und kann - zusammen mit dem client Befehl ''mosquito_sub'', der weiter unten benötigt wird, wie folgt installiert und getestet werden
<syntaxhighlight lang="bash">
sudo apt-get install mosquitto mosquitto-clients

# MQTT Server Test
sudo systemctl status mosquitto

# Start / Stop des Servers
sudo systemctl stop mosquitto
sudo systemctl start mosquitto
</syntaxhighlight>
Danach ist der RPi mit <nowiki>shutdown restart</nowiki> neu zu starten.

==== IO-Module für externe MQTT-Server ====
Damit FHEM mit dem MQTT-Server kommuniziert, muss noch ein IO-Device angelegt werden. Dabei stehen zwei Varianten zur Wahl, das Modul [[MQTT (Modul)|MQTT]] oder seit Ende 2018 [[MQTT2_CLIENT]].

Beide Module können auch dazu genutzt werden, um Daten zwischen zwei FHEM-Installationen auszutauschen, insbesondere kann auch 00_MQTT.pm als Client für einen MQTT2_SERVER eingesetzt werden, der '''auf der anderen Installation''' als MQTT-Serverdienst eingerichtet ist. Darüber hinaus bestehen eine Vielzahl von Kombinationsmöglichkeiten der diversen IO-Module, wenn die Installation auf mehrere Server verteilt ist.
Auf einer FHEM-Installation wird jedoch in der Regel nur eines der IO-Module benötigt.

===== MQTT2_CLIENT =====
Ein MQTT2_CLIENT-IO-Device wird z.B. angelegt mit
define myBroker MQTT2_CLIENT 10.0.0.5:1883 ## bitte EIGENE IP-Adresse eintragen

{{Hinweis|Wenn Sie beabsichtigen, MQTT2_CLIENT zu verwenden, sollten Sie zuerst die [[MQTT2-Module - Praxisbeispiele|Praxisbeispiele zu den MQTT2-Modulen]] lesen, und dabei die Hinweise im Artikel [[MQTT2_CLIENT]] beachten.}}

Ein MQTT2_CLIENT-Device kann ebenfals mit Hilfe von [[allowed]] abgesichert werden, um z.B. SSL-verschlüsselte Kommunikation zu ermöglichem. Client-Module zu diesem IO-Typ sind wiederum [[MQTT2_DEVICE]] und [[MQTT_GENERIC_BRIDGE]].

===== MQTT (Modul) =====
Vorab werden für diese Variante weitere Perl-Pakete benötigt:
<syntaxhighlight lang="bash">
# Perl Version ausgeben
perl -v
# Perl MQTT Module nachinstallieren (läuft ein paar Minuten)
sudo cpan install Net::MQTT::Constants
</syntaxhighlight>
Dabei wird neben dem ausdrücklich aufgeführten Modul noch ''Module::Pluggable'' und ''Net::MQTT::Message'' (sowie ein weiteres, nicht für FHEM genutztes Paket) installiert.

Ein IO-Device des Typs MQTT wird z.B. angelegt mit
{{Randnotiz|RNTyp=g|RNText=Sofern der Broker mit FHEM über localhost kommuniziert, kann als IP 127.0.0.1 verwendet werden.}}
define myBroker MQTT 10.0.0.5:1883 ## bitte EIGENE IP-Adresse eintragen
{{Randnotiz|RNTyp=g|RNText=Außerhalb der offiziellen Quellen sind auch einige ältere Varianten des Moduls MQTT_DEVICE verfügbar, die jeweils spezielle Anforderungen (z.B. für Zigbee2mqtt) separat abbilden. Diese werden hier nicht gesondert behandelt, da solche Sonderfälle heute generischer und einfacher durch den Einsatz von MQTT2_DEVICE abzubilden sind.}}Client-Device-Module zum Modul [[MQTT (Modul)|MQTT]] sind [[MQTT_DEVICE]], ''MQTT_BRIDGE'' (veraltet!) und [[MQTT_GENERIC_BRIDGE]]. Da ''MQTT_DEVICE'' payload im JSON-Format (im Unterschied zu MQTT2_DEVICE) nicht selbst verarbeiten kann wird hier zusätzlich das Modul {{Link2CmdRef|Anker=expandJSON|Lang=de|Label=expandJSON}} benötigt, um den {{Link2Forum|Topic=66761|LinkText=JSON String auszuwerten}}.

===== Auswahl =====
Als Einsteiger sollte man ''MQTT2_CLIENT'' als Interface-Modul wählen. Dies hat folgende Vorteile:
* ''MQTT2_CLIENT'' kann verschlüsselte Verbindungen aufbauen.
* Es sind keine externen Perl-Module erforderlich.
* Als Client-Modul steht u.a. ''MQTT2_DEVICE'' zur Verfügung, das - im Vergleich zu ''MQTT_DEVICE'' direktere Möglichkeiten der Behandlung von heutzutage häufig verbreiteten JSON-Payloads bietet.

=== Performancefragen... ===
...oder was sollte man unter Performance-Gesichtspunkten als Lösung wählen, wenn man in die MQTT-Welt einsteigt<ref>vgl. hierzu diesen {{Link2Forum|Topic=94768|Message=875714|LinkText=Beitrag}} von Rudolf König</ref>?
Grundsätzlich sollte man davon ausgehen, dass innerhalb von FHEM die Verarbeitung derselben Daten näherungsweise denselben Aufwand bedeuten, unabhängig davon, welche der Implementierungen (''MQTT2_CLIENT'', ''MQTT'' oder ''MQTT2_SERVER'') man konkret wählt.
Ein externer Broker hat daher vor allem dann Vorteile, wenn die MQTT Daten überwiegend für was anderes (nicht FHEM) verwendet werden, oder MQTT zweckentfremdet wird (wie z.Bsp. für Musikübertragung). Nutzt man das MQTT-Protokoll dagegen vorwiegend innerhalb von FHEM, ist eher der Einsatz von ''MQTT2_SERVER'' in Betracht zu ziehen. Dieser soll Anfängern die Anbindung von MQTT Geräten in FHEM einfacher machen. Wer später merkt, dass er doch einen externen Broker benötigt, kann dann immer noch auf ''MQTT2_CLIENT'' in Verbindung mit einem anderen Broker wechseln.
Dagegen ist der Weg von ''MQTT_DEVICE'' zu ''MQTT2_DEVICE'' mit erheblich mehr Aufwand verbunden.

=== Kommunikation zu sonstigen FHEM-Geräten über MQTT ===

Möchte man Daten von einem [[Gerät]] (im FHEM-Sinn), das '''nicht''' vom Typ ''MQTT2_DEVICE'' oder ''MQTT_DEVICE'' (je nach IO-Modul) ist, per MQTT-Protokoll versenden (z.B. für eine andere Visualisierungslösung als FHEMWEB, oder als FHEM2FHEM-Ersatzlösung), oder diese sonstigen Geräte über MQTT-Anweisungen von außen steuern können, hat man mehrere Möglichkeiten:

==== MQTT_GENERIC_BRIDGE ====
===== Allgemeines =====
Das Modul {{Link2CmdRef|Anker=MQTT_GENERIC_BRIDGE|Lang=en|Label=MQTT_GENERIC_BRIDGE}} ermöglicht es, sein jeweiliges IO-Modul-Gerät zu nutzen, um diesen Kommunikationsweg für beliebig viele andere FHEM-Geräte bereitzustellen. Dabei erfolgt am MQTT_GENERIC_BRIDGE-Gerät selbst nur eine Basiskonfiguration, im Übrigen durch Attribute an dem jeweiligen Gerät selbst. So kann z.B. ein Aktor des Typs [[CUL_HM]] an- oder ausgeschaltet werden oder auch einfach nur seinen aktuellen Schaltzustand per MQTT-Protokoll publizieren.

Dieses Modul kann seit November 2018 mit allen drei IO-Modul-Varianten zusammen eingesetzt werden, also sowohl mit ''MQTT2_SERVER'' bzw. ''MQTT2_CLIENT'' oder ''MQTT'' (00_MQTT.pm). Seit Rev. 23514 (Jan. 2021) wird für MQTT_GENERIC_BRIDGE iVm. den MQTT2-IO-Modulen '''keine zusätzliche Software mehr''' benötigt.

===== MQTT_GENERIC_BRIDGE und autocreate bei MQTT2-IO-Modulen =====
{{Randnotiz|RNTyp=g|RNText=Alternativ kann eine ''bridgeRegexp'' an einem beliebigen ''MQTT2_DEVICE'' existiert, die die betreffenden Nachrichten mit einer leeren CID zurückgibt.

Die technischen Hintergründe bzgl. autocreate sind diesem {{Link2Forum|Topic=95341|LinkText=Thread}} zu entnehmen.

Beispiel für die Erstellung einer passenden ''bridgeRegexp'':

Es existiert ein "Neben-FHEM" namens ''fhem2'', das von einem "Haupt-FHEM" namens ''fhem'' aus Nachrichten empfangen soll, die dann an die an ''fhem2'' angeschlossene Hardware weitergegeben werden. Die Nachrichten kommen über ein MQTT2_CLIENT-IO mit der CID ''fhem2'' in ''fhem2'' an. Das Haupt-FHEM sendet mit der ''$base'' ''fhem/''. Dann wäre in ''fhem2'' folgendes MQTT2_DEVICE anzulegen (der Name kann frei gewählt werden):
define M_G_B_bridgeRegex_device MQTT2_DEVICE fhem2
attr M_G_B_bridgeRegex_device bridgeRegexp [\b]fhem/.*:.* ""}}
Dabei sollte man jedoch beachten, dass eingehende MQTT-Nachrichten von den MQTT2-IO Modulen (''MQTT2_SERVER'' oder ''MQTT2_CLIENT'') nur dann an die ''MQTT_GENERIC_BRIDGE'' zur weiteren Auswertung übergeben werden, wenn

- zum einen '''kein passender readingList-Eintrag''' an irgendeinem ''MQTT2_DEVICE'' exisitert '''und''' die ''autocreate''-Funktion des betreffenden IOs ausgeschaltet wird und bleibt, '''oder'''
- die Priorität bei der Übergabe der Daten an die weiteren Module geändert wird. Hierfür stellen die Module ''MQTT2_SERVER'' oder ''MQTT2_CLIENT'' das Attribut ''clientOrder'' auf ''MQTT_GENERIC_BRIDGE MQTT2_DEVICE'' zu stellen:
attr <mqtt2_server> clientOrder MQTT_GENERIC_BRIDGE MQTT2_DEVICE

Die letztere Methode mit ''clientOrder'' wird zur Vermeidung von späteren Irritationen ausdrücklich empfohlen!

===== Anwendungsbeispiele =====
Anwendungsfälle und -beispiele für das Modul sind diesem {{Link2Forum|Topic=91642|LinkText=Thread}} zu entnehmen.

==== MQTT_BRIDGE ====
Dieses früher in FHEM enthaltene Modul kann nur zusammen mit einem IO-Gerät des Typs [[MQTT (Modul)|MQTT]] verwendet werden. Dabei wird pro weiterzuleitendem anderen FHEM-Gerät eine eigene Instanz dieses Moduls verwendet. '''Auf den Einsatz dieser Option sollte in neuen Installationen zugunsten von ''MQTT_GENERIC_BRIDGE'' verzichtet werden!'''
{{Hinweis|''MQTT_BRIGE'' wird seit FHEM-Version 6.1 nicht mehr direkt als Modul mit installiert. Es ist bei Bedarf in ''contrib'' zu finden.}}

==== Per publish-Befehl am IO-Gerät ====
Alle drei IO-Module kennen direkte ''publish''-Anweisungen, mit deren Hilfe beliebige ''payloads'' an beliebige ''topics'' gesendet werden können. Dies kann man z.B. in einem [[notify]] oder [[at]] nutzen, um einzelne Events zu publishen oder Werteanfragen abzusetzen.

Hier eine regelmäßige Werteabfrage auf einen [[EBUS-MQTT2|ebus]]:
defmod get_ebus_updates at +*00:15:00 set ebusMQTT publish ebusd/430/Hc1HeatCurve/get;
set ebusMQTT publish ebusd/430/HwcTempDesired/get;
...

==== RAW-Events am IO-Gerät (MQTT2.*) ====
Bei beiden MQTT2-IO-Modulen (MQTT2_SERVER und MQTT2_CLIENT) kann per [[Regulärer Ausdruck|regulärem Ausdruck]] festgelegt werden, welche Nachrichten ein Event erzeugen sollen, auf das dann wieder z.B. mit einem [[notify]] reagiert werden kann, z.B. um beliebige Schaltaktionen auszulösen.

== MQTT-Clients (Beispiele) ==

===Arduino-library===
Zur Kommunikation mit dem Broker von Seiten eines [[Arduino|Arduinos]] mit selbst erstellten Sketches böte sich der PubSubClient an.

===PC-Software===
Um die Funktionalität des Brokers zu testen kann z.B. ein Analyse-Tool wie MQTT.fx verwendet werden, oder die im Paket ''mosquitto-clients'' enthaltenen Linux-Kommandozeilen-Programme ''mosquitto_sub'' und ''mosquitto_pub''. Letzterer könnte z.E. auch aus beliebigen ''shell-scripten'' heraus aufgerufen werden. Als Perl-Bibliothek steht alternativ z.B. [https://metacpan.org/pod/distribution/AnyEvent-MQTT/bin/anyevent-mqtt-pub anyevent-mqtt-pub] zur Verfügung.

=== Tasmota ===
Eine derzeit oft genutzte Möglichkeit für MQTT bilden die [[Sonoff]]-Geräte und weitere [[ESP8266]]-basierte Hardware, die unter vielen Handelsnamen erhältlich sind. Werden diese mit Tasmota ('''T'''heo '''A'''rends '''S'''onoff '''M'''QTT '''O'''ver '''T'''he '''A'''ir - einer offenen Firmware von [https://github.com/arendst arendst]) geflasht, so kommunizieren sie über MQTT. Um diese Geräte einzubinden, ist wie folgt vorzugehen. Zuerst ist ein Serverdienst (Broker) bereitzustellen, wie oben beschrieben.

Unter Sonoff sind einige Topics voreingestellt. arendst stellt insbesondere drei Topic-Präfixe bereit, die seiner Meinung jedes Topic einleiten sollen (in den Eingabemasken als "%prefix%" notiert). Das sind einmal Kommandos (abgekürzt als cmnd), die dazu dienen, Befehle auszuführen. Daten werden mit tele und stat übertragen. Ein Topic besteht dann zuerst aus diesem Präfix und danach dem eigentlichen Topic. Wer also beispielsweise einem Sonoff_Switch einen Befehl senden will, sollte als Topic cmnd/Sonoff_Switch wählen. Wenn der Switch ein- und ausgeschaltet werden kann, muss der Topic noch das Wort POWER enthalten (in MQTT werden viele Kennworte komplett groß geschrieben). Der Topic lautet damit vollständig "cmnd/Sonoff_Switch/POWER/set"

{{Randnotiz|RNTyp=g|RNText=Dabei ist darauf zu achten, dass für den Parameter ''topic = %topic% (sonoff)'' statt ''sonoff'' ein gerätespezifischer eigener Name eingetragen wird. Hierzu kann man z.B. auch die dynamisch aus der Chip-ID erzeugte Kennung ''DVES_%06X'' verwenden, indem man die unter ''client (DVES_8BABA9)'' zu findende Angabe kopiert. Die eigentliche Umbenennung zu einem "sprechenden Namen" kann dann innerhalb von FHEM - mittels ''rename'' oder ggf. mit einem ''alias'' - erfolgen.}}

Link zum Forum: {{Link2Forum|Topic=27532|LinkText=MQTT FHEM Einrichtung}} (hier als ''MQTT_DEVICE''!):

### FHEM Device mit MQTT verbinden ###
define Sonoff_Switch MQTT_DEVICE
attr Sonoff_Switch IODev myBroker
attr Sonoff_Switch devStateIcon ON:rc_GREEN:OFF OFF:rc_RED:ON
attr Sonoff_Switch icon hue_filled_br30
attr Sonoff_Switch publishSet ON OFF cmnd/TestSwitch/POWER
attr Sonoff_Switch room MQTT
attr Sonoff_Switch subscribeReading_Licht stat/Sonoff_Switch/POWER
attr Sonoff_Switch subscribeReading_Sensor tele/Sonoff_Switch/SENSOR
attr Sonoff_Switch subscribeReading_Status stat/Sonoff_Switch/STATUS
attr Sonoff_Switch webCmd ON:OFF

Der hier dargestellte Beispielcode realisiert die Kommunikation zwischen FHEM und dem sonoff Modul via MQTT Broker. Zu beachten ist hier, dass '''subscribeReading_Licht''' und '''subscribeReading_Status''' unterschiedliche Syntax des Topic Strings haben!

=== OpenMQTTGateway ===
Um verschiedene Systeme wie BLE usw. auf MQTT zu bringen bietet sich [https://github.com/1technophile/OpenMQTTGateway OpenMQTTGateway] an, z.B. wird für das Auslesen vieler BLE-Sensoren lediglich ein ESP32-Board ohne Zusatzhardware (ab ca. 5,- Euro in Fernost erhältlich) benötigt, auf das dann eine vorkompilierte Firmware geflasht wird (USB-seriell-Wandler erforderlich).

Nähere Details sind im Artikel [[OpenMQTTGateway]] zu finden.

== Sicherheit ==
Prinzipiell ist MQTT ebenso sicher wie eine Postkarte. Solange man es nicht extra absichert, kann jeder der, im eigenen LAN ist (und die Adresse vom Broker kennt) alle Topics mitlesen.
:<code>meinHaus/Flur/Haustuer:open / close</code>
bietet unter diesen Umständen reichlich Raum für Verbesserungen!

Abhilfe:
=== Username / Passwort ===
Zunächst kann man erst mal einen Username / Passwort vergeben, was alle IO-Device-Module unterstützen. Da ist zwar auch noch lange nicht sicher, aber zumindest steigert es den Aufwand schon mal. Jetzt muss man zumindest schon mal Pakete sniffen und verstehen, um unbefugt zu lesen oder gar zu publishen.

=== TLS ===
Um wirklich sicher zu werden, führt kein Weg an TLS vorbei.

Der MQTT-Client in [[#Tasmota|Tasmota]] (für ESP8266) kann mit TLS betrieben werden, vgl. [https://github.com/arendst/Tasmota/wiki/TLS Beschreibung im Tasmota-Wiki].

Leider kann z.B. ein Arduino das schlicht nicht mehr, da die einfacheren Modelle nicht über ausreichend Speicher und die Rechenleistung verfügen.

'''(Hier fehlt eine Anleitung für allowed usw.)'''

== Probleme ==
=== Anweisung und Ergebnis weichen voneinander ab ===
In der Regel melden MQTT-fähige Geräte entweder den Erhalt einer Nachricht zurück oder den Status nach Durchführung der in der ''payload'' enthaltenen Anweisung. Dabei findet aber in der Regel beim Empfänger eine Verarbeitung der Nachricht statt, ggf. wird diese auch weitergesendet und nochmals verarbeitet, bevor dann ggf. eine Rückmeldung des neuen Status an den MQTT-Server erfolgt. Handelt es sich um einfache on/off-Befehle, bleibt Anweisung und Ergebnis in der Regel identisch. Bei anderen, namentlich bei Dimmer-Werten, kann es zu Rundungsdifferenzen bei nummerischen Werten kommen. So kann z.B. ein Dimm-Wert von 70% gesetzt werden, zürückgemeldet wird dann aber 72% (oder 67%).
Dies ist technisch bedingt, vermeiden kann das jedoch in aller Regel nur der Autor der jeweiligen software/firmware auf dem "rechnenden" Gerät.

=== Unbeabsichtigte Schleifen ===
Durch Fehler in der topic-Struktur können unbeabsichtigte Schleifen entstehen, die FHEM komplett blockieren können. Es ist unbedingt darauf zu achten, dass die jeweiligen Sende- und Empfangs-topics andere sind!

== FAQ ==
=== Welche Infos sollten Anfragen im MQTT-Forum enthalten? ===
* Anfragen bitte nur zur aktuellsten FHEM-Version: Befehl <code>update</code> ergibt Ausgabe "nothing to do..."
* detaillierte Beschreibung des Problems
* Art der Einbindung
** eingesetzter MQTT-Server? (=> MQTT2_SERVER oder externer Serverdienst wie mosquitto?)
** Wenn externer Server: Interface-Modul: MQTT2_CLIENT oder 00_MQTT.pm?
** Wenn MQTT2_SERVER: ''list'' beifügen und klären, ob dieser von der jeweiligen Komponente aus im Netzwerk zu erreichen ist:
*** steht auf "global"?
*** ggf. passendes [[allowed]] definiert, falls weiter entferntes Netzwerk oder falls Zugangsbeschränkungen/Authentifizierungsverfahren eingestellt sind?
*** Modifikationen am ''autocreate''-Attribut?
** Bitte einen Hinweis, falls MQTT_GENERIC_BRIDGE definiert ist bzw. auch ein ''list'' von der MQTT_GENERIC_BRIDGE.
** TYPE des eigentlichen MQTT-Devices (MQTT2_DEVICE, MQTT_DEVICE, TASMOTA_DEVICE, ...)
* Informationen zur eigentlichen Komponente:
** Hersteller, ggf. aktuell verwendete firmware incl. Version (Beispiel: ein Shelly-Gerät mit originaler firmware verhält sich anders als dasselbe Gerät mit Tasmota-, ESPEasy oder ESPurna-firmware!).
** Infos zur MQTT-Konfiguration auf dem Gerät selbst
** Bei weniger gängigen Komponenten oder Diensten:
*** (sofern vorhanden): Link zu Projektseiten, MQTT-API-Seiten usw..
*** Mittschnitte des MQTT-Verkehrs (z.B. durch Einschalten der rawEvents an den MQTT2-Interface-Modulen, s.o.).
** Ein ''list'' des eigentlichen Devices - bei MQTT2_DEVICE gerne in Form einer RAW-Definition (''list -r <devicename>'').
* Bei MQTT2-Einbindung und aktiviertem ''autocreate'' an den Interface-Modulen den Status des ''autocreate''-'Devices:
list TYPE=autocreate
=== Älterer FAQ-Thread im Forum ===
Dieser ist {{Link2Forum|Topic=70119|LinkText=hier}} zu finden. Bitte beachten: es sind einige grundlegende Informationen und Links zu vielen Tools und Fundstellen enthalten, allerdings nur bis zum Stand des Jahres 2017. Die neue Modulgeneration MQTT2_.* wird dort nicht behandelt.

== Links ==
* [http://mqtt.org Offizielle Homepage von MQTT, englisch]
* [http://www.hivemq.com/blog/mqtt-essentials-part-1-introducing-mqtt Sehr gute Einführung, englisch, sind 5 lesenswerte Teile]
* [https://www.heise.de/developer/artikel/MQTT-Protokoll-fuer-das-Internet-der-Dinge-2168152.html Ein Exkurs von Heise mit Beispielen, deutsch, sehr lesenswert]
* [http://www.mqttfx.org/ MQTT FX - ein sehr praktisches Analysetool]
* {{Link2Forum|Topic=69230|LinkText=Diskussionsthread im Forum}}
* {{Link2Forum|Topic=92888|LinkText=Thread, zur Entstehungsgeschichte von MQTT2_CLIENT}}
* {{Link2Forum|Topic=93255|LinkText=Ankündigungsthread zur MQTT2-Erweiterung der MQTT_GENERIC_BRIDGE}}
* [[MQTT_Einf%C3%BChrung_Teil_2|Teil 2 der MQTT Einführung]]: Detailaspekte (vorrangig zur Modulfamilie MQTT/MQTT_DEVICE)
* [[MQTT Einführung Teil 3|Teil 3 der MQTT Einführung]]: Arduino-Client selbst programmieren

== Hinweise ==
<references />

[[Kategorie:Glossary]]
[[Kategorie:HOWTOS]]
[[Kategorie:MQTT|Einführung]]
[[Kategorie:MQTT| ]]

DevelopmentGuidelinesReadings

2025-02-21T20:26:38Z

Beta-User: Teilweise Übernahme aus Diskussionssthread

=Deutsch=
== Einleitung ==
Auf dieser Seite werden Richtlinien für Readings gesammelt, welche in mehreren Modulen auftauchen können um eine Vereinheitlichung zu erreichen. Dadurch soll es Hilfsmodulen und Anwendern leichter fallen, mit den Werten der Readings zu arbeiten.

== Batterie-Readings ==
Basierend auf dieser {{Link2Forum|Topic=87575|LinkText=Diskussion}} haben sich die Entwickler für Readings, welche in Zusammenhang mit Batterien stehen auf folgendes geeinigt:
Es gibt '''nur''' diese drei Readings für den Batteriestatus:
* batteryState
* batteryPercent
* batteryVoltage

Wertebereich:
*batteryState: ok|low
*batteryPercent: \d{1,2}|100
*batteryVoltage: \d+.\d+

Wichtig:
das jeweilige Modul setzt '''nur''' die Readings, die es aus den aktuellen Daten vom Gerät bestimmen kann. Konkret: niemand kann sich darauf verlassen, welche der drei battery Readings vorhanden sind (es gibt nicht überall ein batteryState). Wenn das Gerät früher ein Percent gemeldet hat, aber in der letzten Nachricht nur state, dann wird das Percent Reading nicht angefasst.

<nowiki>####</nowiki> ab hier Entwurf #####

== Energieflüsse ==
Siehe Thread {{Link2Forum|Topic=116747|LinkText=Frevel: Die Idee einheitlicher Devicenamen und Readings}}

== Diskussionsvorschläge für künftige Module ==
Quelle: {{Link2Forum|Topic=117933|LinkText=Diskussion}}

'''Schaltbare Geräte (mehrkanalig=>erster Kanal, "Hauptschalter" oä.):'''
- "state" mit Werten "on" bzw. "off" (für laufende Schaltvorgänge auch "set_xx", s.u.)

'''Leuchtmittel:'''

- "state" wie "schaltbare Geräte"

- "pct" für Helligkeit (Wertebereich: 0-100), alternativ "dim" (Wertebereich: 0-99) oder "brightness" (Wertebereich: 0-255 (bzw. 254))

- "ct" (alternativ: "colorTemp") für die Farbtemperatur

- "hue" für den Farbwert (ohne Helligkeitsanteil)

- "rgb" (alternativ: "color" oder "hex") für Farbwerte mit Helligkeitsanteil (rrggbb)

- "sat" (oder "saturation") für die Farbsättigung

'''Rollladen- und Jalousieaktoren:'''

Wie Leuchtmittel, in der Regel sollte "offen" = "on" = "100" (pct) sein (komplett invertiert ist zulässig)

Falls drehbare Lamellen (direkt) im Device einstellbar sind: "pctSlats" (0-100, 100= ganz nach oben gekippt) (to be verified!)

'''Thermostate (einstellbare Wunschtemperatur):'''

- "desired-temp" für die Wunschtemperatur (typischerweise in °C)

- "temperature" für die gemessene Temperatur, alternativ auch "measured-temp"

- "valve" (oder "level") für Stellgrößen (z.B. Ventilöffnung, "valve" typischerweise 0-100 (%))

'''Thermometer:'''

Temperatur in Reading "temperature" oder "state"

'''Feuchtigkeitsmesser:'''

Luftfeuchte in "humidity", Bodenfeuchte als "moisture"

'''Bewegungs- oder Präsenzmelder, Kontakte:'''

"motion" mit "on" oder "off" bzw. motion/noMotion

"presence" mit "on" oder "off" bzw. present/absent

"contact" mit "open" oder "closed" bzw. "on" oder "off"

'''Füllstandssensoren:'''

"pct" oder "level" (typischerweise in %), bei Koexistenz mit "pct" ggf. "level" als absoluter Messwert (Einheit nicht festgelegt)

'''Drucksensoren:'''

"pressure"

'''Schlösser:'''

"state" für den Haupt-Schließzustand (locked / unlocked?)

set-Befehle: "lock" und "unlock"

'''Geräte, die voreingestellte Szenarien einstellen können:'''

set-Befehl mit "scene"

'''Allgemeiner Gerätestatus'''

- "availability" ("online"/"offline" bzw. "present" / "absent") (Für MQTT alternativer Readingname: "LWT")

- "lastseen" (Zeitstempel in Sekunden)

'''Allgemeines:'''

Als "Transitstatus" darf (analog z.B. CUL_HM) auch ein "set_xx" in allen Readings stehen, bis (hoffentlich...) die Bestätigung vom Gerät zurückkommt, dass das ausgeführt wurde.

also Anweisung "set DEVICE brightness 77" ergibt übergangsweisen Readinginhalt für "brightness" mit "set_77".

<nowiki>#####</nowiki> Ende Entwurf #####

=English=
== Start ==
On this page you will find guidlines how to name common readings. These guidlines are for readings which are used in more than one module and should have the same possible values. This makes it helper modules and users easier, to work with the values from common readings.

== Battery Reading ==
Based on this {{Link2Forum|Topic=87575|LinkText=discussion}} battery-readings should '''only''' be named like:
* batteryState
* batteryPercent
* batteryVoltage

The values should only be:
*batteryState: ok|low
*batteryPercent: \d{1,2}|100
*batteryVoltage: \d+.\d+

Important: The FHEM module will '''only''' report the values received from the device, i.e. not each module reports a batteryState reading. Additionally, if the device sent a batteryPercent value earlier but the last message from the device only contained a 'battery: low', the batteryPercent reading wont be changed.

[[Kategorie:Development]]

MQTT2 DEVICE - Schritt für Schritt

2025-02-21T07:51:15Z

Beta-User: /* MQTT - Datenverkehr mitlesen */ Bild eingefügt

== Einführung ==
Das Protokoll [[MQTT]] ermöglicht einen flexiblen Datenaustausch zwischen unterschiedlichsten Geräten und FHEM und insbesondere auch bidirektionale Kommunikation von und zu FHEM. Es gibt dabei jedoch nur einen geringen Grad der Standardisierung des Datenaustauschs. In der Praxis sind daher relative viele unterschiedliche Wege aufzufinden, wie die Kommunikation via MQTT in den externen Geräten und Diensten konkret umgesetzt wurde - jeder Autor einer firmware oder Software kann dies so lösen, wie es ihm beliebt, und nicht jeder beherzigt dabei den Grundsatz, dass die Kommunikation via MQTT "leichtgewichtig" sein sollte.

{{Randnotiz|RNTyp=Info|RNText=Grundsätzlich stehen für viele Geräte-Typen bereits Vorlagen zur Verfügung, siehe [[AttrTemplate|attrTemplate]], die einem die wesentliche Konfigurationsarbeit abnehmen können, wie sie hier beschrieben ist. Die damit jeweils erzeugten Konfigurationen sind Einrichtungsbeispiele, die v.a. eine in sich konsistenze Zusammenstellung der verschiedenen Attribute enthalten. Es steht jedem User frei, diese Ausgangsbasis dann nach seinem Belieben zu ändern. Spätere Änderungen des verwendeten attrTemplate wirken sich nicht automatisch auf die durch frühere Versionen oder den User nachkonfigurierte Geräte aus! Da es vorkommen kann, dass sich die per MQTT übermittelten Daten und Topics ändern, wenn z.B. eine firmware aktualisiert wurden, kann dies Anpassungen am jeweiligen Template erforderlich machen. Grundsätzlich sollen die per attrTemplate für MQTT2_DEVICE verfügbaren attrTemplate jeweils für die aktuellste verfügbare stabile firmware-Version passen.}}

Das Modul [[MQTT2_DEVICE]] bietet eine Vielzahl von Möglichkeiten, auf die verschiedensten Anforderungen einzugehen, und die ein- und ausgehenden Daten zu einem oder mehreren FHEM-[[Gerät|Gerät/en]] zusammenzufassen. Eine Übersicht häufig vorkommender MQTT-Geräte ist in [[MQTT2-Module - Praxisbeispiele]] zu finden.

Ziel dieses Artikels ist die Darstellung der Schritte, die sich als zweckmäßig erwiesen haben zur Einrichtung von "guten" FHEM-Geräten.
{{Randnotiz|RNTyp=Info|RNText=Viele - teils komplexe Beispiele und weitere Verweise sind im {{Link2Forum|Topic=116162|LinkText=MQTT-Workshop für MQTT2-Module}} zu finden.}}Dabei soll am Ende erreicht werden:
* standardisierte set- (und ggf. get-)-Kommandos, insbesondere unter Beachtung der [[DevelopmentGuidelinesReadings| Developer Guidelines für Readings]]
* Schließen des Informationskreises von eventuellen Kommandos bis zur Rückmeldung des (externen) Gerätes oder Dienstes (im Folgenden: "Gegenstelle")
* standardisierte Reading-Namen, damit möglichst Auswertungen nicht speziell an das jeweilige Gerät angepasst werden müssen
* Reduzierung und Vermeidung von unnötigen Datenpunkten und Events
* Einrichten von regelmäßigen Abfrage-Timern (falls erforderlich!).

== Vorbereitung ==
=== MQTT2_SERVER ===
Selbst, wenn grundsätzlich ein externer MQTT-Server IO-Device zum Einsatz kommt, ist sehr zu empfehlen, für die Beschäftigung mit einem neuen, unbekannten Device zunächst einen {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} einzurichten. Ist der Port 1883 bereits belegt, nimmt man einfach einen anderen Port, z.B. 1884: <code>define m2server MQTT2_SERVER 1884 global</code>. Sollte die Gegenstelle tiefer strukturierte Daten im JSON-Format über verschiedene Topics als Payload übermittelt, kann es ausnahmsweise hilfreich sein, '''in der Einrichtungsphase''' auch das Attribut "autocreate" am MQTT2_SERVER auf "complex" zu stellen: <code>attr m2server autocreate complex</code>. Weiter muss die allgemeine [[Autocreate|autocreate-Instanz]] aktiv sein. Für den Regelbetrieb und für einfache, bekannte Devices (sowie für solche, für die bereits attrTemplate vorhanden sind), wird ausdrücklich empfohlen, das ''autocreate''-Atribut am m2server gar nicht erst zu setzten, dann wird ''autocreate'' mit der (default) Einstellung ''simple'' verwendet. Die Hintergründe sind nachfolgend im Abschnitt zu ''json2nameValue()'' zu finden.

=== Begrifflichkeiten ===
Ein typisches, von "autocreate" erstelltes Gerät sieht dann z.b. (mit autocreate = simple am MQTT2_SERVER) so aus:
<syntaxhighlight lang="text">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD readingList DVES_9B01BD:tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/LWT:.* LWT\
DVES_9B01BD:tele/DVES_9B01BD/UPTIME:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/SENSOR:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO1:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO2:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO3:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/RESULT:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }
attr MQTT2_DVES_9B01BD room MQTT2_DEVICE
</syntaxhighlight>
Wir unterscheiden bei jeder Zeile des readingList-Attributs vier Elemente, die ersten drei werden jeweils durch einen Doppelpunkt voneinander getrennt:
==== CID ====
Dies ist die Gerätekennung (hier: DVES_9B01BD). Diese ist auch Bestandteil des ''define'', über diese wird ermittelt, zu welchem FHEM-Gerät via MQTT eingehende Informationen zugeordnet werden sollen. Diese Angabe ist weder im define noch in der readingList zwingend, aber in der Definition für den Hauptkanal eines Gerätes empfohlen. Es empfiehlt sich, die CID-Angaben bei eigenen readingList-Einträgen wegzulassen bzw. diese zu löschen. So kann einfacher zwischen automatisch generierten und eigenen Angaben unterschieden werden und die Geräte sind leichter zwischen verschiedenen IO-Modulen zu verschieben.
==== Topic ====
Datenpunkt, an den eine Information gesendet wird. Empfangsseitig sind dies hier z.B. ''tele/DVES_9B01BD/STATE'' oder ''tele/DVES_9B01BD/LWT''.
Enthält der Topic Doppelpunkte oder Sonderzeichen, kann dies zu Problemen führen. Da der Topic intern als ''regex'' behandelt wird, kann man sich das in solchen Sonderfälle dadurch zu nutze machen, dass man z.B problematische Zeichen durch Punkte oder "beliebige Zeichenfolgen" ersetzt. So kann z.B. aus dem per autocreate erstellten <code>attr reader readingList SMLReader/Strom/sensor/1/obis/1-0:1.8.0/255/value:.* Strombezug_tariflos</code> folgendes abgeleitet werden: <code>attr reader readingList SMLReader/Strom/sensor/1/obis/1-0.1.8.0/255/value:.* Strombezug_tariflos</code>,

==== Payload ====
Der jeweilige Nachrichteninhalt. Da dieser nicht im vorhinein bekannt ist, wird er in der readingList typischerweise als "beliebige Zeichenfolge" (".*") notiert.

==== Auswertung ====
Dies kann entweder direkt der Reading-Name sein, dem die Payload zugeordnet werden soll, oder ein Perl-Ausdruck. Hier wird z.B. die eingehende Information für ''tele/DVES_9B01BD/LWT'' dem Reading ''LWT'' zugeordnet, während die Informationen aus ''tele/DVES_9B01BD/STATE'' an die Funktion ''json2nameValue()'' übergeben werden. ''$EVENT'' entspricht dabei der ''Payload''.

=== defaults ===
Für unbekannte Gegenstellen ist zunächst immer zu empfehlen, deren "Grundeinstellungen" zu verwenden, und Anpassungen erst und nur insoweit vorzunehmen, als es für ein besseres Zusammenspiel mit FHEM sinnvoll ist. Abzuraten ist insbesondere von:
* Änderungen der Topics und Topic-Sturkturen (ausgenommen den Fall, dass schon andere Gegenstellen im Einsatz sind, die identische Topics verwenden)
* Vergabe von ''friendly names''

== Bestandsaufnahme ==
=== Projektseiten finden ===
Viele Geräte, die das MQTT-Protokoll verwenden, haben eigene Projektseiten oder API-Beschreibungen, denen man entnehmen kann, wie mit dieser Gegenstelle Daten ausgetauscht werden können. Diese sollte man bei allen weiteren Schritten stets zur Hand haben. Dabei kann es neben der allgemeinen Beschreibung auch ein oder mehrere Detail-Seiten geben, auf denen nähere Informationen zu den spezifischen Geräte zu finden sein können.

=== MQTT - Datenverkehr mitlesen ===
[[Datei:Show MQTT traffic.png|mini|466x466px|Beispiel für einen erfolgreichen ''publish-''Test mit MQTT2_CLIENT mit anschließender Rückübermittlung derselben Message vom MQTT-Server.]]
Sowohl MQTT2_SERVER wie MQTT2_CLIENT bieten in der Detailansicht die Option ''Show MQTT traffic''. Darüber läßt sich der ein- und ausgehende Datenverkehr bequem mitlesen. Bei MQTT2_CLIENT wird dabei allerdings vorausgesetzt, dass er überhaupt Daten vom MQTT-Server erhält, also insbesondere die ''subscriptions'' korrekt gesetzt sind (falls per Attribut eingeschränkt).

=== readingList ===
Zunächst empfiehlt es sich, einfach die Gegenstelle neu zu starten und (ggf. über ein FileLog) aufzuzuzeichnen, was über welchen Topic wie oft an Informationen gesendet wird. Dabei kann und sollte durchaus - sofern dies möglich ist - der eine oder andere Schaltvorgang (z.B. über das Web-Interface der Gegenstelle) durchgeführt werden, sofern dies möglich ist (oder allgemeiner: möglichst viele bekannte Anweisungen ausführen lassen). Am Ende sollte man eine möglichst vollständige Auflistung in der readingList erhalten haben.
Falls strukturierte Daten im JSON-Format als Payload verwendet werden, kann man diese auch zusätzlich ohne die Verarbeitung durch ''json2nameValue()'' aufzeichnen, z.B. indem man die betreffende Zeile in der readingList doppelt:
<syntaxhighlight lang="text">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD readingList tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
tele/DVES_9B01BD/STATE:.* json_STATE\
tele/DVES_9B01BD/LWT:.* LWT\
[...]
</syntaxhighlight>
So kann man mit Hilfe des betreffenden Logs ggf. auch über ein externes Tool wie mosquitto_pub MQTT-Nachrichten an FHEM generieren, ohne darauf warten zu müssen, dass diese von der Gegenstelle selbst erzeugt werden.

=== ignoreRegexp ===
Manche Gegenstellen senden beim Start Konfigurationsinformationen, die allerdings nicht durch FHEM ausgewertet werden können. Die betreffenden Topics sollte man (allgemein) so in die ignoreRegexp beim MQTT2_SERVER bzw. [[MQTT2_CLIENT]] aufnehmen, dass derartige Informationen künftig gar nicht mehr an MQTT2_DEVICE weitergereicht werden. Danach kann man die betreffenden Zeilen aus der readingList löschen! Entsprechendes gilt für die hierüber generierten Readings.

Weiter ist zu empfehlen, in diese ignoreRegexp auch die Topics aufzunehmen, über die Gegenstellen typischerweise Kommandos entgegennehmen. Dies könnte z.B. so aussehen:
<code>attr m2server ignoreRegexp shellies/[^/]+/command|cmnd/[^/]+/|homeassistant/.*/config|tasmota/discovery</code>

=== Viele Geräte? ===
==== "split" ====
Sind auf einer Hardware mehrere "Hauptschalter" vorhanden (z.B. ein Relay-Board), ist sehr zu empfehlen, für jeden dieser "Hauptschalter" ein eigenes FHEM-Gerät anzulegen (für logische Einheiten wie Rollladenaktoren ggf. paarweise). MQTT2_DEVICE unterstützt [[DevelopmentModuleAPI#SetExtensions|SetExtensions]] und kann daher Kommandos wie "on-for-timer" über FHEM-interne Mechanismen gut umsetzen. Dies erfordert allerdings, dass die Kommandos "on" und "off" verfügbar sein müssen.
Wird ein Gerät gesplittet, sollten im Gerät, das den ersten (Haupt-) Kanal repräsentiert dann alle Kommunikationsdaten gebündelt werden, Querverweise zu den weiteren Kanälen kann man über das spezielle Readings "associatedWith" herstellen.

==== bridgeRegexp ====
{{Randnotiz|RNTyp=Info|RNText=Manche derartige Interfaces müssen zunächst entsprechend konfiguriert werden, dass die zu einem Sensor oder Aktor gehörenden Daten jeweils auf einem eigenen Topic ausgegeben werden. Insbesondere ist dies bei Tasmota (ZigBee oder Bluetooth) der Fall!}}
In eher seltenen Fällen kommt es vor, dass eine Gegenstelle eine Art "Brücke" zu einer Mehrzahl über diese Brücke anzusteuernder (oder zu empfangender) Aktoren oder Sensoren darstellt. In diesen Fällen kann es geboten sein, die eigentliche Gegenstelle als Hauptdevice darzustellen und für jede weitere Hardware (Sensor oder Aktor) dann ein oder mehrere Einzeldevices anzulegen. Dies kann mit Hilfe des Attributs bridgeRegexp automatisiert erfolgen, wenn sich der Sensor/Aktor aus der Topic-Struktur ablesen läßt.

== readingList optimieren==
=== gute Reading-Namen - Klartext ===
{{Randnotiz|RNTyp=Info|RNText=Beachte zur Vergabe von Reading-Namen v.a. auch [[DevelopmentGuidelinesReadings]] und [[DevelopmentGuidelinesAV]].}}
Viele Gegenstellen senden z.B. einen online/offline-Status als "last will and testament" unter einem Topic, der mit "LWT" endet. Dieses hier sendet zwar passende Daten, aber an einen anderen Topic. In solchen Fällen man kann den von autocreate erzeugten Eintrag einfach anpassen:
attr DEVICE readingList /dingtian/DEVNAME/out/lwt_availability:.* LWT

=== Bedingte Hash-Rückgaben ===
Manchmal erfolgt zwar die Übergabe eines Klartextes als $EVENT - allerdings nicht in der Form, wie man das in FHEM gerne hätte. Hier als "0" oder "1". Mit etwas Perl und der Rückgabe eines Hashes kann man so etwas beliebig umformen:
attr DEVICE readingList DEVNAME/relay/0:.* { $EVENT ? {state=>'on'} : {state=>'off'} }\
DEVNAME/status:.* { $EVENT ? {LWT=>'Online'} : {LWT=>'Offline'} }
Weiteres Beispiel: Der "state" kommt in Großschreibung und soll in Kleinschreibung geändert werden:
attr DEVICE readingList switchbot/esp32_2/bot/switchbottwo/state:.* { { state => lc $EVENT } }

=== json2nameValue() ===
Mit Hilfe der Funktion json2nameValue() (in Verbindung mit dem attribut ''jsonMap'') lassen sich
* "gute Reading-Namen" auch aus JSON-Payloads erzeugen (2. und 3. Argument)
* unnötige Readings vorab ausfiltern (3., 4. und 5. Argument)
Beispiele für die Verwendung der Argumente 1 bis 3 sind der commandref in der Erläuterung des Attributs ''jsonMap'' bei MQTT2_DEVICE zu entnehmen, die (wie die Argumente 2 und 3 optionalen) Argumente 4 und 5 entsprechen einem Positiv- bzw.- Negativ-Filter.
Wird (übergangsweise!) ''autocreate'' in der ''complex''-Variante eingestellt, werden für alle (bisher nicht bekannten) Topics Einträge wie dieser erzeugt:
attr MQTT2_DVES_9B01BD readingList tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT,'STATE_',$JSONMAP) }
* Das zweite Argument (''STATE_'') ist ein "Präfix", der allen aus dem JSON erzeugten Readings aus diesem Topic (zunächst) vorangestellt wird. Mit dessen Hilfe läßt sich rekonsturieren, aus welchem Topic die betreffende Information ursprünglich kam. In der Regel ist dies nach der Einrichtung nicht mehr wichtig, und dieses Argument kann auf "nichts" (zwei einfache Quotes) gestellt werden. Allerdings kann es in Einzelfällen sinnvoll sein, Präfixe zu verwenden, um zwischen scheinbar gleichen Werte aus unterschiedlichen Quellen zu unterscheiden. Dies kann man erst abschließend entscheiden, wenn alle von der Gegenstelle gelieferten Daten bekannt sind.
* Das dritte Argument ''$JSONMAP'' kann in der Regel so belassen werden. Dann kann mit Hilfe des Attributs ''jsonMap'' eine Zuordnungstabelle für Namensänderungen für die zu generierenden Readingnamen erzeugt und/oder Werte schlicht gelöscht werden.
<syntaxhighlight lang="perl6">
json2nameValue($EVENT,'STATE_',$JSONMAP,'positiv')
json2nameValue($EVENT,'STATE_',$JSONMAP,'','negativ')
</syntaxhighlight>
* Das vierte Argument ist optional. Es ist ein (Positiv) Filter, der nur Readings in der Liste erscheinen lässt, die diesem Argument entsprechen, im Beispiel oben wären das alle Readings, die den Ausdruck "positiv" enthalten. Das Argument selber ist eine regexp. '''Achtung:''' Wird dieses Argument zusammen mit dem Attribut jsonMap benutzt, so wird zuerst das Mapping auf die neuen Readings-Bezeichnungen ausgeführt und erst dann dieser Filter ausgeführt, d. h. es muss auf die ersetzten Readings-Bezeichnungen gefiltert werden!
* Das fünfte Argument ist ebenfalls optional. Es ist ein (Negativ) Filter. Im obigen Beispiel werden alle Readings, die den Ausdruck "negativ" enthalten, aus den Readings ausgefiltert. Ebenso wie das 4. Argument ist es eine regexp. Im Zusammenspiel mit jsonMap wird hier zuerst der Filter ausgewertet und erst anschließend erfolgt das Mapping auf die neuen Readings-Namen.

=== Auswertung unterbinden ===
Indem man einen Perl-Aufruf festlegt (geschweifte Klammern), dieser aber nichts zurückgibt, kann man bestimmte unerwünschte Readings ausfiltern. Im einfachsten Fall wäre dies:
shellies/DEVNAME/temperature_f:.* {}

Komplexer mit Auswertung der Payload:
STATTOPIC/RESULT:.* { $EVENT =~ m{HSBColor...(\d+),(\d+),(\d+)} ? $2 eq ReadingsVal($NAME,'saturation','unknown') ? return : { saturation=>$2 } : return }

=== Perl ===
Wie am Beispiel der speziellen Funktion <code>json2nameValue()</code> sowie der Hash-Rückgabe bereits dargestellt, ist es möglich, bei der Auswertung auch Perl-Funktionen einzusetzen, und diverse Variablen an diese zu übergeben. Ebenso ist es möglich, eigenen Perl-Code zu verwenden, der z.B. dann längere Zuordnungstabellen, Event-Reduzierungsmechanismen, ... enthalten kann.

== Events optimieren==
Leider senden relativ viele Gegenstellen in ihren Standardeinstellungen sehr viele Daten, auch ohne dass sich etwas geändert hätte. Dies erzeugt uU. in FHEM eine erhebliche Last, so dass es dringend zu empfehlen ist, alle Maßnahmen zu prüfen, durch die dieses Verhalten unterbunden oder vermindert werden kann. Dabei sollte möglichst frühzeitig eingegriffen werden, entsprechend den folgenden Handlungsoptionen: Daten, die die firmware gar nicht erst sendet, muss FHEM nicht am Interface-Modul entgegennehmen. Daten, die direkt am Interface-Modul verworfen werden (ignoreRegexp), muss das Client-Modul nicht auswerten. Readings, die man (an einem bestimmten Device) nicht benötigt, sollte man nicht erzeugen, damit keine [[Eventhandler]] aktiv werden müssen, unveränderte, aber gewünschte Daten müssen nicht unbedingt (immer) Events erzeugen.

=== firmware-Einstellungen ===
Bei manchen firmwares kann man einstellen, ob bzw. wie oft oder aus welchem Anlass Daten gesendet werden sollen. Es wird dringlich empfohlen, bei "gesprächigen" Gegenstellen zu recherchieren, ob und in welcher Weise diese derartige Möglichkeiten bietet. Falls solche nicht vorhanden sind, lohnt es sich, auf den betreffenden Projektseiten nachzufragen, ob es diese Optionen gibt - nicht selten hat sich ein firmware-Autor darüber schlicht noch keine Gedanken gemacht und baut in der nächsten Version ggf. entsprechende Optionen ein?

=== Auswertung unterbinden ===
(s.o. für Topics/Readings, die gar nicht benötigt werden). Dies ist insbesondere auch zu empfehlen, wenn identische Daten zum gleichen Zeitpunkt sowohl als Klartext wie auch in einem JSON-Format übermittelt werden. In solchen Fällen ist es eher zu empfehlen, die JSON-Zweige zu abonnieren und den Rest (ggf. über einen ignoreRegexp-Eintrag) gar nicht auszuwerten.
Doppelungen sollten in jedem Fall vermieden werden!
Grundsätzlich erzeugt jeder Topic eine eigene Event-Loop, mehrere Readings-updates, die aus einer einzigen JSON-Payload abgeleitet werden, erzeugen dagegen eine gemeinsame Event-Loop. Durch solche Maßnahmen läßt sich die Systembelastung deutlich reduzieren.
Für Daten aus JSON-Payloads besteht darüber hinaus die Möglichkeit, diese komplett auszufiltern (siehe jsonMap weiter oben)

=== event-on-change-reading und Co. ===
Da die firmwares häufig recht gesprächig programmiert sind, sollte man auf eine sinnvolle Begrenzung der durch Aktualisierungen verursachten Events besonderen Wert legen. Dazu ist in erster Linie das Attribut [[Event-on-change-reading|event-on-change-reading]] zu bearbeiten und ggf. passende threshold-Werte zu setzen, es empfiehlt sich allerdings, dabei auch zu untersuchen, inwieweit die weiteren, funktional ergänzenden Attribute zu setzen sind:
* [[Event-min-interval|event-min-interval]]
* [[Event-on-update-reading|event-on-update-reading]]
* timestamp-on-change-reading und
* [[Event-aggregator|event-aggregator]]

=== gute Reading-Namen - userReadings ===
Manchmal werden per MQTT Werte übersendet, die so nicht direkt verwendbar sind. Beispiele hierfür wären:
* Batteriespannungen in mV (z.B. bei zigbee2mqtt)
* Farbwerte als Einzelreading (für die Anzeige in FHEM wird aber ein RGB-Wert benötigt)
In diesen Fällen kann man zwar nicht ohne weiteres den Ausgangswert umrechnen lassen, (über externe Module wie readingsChange sehr wohl), aber es ist über den Weg "userReadings" ohne weiteres möglich, passende Readings zu generieren. Dabei sollte aber zur Verringerung der Systembelastung allgemein sowie ggf. falscher Ergebnisse unbedingt darauf geachtet werden, dass diese auch mit einer ''trigger''-Angabe versehen sind!

== setList ==

=== Allgemeines ===
Die setList ist dazu gedacht, Kommandos zu definieren, welche an die Gegenstelle gesendet werden können.

=== Syntax ===
In der Regel besteht jede Zeile aus folgenden, per Leerzeichen getrennten Argumenten:
* einem setter-Namen, ggf. ergänzt durch ein widget (s.u.)
* einem Topic, unter dem die Payload gesendet werden soll und
* der Payload.
Es können diverse Variablen genutzt werden, u.A. auch $EVENT und $EVTPARTx-Elemente, die der Rückgabe (setter-Name und ggf. gesetzter Wert) aus dem jeweiligen "widget" entsprechen.

=== on und off ===
Damit die weitergehenden Befehle wie ''on-for-timer'' aus den [[DevelopmentModuleIntro#X_Set|SetExtensions]] funktionieren, muss ein MQTT2_DEVICE die Befehle "on" und "off" kennen. Diese sollten also - wenn es eine Art "Hauptschalter" gibt - gesondert für diesen Hauptschalter angegeben werden.
Hat ein Gerät mehrerer solcher "Hauptschalter", empfiehlt es sich, für jeden dieser Schalter eine eigene MQTT2_DEVICE-Instanz anzulegen.

==== setStateList ====
Gibt es in einem Device neben dem "Hauptschalter" weitere setzbare Readings (z.B. für Helligkeit und Farbe oder eine Temperatur), empfiehlt es sich v.a. dann, wenn das Gerät den Empfang (bzw. die Ausführung) von Befehlen bestätigt, nur die auf den jeweiligen Hauptschalter bezogenen ''set''-Anweisungen in ''state'' zu schreiben. Diese (z.B. on, off und toggle) wären dann in das ''setStateList''-Attribut aufzunehmen.

==== setExtensionsEvent ====
Will man per SetExtensions realisierte laufende Timer visualisieren, empfiehlt es sich, dieses Attribut zu setzen.

=== widgets ===
In der setList können prinzipiell alle in [[FHEMWEB/Widgets|Widgets]] dargestellten Eingabemöglichkeiten verwendet werden.

=== Perl-Kommandos ===
Eigentlich ist die setList dazu gedacht, eine publish-Anweisungen über das IODev abzusetzen. Da aber generisch auch Perl-Code aufgerufen werden kann, ist dies nicht zwingend, so dass zum einen aus Perl heraus auch mehrfach-Publishes ebenso möglich sind wie beliebige "fhem"-Kommandos, die gar nichts mit MQTT zu tun haben müssen (z.B. das regelmäßige Löschen von evtl. veralteten Readings am betreffenden Gerät). Wird Text zurückgegeben, wird dies als "<topic> <payload>" interpretiert und dies gepublisht, erfolgt gar keine Rückgabe, unterbleibt dies.

== getList ==
Die getList ist dazu gedacht, asynchrone Abfragen an die Gegenstelle zu ermöglichen.
Die Syntax dabei ist
* einem getter-Namen, ggf. ergänzt durch ein widget (s.u.)
* Reading-Name, unter dem die Antwort erwartet wird
* einem Topic, unter dem die Payload gesendet werden soll und
* (optional) der Payload.
Auch hier können diverse Variablen genutzt werden, und/oder das ganze für die Ausführung von Perl-Code genutzt werden.

== periodicCmd ==
Für regelmäßige Aufgaben (mit mind. minütlicher Frequenz) kann eine Liste von get- oder set-Kommandos angegeben werden. Dies kann für regelmäßige Abfragen ebenso genutzt werden wie z.B. zum Löschen veralteter Informationen/Readings.

== Abschließende Aufgaben ==
Um das finale Aussehen des Gerätes zu beeinflussen, stehen dann noch die weiteren allgemeinen Attribute zur Verfügung, die in [[DeviceOverview anpassen]] beschrieben sind.

== Hinweise ==
<references />
[[Kategorie:HOWTOS]]
[[Kategorie:MQTT]]

Datei:Show MQTT traffic.png

2025-02-21T07:48:23Z

Beta-User:

Beispiel für einen erfolgreichen publish-Test mit anschließender Rückübermittlung der Daten durch den MQTT-Server

MQTT2 DEVICE - Schritt für Schritt

2024-10-28T05:19:06Z

Beta-User: /* gute Reading-Namen - Klartext */

== Einführung ==
Das Protokoll [[MQTT]] ermöglicht einen flexiblen Datenaustausch zwischen unterschiedlichsten Geräten und FHEM und insbesondere auch bidirektionale Kommunikation von und zu FHEM. Es gibt dabei jedoch nur einen geringen Grad der Standardisierung des Datenaustauschs. In der Praxis sind daher relative viele unterschiedliche Wege aufzufinden, wie die Kommunikation via MQTT in den externen Geräten und Diensten konkret umgesetzt wurde - jeder Autor einer firmware oder Software kann dies so lösen, wie es ihm beliebt, und nicht jeder beherzigt dabei den Grundsatz, dass die Kommunikation via MQTT "leichtgewichtig" sein sollte.

{{Randnotiz|RNTyp=Info|RNText=Grundsätzlich stehen für viele Geräte-Typen bereits Vorlagen zur Verfügung, siehe [[AttrTemplate|attrTemplate]], die einem die wesentliche Konfigurationsarbeit abnehmen können, wie sie hier beschrieben ist. Die damit jeweils erzeugten Konfigurationen sind Einrichtungsbeispiele, die v.a. eine in sich konsistenze Zusammenstellung der verschiedenen Attribute enthalten. Es steht jedem User frei, diese Ausgangsbasis dann nach seinem Belieben zu ändern. Spätere Änderungen des verwendeten attrTemplate wirken sich nicht automatisch auf die durch frühere Versionen oder den User nachkonfigurierte Geräte aus! Da es vorkommen kann, dass sich die per MQTT übermittelten Daten und Topics ändern, wenn z.B. eine firmware aktualisiert wurden, kann dies Anpassungen am jeweiligen Template erforderlich machen. Grundsätzlich sollen die per attrTemplate für MQTT2_DEVICE verfügbaren attrTemplate jeweils für die aktuellste verfügbare stabile firmware-Version passen.}}

Das Modul [[MQTT2_DEVICE]] bietet eine Vielzahl von Möglichkeiten, auf die verschiedensten Anforderungen einzugehen, und die ein- und ausgehenden Daten zu einem oder mehreren FHEM-[[Gerät|Gerät/en]] zusammenzufassen. Eine Übersicht häufig vorkommender MQTT-Geräte ist in [[MQTT2-Module - Praxisbeispiele]] zu finden.

Ziel dieses Artikels ist die Darstellung der Schritte, die sich als zweckmäßig erwiesen haben zur Einrichtung von "guten" FHEM-Geräten.
{{Randnotiz|RNTyp=Info|RNText=Viele - teils komplexe Beispiele und weitere Verweise sind im {{Link2Forum|Topic=116162|LinkText=MQTT-Workshop für MQTT2-Module}} zu finden.}}Dabei soll am Ende erreicht werden:
* standardisierte set- (und ggf. get-)-Kommandos, insbesondere unter Beachtung der [[DevelopmentGuidelinesReadings| Developer Guidelines für Readings]]
* Schließen des Informationskreises von eventuellen Kommandos bis zur Rückmeldung des (externen) Gerätes oder Dienstes (im Folgenden: "Gegenstelle")
* standardisierte Reading-Namen, damit möglichst Auswertungen nicht speziell an das jeweilige Gerät angepasst werden müssen
* Reduzierung und Vermeidung von unnötigen Datenpunkten und Events
* Einrichten von regelmäßigen Abfrage-Timern (falls erforderlich!).

== Vorbereitung ==
=== MQTT2_SERVER ===
Selbst, wenn grundsätzlich ein externer MQTT-Server IO-Device zum Einsatz kommt, ist sehr zu empfehlen, für die Beschäftigung mit einem neuen, unbekannten Device zunächst einen {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} einzurichten. Ist der Port 1883 bereits belegt, nimmt man einfach einen anderen Port, z.B. 1884: <code>define m2server MQTT2_SERVER 1884 global</code>. Sollte die Gegenstelle tiefer strukturierte Daten im JSON-Format über verschiedene Topics als Payload übermittelt, kann es ausnahmsweise hilfreich sein, '''in der Einrichtungsphase''' auch das Attribut "autocreate" am MQTT2_SERVER auf "complex" zu stellen: <code>attr m2server autocreate complex</code>. Weiter muss die allgemeine [[Autocreate|autocreate-Instanz]] aktiv sein. Für den Regelbetrieb und für einfache, bekannte Devices (sowie für solche, für die bereits attrTemplate vorhanden sind), wird ausdrücklich empfohlen, das ''autocreate''-Atribut am m2server gar nicht erst zu setzten, dann wird ''autocreate'' mit der (default) Einstellung ''simple'' verwendet. Die Hintergründe sind nachfolgend im Abschnitt zu ''json2nameValue()'' zu finden.

=== Begrifflichkeiten ===
Ein typisches, von "autocreate" erstelltes Gerät sieht dann z.b. (mit autocreate = simple am MQTT2_SERVER) so aus:
<syntaxhighlight lang="text">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD readingList DVES_9B01BD:tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/LWT:.* LWT\
DVES_9B01BD:tele/DVES_9B01BD/UPTIME:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/SENSOR:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO1:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO2:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO3:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/RESULT:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }
attr MQTT2_DVES_9B01BD room MQTT2_DEVICE
</syntaxhighlight>
Wir unterscheiden bei jeder Zeile des readingList-Attributs vier Elemente, die ersten drei werden jeweils durch einen Doppelpunkt voneinander getrennt:
==== CID ====
Dies ist die Gerätekennung (hier: DVES_9B01BD). Diese ist auch Bestandteil des ''define'', über diese wird ermittelt, zu welchem FHEM-Gerät via MQTT eingehende Informationen zugeordnet werden sollen. Diese Angabe ist weder im define noch in der readingList zwingend, aber in der Definition für den Hauptkanal eines Gerätes empfohlen. Es empfiehlt sich, die CID-Angaben bei eigenen readingList-Einträgen wegzulassen bzw. diese zu löschen. So kann einfacher zwischen automatisch generierten und eigenen Angaben unterschieden werden und die Geräte sind leichter zwischen verschiedenen IO-Modulen zu verschieben.
==== Topic ====
Datenpunkt, an den eine Information gesendet wird. Empfangsseitig sind dies hier z.B. ''tele/DVES_9B01BD/STATE'' oder ''tele/DVES_9B01BD/LWT''.
Enthält der Topic Doppelpunkte oder Sonderzeichen, kann dies zu Problemen führen. Da der Topic intern als ''regex'' behandelt wird, kann man sich das in solchen Sonderfälle dadurch zu nutze machen, dass man z.B problematische Zeichen durch Punkte oder "beliebige Zeichenfolgen" ersetzt. So kann z.B. aus dem per autocreate erstellten <code>attr reader readingList SMLReader/Strom/sensor/1/obis/1-0:1.8.0/255/value:.* Strombezug_tariflos</code> folgendes abgeleitet werden: <code>attr reader readingList SMLReader/Strom/sensor/1/obis/1-0.1.8.0/255/value:.* Strombezug_tariflos</code>,

==== Payload ====
Der jeweilige Nachrichteninhalt. Da dieser nicht im vorhinein bekannt ist, wird er in der readingList typischerweise als "beliebige Zeichenfolge" (".*") notiert.

==== Auswertung ====
Dies kann entweder direkt der Reading-Name sein, dem die Payload zugeordnet werden soll, oder ein Perl-Ausdruck. Hier wird z.B. die eingehende Information für ''tele/DVES_9B01BD/LWT'' dem Reading ''LWT'' zugeordnet, während die Informationen aus ''tele/DVES_9B01BD/STATE'' an die Funktion ''json2nameValue()'' übergeben werden. ''$EVENT'' entspricht dabei der ''Payload''.

=== defaults ===
Für unbekannte Gegenstellen ist zunächst immer zu empfehlen, deren "Grundeinstellungen" zu verwenden, und Anpassungen erst und nur insoweit vorzunehmen, als es für ein besseres Zusammenspiel mit FHEM sinnvoll ist. Abzuraten ist insbesondere von:
* Änderungen der Topics und Topic-Sturkturen (ausgenommen den Fall, dass schon andere Gegenstellen im Einsatz sind, die identische Topics verwenden)
* Vergabe von ''friendly names''

== Bestandsaufnahme ==
=== Projektseiten finden ===
Viele Geräte, die das MQTT-Protokoll verwenden, haben eigene Projektseiten oder API-Beschreibungen, denen man entnehmen kann, wie mit dieser Gegenstelle Daten ausgetauscht werden können. Diese sollte man bei allen weiteren Schritten stets zur Hand haben. Dabei kann es neben der allgemeinen Beschreibung auch ein oder mehrere Detail-Seiten geben, auf denen nähere Informationen zu den spezifischen Geräte zu finden sein können.

=== MQTT - Datenverkehr mitlesen ===
Sowohl MQTT2_SERVER wie MQTT2_CLIENT bieten in der Detailansicht die Option ''Show MQTT traffic''. Darüber läßt sich der ein- und ausgehende Datenverkehr bequem mitlesen. Bei MQTT2_CLIENT wird dabei allerdings vorausgesetzt, dass er überhaupt Daten vom MQTT-Server erhält, also insbesondere die ''subscriptions'' korrekt gesetzt sind (falls per Attribut eingeschränkt).

=== readingList ===
Zunächst empfiehlt es sich, einfach die Gegenstelle neu zu starten und (ggf. über ein FileLog) aufzuzuzeichnen, was über welchen Topic wie oft an Informationen gesendet wird. Dabei kann und sollte durchaus - sofern dies möglich ist - der eine oder andere Schaltvorgang (z.B. über das Web-Interface der Gegenstelle) durchgeführt werden, sofern dies möglich ist (oder allgemeiner: möglichst viele bekannte Anweisungen ausführen lassen). Am Ende sollte man eine möglichst vollständige Auflistung in der readingList erhalten haben.
Falls strukturierte Daten im JSON-Format als Payload verwendet werden, kann man diese auch zusätzlich ohne die Verarbeitung durch ''json2nameValue()'' aufzeichnen, z.B. indem man die betreffende Zeile in der readingList doppelt:
<syntaxhighlight lang="text">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD readingList tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
tele/DVES_9B01BD/STATE:.* json_STATE\
tele/DVES_9B01BD/LWT:.* LWT\
[...]
</syntaxhighlight>
So kann man mit Hilfe des betreffenden Logs ggf. auch über ein externes Tool wie mosquitto_pub MQTT-Nachrichten an FHEM generieren, ohne darauf warten zu müssen, dass diese von der Gegenstelle selbst erzeugt werden.

=== ignoreRegexp ===
Manche Gegenstellen senden beim Start Konfigurationsinformationen, die allerdings nicht durch FHEM ausgewertet werden können. Die betreffenden Topics sollte man (allgemein) so in die ignoreRegexp beim MQTT2_SERVER bzw. [[MQTT2_CLIENT]] aufnehmen, dass derartige Informationen künftig gar nicht mehr an MQTT2_DEVICE weitergereicht werden. Danach kann man die betreffenden Zeilen aus der readingList löschen! Entsprechendes gilt für die hierüber generierten Readings.

Weiter ist zu empfehlen, in diese ignoreRegexp auch die Topics aufzunehmen, über die Gegenstellen typischerweise Kommandos entgegennehmen. Dies könnte z.B. so aussehen:
<code>attr m2server ignoreRegexp shellies/[^/]+/command|cmnd/[^/]+/|homeassistant/.*/config|tasmota/discovery</code>

=== Viele Geräte? ===
==== "split" ====
Sind auf einer Hardware mehrere "Hauptschalter" vorhanden (z.B. ein Relay-Board), ist sehr zu empfehlen, für jeden dieser "Hauptschalter" ein eigenes FHEM-Gerät anzulegen (für logische Einheiten wie Rollladenaktoren ggf. paarweise). MQTT2_DEVICE unterstützt [[DevelopmentModuleAPI#SetExtensions|SetExtensions]] und kann daher Kommandos wie "on-for-timer" über FHEM-interne Mechanismen gut umsetzen. Dies erfordert allerdings, dass die Kommandos "on" und "off" verfügbar sein müssen.
Wird ein Gerät gesplittet, sollten im Gerät, das den ersten (Haupt-) Kanal repräsentiert dann alle Kommunikationsdaten gebündelt werden, Querverweise zu den weiteren Kanälen kann man über das spezielle Readings "associatedWith" herstellen.

==== bridgeRegexp ====
{{Randnotiz|RNTyp=Info|RNText=Manche derartige Interfaces müssen zunächst entsprechend konfiguriert werden, dass die zu einem Sensor oder Aktor gehörenden Daten jeweils auf einem eigenen Topic ausgegeben werden. Insbesondere ist dies bei Tasmota (ZigBee oder Bluetooth) der Fall!}}
In eher seltenen Fällen kommt es vor, dass eine Gegenstelle eine Art "Brücke" zu einer Mehrzahl über diese Brücke anzusteuernder (oder zu empfangender) Aktoren oder Sensoren darstellt. In diesen Fällen kann es geboten sein, die eigentliche Gegenstelle als Hauptdevice darzustellen und für jede weitere Hardware (Sensor oder Aktor) dann ein oder mehrere Einzeldevices anzulegen. Dies kann mit Hilfe des Attributs bridgeRegexp automatisiert erfolgen, wenn sich der Sensor/Aktor aus der Topic-Struktur ablesen läßt.

== readingList optimieren==
=== gute Reading-Namen - Klartext ===
{{Randnotiz|RNTyp=Info|RNText=Beachte zur Vergabe von Reading-Namen v.a. auch [[DevelopmentGuidelinesReadings]] und [[DevelopmentGuidelinesAV]].}}
Viele Gegenstellen senden z.B. einen online/offline-Status als "last will and testament" unter einem Topic, der mit "LWT" endet. Dieses hier sendet zwar passende Daten, aber an einen anderen Topic. In solchen Fällen man kann den von autocreate erzeugten Eintrag einfach anpassen:
attr DEVICE readingList /dingtian/DEVNAME/out/lwt_availability:.* LWT

=== Bedingte Hash-Rückgaben ===
Manchmal erfolgt zwar die Übergabe eines Klartextes als $EVENT - allerdings nicht in der Form, wie man das in FHEM gerne hätte. Hier als "0" oder "1". Mit etwas Perl und der Rückgabe eines Hashes kann man so etwas beliebig umformen:
attr DEVICE readingList DEVNAME/relay/0:.* { $EVENT ? {state=>'on'} : {state=>'off'} }\
DEVNAME/status:.* { $EVENT ? {LWT=>'Online'} : {LWT=>'Offline'} }
Weiteres Beispiel: Der "state" kommt in Großschreibung und soll in Kleinschreibung geändert werden:
attr DEVICE readingList switchbot/esp32_2/bot/switchbottwo/state:.* { { state => lc $EVENT } }

=== json2nameValue() ===
Mit Hilfe der Funktion json2nameValue() (in Verbindung mit dem attribut ''jsonMap'') lassen sich
* "gute Reading-Namen" auch aus JSON-Payloads erzeugen (2. und 3. Argument)
* unnötige Readings vorab ausfiltern (3., 4. und 5. Argument)
Beispiele für die Verwendung der Argumente 1 bis 3 sind der commandref in der Erläuterung des Attributs ''jsonMap'' bei MQTT2_DEVICE zu entnehmen, die (wie die Argumente 2 und 3 optionalen) Argumente 4 und 5 entsprechen einem Positiv- bzw.- Negativ-Filter.
Wird (übergangsweise!) ''autocreate'' in der ''complex''-Variante eingestellt, werden für alle (bisher nicht bekannten) Topics Einträge wie dieser erzeugt:
attr MQTT2_DVES_9B01BD readingList tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT,'STATE_',$JSONMAP) }
* Das zweite Argument (''STATE_'') ist ein "Präfix", der allen aus dem JSON erzeugten Readings aus diesem Topic (zunächst) vorangestellt wird. Mit dessen Hilfe läßt sich rekonsturieren, aus welchem Topic die betreffende Information ursprünglich kam. In der Regel ist dies nach der Einrichtung nicht mehr wichtig, und dieses Argument kann auf "nichts" (zwei einfache Quotes) gestellt werden. Allerdings kann es in Einzelfällen sinnvoll sein, Präfixe zu verwenden, um zwischen scheinbar gleichen Werte aus unterschiedlichen Quellen zu unterscheiden. Dies kann man erst abschließend entscheiden, wenn alle von der Gegenstelle gelieferten Daten bekannt sind.
* Das dritte Argument ''$JSONMAP'' kann in der Regel so belassen werden. Dann kann mit Hilfe des Attributs ''jsonMap'' eine Zuordnungstabelle für Namensänderungen für die zu generierenden Readingnamen erzeugt und/oder Werte schlicht gelöscht werden.
<syntaxhighlight lang="perl6">
json2nameValue($EVENT,'STATE_',$JSONMAP,'positiv')
json2nameValue($EVENT,'STATE_',$JSONMAP,'','negativ')
</syntaxhighlight>
* Das vierte Argument ist optional. Es ist ein (Positiv) Filter, der nur Readings in der Liste erscheinen lässt, die diesem Argument entsprechen, im Beispiel oben wären das alle Readings, die den Ausdruck "positiv" enthalten. Das Argument selber ist eine regexp. '''Achtung:''' Wird dieses Argument zusammen mit dem Attribut jsonMap benutzt, so wird zuerst das Mapping auf die neuen Readings-Bezeichnungen ausgeführt und erst dann dieser Filter ausgeführt, d. h. es muss auf die ersetzten Readings-Bezeichnungen gefiltert werden!
* Das fünfte Argument ist ebenfalls optional. Es ist ein (Negativ) Filter. Im obigen Beispiel werden alle Readings, die den Ausdruck "negativ" enthalten, aus den Readings ausgefiltert. Ebenso wie das 4. Argument ist es eine regexp. Im Zusammenspiel mit jsonMap wird hier zuerst der Filter ausgewertet und erst anschließend erfolgt das Mapping auf die neuen Readings-Namen.

=== Auswertung unterbinden ===
Indem man einen Perl-Aufruf festlegt (geschweifte Klammern), dieser aber nichts zurückgibt, kann man bestimmte unerwünschte Readings ausfiltern. Im einfachsten Fall wäre dies:
shellies/DEVNAME/temperature_f:.* {}

Komplexer mit Auswertung der Payload:
STATTOPIC/RESULT:.* { $EVENT =~ m{HSBColor...(\d+),(\d+),(\d+)} ? $2 eq ReadingsVal($NAME,'saturation','unknown') ? return : { saturation=>$2 } : return }

=== Perl ===
Wie am Beispiel der speziellen Funktion <code>json2nameValue()</code> sowie der Hash-Rückgabe bereits dargestellt, ist es möglich, bei der Auswertung auch Perl-Funktionen einzusetzen, und diverse Variablen an diese zu übergeben. Ebenso ist es möglich, eigenen Perl-Code zu verwenden, der z.B. dann längere Zuordnungstabellen, Event-Reduzierungsmechanismen, ... enthalten kann.

== Events optimieren==
Leider senden relativ viele Gegenstellen in ihren Standardeinstellungen sehr viele Daten, auch ohne dass sich etwas geändert hätte. Dies erzeugt uU. in FHEM eine erhebliche Last, so dass es dringend zu empfehlen ist, alle Maßnahmen zu prüfen, durch die dieses Verhalten unterbunden oder vermindert werden kann. Dabei sollte möglichst frühzeitig eingegriffen werden, entsprechend den folgenden Handlungsoptionen: Daten, die die firmware gar nicht erst sendet, muss FHEM nicht am Interface-Modul entgegennehmen. Daten, die direkt am Interface-Modul verworfen werden (ignoreRegexp), muss das Client-Modul nicht auswerten. Readings, die man (an einem bestimmten Device) nicht benötigt, sollte man nicht erzeugen, damit keine [[Eventhandler]] aktiv werden müssen, unveränderte, aber gewünschte Daten müssen nicht unbedingt (immer) Events erzeugen.

=== firmware-Einstellungen ===
Bei manchen firmwares kann man einstellen, ob bzw. wie oft oder aus welchem Anlass Daten gesendet werden sollen. Es wird dringlich empfohlen, bei "gesprächigen" Gegenstellen zu recherchieren, ob und in welcher Weise diese derartige Möglichkeiten bietet. Falls solche nicht vorhanden sind, lohnt es sich, auf den betreffenden Projektseiten nachzufragen, ob es diese Optionen gibt - nicht selten hat sich ein firmware-Autor darüber schlicht noch keine Gedanken gemacht und baut in der nächsten Version ggf. entsprechende Optionen ein?

=== Auswertung unterbinden ===
(s.o. für Topics/Readings, die gar nicht benötigt werden). Dies ist insbesondere auch zu empfehlen, wenn identische Daten zum gleichen Zeitpunkt sowohl als Klartext wie auch in einem JSON-Format übermittelt werden. In solchen Fällen ist es eher zu empfehlen, die JSON-Zweige zu abonnieren und den Rest (ggf. über einen ignoreRegexp-Eintrag) gar nicht auszuwerten.
Doppelungen sollten in jedem Fall vermieden werden!
Grundsätzlich erzeugt jeder Topic eine eigene Event-Loop, mehrere Readings-updates, die aus einer einzigen JSON-Payload abgeleitet werden, erzeugen dagegen eine gemeinsame Event-Loop. Durch solche Maßnahmen läßt sich die Systembelastung deutlich reduzieren.
Für Daten aus JSON-Payloads besteht darüber hinaus die Möglichkeit, diese komplett auszufiltern (siehe jsonMap weiter oben)

=== event-on-change-reading und Co. ===
Da die firmwares häufig recht gesprächig programmiert sind, sollte man auf eine sinnvolle Begrenzung der durch Aktualisierungen verursachten Events besonderen Wert legen. Dazu ist in erster Linie das Attribut [[Event-on-change-reading|event-on-change-reading]] zu bearbeiten und ggf. passende threshold-Werte zu setzen, es empfiehlt sich allerdings, dabei auch zu untersuchen, inwieweit die weiteren, funktional ergänzenden Attribute zu setzen sind:
* [[Event-min-interval|event-min-interval]]
* [[Event-on-update-reading|event-on-update-reading]]
* timestamp-on-change-reading und
* [[Event-aggregator|event-aggregator]]

=== gute Reading-Namen - userReadings ===
Manchmal werden per MQTT Werte übersendet, die so nicht direkt verwendbar sind. Beispiele hierfür wären:
* Batteriespannungen in mV (z.B. bei zigbee2mqtt)
* Farbwerte als Einzelreading (für die Anzeige in FHEM wird aber ein RGB-Wert benötigt)
In diesen Fällen kann man zwar nicht ohne weiteres den Ausgangswert umrechnen lassen, (über externe Module wie readingsChange sehr wohl), aber es ist über den Weg "userReadings" ohne weiteres möglich, passende Readings zu generieren. Dabei sollte aber zur Verringerung der Systembelastung allgemein sowie ggf. falscher Ergebnisse unbedingt darauf geachtet werden, dass diese auch mit einer ''trigger''-Angabe versehen sind!

== setList ==

=== Allgemeines ===
Die setList ist dazu gedacht, Kommandos zu definieren, welche an die Gegenstelle gesendet werden können.

=== Syntax ===
In der Regel besteht jede Zeile aus folgenden, per Leerzeichen getrennten Argumenten:
* einem setter-Namen, ggf. ergänzt durch ein widget (s.u.)
* einem Topic, unter dem die Payload gesendet werden soll und
* der Payload.
Es können diverse Variablen genutzt werden, u.A. auch $EVENT und $EVTPARTx-Elemente, die der Rückgabe (setter-Name und ggf. gesetzter Wert) aus dem jeweiligen "widget" entsprechen.

=== on und off ===
Damit die weitergehenden Befehle wie ''on-for-timer'' aus den [[DevelopmentModuleIntro#X_Set|SetExtensions]] funktionieren, muss ein MQTT2_DEVICE die Befehle "on" und "off" kennen. Diese sollten also - wenn es eine Art "Hauptschalter" gibt - gesondert für diesen Hauptschalter angegeben werden.
Hat ein Gerät mehrerer solcher "Hauptschalter", empfiehlt es sich, für jeden dieser Schalter eine eigene MQTT2_DEVICE-Instanz anzulegen.

==== setStateList ====
Gibt es in einem Device neben dem "Hauptschalter" weitere setzbare Readings (z.B. für Helligkeit und Farbe oder eine Temperatur), empfiehlt es sich v.a. dann, wenn das Gerät den Empfang (bzw. die Ausführung) von Befehlen bestätigt, nur die auf den jeweiligen Hauptschalter bezogenen ''set''-Anweisungen in ''state'' zu schreiben. Diese (z.B. on, off und toggle) wären dann in das ''setStateList''-Attribut aufzunehmen.

==== setExtensionsEvent ====
Will man per SetExtensions realisierte laufende Timer visualisieren, empfiehlt es sich, dieses Attribut zu setzen.

=== widgets ===
In der setList können prinzipiell alle in [[FHEMWEB/Widgets|Widgets]] dargestellten Eingabemöglichkeiten verwendet werden.

=== Perl-Kommandos ===
Eigentlich ist die setList dazu gedacht, eine publish-Anweisungen über das IODev abzusetzen. Da aber generisch auch Perl-Code aufgerufen werden kann, ist dies nicht zwingend, so dass zum einen aus Perl heraus auch mehrfach-Publishes ebenso möglich sind wie beliebige "fhem"-Kommandos, die gar nichts mit MQTT zu tun haben müssen (z.B. das regelmäßige Löschen von evtl. veralteten Readings am betreffenden Gerät). Wird Text zurückgegeben, wird dies als "<topic> <payload>" interpretiert und dies gepublisht, erfolgt gar keine Rückgabe, unterbleibt dies.

== getList ==
Die getList ist dazu gedacht, asynchrone Abfragen an die Gegenstelle zu ermöglichen.
Die Syntax dabei ist
* einem getter-Namen, ggf. ergänzt durch ein widget (s.u.)
* Reading-Name, unter dem die Antwort erwartet wird
* einem Topic, unter dem die Payload gesendet werden soll und
* (optional) der Payload.
Auch hier können diverse Variablen genutzt werden, und/oder das ganze für die Ausführung von Perl-Code genutzt werden.

== periodicCmd ==
Für regelmäßige Aufgaben (mit mind. minütlicher Frequenz) kann eine Liste von get- oder set-Kommandos angegeben werden. Dies kann für regelmäßige Abfragen ebenso genutzt werden wie z.B. zum Löschen veralteter Informationen/Readings.

== Abschließende Aufgaben ==
Um das finale Aussehen des Gerätes zu beeinflussen, stehen dann noch die weiteren allgemeinen Attribute zur Verfügung, die in [[DeviceOverview anpassen]] beschrieben sind.

== Hinweise ==
<references />
[[Kategorie:HOWTOS]]
[[Kategorie:MQTT]]

MQTT2 DEVICE - Schritt für Schritt

2024-10-28T05:18:40Z

Beta-User: /* gute Reading-Namen - Klartext */

== Einführung ==
Das Protokoll [[MQTT]] ermöglicht einen flexiblen Datenaustausch zwischen unterschiedlichsten Geräten und FHEM und insbesondere auch bidirektionale Kommunikation von und zu FHEM. Es gibt dabei jedoch nur einen geringen Grad der Standardisierung des Datenaustauschs. In der Praxis sind daher relative viele unterschiedliche Wege aufzufinden, wie die Kommunikation via MQTT in den externen Geräten und Diensten konkret umgesetzt wurde - jeder Autor einer firmware oder Software kann dies so lösen, wie es ihm beliebt, und nicht jeder beherzigt dabei den Grundsatz, dass die Kommunikation via MQTT "leichtgewichtig" sein sollte.

{{Randnotiz|RNTyp=Info|RNText=Grundsätzlich stehen für viele Geräte-Typen bereits Vorlagen zur Verfügung, siehe [[AttrTemplate|attrTemplate]], die einem die wesentliche Konfigurationsarbeit abnehmen können, wie sie hier beschrieben ist. Die damit jeweils erzeugten Konfigurationen sind Einrichtungsbeispiele, die v.a. eine in sich konsistenze Zusammenstellung der verschiedenen Attribute enthalten. Es steht jedem User frei, diese Ausgangsbasis dann nach seinem Belieben zu ändern. Spätere Änderungen des verwendeten attrTemplate wirken sich nicht automatisch auf die durch frühere Versionen oder den User nachkonfigurierte Geräte aus! Da es vorkommen kann, dass sich die per MQTT übermittelten Daten und Topics ändern, wenn z.B. eine firmware aktualisiert wurden, kann dies Anpassungen am jeweiligen Template erforderlich machen. Grundsätzlich sollen die per attrTemplate für MQTT2_DEVICE verfügbaren attrTemplate jeweils für die aktuellste verfügbare stabile firmware-Version passen.}}

Das Modul [[MQTT2_DEVICE]] bietet eine Vielzahl von Möglichkeiten, auf die verschiedensten Anforderungen einzugehen, und die ein- und ausgehenden Daten zu einem oder mehreren FHEM-[[Gerät|Gerät/en]] zusammenzufassen. Eine Übersicht häufig vorkommender MQTT-Geräte ist in [[MQTT2-Module - Praxisbeispiele]] zu finden.

Ziel dieses Artikels ist die Darstellung der Schritte, die sich als zweckmäßig erwiesen haben zur Einrichtung von "guten" FHEM-Geräten.
{{Randnotiz|RNTyp=Info|RNText=Viele - teils komplexe Beispiele und weitere Verweise sind im {{Link2Forum|Topic=116162|LinkText=MQTT-Workshop für MQTT2-Module}} zu finden.}}Dabei soll am Ende erreicht werden:
* standardisierte set- (und ggf. get-)-Kommandos, insbesondere unter Beachtung der [[DevelopmentGuidelinesReadings| Developer Guidelines für Readings]]
* Schließen des Informationskreises von eventuellen Kommandos bis zur Rückmeldung des (externen) Gerätes oder Dienstes (im Folgenden: "Gegenstelle")
* standardisierte Reading-Namen, damit möglichst Auswertungen nicht speziell an das jeweilige Gerät angepasst werden müssen
* Reduzierung und Vermeidung von unnötigen Datenpunkten und Events
* Einrichten von regelmäßigen Abfrage-Timern (falls erforderlich!).

== Vorbereitung ==
=== MQTT2_SERVER ===
Selbst, wenn grundsätzlich ein externer MQTT-Server IO-Device zum Einsatz kommt, ist sehr zu empfehlen, für die Beschäftigung mit einem neuen, unbekannten Device zunächst einen {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} einzurichten. Ist der Port 1883 bereits belegt, nimmt man einfach einen anderen Port, z.B. 1884: <code>define m2server MQTT2_SERVER 1884 global</code>. Sollte die Gegenstelle tiefer strukturierte Daten im JSON-Format über verschiedene Topics als Payload übermittelt, kann es ausnahmsweise hilfreich sein, '''in der Einrichtungsphase''' auch das Attribut "autocreate" am MQTT2_SERVER auf "complex" zu stellen: <code>attr m2server autocreate complex</code>. Weiter muss die allgemeine [[Autocreate|autocreate-Instanz]] aktiv sein. Für den Regelbetrieb und für einfache, bekannte Devices (sowie für solche, für die bereits attrTemplate vorhanden sind), wird ausdrücklich empfohlen, das ''autocreate''-Atribut am m2server gar nicht erst zu setzten, dann wird ''autocreate'' mit der (default) Einstellung ''simple'' verwendet. Die Hintergründe sind nachfolgend im Abschnitt zu ''json2nameValue()'' zu finden.

=== Begrifflichkeiten ===
Ein typisches, von "autocreate" erstelltes Gerät sieht dann z.b. (mit autocreate = simple am MQTT2_SERVER) so aus:
<syntaxhighlight lang="text">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD readingList DVES_9B01BD:tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/LWT:.* LWT\
DVES_9B01BD:tele/DVES_9B01BD/UPTIME:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/SENSOR:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO1:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO2:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO3:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/RESULT:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }
attr MQTT2_DVES_9B01BD room MQTT2_DEVICE
</syntaxhighlight>
Wir unterscheiden bei jeder Zeile des readingList-Attributs vier Elemente, die ersten drei werden jeweils durch einen Doppelpunkt voneinander getrennt:
==== CID ====
Dies ist die Gerätekennung (hier: DVES_9B01BD). Diese ist auch Bestandteil des ''define'', über diese wird ermittelt, zu welchem FHEM-Gerät via MQTT eingehende Informationen zugeordnet werden sollen. Diese Angabe ist weder im define noch in der readingList zwingend, aber in der Definition für den Hauptkanal eines Gerätes empfohlen. Es empfiehlt sich, die CID-Angaben bei eigenen readingList-Einträgen wegzulassen bzw. diese zu löschen. So kann einfacher zwischen automatisch generierten und eigenen Angaben unterschieden werden und die Geräte sind leichter zwischen verschiedenen IO-Modulen zu verschieben.
==== Topic ====
Datenpunkt, an den eine Information gesendet wird. Empfangsseitig sind dies hier z.B. ''tele/DVES_9B01BD/STATE'' oder ''tele/DVES_9B01BD/LWT''.
Enthält der Topic Doppelpunkte oder Sonderzeichen, kann dies zu Problemen führen. Da der Topic intern als ''regex'' behandelt wird, kann man sich das in solchen Sonderfälle dadurch zu nutze machen, dass man z.B problematische Zeichen durch Punkte oder "beliebige Zeichenfolgen" ersetzt. So kann z.B. aus dem per autocreate erstellten <code>attr reader readingList SMLReader/Strom/sensor/1/obis/1-0:1.8.0/255/value:.* Strombezug_tariflos</code> folgendes abgeleitet werden: <code>attr reader readingList SMLReader/Strom/sensor/1/obis/1-0.1.8.0/255/value:.* Strombezug_tariflos</code>,

==== Payload ====
Der jeweilige Nachrichteninhalt. Da dieser nicht im vorhinein bekannt ist, wird er in der readingList typischerweise als "beliebige Zeichenfolge" (".*") notiert.

==== Auswertung ====
Dies kann entweder direkt der Reading-Name sein, dem die Payload zugeordnet werden soll, oder ein Perl-Ausdruck. Hier wird z.B. die eingehende Information für ''tele/DVES_9B01BD/LWT'' dem Reading ''LWT'' zugeordnet, während die Informationen aus ''tele/DVES_9B01BD/STATE'' an die Funktion ''json2nameValue()'' übergeben werden. ''$EVENT'' entspricht dabei der ''Payload''.

=== defaults ===
Für unbekannte Gegenstellen ist zunächst immer zu empfehlen, deren "Grundeinstellungen" zu verwenden, und Anpassungen erst und nur insoweit vorzunehmen, als es für ein besseres Zusammenspiel mit FHEM sinnvoll ist. Abzuraten ist insbesondere von:
* Änderungen der Topics und Topic-Sturkturen (ausgenommen den Fall, dass schon andere Gegenstellen im Einsatz sind, die identische Topics verwenden)
* Vergabe von ''friendly names''

== Bestandsaufnahme ==
=== Projektseiten finden ===
Viele Geräte, die das MQTT-Protokoll verwenden, haben eigene Projektseiten oder API-Beschreibungen, denen man entnehmen kann, wie mit dieser Gegenstelle Daten ausgetauscht werden können. Diese sollte man bei allen weiteren Schritten stets zur Hand haben. Dabei kann es neben der allgemeinen Beschreibung auch ein oder mehrere Detail-Seiten geben, auf denen nähere Informationen zu den spezifischen Geräte zu finden sein können.

=== MQTT - Datenverkehr mitlesen ===
Sowohl MQTT2_SERVER wie MQTT2_CLIENT bieten in der Detailansicht die Option ''Show MQTT traffic''. Darüber läßt sich der ein- und ausgehende Datenverkehr bequem mitlesen. Bei MQTT2_CLIENT wird dabei allerdings vorausgesetzt, dass er überhaupt Daten vom MQTT-Server erhält, also insbesondere die ''subscriptions'' korrekt gesetzt sind (falls per Attribut eingeschränkt).

=== readingList ===
Zunächst empfiehlt es sich, einfach die Gegenstelle neu zu starten und (ggf. über ein FileLog) aufzuzuzeichnen, was über welchen Topic wie oft an Informationen gesendet wird. Dabei kann und sollte durchaus - sofern dies möglich ist - der eine oder andere Schaltvorgang (z.B. über das Web-Interface der Gegenstelle) durchgeführt werden, sofern dies möglich ist (oder allgemeiner: möglichst viele bekannte Anweisungen ausführen lassen). Am Ende sollte man eine möglichst vollständige Auflistung in der readingList erhalten haben.
Falls strukturierte Daten im JSON-Format als Payload verwendet werden, kann man diese auch zusätzlich ohne die Verarbeitung durch ''json2nameValue()'' aufzeichnen, z.B. indem man die betreffende Zeile in der readingList doppelt:
<syntaxhighlight lang="text">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD readingList tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
tele/DVES_9B01BD/STATE:.* json_STATE\
tele/DVES_9B01BD/LWT:.* LWT\
[...]
</syntaxhighlight>
So kann man mit Hilfe des betreffenden Logs ggf. auch über ein externes Tool wie mosquitto_pub MQTT-Nachrichten an FHEM generieren, ohne darauf warten zu müssen, dass diese von der Gegenstelle selbst erzeugt werden.

=== ignoreRegexp ===
Manche Gegenstellen senden beim Start Konfigurationsinformationen, die allerdings nicht durch FHEM ausgewertet werden können. Die betreffenden Topics sollte man (allgemein) so in die ignoreRegexp beim MQTT2_SERVER bzw. [[MQTT2_CLIENT]] aufnehmen, dass derartige Informationen künftig gar nicht mehr an MQTT2_DEVICE weitergereicht werden. Danach kann man die betreffenden Zeilen aus der readingList löschen! Entsprechendes gilt für die hierüber generierten Readings.

Weiter ist zu empfehlen, in diese ignoreRegexp auch die Topics aufzunehmen, über die Gegenstellen typischerweise Kommandos entgegennehmen. Dies könnte z.B. so aussehen:
<code>attr m2server ignoreRegexp shellies/[^/]+/command|cmnd/[^/]+/|homeassistant/.*/config|tasmota/discovery</code>

=== Viele Geräte? ===
==== "split" ====
Sind auf einer Hardware mehrere "Hauptschalter" vorhanden (z.B. ein Relay-Board), ist sehr zu empfehlen, für jeden dieser "Hauptschalter" ein eigenes FHEM-Gerät anzulegen (für logische Einheiten wie Rollladenaktoren ggf. paarweise). MQTT2_DEVICE unterstützt [[DevelopmentModuleAPI#SetExtensions|SetExtensions]] und kann daher Kommandos wie "on-for-timer" über FHEM-interne Mechanismen gut umsetzen. Dies erfordert allerdings, dass die Kommandos "on" und "off" verfügbar sein müssen.
Wird ein Gerät gesplittet, sollten im Gerät, das den ersten (Haupt-) Kanal repräsentiert dann alle Kommunikationsdaten gebündelt werden, Querverweise zu den weiteren Kanälen kann man über das spezielle Readings "associatedWith" herstellen.

==== bridgeRegexp ====
{{Randnotiz|RNTyp=Info|RNText=Manche derartige Interfaces müssen zunächst entsprechend konfiguriert werden, dass die zu einem Sensor oder Aktor gehörenden Daten jeweils auf einem eigenen Topic ausgegeben werden. Insbesondere ist dies bei Tasmota (ZigBee oder Bluetooth) der Fall!}}
In eher seltenen Fällen kommt es vor, dass eine Gegenstelle eine Art "Brücke" zu einer Mehrzahl über diese Brücke anzusteuernder (oder zu empfangender) Aktoren oder Sensoren darstellt. In diesen Fällen kann es geboten sein, die eigentliche Gegenstelle als Hauptdevice darzustellen und für jede weitere Hardware (Sensor oder Aktor) dann ein oder mehrere Einzeldevices anzulegen. Dies kann mit Hilfe des Attributs bridgeRegexp automatisiert erfolgen, wenn sich der Sensor/Aktor aus der Topic-Struktur ablesen läßt.

== readingList optimieren==
=== gute Reading-Namen - Klartext ===
Viele Gegenstellen senden z.B. einen online/offline-Status als "last will and testament" unter einem Topic, der mit "LWT" endet. Dieses hier sendet zwar passende Daten, aber an einen anderen Topic. In solchen Fällen man kann den von autocreate erzeugten Eintrag einfach anpassen:
attr DEVICE readingList /dingtian/DEVNAME/out/lwt_availability:.* LWT
{{Randnotiz|RNTyp=Info|RNText=Beachte zur Vergabe von Reading-Namen v.a. auch [[DevelopmentGuidelinesReadings]] und [[DevelopmentGuidelinesAV]].}}

=== Bedingte Hash-Rückgaben ===
Manchmal erfolgt zwar die Übergabe eines Klartextes als $EVENT - allerdings nicht in der Form, wie man das in FHEM gerne hätte. Hier als "0" oder "1". Mit etwas Perl und der Rückgabe eines Hashes kann man so etwas beliebig umformen:
attr DEVICE readingList DEVNAME/relay/0:.* { $EVENT ? {state=>'on'} : {state=>'off'} }\
DEVNAME/status:.* { $EVENT ? {LWT=>'Online'} : {LWT=>'Offline'} }
Weiteres Beispiel: Der "state" kommt in Großschreibung und soll in Kleinschreibung geändert werden:
attr DEVICE readingList switchbot/esp32_2/bot/switchbottwo/state:.* { { state => lc $EVENT } }

=== json2nameValue() ===
Mit Hilfe der Funktion json2nameValue() (in Verbindung mit dem attribut ''jsonMap'') lassen sich
* "gute Reading-Namen" auch aus JSON-Payloads erzeugen (2. und 3. Argument)
* unnötige Readings vorab ausfiltern (3., 4. und 5. Argument)
Beispiele für die Verwendung der Argumente 1 bis 3 sind der commandref in der Erläuterung des Attributs ''jsonMap'' bei MQTT2_DEVICE zu entnehmen, die (wie die Argumente 2 und 3 optionalen) Argumente 4 und 5 entsprechen einem Positiv- bzw.- Negativ-Filter.
Wird (übergangsweise!) ''autocreate'' in der ''complex''-Variante eingestellt, werden für alle (bisher nicht bekannten) Topics Einträge wie dieser erzeugt:
attr MQTT2_DVES_9B01BD readingList tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT,'STATE_',$JSONMAP) }
* Das zweite Argument (''STATE_'') ist ein "Präfix", der allen aus dem JSON erzeugten Readings aus diesem Topic (zunächst) vorangestellt wird. Mit dessen Hilfe läßt sich rekonsturieren, aus welchem Topic die betreffende Information ursprünglich kam. In der Regel ist dies nach der Einrichtung nicht mehr wichtig, und dieses Argument kann auf "nichts" (zwei einfache Quotes) gestellt werden. Allerdings kann es in Einzelfällen sinnvoll sein, Präfixe zu verwenden, um zwischen scheinbar gleichen Werte aus unterschiedlichen Quellen zu unterscheiden. Dies kann man erst abschließend entscheiden, wenn alle von der Gegenstelle gelieferten Daten bekannt sind.
* Das dritte Argument ''$JSONMAP'' kann in der Regel so belassen werden. Dann kann mit Hilfe des Attributs ''jsonMap'' eine Zuordnungstabelle für Namensänderungen für die zu generierenden Readingnamen erzeugt und/oder Werte schlicht gelöscht werden.
<syntaxhighlight lang="perl6">
json2nameValue($EVENT,'STATE_',$JSONMAP,'positiv')
json2nameValue($EVENT,'STATE_',$JSONMAP,'','negativ')
</syntaxhighlight>
* Das vierte Argument ist optional. Es ist ein (Positiv) Filter, der nur Readings in der Liste erscheinen lässt, die diesem Argument entsprechen, im Beispiel oben wären das alle Readings, die den Ausdruck "positiv" enthalten. Das Argument selber ist eine regexp. '''Achtung:''' Wird dieses Argument zusammen mit dem Attribut jsonMap benutzt, so wird zuerst das Mapping auf die neuen Readings-Bezeichnungen ausgeführt und erst dann dieser Filter ausgeführt, d. h. es muss auf die ersetzten Readings-Bezeichnungen gefiltert werden!
* Das fünfte Argument ist ebenfalls optional. Es ist ein (Negativ) Filter. Im obigen Beispiel werden alle Readings, die den Ausdruck "negativ" enthalten, aus den Readings ausgefiltert. Ebenso wie das 4. Argument ist es eine regexp. Im Zusammenspiel mit jsonMap wird hier zuerst der Filter ausgewertet und erst anschließend erfolgt das Mapping auf die neuen Readings-Namen.

=== Auswertung unterbinden ===
Indem man einen Perl-Aufruf festlegt (geschweifte Klammern), dieser aber nichts zurückgibt, kann man bestimmte unerwünschte Readings ausfiltern. Im einfachsten Fall wäre dies:
shellies/DEVNAME/temperature_f:.* {}

Komplexer mit Auswertung der Payload:
STATTOPIC/RESULT:.* { $EVENT =~ m{HSBColor...(\d+),(\d+),(\d+)} ? $2 eq ReadingsVal($NAME,'saturation','unknown') ? return : { saturation=>$2 } : return }

=== Perl ===
Wie am Beispiel der speziellen Funktion <code>json2nameValue()</code> sowie der Hash-Rückgabe bereits dargestellt, ist es möglich, bei der Auswertung auch Perl-Funktionen einzusetzen, und diverse Variablen an diese zu übergeben. Ebenso ist es möglich, eigenen Perl-Code zu verwenden, der z.B. dann längere Zuordnungstabellen, Event-Reduzierungsmechanismen, ... enthalten kann.

== Events optimieren==
Leider senden relativ viele Gegenstellen in ihren Standardeinstellungen sehr viele Daten, auch ohne dass sich etwas geändert hätte. Dies erzeugt uU. in FHEM eine erhebliche Last, so dass es dringend zu empfehlen ist, alle Maßnahmen zu prüfen, durch die dieses Verhalten unterbunden oder vermindert werden kann. Dabei sollte möglichst frühzeitig eingegriffen werden, entsprechend den folgenden Handlungsoptionen: Daten, die die firmware gar nicht erst sendet, muss FHEM nicht am Interface-Modul entgegennehmen. Daten, die direkt am Interface-Modul verworfen werden (ignoreRegexp), muss das Client-Modul nicht auswerten. Readings, die man (an einem bestimmten Device) nicht benötigt, sollte man nicht erzeugen, damit keine [[Eventhandler]] aktiv werden müssen, unveränderte, aber gewünschte Daten müssen nicht unbedingt (immer) Events erzeugen.

=== firmware-Einstellungen ===
Bei manchen firmwares kann man einstellen, ob bzw. wie oft oder aus welchem Anlass Daten gesendet werden sollen. Es wird dringlich empfohlen, bei "gesprächigen" Gegenstellen zu recherchieren, ob und in welcher Weise diese derartige Möglichkeiten bietet. Falls solche nicht vorhanden sind, lohnt es sich, auf den betreffenden Projektseiten nachzufragen, ob es diese Optionen gibt - nicht selten hat sich ein firmware-Autor darüber schlicht noch keine Gedanken gemacht und baut in der nächsten Version ggf. entsprechende Optionen ein?

=== Auswertung unterbinden ===
(s.o. für Topics/Readings, die gar nicht benötigt werden). Dies ist insbesondere auch zu empfehlen, wenn identische Daten zum gleichen Zeitpunkt sowohl als Klartext wie auch in einem JSON-Format übermittelt werden. In solchen Fällen ist es eher zu empfehlen, die JSON-Zweige zu abonnieren und den Rest (ggf. über einen ignoreRegexp-Eintrag) gar nicht auszuwerten.
Doppelungen sollten in jedem Fall vermieden werden!
Grundsätzlich erzeugt jeder Topic eine eigene Event-Loop, mehrere Readings-updates, die aus einer einzigen JSON-Payload abgeleitet werden, erzeugen dagegen eine gemeinsame Event-Loop. Durch solche Maßnahmen läßt sich die Systembelastung deutlich reduzieren.
Für Daten aus JSON-Payloads besteht darüber hinaus die Möglichkeit, diese komplett auszufiltern (siehe jsonMap weiter oben)

=== event-on-change-reading und Co. ===
Da die firmwares häufig recht gesprächig programmiert sind, sollte man auf eine sinnvolle Begrenzung der durch Aktualisierungen verursachten Events besonderen Wert legen. Dazu ist in erster Linie das Attribut [[Event-on-change-reading|event-on-change-reading]] zu bearbeiten und ggf. passende threshold-Werte zu setzen, es empfiehlt sich allerdings, dabei auch zu untersuchen, inwieweit die weiteren, funktional ergänzenden Attribute zu setzen sind:
* [[Event-min-interval|event-min-interval]]
* [[Event-on-update-reading|event-on-update-reading]]
* timestamp-on-change-reading und
* [[Event-aggregator|event-aggregator]]

=== gute Reading-Namen - userReadings ===
Manchmal werden per MQTT Werte übersendet, die so nicht direkt verwendbar sind. Beispiele hierfür wären:
* Batteriespannungen in mV (z.B. bei zigbee2mqtt)
* Farbwerte als Einzelreading (für die Anzeige in FHEM wird aber ein RGB-Wert benötigt)
In diesen Fällen kann man zwar nicht ohne weiteres den Ausgangswert umrechnen lassen, (über externe Module wie readingsChange sehr wohl), aber es ist über den Weg "userReadings" ohne weiteres möglich, passende Readings zu generieren. Dabei sollte aber zur Verringerung der Systembelastung allgemein sowie ggf. falscher Ergebnisse unbedingt darauf geachtet werden, dass diese auch mit einer ''trigger''-Angabe versehen sind!

== setList ==

=== Allgemeines ===
Die setList ist dazu gedacht, Kommandos zu definieren, welche an die Gegenstelle gesendet werden können.

=== Syntax ===
In der Regel besteht jede Zeile aus folgenden, per Leerzeichen getrennten Argumenten:
* einem setter-Namen, ggf. ergänzt durch ein widget (s.u.)
* einem Topic, unter dem die Payload gesendet werden soll und
* der Payload.
Es können diverse Variablen genutzt werden, u.A. auch $EVENT und $EVTPARTx-Elemente, die der Rückgabe (setter-Name und ggf. gesetzter Wert) aus dem jeweiligen "widget" entsprechen.

=== on und off ===
Damit die weitergehenden Befehle wie ''on-for-timer'' aus den [[DevelopmentModuleIntro#X_Set|SetExtensions]] funktionieren, muss ein MQTT2_DEVICE die Befehle "on" und "off" kennen. Diese sollten also - wenn es eine Art "Hauptschalter" gibt - gesondert für diesen Hauptschalter angegeben werden.
Hat ein Gerät mehrerer solcher "Hauptschalter", empfiehlt es sich, für jeden dieser Schalter eine eigene MQTT2_DEVICE-Instanz anzulegen.

==== setStateList ====
Gibt es in einem Device neben dem "Hauptschalter" weitere setzbare Readings (z.B. für Helligkeit und Farbe oder eine Temperatur), empfiehlt es sich v.a. dann, wenn das Gerät den Empfang (bzw. die Ausführung) von Befehlen bestätigt, nur die auf den jeweiligen Hauptschalter bezogenen ''set''-Anweisungen in ''state'' zu schreiben. Diese (z.B. on, off und toggle) wären dann in das ''setStateList''-Attribut aufzunehmen.

==== setExtensionsEvent ====
Will man per SetExtensions realisierte laufende Timer visualisieren, empfiehlt es sich, dieses Attribut zu setzen.

=== widgets ===
In der setList können prinzipiell alle in [[FHEMWEB/Widgets|Widgets]] dargestellten Eingabemöglichkeiten verwendet werden.

=== Perl-Kommandos ===
Eigentlich ist die setList dazu gedacht, eine publish-Anweisungen über das IODev abzusetzen. Da aber generisch auch Perl-Code aufgerufen werden kann, ist dies nicht zwingend, so dass zum einen aus Perl heraus auch mehrfach-Publishes ebenso möglich sind wie beliebige "fhem"-Kommandos, die gar nichts mit MQTT zu tun haben müssen (z.B. das regelmäßige Löschen von evtl. veralteten Readings am betreffenden Gerät). Wird Text zurückgegeben, wird dies als "<topic> <payload>" interpretiert und dies gepublisht, erfolgt gar keine Rückgabe, unterbleibt dies.

== getList ==
Die getList ist dazu gedacht, asynchrone Abfragen an die Gegenstelle zu ermöglichen.
Die Syntax dabei ist
* einem getter-Namen, ggf. ergänzt durch ein widget (s.u.)
* Reading-Name, unter dem die Antwort erwartet wird
* einem Topic, unter dem die Payload gesendet werden soll und
* (optional) der Payload.
Auch hier können diverse Variablen genutzt werden, und/oder das ganze für die Ausführung von Perl-Code genutzt werden.

== periodicCmd ==
Für regelmäßige Aufgaben (mit mind. minütlicher Frequenz) kann eine Liste von get- oder set-Kommandos angegeben werden. Dies kann für regelmäßige Abfragen ebenso genutzt werden wie z.B. zum Löschen veralteter Informationen/Readings.

== Abschließende Aufgaben ==
Um das finale Aussehen des Gerätes zu beeinflussen, stehen dann noch die weiteren allgemeinen Attribute zur Verfügung, die in [[DeviceOverview anpassen]] beschrieben sind.

== Hinweise ==
<references />
[[Kategorie:HOWTOS]]
[[Kategorie:MQTT]]

MQTT2-Module - Praxisbeispiele

2024-10-27T06:23:33Z

Beta-User: Typo korrigiert

== Einführung: MQTT bzw. MQTT2 in FHEM ==
{{Randnotiz|RNTyp=y|RNText=Sollten Sie MQTT2_CLIENT verwenden, beachten Sie bitte, dass der MQTT2_CLIENT die ursprüngliche Herkunft der über MQTT verteilten Informationen nicht kennt. Daher ergeben sich in der Anwendung kleinere Unterschiede, zu deren Verständnis die diesbezüglichen [[MQTT2_CLIENT#Anwendung|Hinweise zu MQTT2_CLIENT]] bekannt sein sollten.}}Zur Einbindung von Geräten, welche zur Nutzung des MQTT-Protokols konfiguriert werden können und darüber mit einem MQTT-Server (früher: Broker) kommunizieren, stehen unter FHEM verschiedene Optionen zur Verfügung, wobei nicht alle Module beliebig miteinander verwendet werden können. Details hierzu sind dieser [[MQTT|Übersicht]] zu entnehmen.

Im Rahmen dieses Artikels wird für die eigentlichen Geräte [[MQTT2 DEVICE|MQTT2_DEVICE]] verwendet, damit wird als IO-Device entweder {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} oder [[MQTT2 CLIENT|MQTT2_CLIENT]] benötigt, mit einem IO-Device des Typs [[MQTT (Modul)|MQTT]] funktioniert die nachfolgende Darstellung dagegen nicht<ref>Allerdings können die Konfigurationen in der Regel recht einfach auf die bisherige MQTT-Implementierung übertragen werden</ref>. MQTT2_DEVICE unterstützt u.a. auch die ''setExtensions'' direkt, also z.B. ''on-for-timer<ref>Beachten Sie bei mehrkanaligen Geräten, dass jeweils nur ein Hauptkanal mittels setExtensions verwaltet werden kann! U.a. aus diesen Grund ist es meist sinnvoller, die ''split''-Varianten der attrTemplate-Einrichtung zu verwenden.</ref>'' sowie ''[[MQTT2-Module - Praxisbeispiele#attrTemplate_2|attrTemplate]]''<ref>Auch MQTT_DEVICE unterstützt SetExtensions, allerdings muss dies dort per Attribut eingeschaltet werden</ref>.

=== Allgemeine Einstellungen und Hinweise ===
{{Randnotiz|RNTyp=r|RNText=Beachten Sie, dass für [[autocreate]] in Verbindung mit MQTT2_SERVER '''zwingend''' jeder über MQTT kommunizierende Client eine ClientID angeben muss. Passen Sie daher ggf. die Einstellungen Ihres Geräts an. Manche Geräte verwenden auch "Wegwerf"-ClientID's. Für diese empfiehlt es sich, ggf. dann die durch autocreate erstellten Geräte nachzubearbeiten und die ClientID-Angabe v.a. aus den Inhalten des readingList-Attributs zu entfernen.}}Die nachfolgenden Beispiele gelingen am einfachsten mit '''MQTT2_SERVER als Server ("Broker")''', für diesen sollte dabei ''autocreate'' '''nicht deaktiviert''' sein, damit die erforderlichen MQTT2_DEVICES soweit möglich automatisiert erstellt werden<ref>Dabei wird vorausgesetzt, dass ein allgemeines {{Link2CmdRef|Anker=autocreate|Lang=en|Label=autocreate}}-Device (''TYPE=autocreate'') ebenfalls aktiv ist.</ref> .

Beispiel<ref>MQTT2_SERVER verwendet als default-Einstellung für ''autocreate'' ''simple'', ohne dass ein entsprechendes Attribut gesetzt werden müsste. Die Einstellung ''complex'' empfiehlt sich in der Regel nicht; diese ist jedoch dann zu empfehlen, wenn das Device entweder verschachtelte JSON-Array-Strukturen liefert oder bestimmte Readings nicht gefüllt werden sollen.</ref>:
define MQTT2_FHEM_Server MQTT2_SERVER 1883 global

Falls der MQTT Broker mit Hilfe von [[allowed]] abgesichert wurde, muss in den Geräten ebenfalls User bzw. Passwort eingetragen werden, damit eine MQTT Kommunikation möglich ist.

{{Hinweis|Die Code-Darstellung in diesem Beitrag entspricht jeweils dem RAW-Format zum [[Import von Code Snippets]]. Wer die Attribute direkt und einzeln bearbeitet, muss ggf. die "\" entfernen!}}

=== MQTT-Einstellungen in den Geräten ===
Die Beispiele gehen davon aus, dass die einzubindenden Geräte '''''mit den default-Einstellungen''''' für MQTT betrieben werden, wenn man von den Angaben zum Server und ggf. der Gerätekennung absieht. Es sollten also insbesondere '''keine Veränderungen der topic-Pfade''' vorgenommen werden.

{{Hinweis|Einige der hier beschriebenen Einstellungen haben Änderungen der sich durch die jeweiligen Automatismen eigentlich jeweils ergebenden Standard-Werte zur Folge, insbesondere, was Reading-Namen und von den Geräten gesendete Werte angeht. Sie sollten daher zunächst die Konfiguration des jeweiligen MQTT2-DEVICE-Geräts abschließen, und erst anschließend die weitere Integration mit Event-Handlern, logging usw. vornehmen. }}

=== auto-Konfigurations-features ===
Viele firmwares und Dienste bieten Möglichkeiten an, einer Controller-Software (insbesondere homeassistant) Hilfsdaten zur automatisierten Konfiguration bereitzustellen. Da FHEM diese Daten nicht zu ihrem ursprünglichen Zweck verwenden kann, werden hierdurch lediglich zusätzliche Readings erzeugt, mit denen man als User in der Regel wenig anfangen kann. Es wird daher empfohlen, derartige features '''abzuschalten'''. Wo dies nicht möglich ist, sollte man eine passende [[MQTT2_CLIENT#ignoreRegexp|ignoreRegexp]] setzen bzw. diese passend erweitern!

=== Schritt für Schritt ===
Hier werden in der Regel fertige Konfigurationen für häufige Anwendungsfälle (beispielhaft) dargestellt. In [[MQTT2_DEVICE - Schritt für Schritt]] ist etwas mehr über die Vorgehensweise bei der Zusammenstellung der verschiedenen Attribute und deren Zusammenwirken zu erfahren.

== zigbee2mqtt ==
[[Bild:MQTT2_zigbee2mqtt_Bulbs.png|400px|thumb|Darstellung in FHEMWEB]]
[https://www.zigbee2mqtt.io zigbee2mqtt] ist ein open-source Projekt, mit dem zigbee-Geräte über MQTT direkt angesprochen werden können, ohne dass hierfür eine Bridge eines Herstellers benötigt wird.

Einzelheiten zur Vorgehensweise sind auf der Detailseite [[Zigbee2mqtt|zigbee2mqtt]] zu finden.

== Tasmota ==
{{Randnotiz|RNTyp=r|RNText=Bitte beachten Sie, dass versicherungsrechtliche Probleme entstehen können, wenn die herstellereigene Firmware ersetzt wird!}}[https://github.com/arendst/Sonoff-Tasmota Tasmota] ('''T'''heo '''A'''rends '''S'''onoff '''M'''QTT '''O'''ver '''T'''he '''A'''ir - einer offenen Firmware von [https://github.com/arendst arendst]) ist eine open-source Software für ESP8266-Geräte, die z.B. statt der originalen Firmware für Sonoff-Geräte und andere ESP8266-basierte WLAN-Steckdosen usw. verwendet werden kann.
{{Hinweis|[[Datei:Tasmota mqtt config.png|120px|thumb|right]]Vor allem, aber nicht nur bei Verwendung des MQTT2_CLIENT als IO, ist es empfehlenswert, in der MQTT-Konfiguration der tasmota-Geräte für den Parameter ''<nowiki>topic = %topic% (tasmota)</nowiki>'' ebenfalls die dynamisch aus der Chip-ID erzeugte Kennung ''DVES_%06X'' zu verwenden. (Kopieren Sie einfach diese Zeichenkette aus dem Eingabefeld für ''"client ..."'', siehe nebenstehende Abbildung). Die eigentliche Umbenennung zu einem "sprechenden Namen" kann dann innerhalb von FHEM - mittels ''rename'' oder ggf. mit einem ''alias'' - erfolgen.}}
=== MQTT2_DEVICE ===
Dieses sollte bei aktiviertem ''autocreate'' am MQTT2_SERVER-Device automatisch angelegt werden, sobald das betreffende Gerät eingesteckt oder neu gestartet oder an einem evtl. vorhandenen Taster geschalten wird. Bislang wurden Tasmota version(en) ab 6.1.1 bis min. 8.1.0 getestet, dies auf verschiedener Hardware, zunächst mit Sonoff Touch und S20, zwischenzeitlich mit einer Vielzahl von Geräten, die per USB-Adapter oder mit der Methode aus dem [https://www.heise.de/ct/artikel/Tuya-Convert-IoT-Geraete-ohne-Loeten-vom-Cloud-Zwang-befreien-4283623.html Tuya-Convert]-Projekt des heise-Verlags auf Tasmota umgeflasht wurden.

=== Manuelle Anpassungen - Schalter ===
Die RAW-Definition kann dann beispielsweise wie folgt ergänzt werden:
<syntaxhighlight lang="perl">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD IODev m2server
attr MQTT2_DVES_9B01BD devStateIcon on:FS20.on:off off:FS20.off:on
attr MQTT2_DVES_9B01BD readingList DVES_9B01BD:tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/LWT:.* LWT\
DVES_9B01BD:tele/DVES_9B01BD/UPTIME:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/SENSOR:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO1:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO2:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO3:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/RESULT:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }
attr MQTT2_DVES_9B01BD room MQTT2_DEVICE
attr MQTT2_DVES_9B01BD setList on cmnd/DVES_9B01BD/POWER on\
off cmnd/DVES_9B01BD/POWER off\
reboot cmnd/DVES_9B01BD/Restart 1
attr MQTT2_DVES_9B01BD webCmd on:off:reboot
</syntaxhighlight>

=== Manuelle Anpassungen - Dimmer ===
{{Randnotiz|RNTyp=r|RNText=Dieses Beispiel ist nur bedingt zur Nachahmung zu empfehlen: Prinzipiell kann man Readings und setter in MQTT2_DEVICE fast nach Belieben benennen. Wählt man allerdings FHEM-typische Namen, kann dies sehr zur Vereinfachung beitragen. Z.B. wird eine Sprachssteuerung bei einem Dimmer üblicherweise automatisch korrekt eingestellt werden, wenn der für die Helligkeit zuständige setter z.B. pct (oder brightness) heißt, oder eine abzufragende Temperatur temperature. Entsprechendes gilt im Rahmen von devspec-Abfragen.}}Bei einem Dimmer sind einige zusätzliche Anpassungen vorzunehmen. Ein Dimmer wird über '''POWER''' geschaltet und über '''Dimmer''' gedimmt. Damit das funktioniert, müssen ein stateFormat und devStateIcon zusammenarbeiten:
<syntaxhighlight lang="perl">
attr MQTT2_DVES_2DF34D devStateIcon 10\d.*:dim100%@orange:off 1\d.*:dim12%@orange:off 2\d.*:dim18%@orange:off 3\d.*:dim31%@orange:off 4\d.*:dim43%@orange:off 5\d.*:dim50%@orange:off 6\d.*:dim62%@orange:off 7\d.*:dim68%@orange:off 8\d.*:dim81%@orange:off 9\d.*:dim93%@orange:off 0:FS20.off:on .*:FS20.off@orange:off
attr MQTT2_DVES_2DF34D stateFormat {if(ReadingsVal($name,"POWER",0)eq"off"){0}else{ReadingsVal($name,"Dimmer",0)}}
</syntaxhighlight>
Nun kann man über das Icon ein- und ausschalten und der Zustand des Dimmers wird korrekt angezeigt.

Es fehlt noch ein Slider, um auch dimmen zu können. Zusätzlich muss setList noch um Dimmer erweitert werden:
<syntaxhighlight lang="text">
attr MQTT2_DVES_2DF34D setList on cmnd/dimmer/POWER on\
off cmnd/dimmer/POWER off\
Dimmer cmnd/dimmer/Dimmer
attr MQTT2_DVES_2DF34D webCmd Dimmer
attr MQTT2_DVES_2DF34D widgetOverride Dimmer:slider,0,1,100
</syntaxhighlight>

=== attrTemplate ===
===== Allgemeines =====
Für gängige Tasmota-Geräte stehen ''templates'' bereit, mit denen sich diese schnell konfigurieren lassen.
Beachten Sie dazu den Abschnitt ''attrTemplate'' in [[MQTT2 DEVICE#attrTemplate|MQTT2_DEVICE]]. Bei Anwendung eines template mit "split" im Namen werden dabei weitere Geräte angelegt und konfiguriert.{{Hinweis|Bitte attrTemplates nicht verwechseln mit templates, die auf den Tasmota- bzw. Blackadder-Seiten angeboten werden, welche zur Konfiguration der firmware genutzt werden können! Es sollte zunächst die firmware korrekt eingerichtet werden, so dass das Gerät selbst direkt auf dessen Web-Interface korrekt bedient werden kann.}}

===== Kein passendes attrTemplate vorhanden? =====
Exisitert (noch) kein passendes attrTemplate, ist zu empfehlen, zunächst das "''tasmota_basic''" anzuwenden. Dieses führt einige Basiskonfigurationen durch, die für FHEM hilfreich sind, z.B. wird die firmware so eingestellt, dass Schaltzustände in Kleinschreibung übermittelt werden, statt der defaults "ON" bzw. "OFF".

Allerdings stellt dieses das ''autocreate'' an dem MQTT2_DEVICE auf 0, was dann nicht optimal ist, wenn man weitere Readings aus dem Gerät erwartet, etwa, weil zusätzliche Sensoren vorhanden sind. In diesem Fall empfiehlt es sich, das ''autocreate''-Attribut an dem MQTT2_DEVICE zu löschen, damit alle weiteren Informationen verarbeitet werden und ggf. im ''jsonMap''-Attribut nur die Angabe "''POWER1:state''" zu belassen.

=== on-for-timer ===
Um z.B. ein Relais nur für einen Zeitraum anzuschalten, kann man bei Tasmota-Geräten zwischen mehrere Varianten wählen. Ohne speziellen ''setter'' in der ''setList'' werden die '''SetExtensions''' verwendet. Timer laufen damit innerhalb FHEM. Da diese intern als temporäres [[at]] ausgeführt werden, sind diese auch noch nach einem FHEM-Neustart vorhanden, sofern FHEM ordnungsgemäß beendet und neu gestartet wird.

Die Tasmota-firmware bietet ergänzend dazu zwei Möglichkeiten an, bei denen der Timer direkt auf dem ESP-Microcontroller verwaltet wird:

==== delay ====
Zeile zur Erweiterung der ''setList'' (Attributeingabe via FHEMWEB!):
on-for-timer {my $duration = $EVTPART1*10; 'cmnd/DVES_575127/Backlog POWER1 1; delay '.$duration.'; POWER1 0'}

Ohne Auswirkungen auf alles, was danach kommt, hat aber den Nachteil, dass die möglichen Zeitspannen auf 3600 1/10 Sekunden begrenzt sind (siehe [https://tasmota.github.io/docs/Commands/#delay Commands - Tasmota Delay]), also 6 Minuten.

====pulseTime ====
Zeile zur Erweiterung der ''setList'' (s.o.):
on-for-timer {my $duration = $EVTPART1 < 11.2 ? $EVTPART1*10 : $EVTPART1+100; 'CMNDTOPIC/Backlog pulseTime1 '.$duration.'; POWER1 1'}
Auch hier sind die möglichen längsten Einschaltdauern begrenzt, allerdings ist diese mit 18h deutlich länger als mit ''delay''. Diese Implementierung hat den Nachteil, dass der ESP-Microcontroller die jeweils letzte pulseTime auch für alle weiteren "normalen" Einschaltvorgänge berücksichtigt, das Relais also ebenfalls nach Ablauf der übermittelten pulseTime abgeschaltet wird; dies gilt allerdings ohne explizites ''save'' nur bis zum nächsten reboot des Microcontrollers.

Da nach dem ersten pulseTime setzten, diese immer benutzt wird, kann man mit einem kleine Workaround das Device normal arbeiten lassen. Dafür wird bei jedem anderem Befehl, aus der PulseTime, der Timer deaktiviert.
Hierfür machen wir uns zu nutzen, dass man mehrere Befehle gleichzeitig an Tasmota senden kann (backlog). Ob diese Lösung auch mit anderen MQTT Firmwares funktioniert, kann ich nicht sagen. Es wurde lediglich mit Tasmota getestet.
Wir senden also, bevor wir den eigentlich Tasmota Befehl zum Ein- oder Ausschalten schicken, einen Befehl zum deaktivieren des Timers: "pulseTime 0"
Hier ein Beispiel: (das entsprechende device "DEV_611F3E" muss gegen das eigene ersetzt werden)
off:noArg cmnd/DVES_611F3E/backlog pulseTime 0; POWER1 0
on:noArg cmnd/DVES_611F3E/backlog pulseTime 0; POWER1 1
toggle:noArg cmnd/DVES_611F3E/backlog pulseTime 0; POWER1 2

=== zigbee2tasmota ===
[https://tasmota.github.io/docs/Zigbee/ zigbee2tasmota] ist eine Erweiterung der Tasmota-firmware für Microcontroller, insbesondere dem ESP8266 (und ESP32)(link), über die einige ZigBee-Chipsätze (insbesondere TI CC2530) als [[ZigBee#Koordinator_.28ZigBee_coordinator.2C_ZC.29|Coordinator]] eingebunden werden können, um ein ZigBee-Netzwerk aufzubauen.
{{Hinweis|Stand 08/2020 war die Einbindung anderer Chipsätze erst in einem Alpha-Stadium; die Zahl der über einen CC2530 einbindbaren ZigBee-Geräte ist daher derzeit relativ begrenzt (ca. 16)!}}
Auch für diese Lösung stehen einige ''attrTemplate'' zur Verfügung. Nähere Informationen hierzu sind dem Artikel [[Zigbee2Tasmota-MQTT]] zu entnehmen.

== ESPurna ==
ESPurna ist eine weitere alternative firmware für ESP8266-basierte Geräte, Details sind der [https://github.com/xoseperez/espurna/wiki Projektseite] zu entnehmen.

Das Format, in dem ESPurna Daten sendet, unterscheidet sich v.a. darin, dass bool'sche Werte als 0 oder 1 gesendet werden, und nicht wie sonst üblich als "on" oder "off" oä.. Es stehen einige Mustertemplates zur Verfügung, um diese Art der Payload in FHEM-konforme Werte zu überführen.

== Shelly ==
=== Vorbemerkung ===
Auch für Shelly-Geräte steht eine Auswahl an [[MQTT2-Module - Praxisbeispiele#attrTemplate_2|templates]] bereit.
Beachten Sie auch hier, dass uU. bei Anwendung eines template mit "split" im Namen weitere Geräte angelegt und konfiguriert werden.

Standardmäßig senden die Shelly-Geräte ihren kompletten Status alle 30 Sekunden. Dies kann man über den Parameter ''mqtt_update_period'' in den ''settings'' ändern, allerdings ist dieser nur über die HTTP-Schnittstelle des Shelly verfügbar. Um diese Statusupdates abzustellen, kann über den Browser folgender Befehl verwendet werden:
http://<ip-des-shelly>/settings?mqtt_update_period=0,
Soweit bekannt, werden dann nur statische updates ausgeschaltet, z.B. für das Relay bzw. angeschlossene Taster oder Schalter; insbesondere Verbrauchswerte werden dennoch aktualisiert.

=== Shelly1 ===

=== Shellybulb ===
Zunächst muss man einen Statusupdate des Shellybulb erzwingen (Aus- und Einschalten, physikalisch oder per Web-UI), damit das Gerät bei eingeschaltetem autocreate angelegt wird. Dies sieht zunächst so aus:
Internals:
CFGFN
CID shellybulb_3CC533
DEF shellybulb_3CC533
DEVICETOPIC MQTT2_shellybulb_3CC533
IODev MQTT2_FHEM_Server
NAME MQTT2_shellybulb_3CC533
NR 246
STATE ???
TYPE MQTT2_DEVICE
READINGS:
2018-12-12 19:28:08 status_blue 0
2018-12-12 19:28:08 status_brightness 61
2018-12-12 19:28:08 status_effect 0
2018-12-12 19:28:08 status_gain 26
2018-12-12 19:28:08 status_green 0
2018-12-12 19:28:08 status_ison true
2018-12-12 19:28:08 status_mode color
2018-12-12 19:28:08 status_red 255
2018-12-12 19:28:08 status_temp 3250
2018-12-12 19:28:08 status_white 0
Attributes:
IODev MQTT2_FHEM_Server
readingList shellybulb_3CC533:shellies/shellybulb-3CC533/color/0/status:.* { json2nameValue($EVENT, 'status_') }
room MQTT2_DEVICE
[[Bild:MQTT2 Shellybulb.png|400px|thumb|Darstellung in FHEMWEB nach Anwendung des template]]Dann bei den set-Anweisungen das attrTemplate "shellybulb" auswählen und setzen. Es erscheint eine Abfrage, ob die vorhandenen Readings gelöscht werden sollen. Diese bitte bestätigen und die Seite neu laden. Danach einmal An- und Ausschalten, damit die Readings auch durch einen neuen Status initialisiert werden und die Seite im Browser neu laden.

=== Shelly Plug S ===
Über die Leistungsmessung des Shelly Plug S lässt sich sehr einfach auch eine Erkennung des Betriebszustandes des angeschlossenen Gerätes realisieren. Dazu stellt man zuerst fest, wieviel Leistung das Gerät in jedem Betriebszustand verbraucht und kann dann z.B. für einen angeschlossenen Fernseher, der im Standby 1 Watt und im Betrieb > 100 Watt verbraucht, den Zustand erkennen und als on/off Status anzeigen. Dazu wird das state Reading wie folgt definiert:
attr readingList shellies/shellyplug-s-123456/relay/0/power:.* { { state => $EVTPART0<100?"off":"on" } }
Der Status des MQTT2 Devices zeigt dann bei <100W "off" und sonst "on" an.

=== HTTP-Commands ===
In diesem {{Link2Forum|Topic=102369|LinkText=Forumsbeitrag}} wird eine Lösung vorgestellt, um über [[99 myUtils anlegen|myUtils-Code]] weitere Kommandos bereitzustellen, die sonst nur direkt über das Web-Interface zu erreichen sind.

== Shelly Gen2 ==
=== Vorbereitung ===
Shelly mit dem WLAN verbinden, entweder über die Shelly APP oder per Laptop auf den Offenen AP des Shelly verbinden und dann übers WebUI des Shelly mit dem Heimischen WLAN verbinden. Über die APP geht dies meist etwas einfach und schneller, besonders wenn man mehrere Shelly Geräte hinzufügen möchte. Durch die BT Unterstützung der Gen2 Geräte, klappt dies meist auch deutlich schneller und zuverlässiger als noch bei Gen 1 Geräten.
Nachdem der Shelly mit dem WLAN verbunden ist, sollte die Firmware überprüft und gegebenenfalls aktualisiert werden (Stand Anfang 2022 scheint die firmware noch nicht voll ausgereift gewesen zu sein, da dass insbesondere die MQTT-Schnittstelle immer wieder überarbeitet wurde). Bitte KEINE BETA Versionen installieren, wenn nicht dazu aufgefordert wurde.
Nach dem, durch das Update ausgelösten, Neustart kurz Prüfen ob die Uhrzeit passt, wenn trotz richtiger Zeitzone die Uhrzeit nicht stimmt hilft ein weiterer Neustart.
Nun auf Networks| Internet (leider in APP und WebUI unterschiedlich), hier auf MQTT und die Einstellungen für den verwendeten MQTT Server treffen. Diese Einstellungen werden auch wieder durch Neustart übernommen.
=== Shelly Plus 1 ===
Zunächst muss man einen Statusupdate des Shelly erzwingen (Aus- und Einschalten, physikalisch oder per Web-UI), damit das Gerät bei eingeschaltetem autocreate angelegt wird. Dies sieht zunächst so aus:
<syntaxhighlight lang="text">
defmod MQTT2_shellyplus1_441793a34044 MQTT2_DEVICE shellyplus1_441793a34044
attr MQTT2_shellyplus1_441793a34044 readingList shellyplus1_441793a34044:shellyplus1-441793a34044/online:.* online\
shellyplus1_441793a34044:shellyplus1-441793a34044/status/mqtt:.* { json2nameValue($EVENT) }\
shellyplus1_441793a34044:shellyplus1-441793a34044/events/rpc:.* { json2nameValue($EVENT) }\
shellyplus1_441793a34044:shellyplus1-441793a34044/status/sys:.* { json2nameValue($EVENT) }\
shellyplus1_441793a34044:shellyplus1-441793a34044/status/switch_0:.* { json2nameValue($EVENT) }
attr MQTT2_shellyplus1_441793a34044 room MQTT2_DEVICE

setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 IODev m2s
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 available_updates_beta_version 0.10.0-beta6
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 cfg_rev 7
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 connected true
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 dst shellyplus1-441793a34044/events
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 fs_free 237568
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 fs_size 458752
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 id 0
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 mac 441793A34044
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 method NotifyStatus
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 online true
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 output false
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_mqtt_connected true
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 params_switch_0_id 0
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 params_switch_0_output false
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 params_switch_0_source WS_in
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_switch_0_temperature_tC 39.88
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_switch_0_temperature_tF 103.78
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 params_sys_available_updates_beta_version 0.10.0-beta6
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 params_ts 1646474952.66
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_wifi_rssi -57
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_wifi_ssid WLAN-Alex
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_wifi_sta_ip 192.168.177.167
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_wifi_status got ip
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 ram_free 179764
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 ram_size 249456
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 restart_required false
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 source WS_in
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 src shellyplus1-441793a34044
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 temperature_tC 39.9
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 temperature_tF 103.9
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 time 11:08
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 unixtime 1646474911
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 uptime 7
</syntaxhighlight>

Über die set Anweisung unterhalb der Device Übersicht können wir ein attrTemplate wählen; shellyPlus_1
Es erscheint eine kurze Übersicht was im Template enthalten ist, dieses befindet sich noch im Aufbau und wird aktuell von der Community aufgebaut und weiterentwickelt. Mit einem Klick auf „set“ laden wir das Template und übernehmen die Einstellungen für den Shelly Plus 1.
Damit ist der Shelly bereit, im Status wird neben dem Namen auch der Onlinestatus des Shellys (grüner | roter Punkt) so wie eine Lampe mit Toggle (on | off) Funktion und die Temperatur des Shellys angezeigt. Darüber hinaus verschwindet die Lampe und wird durch einen klickbaren Hinweis ersetzt, wenn ein Neustart des Shellys nötig ist.

=== Tipps ===
{{Randnotiz|RNTyp=g|RNText=So nimmt man bei Verwendung eines normalen Schalters (eine Stellung EIN eine AUS) gerne den „Flip“ Mode – damit wird der Shelly IMMER umgeschaltet, egal in welche Stellung der Schalter sich bewegt („Kreuzschaltung“). Diese Einstellungen trifft man grundlegend im WebUI des Shelly (oder APP) unter „Channel settings“.
Für den „Flip“ müssen wir die Grundeinstellung des „Power on default“ auch ändern (gleiche Seite) - persönlich wähle ich „Restore last“, also: nach Stromausfall wird der letzte Zustand wieder hergestellt; grundsätzlich gehen alle Modi außer „Match input“.
}}
Das aktuelle Template wurde um die Funktion erweitert, den Button Mode umzuschalten. In den meisten Fällen legt man sich auf eine Schaltmethode fest, welche zum Hardware Setup passt.

Manchmal will man aber vielleicht den Hardware Schalter deaktivieren, nennen wir es „Kindersicherung“. Bei Shelly heißt das „detached“.
Diese Funktion wurde ins Template als „in_mode“ Übernommen. Mögliche set Befehle sind „flip“, „detached“ „toggle“. Bedingung zur Verwendung ist: „relay power on default“ darf NICHT „Match input“ sein. Sollte Follow statt Flip bevorzugt werden, müsste entsprechende Zeile in der setList von „flip“ auf „follow“ angepasst werden.

Der Befehlt lässt sich mit dem webCmd in_mode auch schnell zugänglich in die Übersicht vom Shelly setzen, so erhält man neben dem Status ein Dropdown mit flip detached und toggle zum schnellen umschalten. Mit webCmdLabel kann man noch einen Namen für das Dropdown setzen.

== OpenMQTTGateway ==
Um verschiedene Systeme wie BLE usw. auf MQTT zu bringen bietet sich [https://github.com/1technophile/OpenMQTTGateway OpenMQTTGateway] an, z.B. wird für das Auslesen vieler BLE-Seonsoren lediglich ein ESP32-Board ohne Zusatzhardware (ab ca. 5,- Euro in Fernost erhältlich) benötigt, auf das dann eine vorkompilierte firmware geflasht wird (hierfür wird ein USB-seriell-Wandler benötigt).

Nähere Details sind im Artikel [[OpenMQTTGateway]] zu finden.

== 8-Port-Ethernet Board ==
<gallery>
datei:8-relais-ethernetboard closed.jpg|mit Gehäuse
datei:8-Port-MQTT-Relais-Board.jpg|ohne Gehäuse
</gallery>
In diesem {{Link2Forum|Topic=107536|Message=1016379|LinkText=Forenbeitrag}} bzw. dem betreffenden Thread wurde ein Relais-Board vorgestellt, mit dem 8 Relais über Ethernetkabel verbunden werden, die Kommunikation erfolgt dann über MQTT. Über die verwendete Software ist wenig bekannt, es könnte jedoch sein, dass diese Art der Einbindung auch bei weiteren Boards funktioniert, die einen bestimmten Ethernet-Chipset von TI (DP83848) und eine Cortex M3 MCU verwenden.

== Milight-Bridge ==
=== Vorbemerkung ===
Der [https://github.com/sidoh/esp8266_milight_hub esp8266_milight_hub] ist ein open source- Projekt, mit dem auf Basis von ''openmili'' eine Vielzahl von MiLight-Geräten gesteuert werden können. Der MiLight-Hub erstetzt dabei eine beliebige Zahl von Milight-Bridges und ist auch zu verschiedenen Versionen des MiLight-Protokols kompatibel. Allerdings lassen sich manche MiLight-Geräte nicht an die Bridge anlernen, und es werden auch nicht alle Fernbedienungs-Typen voll unterstützt.
Neben MQTT kann dieser auch mit HTTPMOD oder Wifilight (bzw. den MiLight-Modulen) gesteuert werden. Die Hardware entspricht dabei im Wesentlichen einem MySensors-Wifi-Gateway<ref>Es wird lediglich ein anderer CS-PIN genutzt. Dies kann einfach in der Web-Oberfläche der Firmware umgestellt werden.</ref>.
Hier wird vorausgesetzt, dass eine funktionierende Bridge vorhanden ist und die zu steuernden Leuchtmittel mit dem Hub bereits verbunden (gepairt) sind bzw. entsprechende Fernbedienungs-Signale empfangen werden können (bei vorhandenem pairing eines Leuchtmittels an die Fernbedienung).
Der Vorteil der MQTT-Lösung liegt darin, dass man bei kompatiblen Fernbedienungen auch direkt Informationen über Schaltvorgänge erhält, die mit der Fernbedienung ausgelöst werden.

=== Einstellungen am MiLight-Hub ===
Die zum FHEM-Server bzw. dem MQTT2_SERVER passenden Vorgaben sind im Web-Interface des Hub einzustellen. Gegebenenfalls passen Sie die vom Hub zurückzugebenden Elemente im Web-Interface des Hub an.
Die Einstellungen für ''MQTT topic pattern'' usw. können auf den default-Werten<ref>Diese sind: ''milight/:device_id/:device_type/:group_id'' für "topic pattern" ''milight/updates/:hex_device_id/:device_type/:group_id'' für "update topic pattern" ''milight/states/:hex_device_id/:device_type/:group_id'' für "state topic pattern". Der Autor hat derzeit folgende Infotypen zum Senden markiert: "status, brightness, hue, color, mode, color_temp, bulb_mode, computed_color, hex_color" (enthält eventuell zu viele Angaben. Bei einem Eventhandler muss man uU. darauf achten, dass kurz hintereinander zweimal dasselbe Event kommen kann (für ON/OFF)).</ref> belassen werden, für die seit Mitte 2019 vorhandene Option, eine LWT-Message zu senden (''MQTT Client Status Topic''), tragen Sie ''milight/LWT'' ein und aktivieren ''Detailed''.

=== FHEM-Devices ===
[[Bild:MQTT2 MiLight.png|400px|thumb|Milight: Darstellung in FHEMWEB]]
==== Bridge ====
Wird nun über den Hub oder eine von diesem erkannte Fernbedienung ein vorhandenes Leuchtmittel geschaltet, wird bei eingeschaltetem autocreate ein erstes Device erstellt, die zunächst erstellte Definition sieht typischerweise etwa so aus:
defmod MQTT2_milight_hub_1370325 MQTT2_DEVICE milight_hub_1370325
attr MQTT2_milight_hub_1370325 IODev MQTT2_FHEM_Server
attr MQTT2_milight_hub_1370325 readingList milight_hub_1370325:milight/updates/0xBE59/rgbw/1:.* { json2nameValue($EVENT, '1_', $JSONMAP) }
attr MQTT2_milight_hub_1370325 room MQTT2_DEVICE

Auf dieses Device wird nun das ''template'' '''esp_milight_hub_bridge''' angewandt.

==== Einzelne Leuchtmittel ====

Wird nun nochmals das oben verwendete Leuchtmittel geschaltet, erstellt autocreate ein weiteres Device:
defmod MQTT2_milight_0xBE59_1 MQTT2_DEVICE milight_0xBE59_1
attr MQTT2_milight_0xBE59_1 IODev MQTT2_FHEM_Server
attr MQTT2_milight_0xBE59_1 readingList milight/states/0xBE59/rgbw/1:.* { json2nameValue($EVENT, '1_', $JSONMAP) }
attr MQTT2_milight_0xBE59_1 room MQTT2_DEVICE

Auf dieses wird nun eines der Bulb-templates angewendet. Wählt man das template X_01_esp_milight_hub_rgbw_bulb, wird eine einfache Variante erstellt, die neben einem toggelnden Icon nur Regler für Helligkeit, die Farbe und zwei Schaltflächen für den Weiß- und Nachtmodus enthält. Wer mehr oder andere Steuerelemente erhalten möchte, verwendet ein anderes template. Nicht benötigte Elemente kann man dabei einfach aus der Definition löschen.

Alle weiteren Devices werden genauso erstellt.

Um ein Device zu erhalten, mit dem sich alle Kanäle gleichzeitig steuern lassen, kann das template ''X_01a_esp_milight_hub_make_rgbw_group'' verwendet werden. Dieses verändert nicht das aktuelle Device, sondern erstellt '''eine Kopie''', die dann modifiziert wird. Diese Kopie ist unter dem Namen ''milight_<RemoteID>_0'' im selben Raum zu finden wie das Ausgangsgerät und kann ebenfalls an die eigenen Wünsche angepasst werden.

Weitere Beispiele:
Beispiel für ein RGB-CCT-Device:
defmod Licht_Wz_all MQTT2_DEVICE
attr Licht_Wz_all IODev MQTT2_Broker
attr Licht_Wz_all eventMap /set_white:Weiss/night_mode:Nacht/white_mode:white/on:on/off:off/ON:on/OFF:off/next_mode:Mode/mode_speed_up:Up/mode_speed_down:Down/
attr Licht_Wz_all group Licht
attr Licht_Wz_all icon light_control
attr Licht_Wz_all readingList milight/0x5D02/rgb_cct/0:.* { json2nameValue($EVENT) }\
milight/updates/0x5D02/rgb_cct/0:.* { json2nameValue($EVENT) }\
milight/states/0x5D02/rgb_cct/0:.* { json2nameValue($EVENT) }\

attr Licht_Wz_all room Wohnzimmer
attr Licht_Wz_all setList on milight/0x5D02/rgb_cct/0 {"status":"ON"}\
off milight/0x5D02/rgb_cct/0 {"status":"OFF"}\
level milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
hue:colorpicker,HUE,0,1,359 milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
command:uzsuSelectRadio,Weiss,Nacht,Mode,Up,Down milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
brightness:colorpicker,BRI,0,1,255 milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
next_mode milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
mode_speed_up milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
mode_speed_down milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
saturation:colorpicker,BRI,0,1,100 milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
color_temp:colorpicker,CT,153,1,370 milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
device_id milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
effect milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
mode milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
commands milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}
attr Licht_Wz_all sortby 1
attr Licht_Wz_all webCmd command:brightness:saturation:color_temp:hue
attr Licht_Wz_all webCmdLabel command\
:brightness:saturation\
:color_temp:hue
==== Ein Leuchtmittel, mehrere Fernbedienungen ====
Pairt man mehrere Fernbedienungen mit einem Leuchtmittel, sollten auch alle entsprechenden Fernbedienungscodes in das readingList-Attribut übernommen werden. Dazu übernimmt man am einfachsten die Einträge aus den zusätzlichen MQTT2_DEVICEs. Benötigt man das zusätzliche Device nicht separat, um z.B. eine getrennte Gruppenschaltung zu realisieren, kann man dieses löschen. Beispiel-readingList für ein Device, das auf zwei Fernbedienungscodes und zwei Gruppen "hört":

attr Licht_Wz_all readingList milight/states/0x1234/rgbw/2:.* {json2nameValue($EVENT) }\
milight/updates/0x1234/rgbw/2:.* { json2nameValue($EVENT) }\
milight/states/0x1234/rgbw/0:.* { json2nameValue($EVENT) }\
milight/updates/0x1234/rgbw/0:.* { json2nameValue($EVENT) }\
milight/states/0xABCD/rgbw/0:.* { json2nameValue($EVENT) }\
milight/updates/0xABCD/rgbw/0:.* { json2nameValue($EVENT) }\
milight/states/0xABCD/rgbw/4:.* { json2nameValue($EVENT) }\
milight/updates/0xABCD/rgbw/4:.* { json2nameValue($EVENT) }

==== Fernbedienung als Input-Device nutzen ====
In diesem {{Link2Forum|Topic=103493|LinkText=Thread}} ist dargestellt, wie man eine Fernbedingung des Typs FUT089 dazu verwenden kann, einen [[MPD]] oder Rollladenaktoren zu steuern, oder diese Fernbedienung für [[Hue#HUE-Device|HUEDevice]]-Leuchtmittel zu nutzen.
Um hier nur Differenz-Meldungen direkt an die betreffende myUtils-Funktion zu übergeben und doppelte Events zu verhindern, sollte hier die readingList so angepasst werden, dass nur Messages aus dem "updates"-Zweig ausgewertet werden:
defmod MiLight_RC1_0 MQTT2_DEVICE milight_0xABCD_0
attr MiLight_RC1_0 readingList milight/states/0xABCD/fut089/[0-8]:.* {}
milight/updates/0xABCD/fut089/0:.* { FHEM::attrT_MiLight_Utils::MPDcontrol('myMPD',$EVENT, 'Yamaha_Main') }\
milight/updates/0x5D47/fut089/1:.* { FHEM::attrT_MiLight_Utils::FUT_to_RGBW('Licht_Stehlampe_links',$EVENT) }\
milight/updates/0x5D47/fut089/2:.* { FHEM::attrT_MiLight_Utils::FUT_to_RGBW('Licht_Stehlampe_rechts',$EVENT) }\
milight/updates/0x5D47/fut089/3:.* { FHEM::attrT_MiLight_Utils::four_Lights_matrix($EVENT, 'Licht_WoZi_Vorn_Aussen', 'Licht_WoZi_Vorn_Mitte', 'Licht_WoZi_Hinten_Aussen', 'Licht_WoZi_Hinten_Mitte') }\
milight/updates/0x5D47/fut089/4:.* { FHEM::attrT_MiLight_Utils::shuttercontrol('Jalousie_WZ',$EVENT) }\
milight/updates/0x5D47/fut089/5:.* { FHEM::attrT_MiLight_Utils::shuttercontrol('Rollladen_WZ_SSO',$EVENT) }\
milight/updates/0x5D47/fut089/6:.* { FHEM::attrT_MiLight_Utils::shuttercontrol('Rollladen_WZ_SSW',$EVENT) }\
milight/updates/0x5D47/fut089/7:.* {}\
milight/updates/0x5D47/fut089/8:.* {}
attr MiLight_RC_WZ stateFormat CommandSet

== eBus ==
An dieser Stelle sollen lediglich die Grundzüge erläutert werden, eine ausführliche Anleitung über die Konfiguration des [[EBUS-MQTT2|eBus mit MQTT2 gibt es hier]].

=== Vorbereitung und Definition am eBus ===
Vorausgesetzt wird ein laufender eBus-Dämon. Dessen Einrichtung wird im Artikel [[EBUS#Software|EBUS]] beschrieben.
In der Konfiguration des Dämons ( /etc/default/ebusd ) ist die Kommunikation über MQTT zu aktivieren und die Topic-Struktur festzulegen, z.B. ''ebusd/%circuit/%name''.
--accesslevel=* --mqttport=1883 --mqttjson --mqtthost=IpAdresseMQTTSERVER --mqtttopic=ebusd/%circuit/%name
{{Hinweis|Nachfolgend wird davon ausgegangen, dass als Vorgabe für mqtttopic ''ebusd'' verwendet wurde. Dies kann geändert werden, es wird aber dringend empfohlen, das mqtttopic in jedem Fall mit ''ebus...'' zu beginnen!}}

=== Vorbereitung und Definition in FHEM ===
Unabhängig von dem konkret genutzten IO-Modul (MQTT2_SERVER oder MQTT2_CLIENT) sollte an diesem '''''vor''''' den nachfolgenden Schritten zunächst das autocreate ausgeschaltet werden. Weiter sollte geprüft werden, ob es bereits MQTT2_DEVICE-Geräte gibt, die Einträge in der ''readingList'' enthalten, die vom ebus stammen. Da wir die ''readingList'' anschließend mit erweiterten JSON-Optionen erstellen wollen, müssen zumindest sämtliche ''readingList''-Attribute entsprechend bereinigt oder gelöscht werden; in der Regel ist es einfacher, diese Geräte nach dem Deaktivieren des autocreate am IO zu löschen.
{{Randnotiz|RNTyp=y|RNText=Sollten Sie MQTT2_CLIENT als IO nutzen, sollte für das weitere Vorgehen eine Kopie des MQTT2-"Sammeldevices" genutzt werden, und dessen ''CID'' auf ''ebusd'' geändert werden. Nach Anwendung des ebusd-splitter-templates müssen dann alle den ebus betreffenden Einträge aus der ''readingList'' des "Sammeldevices" gelöscht werden oder diese ganz gelöscht.}}Ist der ebus-Dämon lauffähig und für MQTT konfiguriert, sendet dieser regelmäßige Messages.

Sind die Vorbereitungen abgeschlossen, aktivieren wir ''autocreate'' wieder, allerdings wählen wir als autocreate-Methode ''complex'' aus, da der eBus-Dämon teilweise<ref>Dies betrifft vorrangig die Statusmeldungen</ref> eine weiter verschachtelte JSON-Struktur zum Versenden der Informationen verwendet als üblich. Danach wird wie bei den anderen o.g. Geräten automatisch ein neues MQTT2_DEVICE angelegt<ref>Bei Verwendung des MQTT2_CLIENT wird dann die ''readingList'' am bereits definierten MQTT2_DEVICE aus der Kopie des "Sammeldevice" automatisch wieder erstellt bzw. gefüllt.</ref>

==== "ebus-Bridge" ====
Auf das von ''autocreate'' erstellte MQTT2_DEVICE wird nunmehr das template ''eBus_daemon_splitter'' angewendet. Nach einiger Zeit sollte sowohl die readingList an diesem Device erweitert worden sein, wie auch ein oder mehrere neue MQTT2_DEVICE-Geräte angelegt.
Dieses Device liefert zukünftig Readings zum Dämon selbst, wie dessen ''uptime'', alle weiteren am eBus angeschlossenen Teilnehmer werden dagegen zweckmäßigerweise durch ein oder mehrere weitere MQTT2_DEVICE-Geräte dargestellt.

Das ''attrTemplate'' läd eine weitere ''attrTemplate''-file und [[99 myUtils anlegen|99_myUtils-Code]] vom FHEM-Server nach. Beides steht dann auch unmittelbar zur Nutzung zur Verfügung.
==== "ebusd_bai" und weitere Geräte ====
{{Hinweis|Der eBus-Dämon sendet nicht alle Informationen zu allen am eBus angeschlossenen Geräte automatisch. Diese müssen teilweise erst aktiv angefragt werden. Wie das im einzelnen erfolgen kann, ist dem o.g. Detailartikel zu entnehmen.}}
Funktioniert die Kommunikation zwischen dem eBus-Dämon und FHEM, sollte nach einigen Minuten zumindest ein weiteres Gerät namens ''MQTT2_ebus_bai'' angelegt worden sein.

== Sonos2Mqtt ==
Aus einem Versuch heraus ist ein {{Link2Forum|Topic=111711|LinkText=kleines Projekt}} geworden: Die Sonos Umgebung mit Hilfe von sonos2mqtt als generisches MQTT2_DEVICE komfortabel in FHEM einzubinden.

Mit Hilfe von ein paar Templates ist die grundlegende Einbindung in FHEM nach einer kleinen Installation auf Systemebene schnell erledigt. Es läuft derzeit noch zahlreiche Entwicklung und Ideenfindung, die Fortschritte sind live im Thread oder [[Sonos2mqtt|konsolidiert im Wiki]] zu finden.

=== Setup im System ===
Für dies Funktion wird der nodejs Server [https://github.com/svrooij/sonos2mqtt sonos2mqtt] benötigt. Entweder installiert man den lokal, irgendwo im Netzwerk oder nutzt den [[MQTT2-Module - Praxisbeispiele#Verwendung des Docker Containers|Docker Container.]]

Der nodejs Server sonos2mqtt kann aus Sicht von FHEM irgendwo im Netzwerk stehen - aber er muss im gleichen Netzwerk wie die Sonosplayer stehen. Das UPNP Sonosnetzwerk funktioniert nicht über Netzwerksegmente hinweg.

Eine Beschreibung aller Startparameter für sonos2mqtt findet man [https://svrooij.github.io/sonos2mqtt in der offiziellen Doku].

Erreicht der nodejs Server sonos2mqtt den MQTT Server nicht über - default: localhost, Port 1883, keine Anmeldung" - muss der Parameter --mqtt gesetzt werden!

Beispiele:
:<code>--mqtt mqtt://myuser:the_secret_password@192.168.0.3:1800</code> # alles gesetzt
:<code>--mqtt mqtt://192.168.0.3:1800</code> # IP Adresse und Port gesetzt, keine Anmeldung am MQTT Server
:<code>--mqtt mqtt://192.168.0.3</code> # IP Adresse gesetzt, Port ist Standard 1883

Erfolgt der Start mit pm2, werden die Parameter mit einem ''zusätzlichen'' doppelten Bindestrich (--) hinter dem nodejs Modul übergeben.

Beispiel:
<syntaxhighlight lang="perl">
pm2 start sonos2mqtt -- --mqtt mqtt://myuser:the_secret_password@192.168.0.3:1800
</syntaxhighlight>

'''Lokales Setup'''

Voraussetzung: nodejs und pm2 ist installiert und für alle Benutzer verfügbar. <syntaxhighlight lang="bash">
sudo npm install -g sonos2mqtt
</syntaxhighlight>
Je nach Entwicklungsstand sind auch Betaversionen verfügbar. Für aktuelle Betaversionen wird dieser Zusatz beim Setup verwendet. -> sonosmqtt@3.1.0-beta.1

Wird der sonos2mqtt Server auf einer anderen Maschine eingerichtet, ist der Start entsprechend diesem Absatz [[MQTT2-Module - Praxisbeispiele#Autostart von sonos2mqtt im System mit pm2 .28Alternative.29|Autostart von Sonos2mqtt im System mit pm2]] einzurichten.

=== Setup in FHEM ===
Man definiert lediglich ein Bridge Device, der Rest wird automatisch erledigt.

Voraussetzung:
* autocreate im System ist aktiv.
* Der verwendete MQTT2_SERVER steht auf '''autocreate simple''' (default/Standard).
* Templates aktuell - FHEM uptodate oder bei Bedarf in der FHEM Kommandozeile aktualisieren:
<pre>
{ Svn_GetFile("FHEM/lib/AttrTemplate/mqtt2.template", "FHEM/lib/AttrTemplate/mqtt2.template", sub(){ AttrTemplate_Initialize() }) }
</pre>
Bei der Anwendung des Templates für die Bridge wird das Attribut devicetopic ausgelesen oder auf default sonos gesetzt!

Wird ein anderer Devicetopic verwendet, muss der bei der Anlage der Bridge gesetzt werden!

Diese Zeilen einzeln in der FHEM Kommandozeile oder als Block in der Raw Definition. <syntaxhighlight lang="perl">
define SonosBridge MQTT2_DEVICE
attr SonosBridge room MQTT2_DEVICE
set SonosBridge attrTemplate sonos2mqtt_bridge_comfort
</syntaxhighlight>
Das Template sonos2mqtt_bridge_comfort:
* setzt das Template sonos2mqtt_bridge auf das Device,
* lädt die Datei 99_sonos2mqttUtils.pm aus dem contrib Ordner nach,
* definiert ein notify, dies erledigt im weiteren Betrieb die automatische Konfiguration der automatisch erzeugten MQTT2_DEVICEs.
** mit dem Template sonos2mqtt_speaker (das Template kann auch manuell auf vorhandene Player angewendet werden, die automatische Erzeugung der Player wird aber empfohlen)
** Ermittelt Detailinformation des jeweiligen Players (vor allem IP Adresse und Modelnumber)
** Lädt die Sonosgeräte Icons von den UPNP Devices herunter
** erweitert das setList input Kommando um den TV Eingang (HDMI, spdif) bzw. Line_IN Eingang falls vorhanden (Modelnumber)
* Die Player werden automatisch einzeln erzeugt wenn sie mqtt Nachrichten senden (Play/Stop) oder (alle sofort) wenn der sonos2mqtt Server gestartet wird.

==== Wozu dient die Bridge? ====
Sie stellt ein paar wesentliche Funktionen zu Verfügung
# Auffangen von nicht benötigten MQTT Nachrichten.
# Erzeugung/Weiterleitung von Nachrichten für die einzelnen Player - damit auch die Erzeugung von separaten Playern nach dem Schema MQTT2_RINCON12345678901234567.
# Statusanzeige sonos2mqtt als Reading connected (0 offline, 1 connected, 2 Player connected).
Sie kann zusätzlich als zentrales Device verwendet werden, um die Sonos Umgebung abzubilden, z.B. Readings für Favoriten u.ä.

==== Start sonos2mqtt lokal ====
Der Start / Stop des sonos2mqtt Servers innerhalb von FHEM ist nur lokal simpel möglich. Ist der Server irgendwo im Netzwerk oder im Docker Container, muss man andere Möglichkeiten finden. Der Neustart aus FHEM ist zwar praktisch, aber nicht erforderlich.

Wird eine existierenden Sonos Landschaft inhaltlich verändert (Player dazu/weg), muss der Server neu gestartet werden. Werden Player temporär abgeschaltet, merkt das der Server nach einer Zeit selbst, oder man forciert dies mit einem CheckSubscription an der Bridge.

Soll das Modul sonos2mqtt mit seinen default Einstellungen gestartet werden, genügt dieser kurze Befehl (in der FHEM Kommandozeile):
<syntaxhighlight lang="bash">
"pm2 start sonos2mqtt"
</syntaxhighlight>
Tipp: Verwendet man anstatt "Befehl" den Syntax {qx(Befehl)} in der FHEM Kommandozeile, wirkt der Befehl zwar blockierend aber die Ausgabe erfolgt im Browser und nicht im Logfile. Mit dem Parameter -s erfolgt keine Ausgabe.

==== Autostart von sonos2mqtt mit FHEM ====
Der Code startet sowohl das sonso2mqtt Modul sofort und implementiert ein notify für den zukünftigen automatischen Start beim Start von FHEM.
<syntaxhighlight lang="perl">
define n_pm2_sonos notify global:INITIALIZED|n_pm2_sonos:start "pm2 -s start sonos2mqtt"
trigger n_pm2_sonos start
</syntaxhighlight>

=== Autostart von sonos2mqtt im System mit pm2 (Alternative) ===
Der obige Code startet das sonos2mqtt nodejs Modul mit pm2 beim Start von FHEM. Sollte das nicht funktionieren oder nicht ins gesamte Konzept passen (weil z.B. mehrere nodejs Module geladen werden) kann der automatische Start direkt im System erfolgen. Zunächst dafür das oben eventuell schon definierte notify löschen!<syntaxhighlight lang="perl">
delete n_pm2_sonos
</syntaxhighlight>Der Start des Modul muss nicht mit erhöhten Rechten geschehen! Im Terminal folgendes eingeben (unter dem angemeldeten Benutzer wird sonos2mqtt später immer gestartet):<syntaxhighlight lang="bash">
pm2 start sonos2mqtt
pm2 startup
</syntaxhighlight>
Der letzte Befehl "redet", d.h. es gibt eine Ausgabe in der Art:
<syntaxhighlight lang="bash">
[PM2] To setup the Startup Script, copy/paste the following command:
sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u pi --hp /home/pi
</syntaxhighlight>
Man tut einfach genau das, was dasteht: die letzte Zeile kopieren und wieder einfügen und ausführen. Danach muss man die Konfiguration von pm2 noch sichern:
<syntaxhighlight lang="bash">
pm2 save
</syntaxhighlight>

=== Verwendung des Docker Containers ===
Ergänzend zur [https://svrooij.io/sonos2mqtt/getting-started.html#run-sonos2mqtt-in-docker Original Doku:]

Beim Container findet die Konfiguration der Verbindung zum FHEM in den Environment Variablen statt:
<syntaxhighlight lang="perl">
environment:
- SONOS2MQTT_DEVICE=192.168.56.207 # hier muss einer der Sonos Lautsprecher stehen
- SONOS2MQTT_MQTT=mqtt://192.168.56.121:1883 # mqtt2_server FHEM, erweiterter Syntax siehe oben
- SONOS_LISTENER_HOST=192.168.56.121 # Docker host IP
</syntaxhighlight>

=== Sonos2mqtt mit mehr Komfort ===
Im Wiki Artikel [[Sonos2mqtt]] geht es weiter.

== Owntracks GPS Tracking in FHEM über MQTT - Cloud ==
Das hier gezeiget Beispiel verwendet eine MQTT Instanz im Internet, die mit einem MQTT2_CLIENT angebunden wird. Da wenig Traffic benötigt wird, genügt z.B. eine kostenfreie Instanz z.B. bei myqtthub (Stand. Dezember 2020)

Alternativ kann man einen MQTT2_SERVER auch direkt verfügbar machen, wenn man sich sicher ist was man da tut! Siehe {{Link2Forum|Topic=99666|Message=1028576|LinkText=diesen Forenbeitrag}}. Das Bridge Device wird dabei genau so benötigt, nur der IODev ist dann der MQTT2_SERVER.

=== owntracks auf dem Smartphone konfigurieren ===
Menü / Einstellung / Verbindung

Dort sind insgesamt 4 Registerkarten mit Werten zu füllen (Beispiel):
* Modus -> MQTT
* Hostname ->
** Hostnamen: host.cloud.com
** Port: 8883
** ClientID: ID vom Provider
** WebSockets (nicht nutzen)
* Identifikation ->
** Benutzername: user-name
** Passwort: user-password
** GeräteID: mi6 (erscheint in FHEM im Device Namen verwendet)
** TrackerID: hk (nur zweistellig, erscheint als ID in der owntracks Karte)
* Sicherheit ->
** TLS aktivieren
=== Definition in FHEM ===
Der MQTT2_CLIENT wird so eingerichtet, man braucht eine andere ClientID als auf dem Smartphone! Stimmt alles sollte das Gerät sofort open anzeigen.<syntaxhighlight lang="perl">
MQTT2_CLIENT einrichten, autocreate simpel
define mqtt2Cloud MQTT2_CLIENT host.cloud.com:8883
attr mqtt2Cloud SSL 1
attr mqtt2Cloud autocreate simple
attr mqtt2Cloud clientId fhem1
attr mqtt2Cloud room MQTT2_IO
attr mqtt2Cloud username user-name
set mqtt2Cloud password user-password
</syntaxhighlight>Für die automatische Erzeugung der Trackergeräte in FHEM richtig man zuerst ein Bridge Device ein:<syntaxhighlight lang="perl">
define MQTT2_Cloud_bridge MQTT2_DEVICE
attr MQTT2_Cloud_bridge IODev mqtt2Cloud
attr MQTT2_Cloud_bridge autocreate 1
attr MQTT2_Cloud_bridge room MQTT2_DEVICE
</syntaxhighlight>Dies wird entweder mit dem Template allgemein konfiguriert<syntaxhighlight lang="perl">
set MQTT2_Cloud_bridge attrTemplate MQTT2_CLIENT_general_bridge
</syntaxhighlight>oder manuell nur für owntracks eingerichtet<syntaxhighlight lang="perl">
attr MQTT2_Cloud_bridge bridgeRegexp owntracks/[^/]+/([^/:]+).* "owntracks_$1"
</syntaxhighlight>MQTT2 Geräte für owntracks werden jetzt automatisch mit dem Namen MQTT2_owntracks_<GeräteID> erzeugt. Diese werden einfach mit dem Template owntracks_device fertig konfiguriert. Bei einem IOS Gerät kann man danach noch das Template owntracks_device_IOS als Erweiterung anwenden.

==== Anwesenheitserkennung ====
Die Anwesenheit kann im owntracks Device direkt für die selbst definierten Plätze abgelesen werden: entweder steht im reading place der jeweilige Ort oder away. Um hier noch eine gewisse Einheitlichkeit in der Verwendung zu bekommen kann man ein PRESENCE Device verwenden: <syntaxhighlight lang="perl">
define OT_Mi6 PRESENCE event MQTT2_owntracks_mi6:place:.away MQTT2_owntracks_mi6:place:.<Home>
</syntaxhighlight>Im Move Modus erfolgt die Erkennung sehr schnell und damit einige Sekunden eher als eine BT Erkennung im Haus - der Akkuverbrauch steigt enorm. Im Significant Modus kann es schon mal ein paar Minuten dauern - ein relevanter Akku Verbrauch ist nicht erkennbar.

== Owntracks GPS Tracking in FHEM direkt an den eigenen Fhem-Server ==
Dieses Beispiel beschreibt den direkten MQTT2 Zugang wobei das IODev dann der MQTT2_SERVER ist. Hierzu bitte {{Link2Forum|Topic=99666|Message=1028576|LinkText=diesen Forenbeitrag}} lesen.

=== SSL - Zertifikate fuer fhem erstellen. ===
Zunächst erstellen wir fuer den MQTT - Server CA zertifizierte SSL Zertifikate. Diese sind identisch mit den SSL - Zertifikaten, welche man evtl. schon fuer den SSL - Zugang seines FHEMWEB - Device erstellt hat.

Hat man den FHEMWEB schon mit eiem SSL Zertifikat (http'''s'''://) abgesichert, muss man daraus nur noch den .p12 - Container erstellen.

Hat man den FHEMWEB noch nicht abgesichert (http://), dann wir es höchste Zeit!

Für die Erstellung dieser SSL Zertifikate folgt dem Wiki-Beitrag [[FHEM mit HTTPS SSL-Zertifikat und eine eigene Zertifizierungsstelle]].

Die darin beschriebenen Dateien, das cacert.pem sowie den server.p12 - Container müsst ihr nun an euer Mobiltelefon senden.

=== Definition in FHEM ===
Der MQTT2_Server wird wie folgt eingerichtet.<syntaxhighlight lang="perl">
define myMQTT2Server_extern MQTT2_SERVER IPV6:1884 global
attr MQTTBroker_extern SSL 1
attr MQTTBroker_extern autocreate complex
attr MQTTBroker_extern event-on-change-reading .*
attr MQTTBroker_extern group MQTT2
attr MQTTBroker_extern icon mqtt_broker
attr MQTTBroker_extern room MQTT2
</syntaxhighlight>

Der MQTT2_Server wird zusätzlich über "allowed" abgesichert:<syntaxhighlight lang="perl">
define allowed_MQTT2Server_extern allowed
attr allowed_MQTT2Server_extern DbLogExclude .*
attr allowed_MQTT2Server_extern group MQTT2
attr allowed_MQTT2Server_extern room MQTT2
attr allowed_MQTT2Server_extern validFor myMQTT2Server_extern
</syntaxhighlight>Jetzt vergeben wir noch einen Usernamen und ein Passwort für dieses "allowed" - Device<syntaxhighlight lang="perl">
set allowed_MQTT2Server_extern basicAuth MyMQTT2Username MyMQTT2Password

</syntaxhighlight>Denkt bitte daran einen eigenen Usernamen und ein eigenes langes, kompliziertes Passwort zu verwenden. Vorsicht bei Sonderzeichen!

=== Port-Freigaben im Router ===
An dieser Stelle müssen wir den Port 1884 in den Internet - Freigaben eures Routers freigeben.

Bei der Fritz!Box wird dies beispielsweise unter Internet -> Freigaben -> Port-Freigaben gemacht. Die Details hierzu entnehmt bitte der Bedienungsanleitung eures Routers.

Wichtig ist dabei, das ihr das Protokol "TCP" verwendet und der Port 1884 extern nach Port 1884 intern an die IP - Adresse des jeweiligen fhem-Servers übermittelt wird.

=== owntracks auf dem Smartphone konfigurieren ===
Menü / Einstellung / Verbindung

Dort sind insgesamt 4 Registerkarten mit Werten zu füllen (Beispiel):
* Modus -> MQTT
* Hostname ->
** Hostnamen: subdomain.dyndns.com
** Port: 1884
** ClientID: Vorname_Nachname
** WebSockets (nicht nutzen)
* Identifikation ->
** Benutzername: MyMQTT2Username
** Passwort: MyMQTT2Password
** GeräteID: mi6 (erscheint in FHEM im Device Namen verwendet)
** TrackerID: hk (nur zweistellig, erscheint als ID in der owntracks Karte. Empfehlung: Die Initialien verwenden.)
* Sicherheit ->
** TLS aktivieren
** CA-Zertifikat: cacert.pem
** Client-Zertifikat: server.p12
** Passwort fuer Client-Zertifikat: Passwort für den server.p12 - Container

Wenn alles richtig gemacht wurde, dann erstellt das myMQTT2Server_extern - Device automatisch ein neues Device für jede owntracks-App, die sich an dem myMQTT2Server_extern - Device meldet.

Übrigens: Will man seine gesamte Familie ebenfalls über owntracks tracken, so muss man in den jeweiligen APPs nur die Werte für ClientID, GeräteID und TrackerID individuell gestalten.

An den fhem- Einstellungen müssen keine weiteren Änderungen vorgenommen werden.
== Allgemeine Hinweise ==
=== MQTT2_SERVER und MQTT2_CLIENT für Debugging nutzen ===
Nutzt man das rawEvents-Attribut am MQTT2-IO<ref>z.B. <code>attr MQTT2_FHEM_Server rawEvents .*</code>, der regex-Filter kann wie üblich angepasst werden</ref>, kann man den Datenverkehr des Servers am Event-Monitor mitschneiden. Dies ist insbesondere für unbekannte Geräte nützlich, deren Topic- und Payload-Struktur noch nicht bekannt ist.
Um den kompletten MQTT Datenaustausch mitzuschneiden, kann man mit <code>attr mqtt2_server verbose 5</code> auch alles ins FHEM-Log schreiben lassen.

=== autocreate funktioniert anscheinend nicht? ===
In der Regel wird bei neu eingehenden MQTT-Messages über ''autocreate'' ein neues Device erstellt, wenn Nachrichten von einem bisher unbekannten Gerät kommen. Geschieht dies nicht, sollten folgende Punkte geprüft werden:
# (nur bei MQTT2_SERVER:) Der Client muss eine ClientID angeben, diese darf nicht den defaults von ''mosquito_sub'' entsprechen.
# Ein allgemeines {{Link2CmdRef|Anker=autocreate|Lang=en|Label=autocreate}}-Device (''TYPE=autocreate'') muss vorhanden und aktiv sein.
# ''autocreate'' am IO muss eingeschaltet sein, was für MQTT2_SERVER bedeutet, dass es nicht auf "0" stehen darf (hier ist dann ''simple'' die aktive Voreinstellung), für MQTT2_CLIENT sollte ebenfalls ''simple'' verwendet werden; dies muss hier allerdings explizit gesetzt werden.

Wird dann immer noch kein Device erstellt, gibt es in aller Regel ein Device, das bereits einen entsprechenden Eintrag in der readingList enthält, oder es sind keine Nachrichten eingegangen. Überprüfen Sie daher dann ggf. die Einstellungen am Client-Gerät (z.B. im Web-Interface des Shelly oder Tasmota-geflashten ESP8266).

Das ''autocreate'' am Device schließlich bestimmt, ob die ''readingsList'' erweitert werden darf, wenn Informationen über bisher nicht über die readingList abgedeckte Topics empfangen werden und vom MQTT2-IO als zu diesem Device/ClientID gehörend identifiziert wurden.

=== attrTemplate ===
{{Randnotiz|RNTyp=Info|RNText=Die per attrTemplate jeweils erzeugten Konfigurationen sind Einrichtungsbeispiele, die v.a. eine in sich konsistenze Zusammenstellung der verschiedenen Attribute enthalten. Es steht jedem User frei, diese Ausgangsbasis dann nach seinem Belieben zu ändern. Spätere Änderungen des verwendeten attrTemplate wirken sich nicht automatisch auf die durch frühere Versionen oder den User nachkonfigurierte Geräte aus! Da es vorkommen kann, dass sich die per MQTT übermittelten Daten und Topics ändern, wenn z.B. eine firmware aktualisiert wurden, kann dies Anpassungen am jeweiligen Template erforderlich machen. Grundsätzlich sollen die per attrTemplate für MQTT2_DEVICE verfügbaren attrTemplate jeweils für die aktuellste verfügbare stabile firmware-Version passen.}}
Zur Konfiguration von MQTT2_DEVICE-Geräten kann die Funktion ''[[AttrTemplate|attrTemplate]]'' genutzt werden.
Die Anwendung für MQTT2_DEVICE ist [[MQTT2 DEVICE#attrTemplate|hier]] beschrieben.

{{Hinweis|In einigen Fällen kann es vorkommen, dass die template-Bezeichnung zwischenzeitlich geändert wurde. Seit 21.09.2019 erfolgt die Sortierung der auswählbaren templates nicht mehr nur nach den Namen, so dass die entsprechenden Namensbestandteile entfallen sind, die einer besseren Sortierung dienten.}}

=== attrTemplate: Es werden nicht alle templates angezeigt ===
Siehe Beitrag [[AttrTemplate#Warum finde ich das Template xyz nicht.3F|AttrTemplate: Warum finde ich das Template xyz nicht.]]

=== attrTemplate und Sprachsteuerung ===
Konfiguriert man MQTT2_DEVICE-Geräte mit attrTemplate, werden in der Regel auch direkt die für die Sprachsteuerung der Geräte erforderlichen Attribute mit gesetzt. Weiterführende Hinweise sind auch zu diesem Teilaspekt von ''[[AttrTemplate|attrTemplate]]'' dem betreffenden Hauptartikel zu entnehmen.

=== bridgeRegexp ===
[[Datei:Mqtt2 server.png|300px|thumb|left|Logische Verortung der bridgeRegexp-Angaben]]{{Randnotiz|RNTyp=y|RNText=Beachten Sie, dass aufgrund des geschilderten Prinzips eine Änderung einer bridgeRegexp bei einem Gerät auch dazu führt, dass alle Readings eines Geräts und alle readingList-Einträge gelöscht werden.}}Üblicherweise werden alle Informationen, die aus einer Quelle stammen auch '''''einem''''' ''MQTT2_DEVICE'' zugeordnet, wobei im Falle des dort nicht aktivierten autocreate-Attributs entsprechende readingList-Einträge erzeugt werden. In dem nebenstehenden Schaubild wären dies die Geräte ''A'' bis ''D''. Das '''Attribut''' ''bridgeRegexp'' kann dazu genutzt werden, um neue, bisher unbekannte Topic-Strukturen im Rahmen des autocreate-Vorgangs anders zu strukturieren. Diese werden dabei im Ergebnis einem '''anderen Device''' (das ggf. erst erstellt wird) zugeschlagen, sollte eine zu der topic-Struktur passende regex in diesem Attribut gesetzt sein. Für dessen CID und die Bildung des Names wird die im 2. Teil jedes Eintrags als ''newClientId'' hinterlegte Angabe verwendet. In nebenstehendem Schaubild ist dies exemplarisch für die Gerätegruppe ''D'' mit dem ''bridge''-Device ''D'' und dessen ''Satelliten'' ''D1'' bis ''D4'' dargestellt.
Dementsprechend sind in den hier aufgeführten Beispielen ''bridgeRegexp''-Attribute immer dort zu finden, wo ein Gerät oder Dienst dazu dient, mit weiteren, ggf. auf andere Weise kommunizierende Geräte oder Baugruppen zu kommunizieren, wie z.B. für über hier dargestellten ''zigbee2mqtt'' oder ''zigbee2tasmota''. Ein Sonderfall hierbei ist das template ''MQTT2_CLIENT_general_bridge'' zur Verwendung mit dem [[MQTT2_CLIENT#Anwendung|MQTT2_CLIENT]], denn aus dessen Sicht stammen alle Informationen aus derselben Quelle, nämlich z.B. dem ''mosquitto''-Server und würden sonst alle ein und demselben MQTT2_DEVICE zugewiesen.

=== Ständig neue Devices? ===
MQTT2_SERVER kann zwischen verschiedenen Geräten auch anhand der ClientID unterscheiden. Für jedes neu erkannte Gerät wird auch ein eigenes MQTT2_DEVICE angelegt. Abhilfemaßnahmen:
==== Vergabe einer ClientID ====
Die meisten MQTT-fähigen Geräte enthalten Optionen zur Vergabe einer eindeutigen ClientID (siehe das Beispiel des zigbee2mqtt-Dienstes oben).
Wird keine ClientID vergeben, verwenden manche Clients für jede Verbindung wieder neue ID's. Es wird empfohlen, möglichst von diesen Einstelloptionen Gebrauch zu machen.

==== Löschen der ClientID aus der readingList usw. ====
Ist dies nicht möglich oder erwünscht, kann man auch die ClientID aus den readingList-, setList- und getList-Attributen entfernen. Dies ist jedenfalls solange unschädlich als nicht mehrere Geräte identische Topic-Pfade verwenden (daher die Empfehlung, insbesondere bei Tasmota-Geräten den ''default'' "sonoff" zu ändern).
Beispielsweise wäre <code>attr Milight_Bridge readingList milight_hub_1370325:milight/LWT:.* {json2nameValue($EVENT) }</code> zu ändern in <code>attr Milight_Bridge readingList milight/LWT:.* {json2nameValue($EVENT) }</code>
Die über ''attrTemplate'' verfügbaren Konfigurationen verwenden in der Regel keine ClientID's bzw. entfernen diese.

=== Wildcards in readingList und setList ===
Auch in readingList und in setList sollten sich sog. wildcards verwenden lassen. Die Vorgehensweise ist jedoch unterschiedlich:

In ''readingList'' werden normale regex-Ausdrücke verwendet. Ein Punkt steht daher z.B. für ein beliebiges Zeichen, alles zwischen zwei Topic-Tree-Elementen (getrennt typischerweise durch einen "/") kann man so schreiben: "[^/]+" (entspricht: "Mindestens ein Zeichen, das kein Schrägstrich ist"). Ergänzender Hinweis: Will man z.B. Informationen aus einem beliebigen Teil des Topic-trees extrahieren und als Reading-Namen verwenden, kann dies im Rahmen eines Perl-Aufrufs geschehen. Beispiele aus der mqtt2.template-file: OpenMQTTGateway_BT_scanner und OpenMQTTGateway_BT_gtag (letzteres überführt die Information, über welches Gateway bestimmte Informationen eingegangen ist jeweils in eigene Readings pro Gateway).

In ''setList'' gelten dagegen die wildcard-Konventionen aus der MQTT-Welt. Dort steht "+" für einen austauschbaren Teil des Topic-Trees (zwischen zwei Schrägstrichen). Anmerkung: Bitte vorher prüfen, ob es wirklich sinnvoll ist, derart unspezifische Publishes vorzunehmen. Meist gibt es "Gruppen-Topics", auf die mehrere Geräte eines bestimmten Typs hören bzw. man kann dies dort (in der firmware bzw. auf den Konfigurationsseiten der Geräte) einstellen.

=== Die JSON-Daten sollen ausnahmsweise nicht ausgepackt werden ===
In manchen Fällen ist das automatische Auspacken der JSON-Payload nicht erwünscht. In diesen Fällen kann man einfach den gewünschten Reading-Namen in die readingList eintragen, statt der Anweisung, den JSON an json2NameValue() zu übergeben. Aus
<pre>
attr MQTT_OwnTracks readingList owntracks/clouduser/mi6:.* { json2nameValue($EVENT) }\
owntracks/clouduser/mi6/waypoints:.* { json2nameValue($EVENT) }\
owntracks/clouduser/mi6/event:.* { json2nameValue($EVENT) }
</pre>
wird dann:
<pre>
attr MQTT_OwnTracks readingList owntracks/clouduser/mi6:.* json_mi6\
owntracks/clouduser/mi6/waypoints:.* json_waypoints\
owntracks/clouduser/mi6/event:.* json_event
</pre>
Erforderlichenfalls kann man die Einträge auch doppelt erstellen, um sowohl den JSON wie auch die ausgepackten Readings zu erhalten.

=== Die JSON-Daten vor dem auspacken manipulieren ===
Aus diversen Gründen kann es zweckmäßig sein, einen bestimmten Wert der JSON-Payload zu ignorieren.
Z.B. sendet ein Client statt eines Messwertes die Info "bad". Dieser Fehlerwert soll aus der JSON-Payload "ausgefiltert" werden:
<pre>
attr DEVICE readingList <your topic>:.* { my $rets = json2nameValue($EVENT,'',$JSONMAP);; my %cleaned = map { $_,$rets->{$_} } grep { 'bad' ne $rets->{$_} } keys %{$rets};; return \%cleaned }
</pre>

Oder auch einen Wert umzubenennen wenn die JSON-Payload nur ein Objekt beinhaltet:
<pre>
attr DEVICE readingList <your topic>:.* {my %h=(0=>'SofortLaden',1=>'MinPV',2=>'NurPV',3=>'Stop',4=>'Standby');; return {ChargeMode=>$h{$EVENT}}}
</pre>

=== Unnötige Konfigurationsinformationen verwerfen ===
Siehe Einleitung und den [[MQTT2_CLIENT#ignoreRegexp|ignoreRegexp-Abschnitt zu MQTT2_CLIENT]].

=== Weiterführende Themen ===
==== Verbinden mehrerer FHEM-Instanzen über MQTT ====
Wie im Hauptartikel zu [[MQTT#Kommunikation zu sonstigen FHEM-Geräten über MQTT|MQTT]] erläutert, gibt es mehrere Varianten, wie man mit Hilfe von FHEM aus Events an beliebigen Geräten MQTT-Messages erzeugen kann. So kann man z.B. Messdaten eines Systems über ein ''notify'' iVm. einer einfachen ''publish''-Anweisung an ein zweites FHEM schicken, das diese Daten dann z.B. mit Hilfe der MQTT2-Module auswerten kann.
Damit dabei Nachrichten unterschiedlicher Quellen auch als getrennte Readings bzw. ggf. auch gesonderten MQTT2_DEVICE-Instanzen zugeordnet werden, sollte man entsprechende Topic-Strukturen wählen, die dann auch mit Hilfe einer geeigneten ''bridgeRegexp'' automatisiert ausgewertet werden kann, siehe z.B. dieser {{Link2Forum|Topic=107145|LinkText=Forumsthread}}:
attr MQTT2_myMqttServer bridgeRegexp \
SmartHome/MqttGenericBridge2/([A-Za-z0-9]*)/.*:.* "mgb2_$1"
Dabei werden die betreffenden Informationen der entfernten FHEM-Instanz alle nach dem Schema ''SmartHome/MqttGenericBridge2/<Device-Name>/<Reading-Name>'' versendet.

==== Umstellung von MQTT_DEVICE (und Derivaten wie XiaomiMQTTDevice) zu MQTT2_DEVICE ====
Wer beabsichtigt, von der Implementierung MQTT+MQTT_DEVICE zu MQTT2-IO und MQTT2_DEVICE zu wechseln, sollte einige Punkte beachten. Viele diesbezügliche Fragen sind vor allem in {{Link2Forum|Topic=103762|LinkText=diesem Foren-Thread}}

näher erläutert.

== Links ==
* {{Link2Forum|Topic=91394|LinkText=Thread, aus dem diese Anleitung ursprünglich entstanden ist}}
* {{Link2Forum|Topic=91807|LinkText=Thread zum Tasmota-Device}}
* {{Link2Forum|Topic=97989|LinkText=Thread, aus dem diese Anleitung für den eBus ursprünglich entstanden ist}}
* {{Link2Forum|Topic=94495|LinkText=Neue templates einreichen}}
* {{Link2Forum|Topic=94494|LinkText=Fragen, Wünsche und Kritik zu mqtt2.template}}
* {{Link2Forum|Topic=116162|LinkText=Der MQTT-Workshop für MQTT2-Module}}

== Hinweise ==
<references />
[[Kategorie:HOWTOS]]
[[Kategorie:MQTT]]
[[Kategorie:IP Components|IP Komponenten]]
[[Kategorie:Other Components]]
[[Kategorie:Interfaces]]

AttrTemplate

2024-06-26T13:56:59Z

Beta-User: /* Einführung */

{{SEITENTITEL:AttrTemplate}}
{{Infobox Modul
|ModPurpose=Hilfsmodul bzw. Befehl, das/der die Einrichtung von Geräten erleichtern kann
|ModType=cmd
|ModCmdRef=
|ModForumArea=Automatisierung
|ModTechName=AttrTemplate.pm
|ModOwner=rudolfkoenig ({{Link2FU|8|Forum}} / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}

AttrTemplate ist ein Hilfsmodul, mit dessen Hilfe Geräte auf einfache Weise mit einer passenden Konfiguration versehen lassen.

Das Modul ''AttrTemplate'' ist indirekt Bestandteil der SetExtensions, das Modul kann von Modulautoren aber auch ohne diese mit in beliebige (Geräte-) Module mit eingebaut werden. Über diesen Mechanismus ist der Befehl ''attrTemplate'' in einer Vielzahl von Modulen verfügbar.

==Einführung==
Ziel von ''attrTemplate'' ist es, den Nutzer bei der Konfiguration von Geräten zu unterstützen, indem vorrangig entsprechende [[Attribute]] gesetzt werden. Grundsätzlich ist es jedoch auch möglich, beliebige FHEM-Befehle oder Perl-Code im Rahmen von attrTemplate auszulösen.
Teilt man entsprechende ''templates'', sollte jedoch deutlich darauf hingewiesen werden, wenn ein Template etwas anderes tut als nur Attribute zu setzen, also insbesondere dauerhafte Konfigurationsänderungen in der Hardware selbst vorzunehmen.

Um Ihnen die Auswahl zu erleichtern, kann
* mit <code>set <Device-Name> attrTemplate ?</code> eine Liste der vorhandenen Templates samt kurzer Beschreibung aufgerufen werden.
* in der Detailansicht der Geräte über das Dropdownfeld ein ''template'' ausgewählt werden. Nun erhält man unmittelbar unter dem ''set''-Befehl ebenfalls entsprechende weitere Informationen sowie den Code des ''template'' angezeigt, der bei Drücken auf ''set'' ausgeführt wird.
Hat man ein passendes ''template'' gefunden, wird mit <code>set <Device-Name> attrTemplate <template_name></code> angewendet, wodurch die entsprechenden, in dem ''template'' hinterlegten Kommandos ausgeführt werden.

{{Hinweis|Vor allem, wenn man ''attrTemplate'' für die Konfiguration von [[MQTT2_DEVICE]] verwendet, sollte man die '''default'''-Einstellungen für die Topic-Strukturen etc. nicht am Gerät ändern, da andernfalls die Automatismen ggf. nicht greifen und z.B. passende attrTemplate für das Device gar nicht angezeigt werden.}}

== Syntax ==

{{Link2Forum|Topic=104804|Message=988100|LinkText=Hier}} und {{Link2Forum|Topic=99195|Message=925952|LinkText=hier}} hat Rudolf König die Syntax erläutert, die in den attrTemplate-Dateien verwendet werden können:
* leere Zeilen werden ignoriert
* Zeilen die mit # anfangen sind Kommentare (s.u. ''desc:'')
* Zeilen, die mit einem der folgenden Schlüsselwörter beginnen, werden speziell interpretiert: ''name: filter: prereq: option: par: desc: farewell: order:''
** '''name:''' Name des Templates, markiert gleichzeitig das Ende des vorherigen Templates
** '''filter:''' devspec2array Ausdruck, der beschreibt, für welche Geräte dieses Template anwendbar ist. Wird erst beim "set ?" ausgeführt.
** '''prereq:''' ist entweder ein Perl-Ausdruck {}, oder ein ''devspec2array'', was genau ein Gerät spezifiziert. Falls mindestens ein prereq existiert, was nicht zutrifft, wird das betroffene Template aus dem Speicher entfernt. Die Auswertung erfolgt beim FHEM Start oder bei {AttrTemplate_Initialize()}
** '''option:''' Syntax entspricht prereq, wird jedoch beim Einlesen des template Files ausgeführt. Falls nicht wahr ist, werden die darauffolgenden Zeilen des Template nicht ausgeführt. Ist für sowas wie "setze zusätzlich Attribut XY falls die Installation HomeAssistant kennt" gedacht.
** '''par:''' kann mehrfach vorkommen, Syntax: <code>par:<ParameterName>;<Kommentar>;<Perl-Code></code>. ''Perl-Code'' versucht den Wert zu finden, falls nicht möglich (''return undef''), wird ein Dialog mit "Replace" angezeigt (bzw. Usage:... im telnet). ''ParameterName'' wird in jeder Befehlzeile ersetzt mit dem Wert. Zusätzlich: ''DEVICE'' wird mit dem Namen des Gerätes ersetzt, wird ''DEVICE'' (z.B. für Modulnamen) als Text benötigt, muß es ''escaped'' werden (z.B. MQTT2_\DEVICE).
** '''pardefault:''' Wie '''par:''', allerdings wird ein ggf. ermittelter Wert nicht automatisch übernommen, sondern als Vorgabe in einem Dialogfeld zur Bestätigung (bzw. Änderung) durch den User angezeigt.
** '''desc:''' Kommentar fuer <code>set attrTemplate help ?</code>. Die letzte Zeile mit # vor ''name:'' wird als ''desc:'' interpretiert, falls kein ''desc:'' vorhanden ist.
** '''farewell:''' wird zum Schluss als Dialog (oder Text in telnet) angezeigt, falls beim Anwenden der Befehle kein Fehler aufgetreten ist.
** '''order:''' bestimmt die Reihenfolge, in der die Templates im [[FHEMWEB|Webfrontend]] angezeigt werden; falls nicht vorhanden, wird ''name:'' genommen.
** '''loop:''' ermöglicht es, die zwischen ''loop:<parameter-name>:<wert1>:<wert2>:....'' und ''loop:END'' stehenden Zeilen wiederholt auszuführen und dabei bei jedem Durchlauf die als ''<parameter-name>'' bezeichnete Variable durch die darauffolgende Werteliste (getrennt per Doppelpunkt) zu ersetzen.
* alle anderen Zeilen werden als auszuführende Befehle interpretiert, wenn man <code>set <Device-Name> attrTemplate TemplateName</code> ausführt.

==Eigene Templates entwickeln==
Wer plant, mehrere gleichartige Geräte anzulegen, aber andere Einstellungen zu wählen, als sie in den vorhandenen Templates enthalten sind, kann hierfür ebenfalls die attrTemplate-Funktion mit eigenen Templates nutzen. Hierfür können die vorhandenen Templates der im Unterverzeichnis ''fhem/FHEM/lib/AttrTemplate'' zu findenden Dateien als Basis dienen. Ihre Templates speichern Sie einfach als neue Datei mit der Endung ''.template'' im selben Verzeichnis (auf Linux-konforme Zeilenumbrüche achten) und lesen diese mit <code>{ AttrTemplate_Initialize() }</code> neu ein. Danach können Sie diese direkt verwenden.

Haben Sie ein Template erstellt und möchten dieses teilen, erstellen Sie einfach einen Beitrag im entsprechenden Forenbereichen, für manche Module existieren auch spezielle Threads (siehe Linkliste unten)

=== Sprachsteuerung ===
Zur Einbindung von Sprachsteuerungslösungen ([[Siri|Siri,]] [[Alexa]] und [[Google Assistant FHEM Connect|gassistant]]) gibt es eine Reihe zentraler attrTemplates, die meist direkt aus anderen attrTemplates heraus aufgerufen werden. Es ist auch möglich, diese attrTemplate direkt aufzurufen, z.B. wenn man erst später eine Spracherkennungslösung eingebunden hat. Wegen der Namen der templates sollte man dazu direkt die betreffende attrTemplate-file ''[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/lib/AttrTemplate/speechrecogn.template speechrecogn.template]'' konsultieren, die Beschreibung, welches template für welche Funktionalität gedacht ist sowie eventuelle Parameter sind jeweils hinter dem ''desc:'' zu finden.

=== Spezielle Fragen zur Entwicklung neuer Templates ===
* Ersetzungen von Schlüsselbegriffen, die durch den AttrTemplate-Code aufgelöst bzw. durch entsprechende andere Werte ersetzt werden, (insbesondere von ''DEVICE'') kann man verhindern, indem man diese ''escaped''. Beispiel: Um im Ergebnis ein "MQTT2_DEVICE" zu erzielen, muß "MQTT2_\DEVICE" geschrieben werden.

==Warum finde ich das Template xyz nicht?==
In den dropdown-Auswahllisten entsprechender Geräte werden teils deutlich weniger Möglichkeiten angeboten, als in den attrTemplate-files aufgeführt sind. Gesteuert wird dies durch die bereits oben genannten Ausdrücke ''filter'' und ''prereq'':

=== filter ===
''filter'' bewirkt, dass das template schlicht nicht in der Auswahlliste erscheint, aber an sich geladen ist und über die Kommandozeile auch angewendet werden kann. Allerdings müssen Sie in diesen Fällen damit rechnen, dass mindestens einzelne Elemente zur Ausführung des template-Code nicht vorhanden sind, und Sie diese Parameter über ein Dialogfeld eingeben müssen.

Geladene attrTemplate werden angezeigt, wenn man
:<code>set <device> attrTemplate ?</code>
ausführt.

In der Regel ist es zu empfehlen, die in filter abgefragten Daten händisch einzupflegen, also z.B. bei einem Tasmota-MQTT2_DEVICE wenigstens das "LWT"-readingsList-Element anzugeben.

=== prereq ===
Trifft ein ''prereq'' nicht zu, wird das betreffende Template gar nicht geladen. Es erscheint dann weder bei Aufruf des "?", noch kann es über die Kommandozeile ausgeführt werden. In der Regel macht es auch wenig Sinn, ein template ausführen zu wollen, dessen Voraussetzungen nicht gegeben sind, etwa weil (noch) kein passendes Bridge-Gerät definiert ist.

=== Deaktivierung über ''global'' ===
Darüber hinaus kann das Modul insgesamt über folgende Einstellung deaktiviert werden:
<syntaxhighlight lang="perl">
attr global disableFeatures attrTemplate
</syntaxhighlight>
Dann werden insgesamt keine attrTemplates mehr geladen.

==Links==
* {{Link2Forum|Topic=93370|LinkText=Ankündigung des Moduls im Forum}}
* [[MQTT2_DEVICE#attrTemplate|Wiki zu attrTemplate und MQTT2_DEVICE]] - enthält auch Links zu speziellen Threads für bestimmte Device-Typen
* {{Link2Forum|Topic=94495|LinkText=Thread für getestete Vorschläge (MQTT2_DEVICE)}}.
* {{Link2Forum|Topic=94494|LinkText=Thread für Fragen und Anregungen (MQTT2_DEVICE)}}.
* {{Link2Forum|Topic=97694|LinkText=Thread für HTTPMOD}}.
<references />
[[Kategorie:FHEM-Verwendung]]
[[Kategorie:HOWTOS]]

Weekprofile

2023-05-17T08:59:47Z

Beta-User: fix commandref links

{{SEITENTITEL:weekprofile}}
{{Infobox Modul
|ModPurpose=Verwaltung von Wochenprofilen für Heizungssteuerung
|ModType=h
|ModForumArea=Frontends
|ModCmdRef=weekprofile
|ModTechName=98_weekprofile.pm
|ModOwner={{Link2FU|7869|Risiko}}
}}

Das Modul [[weekprofile]] stellt Funktionen zur Verwaltung von Wochenprofilen\Wochenplänen für Heizkörperthermostate zur Verfügung. Aktuell werden folgenden Systeme unterstützt:
* [[MAX]]
* [[HomeMatic]]
* CCU2 (experimentell)
* [[WeekdayTimer]] (ermöglicht seit 12/2019 indirekt die Steuerung von anderen Device-Typen wie [[Z-Wave]], [[MQTT2_DEVICE]] bzw. [[MQTT_DEVICE]], [[ZigBee]], ...)

Es ist möglich, verschiedene Wochenprofile anzulegen, zu kopieren, zu ändern und zu löschen. Außerdem können die erstellten Profile den entsprechenden Devices zugewiesen werden.

== Voraussetzung ==
Zum einwandfreien Betrieb des Moduls wird JSON benötigt. Dieses kann z.B. über folgenden Befehl installiert werden
:<code>sudo apt-get install libjson-pp-perl</code>

Seit SVN-Version: 21314 unterstützt Weekprofile [[configdb]]. Die Profil-\Konfigurationsdatei muss bei einem Update in configDB importiert werden.

== FHEMWEB Widget ==
[[Datei:Weekprofile_master.png|thumb|right|Widget Beispielansicht]]
Zur Bedienung des Moduls existiert ein passendes widget für FHEMWEB.
Alle notwendigen Aufgaben wie bspw. Kopieren, Bearbeiten, Zuweisen, etc. können über die FHEMWEB Oberfläche erfolgen.

Ein direkte Verwendung der Befehle für get und set ist somit nicht zwingend erforderlich.

== Betriebsarten ==
Das Modul besitzt drei unterschiedliche Betriebsarten, die im Folgenden beschrieben werden. Obwohl auch Mischformen möglich sind, sollte man sich der Übersichtlichkeit halber für eine Betriebsart entscheiden.

Bei allen Änderungen sollte man immer bedenken, dass die Änderungen an die entsprechenden Thermostaten übertragen werden müssen, was je nach Menge etwas Zeit in Anspruch nehmen kann.

=== Assoziiertes Master Gerät ===
Dieses ist der einfachste Betriebsmodus, bei dem jeder Definition genau ein Thermostat zugeordnet ist. D.h. entsprechend der Anzahl der Thermostaten, die man steuern möchte, benötigt man eine passende Anzahl von Weekprofile-Definitionen. Bei der Definition des Moduls wird das zu steuernde Thermostat direkt mit angegeben.

:<code>define <name> weekprofile <device></code>
Beispiel:
:<code>define EG_Bad_WEEKPROFILE weekprofile EG_Bad_THERMOSTAT_Climate</code>
'''Hinweis:''' 
Bei HomeMatic müssen die Kanäle "Clima" bzw. "_Climate" verwendet werden. 
Bei der Definition wird automatisch ein Wochenplan mit dem Namen 'master' angelegt.
Der Wochenplan entspricht dem im Device hinterlegtem Profil.

Dieser spezielle Masterplan kann nicht gelöscht werden, da er immer dem aktuellen Profil im Device entspricht.
Ändert man das Profil direkt über das Device, wird der Masterplan automatisch aktualisiert.

Wird der Masterplan über das Modul weekprofile geändert\gespeichert, wird das Profil automatisch zum assoziiertem Device übertragen.

Wird in dieser Betriebsart für einen Befehl kein spezielles Device angegeben, wird immer das assoziierte Device verwendet. So wird bspw. bei
:<code>set <name> send_to_device urlaub</code>
das Profil 'urlaub' an das bei define angegebene Thermostat übertragen.

==== Funktionen des Wigets ====
{| class="wikitable"
|-
! Button
! Funktion
|-
| Zahnräder
| Beabeitungsmodus öffnen; Auf der dann angezeigten Seite kann über "-->" der Plan eines Tages auf einen anderen kopiert werden.
|-
| 'DropDown'
| Profil für Ansicht/Bearbeitung auswählen
|-
| '+'
| Neues Profil durch Kopie erstellen
|-
| '-'
| Profil löschen
|-
| '-->'
| Profil an ein oder mehrere Thermostate übertragen, die nicht dem assoziierten Mastergerät entsprechen. Dabei bietet das Modul alle kompatiblen gefundenen Thermostaten automatisch zur Auswahl an.
|}

=== Standard Verwaltung ===
Diese Betriebsart ist für die einfache Verwaltung von Wochenplänen gedacht, welche dann an unterschiedliche Thermostate manuell übertragen werden können.
Für diese Betriebsart sollte kein assoziiertes Master Gerät bei define angegeben werden.
:<code>define <name> weekprofile</code>
In diesem Fall wird beim erstmaligen Anlegen ein Default-Profil mit dem Namen 'default' angelegt.
Dieses bildet die Grundlage zur Erstellung weiterer Pläne durch kopieren.
Existieren mindestens. 2 Profile, kann das Default-Profil gelöscht werden.
Die einzelnen Wochenpläne können mittels <code>send_to_device</code> an ein oder mehrere Thermostate übertragen werden.

==== Funktionen des Wigets ====
Siehe Betriebsmodus assoziiertes Master Gerät.

=== Topics ===
Dieser Betriebsmodus erlaubt es mit Hilfe von Topics oder Kategorien wie bspw. (Urlaub, Sommer, Winter, Party, etc.) komplexeren Verwaltung von Wochenplänen zu realisieren.
Dieses Feature wird mittels dem Atribute <code>useTopics</code> aktiviert.
Innerhalb eines Topics kann es mehrere Wochenpläne geben. Sinnvollerweise für jedes Thermostat ein Wochenplan.
Mit dem Befehl <code>restore_topic</code> kann man dann zwischen unterschiedlichen Kategorien wechseln. Die Wochenpläne werden automatisch an die Thermostate übertragen. Dazu muss im Thermostat ein User-Attribut 'weekprofile' mit dem Namen des verbundenen Wochenplans hinterlegt sein.

Bei der Verwendung von Topics wird beim erstmaligen Anlegen automatisch die Topic 'default' mit den Default-Wochenprofil 'default' angelegt.
In dieser Topic kann man beispielsweise Pläne ablegen, die bei mehreren Thermostaten oder anderen Kategorien verwendet werden sollen.

'''Wichtig:''' 
Bei der Verwendung von Topics, besteht der Profilname immer aus <code>Topicname:Planname</code> 
Wird kein Topicname angegeben, wird immer 'default' als Topicnamen verwendet.

==== Verwendung von Referenzen ====
Mittels Referenzierung kann man auf dieser Pläne verweisen und muss so nur einen Plan ändern, um gleich für eine Vielzahl von Thermostaten die Pläne zu ändern.
So könnte bspw. ''Sommer:Plan_WZ'' nur eine Referenz auf ''default:Fest_24h'' sein. 
Existiert ''default:Fest_24h'', wird der Verweis so angelegt:
:<code>set weekprf reference_profile default:Fest_24h Sommer:Plan_WZ</code>
Referenzen können nicht bearbeitet werden. Im Beispiel wäre der Plan ''Sommer:Plan_WZ'' nicht bearbeitbar. 

Für das Anlegen eines Wochenplans, der auf einen anderen referenziert, wählt man den Quellplan im Dropdown aus und erstellt dann einen neuen, indem man den entsprechenden Haken beim Erstellen aktiviert.

==== Funktionen des Wigets ====
{| class="wikitable"
|-
! Button
! Funktion
|-
| Zahnräder
| Beabeitungsmodus öffnen; Auf der dann angezeigten Seite kann über "-->" der Plan eines Tages auf einen anderen kopiert werden.
|-
| 'DropDown'
| Profil für Ansicht/Bearbeitung/Referenzierung auswählen
|-
| '+'
| Neues Profil durch Kopie erstellen
|-
| '-'
| Profil löschen
|-
| 'T'
| Topic aktiviert und die entsprechenden Wochenpläne an die Thermostaten übertragen.
|}

==== Beispiel ====
User-Attribut im Thermostat definieren:

MAX Thermostate:
:<code>define WT_Wohnzimmer MAX WallMountedThermostat 0d657f</code>
:<code>attr WT_Wohnzimmer userattr weekprofile</code>
:<code>attr WT_Wohnzimmer weekprofile Plan_WZ</code>

HomeMatic Thermostate:

Fügen Sie ein [[HM-CC-RT-DN Funk-Heizkörperthermostat]] über hmPairForSec hinzu (Beispiel DeviceName HM_123456)
:<code>attr HM_123456_Clima userattr weekprofile</code>
:<code>attr HM_123456_Clima weekprofile Plan_WZ</code>
Weiter wird angenommen, dass es die Topics Winter und Sommer mit jeweils einem Wochenplan Namens 'Plan_WZ' im Modul 'weekprf' gibt.
:<code>define weekprf weekprofile</code>
:<code>attr weekprf useTopics 1</code>

Die Abfrage mittels <code>get weekprf profile_names *</code> muss ergeben:
:''Winter:Plan_WZ,Sommer:Plan_WZ''

Wechselt man nun mit <code>set weekprf restore_topic Sommer</code> auf Sommer, wird der Plan ''Sommer:Plan_WZ'' an das Thermostat ''WT_Wohnzimmer'' übertragen.

== Befehle und Attribute ==
=== Modul Befehle: set ===
==== Wochenprofile kopieren ====
Siehe {{Link2CmdRef|Anker=weekprofile-set}}

==== Wochenprofile löschen ====
Siehe {{Link2CmdRef|Anker=weekprofile-set}}

==== Wochenprofile an ein Device übertragen ====
Siehe {{Link2CmdRef|Anker=weekprofile-set}}

==== Wochenprofile per Datei konfigurieren ====
Die Wochenprofile werden mit dem Befehl
:<code>set <name> profile_data <profilename> <json data></code>
angelegt/geändert (überschrieben). Die eigentlichen Daten müssen dabei in einer [https://de.wikipedia.org/wiki/JavaScript_Object_Notation JSON] Datenstruktur angegeben werden.

Für jeden Tag müssen die Schaltzeiten und die Solltemperaturen in Form von Listen angegeben werden.
Die Datenstruktur sieht bspw. wie folgt aus:

<syntaxhighlight lang="JSON">{
"Sun": {
"time": ["06:00","22:00","24:00"],
"temp": ["20.0","22.0","20.0"]
},
"Sat": {
"time": ["06:00","22:00","24:00"],
"temp": ["20.0","22.0","20.0"]
},
"Thu": {
"time": ["06:00","22:00","24:00"],
"temp": ["20.0","22.0","20.0"]
},
"Fri": {
"time": ["06:00","22:00","24:00"],
"temp": ["20.0","22.0","20.0"]
},
"Tue": {
"time": ["06:00","22:00","24:00"],
"temp": ["20.0","22.0","20.0"]
},
"Wed": {
"time": ["06:00","22:00","24:00"],
"temp": ["20.0","22.0","20.0"]
},
"Mon": {
"time": ["06:00","22:00","24:00"],
"temp": ["20.0","22.0","20.0"]
}
}
</syntaxhighlight>

Es handelt sich dabei um eine unsortierte Liste von "Tages-Objekten", die wiederum eine unsortierte Liste von Schlüssel-Werte Paaren enthält. Die beiden verwendeten Schlüssel "time" und "temp" für Zeit und Temperatur verweisen jeweils auf eine sortierte Liste mit Werten.

Der Schlüssel "time" enthält die Liste der gewünschten Zeitpunkte, zu denen ein Temperaturwechsel stattfinden soll. Die Zeitangaben müssen im Format "hh:mm" angegeben werden. Falls für den ganzen Tag nur eine Temperatur verwendet werden soll, so ist als Zeitpunkt "24:00" anzugeben.

Der Schlüssel "temp" enthält die Temperaturen, die zu den in "time" hinterlegten Schaltzeitpunkten eingestellt werden sollen. Dabei entspricht die Reihenfolge der Temperaturen der Reihenfolge der Zeitpunkte in "time".

Zur Übergabe an FHEM sollte die JSON Struktur von sämtlichen Formatierungen (Zeilenumbrüche, Tabs, überflüssige Leerzeichen) bereinigt werden, so dass ein einzeiliger String entsteht. Für das oben angegebene Beispiel würde das dann so aussehen:

<code><nowiki>{"Sun":{"time":["06:00","22:00","24:00"],"temp":["20.0","22.0","20.0"]},"Sat":{"time":["06:00","22:00","24:00"],"temp":["20.0","22.0","20.0"]},"Thu":{"time":["06:00","22:00","24:00"],"temp":["20.0","22.0","20.0"]},"Fri":{"time":["06:00","22:00","24:00"],"temp":["20.0","22.0","20.0"]},"Tue":{"time":["06:00","22:00","24:00"],"temp":["20.0","22.0","20.0"]},"Wed":{"time":["06:00","22:00","24:00"],"temp":["20.0","22.0","20.0"]},"Mon":{"time":["06:00","22:00","24:00"],"temp":["20.0","22.0","20.0"]}}</nowiki></code>

==== Referenzprofil konfigurieren ====
Dieser Befehl kommt nur zum Tragen, wenn per Attribut useTopics die Verwendung von Topics aktiviert wurde.

Siehe {{Link2CmdRef|Anker=weekprofile-set}}

==== Topic wiederherstellen ====
Dieser Befehl kommt nur zum Tragen, wenn per Attribut useTopics die Verwendung von Topics aktiviert wurde.

Siehe {{Link2CmdRef|Anker=weekprofile-set}}
=== Modul Befehle: get ===

==== Wochenprofile exportieren ====
Siehe {{Link2CmdRef|Anker=weekprofile-get}}

==== Wochenprofilnamen exportieren ====
Siehe {{Link2CmdRef|Anker=weekprofile-get}}

==== Wochenprofil-Refrenzen exportieren ====
Siehe {{Link2CmdRef|Anker=weekprofile-get}}

=== Modul Attribute ===
Die meisten Attribute sind selbsterklärend. Daher wird an dieser Stelle zumeist auf die Informationen in der Siehe {{Link2CmdRef|Anker=weekprofile-attr}} verwiesen.

==== Namen der Wochentage festlegen ====
widgetWeekdays: Siehe {{Link2CmdRef|Anker=weekprofile-attr}}

==== Anzeigeart: Anzahl der Spalten====
widgetEditDaysInRow: Siehe {{Link2CmdRef|Anker=weekprofile-attr}}

==== Anzeigeart: editieren auf neuer Seite ====
widgetEditOnNewPage: Siehe {{Link2CmdRef|Anker=weekprofile-attr}}

==== Pfad zur Konfigurationsdatei ====
configFile: Siehe {{Link2CmdRef|Anker=weekprofile-attr}}

==== Verwendung von Topics ====
useTopics: Aktiviert den Betriebsmodus: Topics

== WeekdayTimer ==
Über WeekdayTimer als "Zwischenschicht" können beliebige Thermostat-Devices weiterer, nicht direkt unterstützter Modul-Typen mit Temperaturprofilen aus ''weekprofile'' versorgt werden, auch die Änderung im laufenden Betrieb ist ohne weiteres möglich, z.B. um zwischen Urlaubs- und Anwesenheits-Topic umzuschalten. WeekdayTimer kann dabei u.A. auch Fensterkontakte abfragen und die jeweilige nächste Schaltung verzögern, bis das Fenster wieder geschlossen ist. Weitere Informationen sind der Dokumentation von WeekdayTimer zu entehmen.

Dabei ist lediglich zu beachten, dass prinzipbedingt die erste Schaltzeit des Tages nicht direkt auf Mitternacht festgelegt wird, sondern 10 Minuten danach.
Übertragen werden Profile von weekprofile aus mittels
:<code>set weekprf send_to_device holiday:livingrooms myWeekdayTimer</code>
Dies hat denselben Effekt, wie wenn man vom WeekdayTimer-Device aus das betreffende Profil über dessen setter ''weekprofile'' abruft:
:<code>set myWeekdayTimer weekprofile weekprf:holiday:livingrooms</code>
Nutzt man auf bei weekprofile keine ''topics'', ist ''"default"'' als Topic anzugeben:
:<code>set weekprf send_to_device default:livingrooms myWeekdayTimer</code>

== bekannte Probleme ==
* Derzeit (Version: 10924) können keine Leerzeichen oder Umlaute verwendet werden. Leerzeichen werden bei der Eingabe abgefangen. Hat man versehentlich doch Umlaute verwendet, müssen in der Datei ./log/weekprofile-<name>.cfg die entsprechenden Zeilen manuell gelöscht/umbenennt werden und danach ein [[rereadcfg]] ausführt werden.
* Speichert man einen Wochenplan, wird die Änderung erst nach einem reload der Seite angezeigt.

== Links ==
*{{Link2Forum|Topic=46117|LinkText=Thread}} im FHEM-Forum
*[http://www.jsoneditoronline.org/ JSON-Editor] für eine einfache Bearbeitung der JSON Daten

AttrTemplate

2023-01-31T06:38:06Z

Beta-User: /* Syntax */ pardefault ergänzt

{{SEITENTITEL:AttrTemplate}}
{{Infobox Modul
|ModPurpose=Hilfsmodul bzw. Befehl, das/der die Einrichtung von Geräten erleichtern kann
|ModType=cmd
|ModCmdRef=
|ModForumArea=Automatisierung
|ModTechName=AttrTemplate.pm
|ModOwner=rudolfkoenig ({{Link2FU|8|Forum}} / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}

AttrTemplate ist ein Hilfsmodul, mit dessen Hilfe Geräte auf einfache Weise mit einer passenden Konfiguration versehen lassen.

Das Modul ''AttrTemplate'' ist indirekt Bestandteil der SetExtensions, das Modul kann von Modulautoren aber auch ohne diese mit in beliebige (Geräte-) Module mit eingebaut werden. Über diesen Mechanismus ist der Befehl ''attrTemplate'' in einer Vielzahl von Modulen verfügbar.

==Einführung==
Ziel von ''attrTemplate'' ist es, den Nutzer bei der Konfiguration von Geräten zu unterstützen, indem vorrangig entsprechende [[Attribute]] gesetzt werden. Grundsätzlich ist es jedoch auch möglich, beliebige FHEM-Befehle oder Perl-Code im Rahmen von attrTemplate auszulösen.
Teilt man entsprechende ''templates'', sollte jedoch deutlich darauf hingewiesen werden, wenn ein Template etwas anderes tut als nur Attribute zu setzen, also insbesondere dauerhafte Konfigurationsänderungen in der Hardware selbst vorzunehmen.

Um Ihnen die Auswahl zu erleichtern, kann
* mit <code>set <Device-Name> attrTemplate ?</code> eine Liste der vorhandenen Templates samt kurzer Beschreibung aufgerufen werden.
* in der Detailansicht der Geräte über das Dropdownfeld ein ''template'' ausgewählt werden. Nun erhält man unmittelbar unter dem ''set''-Befehl ebenfalls entsprechende weitere Informationen sowie den Code des ''template'' angezeigt, der bei Drücken auf ''set'' ausgeführt wird.
Hat man ein passendes ''template'' gefunden, wird mit <code>set <Device-Name> attrTemplate <template_name></code> angewendet, wodurch die entsprechenden, in dem ''template'' hinterlegten Kommandos ausgeführt werden.

== Syntax ==

{{Link2Forum|Topic=104804|Message=988100|LinkText=Hier}} und {{Link2Forum|Topic=99195|Message=925952|LinkText=hier}} hat Rudolf König die Syntax erläutert, die in den attrTemplate-Dateien verwendet werden können:
* leere Zeilen werden ignoriert
* Zeilen die mit # anfangen sind Kommentare (s.u. ''desc:'')
* Zeilen, die mit einem der folgenden Schlüsselwörter beginnen, werden speziell interpretiert: ''name: filter: prereq: option: par: desc: farewell: order:''
** '''name:''' Name des Templates, markiert gleichzeitig das Ende des vorherigen Templates
** '''filter:''' devspec2array Ausdruck, der beschreibt, für welche Geräte dieses Template anwendbar ist. Wird erst beim "set ?" ausgeführt.
** '''prereq:''' ist entweder ein Perl-Ausdruck {}, oder ein ''devspec2array'', was genau ein Gerät spezifiziert. Falls mindestens ein prereq existiert, was nicht zutrifft, wird das betroffene Template aus dem Speicher entfernt. Die Auswertung erfolgt beim FHEM Start oder bei {AttrTemplate_Initialize()}
** '''option:''' Syntax entspricht prereq, wird jedoch beim Einlesen des template Files ausgeführt. Falls nicht wahr ist, werden die darauffolgenden Zeilen des Template nicht ausgeführt. Ist für sowas wie "setze zusätzlich Attribut XY falls die Installation HomeAssistant kennt" gedacht.
** '''par:''' kann mehrfach vorkommen, Syntax: <code>par:<ParameterName>;<Kommentar>;<Perl-Code></code>. ''Perl-Code'' versucht den Wert zu finden, falls nicht möglich (''return undef''), wird ein Dialog mit "Replace" angezeigt (bzw. Usage:... im telnet). ''ParameterName'' wird in jeder Befehlzeile ersetzt mit dem Wert. Zusätzlich: ''DEVICE'' wird mit dem Namen des Gerätes ersetzt, wird ''DEVICE'' (z.B. für Modulnamen) als Text benötigt, muß es ''escaped'' werden (z.B. MQTT2_\DEVICE).
** '''pardefault:''' Wie '''par:''', allerdings wird ein ggf. ermittelter Wert nicht automatisch übernommen, sondern als Vorgabe in einem Dialogfeld zur Bestätigung (bzw. Änderung) durch den User angezeigt.
** '''desc:''' Kommentar fuer <code>set attrTemplate help ?</code>. Die letzte Zeile mit # vor ''name:'' wird als ''desc:'' interpretiert, falls kein ''desc:'' vorhanden ist.
** '''farewell:''' wird zum Schluss als Dialog (oder Text in telnet) angezeigt, falls beim Anwenden der Befehle kein Fehler aufgetreten ist.
** '''order:''' bestimmt die Reihenfolge, in der die Templates im [[FHEMWEB|Webfrontend]] angezeigt werden; falls nicht vorhanden, wird ''name:'' genommen.
** '''loop:''' ermöglicht es, die zwischen ''loop:<parameter-name>:<wert1>:<wert2>:....'' und ''loop:END'' stehenden Zeilen wiederholt auszuführen und dabei bei jedem Durchlauf die als ''<parameter-name>'' bezeichnete Variable durch die darauffolgende Werteliste (getrennt per Doppelpunkt) zu ersetzen.
* alle anderen Zeilen werden als auszuführende Befehle interpretiert, wenn man <code>set <Device-Name> attrTemplate TemplateName</code> ausführt.

==Eigene Templates entwickeln==
Wer plant, mehrere gleichartige Geräte anzulegen, aber andere Einstellungen zu wählen, als sie in den vorhandenen Templates enthalten sind, kann hierfür ebenfalls die attrTemplate-Funktion mit eigenen Templates nutzen. Hierfür können die vorhandenen Templates der im Unterverzeichnis ''fhem/FHEM/lib/AttrTemplate'' zu findenden Dateien als Basis dienen. Ihre Templates speichern Sie einfach als neue Datei mit der Endung ''.template'' im selben Verzeichnis (auf Linux-konforme Zeilenumbrüche achten) und lesen diese mit <code>{ AttrTemplate_Initialize() }</code> neu ein. Danach können Sie diese direkt verwenden.

Haben Sie ein Template erstellt und möchten dieses teilen, erstellen Sie einfach einen Beitrag im entsprechenden Forenbereichen, für manche Module existieren auch spezielle Threads (siehe Linkliste unten)

=== Sprachsteuerung ===
Zur Einbindung von Sprachsteuerungslösungen ([[Siri|Siri,]] [[Alexa]] und [[Google Assistant FHEM Connect|gassistant]]) gibt es eine Reihe zentraler attrTemplates, die meist direkt aus anderen attrTemplates heraus aufgerufen werden. Es ist auch möglich, diese attrTemplate direkt aufzurufen, z.B. wenn man erst später eine Spracherkennungslösung eingebunden hat. Wegen der Namen der templates sollte man dazu direkt die betreffende attrTemplate-file ''[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/lib/AttrTemplate/speechrecogn.template speechrecogn.template]'' konsultieren, die Beschreibung, welches template für welche Funktionalität gedacht ist sowie eventuelle Parameter sind jeweils hinter dem ''desc:'' zu finden.

=== Spezielle Fragen zur Entwicklung neuer Templates ===
* Ersetzungen von Schlüsselbegriffen, die durch den AttrTemplate-Code aufgelöst bzw. durch entsprechende andere Werte ersetzt werden, (insbesondere von ''DEVICE'') kann man verhindern, indem man diese ''escaped''. Beispiel: Um im Ergebnis ein "MQTT2_DEVICE" zu erzielen, muß "MQTT2_\DEVICE" geschrieben werden.

==Warum finde ich das Template xyz nicht?==
In den dropdown-Auswahllisten entsprechender Geräte werden teils deutlich weniger Möglichkeiten angeboten, als in den attrTemplate-files aufgeführt sind. Gesteuert wird dies durch die bereits oben genannten Ausdrücke ''filter'' und ''prereq'':

=== filter ===
''filter'' bewirkt, dass das template schlicht nicht in der Auswahlliste erscheint, aber an sich geladen ist und über die Kommandozeile auch angewendet werden kann. Allerdings müssen Sie in diesen Fällen damit rechnen, dass mindestens einzelne Elemente zur Ausführung des template-Code nicht vorhanden sind, und Sie diese Parameter über ein Dialogfeld eingeben müssen.

Geladene attrTemplate werden angezeigt, wenn man
:<code>set <device> attrTemplate ?</code>
ausführt.

In der Regel ist es zu empfehlen, die in filter abgefragten Daten händisch einzupflegen, also z.B. bei einem Tasmota-MQTT2_DEVICE wenigstens das "LWT"-readingsList-Element anzugeben.

=== prereq ===
Trifft ein ''prereq'' nicht zu, wird das betreffende Template gar nicht geladen. Es erscheint dann weder bei Aufruf des "?", noch kann es über die Kommandozeile ausgeführt werden. In der Regel macht es auch wenig Sinn, ein template ausführen zu wollen, dessen Voraussetzungen nicht gegeben sind, etwa weil (noch) kein passendes Bridge-Gerät definiert ist.

=== Deaktivierung über ''global'' ===
Darüber hinaus kann das Modul insgesamt über folgende Einstellung deaktiviert werden:
<syntaxhighlight lang="perl">
attr global disableFeatures attrTemplate
</syntaxhighlight>
Dann werden insgesamt keine attrTemplates mehr geladen.

==Links==
* {{Link2Forum|Topic=93370|LinkText=Ankündigung des Moduls im Forum}}
* [[MQTT2_DEVICE#attrTemplate|Wiki zu attrTemplate und MQTT2_DEVICE]] - enthält auch Links zu speziellen Threads für bestimmte Device-Typen
* {{Link2Forum|Topic=94495|LinkText=Thread für getestete Vorschläge (MQTT2_DEVICE)}}.
* {{Link2Forum|Topic=94494|LinkText=Thread für Fragen und Anregungen (MQTT2_DEVICE)}}.
* {{Link2Forum|Topic=97694|LinkText=Thread für HTTPMOD}}.
<references />
[[Kategorie:FHEM-Verwendung]]
[[Kategorie:HOWTOS]]

MsgDialog

2023-01-26T14:20:33Z

Beta-User: /* TelegramBot */ Typo..

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]])
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig userattr msgDialog_evalSpecials:textField-long msgDialog_msgCommand:textField
attr myMsgConfig msgContactPush <Name des TelegramBot-device>
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>\
TelegramBot=<Name des TelegramBot-device>
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message". Wenn nicht gesetzt, wird die Vorgabe verwendet.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

Der Inhalt vom Attribut msgContactPush muss folgendem Muster entsprechen:
<pre>
<NAME des TelegramBot Device>:@<zum ROOMMATE/GUEST gehörende Telegram ID>
</pre>

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": "deletereading TYPE=msgDialog $recipient_history",\
"message": [\
"{return('(' . join(') (', sort{lc($a) cmp lc($b)} (split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger', 1)))) . ') (abbrechen) ')}",\
"Ich kann folgendes für dich tun:"\
]\
},\
"zurück": {\
"commands": "set $recipient_history=.+ say @$recipient {(ReadingsVal($DEV, '$recipient_history', '') =~ m/((.+)\\|.+$)/;;;; return($2 || $1);;;;)}"\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": "deletereading TYPE=msgDialog $recipient_history",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Dialog abgebrochen."\
]\
},\
"beenden": {\
"match": "\/?beenden",\
"commands": "deletereading TYPE=msgDialog $recipient_history",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog allowed everyone
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die '''DEF''' in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands": "single command"
</pre>
<pre>
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Texte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

;Dialogfelder
:Um Dialogfelder im Keyboard anzuzeigen müssen diese innerhalb des message-Blocks in runden Klammern stehen(). Wichtig ist das nach der schließenden Klammer ein Leerzeichen folgt. Damit das Keyboard angezeigt wird, muss auch ein normaler Text im bessage-Block enthalten sein.
<pre>
"message": [
"(Dialogfeld 1) ",
"(Dialogfeld 2) ",
"Bitte wähle ein Dialogfeld aus"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Hilfe bei der Fehlersuche ==
Hier entsteht eine Sammlung von Tipps bei der Fehlersuche. Die meisten dieser "Stolpersteine"
entstehen häufig bei der Erstellung eines ersten eigenen Dialoges.

=== Das Attribut allowed fehlt oder ist nicht korrekt gesetzt ===
Das allowed-Attribut dient dazu, einzelne Dialoge für alle oder nur bestimmte Benutzer zu berechtigen.
Fehlt es, wird der Dialog dem aufrufenden Benutzer nicht angezeigt.
<pre>
attr Testdialog allowed everyone
</pre>

=== Das Attribut msgDialog_evalSpecials fehlt oder ist nicht korrekt gesetzt ===
Dieses Attribut gehört dem msgConfig device und muss wie in 2.3 zu lesen
korrekt befüllt werden.
<pre>
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
</pre>

=== Das Attribut utf8Special fehlt beim TelegramBot device ===
Dieses Attribut ist für die korrekte UTF-8 Kodierung zuständig und im Standard deaktiviert.
Der Satz "Was kann ich für dich tun?" aus dem Meta-Dialog enthält bereits einen Umlaut!

Folgende FHEM-Log-Fehlermeldung kann auf das fehlende Attribut hindeuten:
<pre>
<Datum> <Zeit> 3: TelegramBot_Callback <TelegramBot-Device>: resulted in NonBlockingGet timed out on read from <hidden> after 30s from SendIt
</pre>

=== JSON-Syntax Fehler ===
Das Modul prüft vor dem Abspeichern auf eine korrekte JSON-Syntax.
Meistens wird auch eine sprechende Meldung angezeigt:
<pre>
Usage: define <name> msgDialog {JSON}

, or ] expected while parsing array, at character offset 73 (before "}\n}") at ./FHEM/76_msgDialog.pm line 93.
</pre>
Eine gute Anlaufstelle zur Überprüfung von JSON-Code ist hier: https://jsonlint.com/

=== Es werden keine Dialoge angezeigt ===
Ohne die Angabe einer normalen Nachricht wird bei Keyboards kein Dialog angezeigt:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Erst mit der Nachricht "Möchtest Du Lampen ein oder ausschalten?" erscheint der Dialog:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
"Möchtest Du Lampen ein oder ausschalten?"
],
</pre>

=== Innerhalb eines Dialogs fehlen einzelne Menüeinträge ===
Das liegt das meistens an einem fehlenden Leerzeichen:
<pre>
"message": [
"(Lampen einschalten)",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Bei "Lampen ausschalten" ist dagegen korrekt ein Leerzeichen zu sehen und somit auch der Menüeintrag im Dialog.

=== ":" bei Inline Keyboards ===
Bei Inline Keyboards wird der letzte : als Trennzeichen zwischen Nachricht und Befehl ausgewertet.
Beispiel:
<pre>
"(Temperatur: [heizung:desiredTemperature]°C:setheiz) "
</pre>
oder
<pre>
"([test:state]:weiter) " wenn [test:state] = "Status: ok"
</pre>

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In [[TelegramBot|Telegram]] gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return if $TYPE ne 'TelegramBot';;\
\
my $sentMsgId = ReadingsVal($NAME, 'sentMsgId', '');;\
my $sentMsgPeerId = ReadingsVal($NAME, 'sentMsgPeerId', '');;\
my $contact = (devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*"))[0];;\
\
readingsSingleUpdate($defs{$NAME}, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, 'state', 'inactive') eq 'active' ? '.*:ios-on-blue:inactive' : '.*:ios-off:active'}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]
[[Kategorie:Telegram]]
[[Kategorie:Jabber]]
[[Kategorie:WhatsApp]]

MsgDialog

2023-01-26T14:08:20Z

Beta-User: /* TelegramBot */ - Code update

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]])
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig userattr msgDialog_evalSpecials:textField-long msgDialog_msgCommand:textField
attr myMsgConfig msgContactPush <Name des TelegramBot-device>
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>\
TelegramBot=<Name des TelegramBot-device>
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message". Wenn nicht gesetzt, wird die Vorgabe verwendet.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

Der Inhalt vom Attribut msgContactPush muss folgendem Muster entsprechen:
<pre>
<NAME des TelegramBot Device>:@<zum ROOMMATE/GUEST gehörende Telegram ID>
</pre>

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": "deletereading TYPE=msgDialog $recipient_history",\
"message": [\
"{return('(' . join(') (', sort{lc($a) cmp lc($b)} (split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger', 1)))) . ') (abbrechen) ')}",\
"Ich kann folgendes für dich tun:"\
]\
},\
"zurück": {\
"commands": "set $recipient_history=.+ say @$recipient {(ReadingsVal($DEV, '$recipient_history', '') =~ m/((.+)\\|.+$)/;;;; return($2 || $1);;;;)}"\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": "deletereading TYPE=msgDialog $recipient_history",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Dialog abgebrochen."\
]\
},\
"beenden": {\
"match": "\/?beenden",\
"commands": "deletereading TYPE=msgDialog $recipient_history",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog allowed everyone
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die '''DEF''' in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands": "single command"
</pre>
<pre>
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Texte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

;Dialogfelder
:Um Dialogfelder im Keyboard anzuzeigen müssen diese innerhalb des message-Blocks in runden Klammern stehen(). Wichtig ist das nach der schließenden Klammer ein Leerzeichen folgt. Damit das Keyboard angezeigt wird, muss auch ein normaler Text im bessage-Block enthalten sein.
<pre>
"message": [
"(Dialogfeld 1) ",
"(Dialogfeld 2) ",
"Bitte wähle ein Dialogfeld aus"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Hilfe bei der Fehlersuche ==
Hier entsteht eine Sammlung von Tipps bei der Fehlersuche. Die meisten dieser "Stolpersteine"
entstehen häufig bei der Erstellung eines ersten eigenen Dialoges.

=== Das Attribut allowed fehlt oder ist nicht korrekt gesetzt ===
Das allowed-Attribut dient dazu, einzelne Dialoge für alle oder nur bestimmte Benutzer zu berechtigen.
Fehlt es, wird der Dialog dem aufrufenden Benutzer nicht angezeigt.
<pre>
attr Testdialog allowed everyone
</pre>

=== Das Attribut msgDialog_evalSpecials fehlt oder ist nicht korrekt gesetzt ===
Dieses Attribut gehört dem msgConfig device und muss wie in 2.3 zu lesen
korrekt befüllt werden.
<pre>
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
</pre>

=== Das Attribut utf8Special fehlt beim TelegramBot device ===
Dieses Attribut ist für die korrekte UTF-8 Kodierung zuständig und im Standard deaktiviert.
Der Satz "Was kann ich für dich tun?" aus dem Meta-Dialog enthält bereits einen Umlaut!

Folgende FHEM-Log-Fehlermeldung kann auf das fehlende Attribut hindeuten:
<pre>
<Datum> <Zeit> 3: TelegramBot_Callback <TelegramBot-Device>: resulted in NonBlockingGet timed out on read from <hidden> after 30s from SendIt
</pre>

=== JSON-Syntax Fehler ===
Das Modul prüft vor dem Abspeichern auf eine korrekte JSON-Syntax.
Meistens wird auch eine sprechende Meldung angezeigt:
<pre>
Usage: define <name> msgDialog {JSON}

, or ] expected while parsing array, at character offset 73 (before "}\n}") at ./FHEM/76_msgDialog.pm line 93.
</pre>
Eine gute Anlaufstelle zur Überprüfung von JSON-Code ist hier: https://jsonlint.com/

=== Es werden keine Dialoge angezeigt ===
Ohne die Angabe einer normalen Nachricht wird bei Keyboards kein Dialog angezeigt:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Erst mit der Nachricht "Möchtest Du Lampen ein oder ausschalten?" erscheint der Dialog:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
"Möchtest Du Lampen ein oder ausschalten?"
],
</pre>

=== Innerhalb eines Dialogs fehlen einzelne Menüeinträge ===
Das liegt das meistens an einem fehlenden Leerzeichen:
<pre>
"message": [
"(Lampen einschalten)",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Bei "Lampen ausschalten" ist dagegen korrekt ein Leerzeichen zu sehen und somit auch der Menüeintrag im Dialog.

=== ":" bei Inline Keyboards ===
Bei Inline Keyboards wird der letzte : als Trennzeichen zwischen Nachricht und Befehl ausgewertet.
Beispiel:
<pre>
"(Temperatur: [heizung:desiredTemperature]°C:setheiz) "
</pre>
oder
<pre>
"([test:state]:weiter) " wenn [test:state] = "Status: ok"
</pre>

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In [[TelegramBot|Telegram]] gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return if $TYPE ne 'TelegramBot';;\
\
my $dev_hash = ;;\
my $sentMsgId = ReadingsVal($NAME, 'sentMsgId', '');;\
my $sentMsgPeerId = ReadingsVal($NAME, 'sentMsgPeerId', '');;\
my $contact = (devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*"))[0];;\
\
readingsSingleUpdate($defs{$NAME}, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, 'state', 'inactive') eq 'active' ? '.*:ios-on-blue:inactive' : '.*:ios-off:active'}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]
[[Kategorie:Telegram]]
[[Kategorie:Jabber]]
[[Kategorie:WhatsApp]]

HM-CC-RT-DN Funk-Heizkörperthermostat

2023-01-12T14:16:11Z

Beta-User: update von virtuellen Sensoren

{{Infobox Hardware
|Bild=HM-CC-RT-DN.jpg
|Bildbeschreibung=HM-CC-RT-DN an Heizkörper montiert
|HWProtocol=[[HomeMatic]]
|HWType=[[HomeMatic Type Thermostat|thermostat]]
|HWCategory=[[:Kategorie:Heizungsventile|Heizungsventile]]
|HWComm=868 MHz
|HWChannels=6
|HWVoltage=3 V
|HWPowerConsumption=180 mA
|HWPoweredBy=2x LR6/Mignon/AA
|HWSize=54x65x93 mm (BxHxT)
|HWDeviceFHEM=[[CUL_HM]]

|HWManufacturer=ELV / eQ-3
}}
'''HM-CC-RT-DN''' (häufig einfach '''RT''' genannt) ist ein Funk-''Heizkörperthermostate'' mit integriertem ''Stellantrieb''. Das Thermostat ist seit September 2013 verfügbar und ist der Nachfolger des [[HM-CC-VD Funk-Stellantrieb]]s.

== Vorbemerkungen ==
: ''→ Einstellungen und Informationen, die alle [[HomeMatic]] Thermostate betreffen, sind unter [[HomeMatic Type Thermostat#Temperaturlisten|HomeMatic Type Thermostat]] zu finden.''

Der HM-CC-RT-DN kann die Temperatur selbst messen (im Gegensatz zum [[HM-CC-VD Funk-Stellantrieb|Vorgänger]]) und verfügt über eine Fenster-Offen-Erkennung sowie eine Boost-Funktion. Der HM-CC-RT-DN ''kann'' von einem [[HM-TC-IT-WM-W-EU Funk-Wandthermostat AP]] gesteuert werden, das ist aber ''optional''.

Das Gerät wird seit Anfang Oktober 2013 von FHEM unterstützt (siehe Diskussion im {{Link2Forum|Topic=14738|LinkText=Forum}}).

Der HM-CC-RT-DN scheint das erste HomeMatic-Device zu sein, bei dem ein Update der Firmware auch vom Anwender durchgeführt werden kann. Ein Firmware-Update erfordert einen [[HM-CFG-USB_USB_Konfigurations-Adapter|USB Konfigurations-Adapter]] und eine auf der eQ-3 Webseite herunterladbare Firmwareupdate-Software. Weitere Details sind unter [[#Firmware Update|Firmware Update]] beschrieben.
{{Hinweis|Die Solltemperaturen eines HM-CC-RT-DN lassen sich ''nicht'' durch einen [[HM-CC-TC Funk-Wandthermostat]] ''steuern''. Dieser kann nur die Ist-Temperatur an den HM-CC-RT-DN weitergeben, damit nicht die am HM-CC-RT-DN direkt gemessene Raumtemperatur zur Regelung verwendet wird.}}
Mit einem HM-CC-RT-DN können maximal (neben der Zentrale/FHEM):
* 7 HomeMatic Heizkörperthermostate
* 8 HomeMatic Tür-Fensterkontakte / Fenster-Drehgriffkontakte
* 8 Tastenpaare von HomeMatic Fernbedienungen bzw. Display-Wandtaster
* 1 HomeMatic Innen-Temperatur-Sensor
[[Peering (HomeMatic)|gepeert]] werden.

{{Hinweis|Wird für Wartungs-/Umbaumaßnahmen das Wasser der Heizung abgelassen bzw. diese neubefüllt, sind alle Stellantriebe manuell dauerhaft auf '''on''' zu setzen: set <HM_Stellantrieb>_Clima controlManu on. Beim Einsatz eines Wandthermostaten ist der Wandthermostat entsprechend einzustellen.}}

== Technische Daten ==
* Betriebsspannung: 2 Stck. 1,5V LR6/Mignon/AA
* Stromaufnahme: 180 mA max.
* Abmessungen (B x H x T): 54 x 65 x 93 mm
* Gewicht: 180 g (ohne Batterien)
* Ventilanschluss: M30 x 1,5 mm

Aktuelle Firmware: 1.5 (2020)

== Betrieb mit FHEM ==
Der Funk-Heizkörperthermostat muss zuerst mit FHEM [[Pairing (HomeMatic)|gepairt]] werden. Stellen Sie sicher, dass FHEM aktuell ist ([[update]] durchführen)

Das Pairing sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden (mittlere Taste mindestens drei Sekunden drücken, um den Vorgang auszulösen). Vereinzelt muss mehrfach gepairt werden, es wurde auch berichtet, dass dabei die Batterie zwichendurch entfernt und neu eingelegt werden muss.

=== Channels (Kanäle) ===
==== Channel (Kanal) 01 _Weather ====

Dieser Kanal dient zur Einspeisung der (gemessenen) ''Ist-Temperatur''. Als Sensor können zum Beispiel das [[HM-TC-IT-WM-W-EU Funk-Wandthermostat AP|HM-TC-IT-WM-W-EU Funk-Wandthermostat]] oder ein [[HM-WDS40-TH-I Funk-Temperatur-/Feuchtesensor innen (IT)|HM-WDS40-TH-I Funk-Temperatur-/Feuchtesensor]] dienen.

Ein Temperatur-Sensor ''tempSensor'' kann mit dem ''_Weather''-Kanal wie folgt [[Peering (HomeMatic)|gepeert]] werden:

set <HM-TC-IT-WM-W-EU>_Weather peerChan 0 <HM-CC-RT-DN>_Weather single set

Beispiel:
set EG_Buero_WANDTHERMOSTAT_Weather peerChan 0 EG_Buero_THERMOSTAT_Weather single set

ACHTUNG: Das Wandthermostat sowie das Thermostat Ventil (Beispiel "EG_Buero_WANDTHERMOSTAT" und EG_Buero_THERMOSTAT) werden vorher in FHEM den Status "CMDs_done" anzeigen.
Beim peerChan wird dann bei beiden "CMDs_pending" stehen. Wobei das Wandthermostat sehr schnell wieder auf CMDs_done zurück springt.
Allerdings ist dringend darauf zu achten, dass das Thermostat Ventil auch wieder auf "CMDs_done" wechselt, bevor man den nächsten Befehl absendet.
Das Heizkörper Ventil kann unter Umständen 3 bis 5 min benötigen bis wieder "CMDs_done" steht. Evtl. kann man dies durch die BOOST Taste beschleunigen. Da das Ventil etwa alle 3 min aufwacht, prüft und Daten sendet / empfängt. Sollte man mit dem Befehlen weiter gemacht haben, so kann es zu dem Problem führen, dass einer nicht mehr mit dem Pending aufhört. In dem Fall empfiehlt es sich beide Devices von FHEM abzumelden und auf Werkseinstellung zu resetten.

Zum Test haucht man das Wandthermostat an oder hält es einige Zeit in der Hand bis die Temperatur steigt, nach etwa 3 Minuten sollte man auch am Thermostat Ventil einen Temperaturanstieg sehen.

==== Channel (Kanal) 02 _Climate ====
Dieser Kanal erlaubt es dem [[HM-TC-IT-WM-W-EU Funk-Wandthermostat AP|HM-TC-IT-WM-W-EU Funk-Wandthermostat]] den HM-CC-RT-DN zu steuern. Dazu müssen die beiden Geräte gepeert werden:

set <HM-TC-IT-WM-W-EU>_Climate peerChan 0 <HM-CC-RT-DN>_Climate single set

==== Channel (Kanal) 03 _WindowRec ====
Mit diesem Kanal können Fensterkontakte ([[HM-SEC-SC Tür-Fensterkontakt|HM-SEC-SC]] und [[HM-Sec-RHS Funk-Fenster-Drehgriffkontakt|HM-SEC-RHS]]) ihren Fensterstatus (geöffnet / gekippt) an ein oder mehrere Thermostate senden. Die Thermostate stellen anschließend die entsprechende (konfigurierbare) Temperatur ein. Der Temperaturwert kann je Fenster-Sensor unterschiedlich definiert werden. Sind mehrere Fenster gleichzeitig geöffnet, so wird der Thermostat auf die Temperatur des Sensors mit dem geringsten Temperaturwert eingestellt.
Ferner wird empfohlen, bei Einsatz von externen Sensoren, die interne „Fenster auf Erkennung“ zu deaktivieren (weitere Details sind im [[HM-CC-RT-DN Funk-Heizkörperthermostat#Channel .28Kanal.29 04 _Clima|Channel (Kanal) 04 _Clima]] beschrieben).

Der Befehl zum Peeren lautet, wobei <fensterSensor> die FHEM-Kanalbezeichnung für den Fensterkontakt ist und <rt_WindowRec> die Kanalbezeichnung für den entsprechenden Kanal des Heizkörperthermostates (siehe {{Link2Forum|Topic=41541|LinkText=diesen Thread}}):
set <fensterSensor> peerChan 0 <rt_WindowRec>_WindowRec single

Zum Löschen (=unpeeren) dieser Kopplung:
set <fensterSensor> peerChan 0 <rt_WindowRec>_WindowRec single unset

'''Achtung''': Der Peer-(Lösch-)Vorgang muss erst am Fensterkontakt durch Drücken der Anlerntaste ausgelöst werden, und zwar auch dann, wenn der Fensterkontakt schon vorher mit FHEM gepairt wurde. Dann kann der oben genannte Befehl in FHEM abgesetzt werden. Wichtig scheint auch, dass der Fensterkontakt geschlossen ist wenn man die Anlerntaste drückt.

Der Befehl zur Temperatureinstellung des Heizkörperthermostaten für den Zustand "Fenster offen" lautet, wobei <fensterSensor> die FHEM-Kanalbezeichnung für den Fensterkontakt ist und <rt_WindowRec> die Kanalbezeichnung für den entsprechenden Kanal des Heizkörperthermostates, sowie <Temp> die einzustellende Temperatur (ganzzahliger Wert):
set <rt_WindowRec>_WindowRec regSet winOpnTemp <Temp> <fensterSensor>

Weitere Hinweise im Forum, siehe {{Link2Forum|Topic=41541|Message=348044|LinkText=FHEM Forum-Beitrag}}

==== Channel (Kanal) 04 _Clima ====
Dieser Kanal dient zum Einstellen der Betriebsparameter, auch [[#Temperaturlisten|Temperaturlisten]] sind hierauf zu übertragen.
Mit dem Modul [[Weekprofile|Wochenplan / Weekprofile]] können die Wochenpläne komfortabel in FHEM erstellt und an die Thermostate übertragen werden.

{{Hinweis|In älteren Versionen von FHEM wurde dieser Kanal durch ''autocreate'' als <code>_ClimRT_tr</code> angelegt. Der Hersteller hat hier offenbar die internen Bezeichnungen geändert, denn beim Vorläufermodell HM-CC-TC mussten Temperaturlisten auf den Kanal ''Climate'' übertragen werden.}}

Die maximale Öffnung des Ventils kann mittels folgendem Befehl eingestellt werden (hier auf 80 %):
set <HM-CC-RT-DN>_Clima regSet valveMaxPos 80

Die interne "Fenster-auf"-Erkennung kann man wie folgt abschalten:
set <HM-CC-RT-DN>_Clima regSet winOpnMode off

==== Channel (Kanal) 05 _ClimaTeam ====
Dieser Kanal erlaubt es mehrere HM-CC-RT-DN zu einem "Team" zu gruppieren. Ein Mitglied des Teams meldet
* Änderungen der Temperatur am Handrad
* Einschalten des Boost-Modus am Taster
an seine "Teamkollegen" weiter. Folgende Änderungen werden '''nicht''' weitergegeben:
* Status der Fensterkontakte
* Temperaturlisten/Wochenplan und daraus folgende Änderungen
* Änderungen durch Fernbedienungen
* Änderungen durch eine HomeMatic-Zentrale

Befehl zum Peeren, wobei ''<HM-CC-RT-DN#1>_ClimaTeam'', ''<HM-CC-RT-DN#2>_ClimaTeam'', ..., ''<HM-CC-RT-DN#8>_ClimaTeam'' die Kanalbezeichnungen der jeweiligen ClimaTeam-Kanäle sind:
set <HM-CC-RT-DN#1>_ClimaTeam peerChan 0 <HM-CC-RT-DN#2>_ClimaTeam single
set <HM-CC-RT-DN#1>_ClimaTeam peerChan 0 <HM-CC-RT-DN#3>_ClimaTeam single
set <HM-CC-RT-DN#2>_ClimaTeam peerChan 0 <HM-CC-RT-DN#3>_ClimaTeam single
...

==== Channel (Kanal) 06 _remote ====
Dieser Kanal kann an eine Fernbedienung gekoppelt werden. Per Tastendruck kann man einen bestimmten Mode und/oder eine bestimmte Temperatur wählen. Dabei kann die Reaktion auf einen langen oder kurzen Tastendruck gesondert eingestellt werden.

Der Befehl zum Peeren lautet, wobei <button> die Kanalbezeichnung der Fernbedienung und <rt-remote> die Kanalbezeichnung des Heizkörperthermostates ist:
set <nowiki><button> peerChan 0 <HM-CC-RT-DN>_remote single</nowiki>

=== Betriebsmodus Auto, Manu, Party (Urlaub) ===

Der HM-CC-RT-DN verfügt über drei Betriebsmodus: Auto, Manu (Manuell) und Party (Urlaub).

==== Modus Auto ====
Das Gerät arbeitet gemäß des gespeicherten Wochenprogramms. Manuelle Änderungen sind möglich, werden aber beim nächsten Schaltpunkt überschrieben.

==== Modus Manu ====
Die Temperatur wird manuell eingestellt, das Wochenprogramm wird nicht abgearbeitet. "Manuell Einstellen" bedeutet entweder am Handrad oder durch Übermittlung eines "set desired temp"-Befehls von FHEM (oder equivalent von einer CCU).

==== Modus Party (Urlaub) ====
Die eingestellte Temperatur gilt bis zu einem gegebenen Endzeitpunkt, anschließend wechselt das Thermostat in den ''Auto''-Modus.

==== Welchen Modus nutzen? ====
Im Umfeld von FHEM sind alle drei Modi einsetzbar. Betrieb in "Auto" hat den Vorteil, dass bei Ausfall der FHEM-Instanz der Thermostat trotzdem noch die eingespeicherten Wochenprogramme abarbeitet. Nachteilig ist aber, dass die Steuerung komplexer wird, weil sowohl die Einstellungen am Thermostat als auch Schaltbefehle von FHEM das Verhalten beeinflussen. Vielfach wird daher im Umfeld von FHEM der Modus "Manu" benutzt, hier wird die Temperatur nur per einzelnem FHEM Schaltbefehl gesteuert, ausgelöst z.b. durch "at" Kommandos, Anwesenheitserkennung oder Bewegungsmelder. Sollte FHEM (oder die Funkverbindung) ausfallen, bleibt der Thermostat allerdings auf der letzten eingestellten Temperatur stehen.

Denkbar ist auch, den Modus "Auto" zu verwenden und dann die Steuerung per FHEM dadurch durchzuführen, dass durch FHEM die Wochenprogramme verändert werden. Dies verbindet zwar die Vorteil der vorgenannten Methoden, ist aber am Aufwendigsten in der Programmierung und erzeugt die höchste Funklast.

Auch der Urlaubsmodus ist einsetzbar, so kann beispielsweise bei Abwesenheit ein niedrigeres Temperaturprofil eingestellt werden, ohne dass eventuell vorhandene Temperaturlisten verändert werden müssen.

set <HM-CC-RT-DN>_Clima controlParty 16 06.12.13 16:30 09.12.13 05:00

Dadurch wird
* von 06.12.2013, 16:30 Uhr
* bis 09.12.2013, 05:00 Uhr
* die gewünschte Raumtemperatur auf 16 °C eingestellt.

{{Hinweis|
* Der Befehl muss auf dem Kanal 4 ''(_Clima)'' erfolgen.
* Es werden nur Uhrzeiten zu jeder vollen oder halben Stunde angenommen (Minuten also 00 oder 30).}}

Mit der folgenden Funktion <code>Urlaub()</code> kann man eine ganze Wohnung (also mehrere RTs) mit nur einem Befehl in den Party-Modus versetzen. Im Beispiel werden zwei Heizkörper ("Treppenhaus" und "Kammer") angesteuert.

Zu beachten sind folgende Dinge:
# Aktuelle Dateien (z.B. <code>10_CUL_HM</code>) verwenden!
# Bei dem ''controlParty''-Befehl ''kein'' Komma zwischen den Parametern.
# Bei der Funktion die Parameterübergabe definieren <code>($$$$$)</code>

'''Aufruf:'''
:<code>{Urlaub ("16", "06.12.13", "16:30", "09.12.13" ,"05:00")}</code>

'''Funktion:'''
<syntaxhighlight lang="perl">
my $Urlaub;
sub
Urlaub($$$$$)
{
my ($temp, $startDate, $startTime, $endDate, $endTime) = @_;

# HM-CC-RT-DN akzeptiert nur Zeiten, die auf Minute 00 oder 30 enden.
# Daher $startTime und $endTime abrunden
$startTime =~ s/\:[0-2].$/:00/;
$startTime =~ s/\:[3-5].$/:30/;
$endTime =~ s/\:[0-2].$/:00/;
$endTime =~ s/\:[3-5].$/:30/;

# controlParty bei jedem HM-CC-RT-DN setzen.
for my $rt (qw(Kammer Treppenhaus)) {
fhem ("set $rt controlParty $temp $startDate $startTime $endDate $endTime");
}
}
</syntaxhighlight>

=== Tastensperre ===

Um zu verhindern, dass der Modus oder die Temperatur per Tasten bzw. Drehrad am HM-CC-RT-DN verändert wird, kann eine Tastensperre gesetzt werden. Dies erfolgt mittels des Befehls:

set <HM-CC-RT-DN> regSet btnLock on

Rückgängig machen geht per:

set <HM-CC-RT-DN> regSet btnLock off

Diese Tastensperre kann man aber am HM-CC-RT-DN durch eine Tastenkombination wieder zurücksetzen. Um sie nur per FHEM rücksetzen zu können, muss

set <HM-CC-RT-DN> regSet globalBtnLock on

eingegeben werden. Rückgängig geht wieder per:

set <HM-CC-RT-DN> regSet globalBtnLock off

Es gibt auch eine Tastensperre die nur das Umschalten des Modus (Auto, Manuell, Urlaub) am Gerät verhindert. Diese wird mit

set <HM-CC-RT-DN> regSet modusBtnLock on

eingeschaltet. Abschalten geht mit:

set <HM-CC-RT-DN> regSet modusBtnLock off

=== Burst-Modus ===
Das ist ein '''Übertragungs'''modus für Nachrichten zwischen HM-Geräten und der Zentrale. Der RT erwacht alle 2,5 Minuten und dann überträgt die Zentrale die Kommandos. Wenn man einen Fensterkontakt oder eine Fernsteuerung nutzt, muss der RT sofort reagieren - dann muss man den Burst ''enablen''. Der RT kann in diesem Fall sofort aufgeweckt werden und bearbeitet die Anforderung (Request). Das kann man auch von der Zentrale aus nutzen (so man möchte). Das ist der '''Vorteil''' des eingeschalteten Burst-Modus.

'''Nachteil:''' Der Burst-Modus benötigt mehr Leistung, das heißt die Batterien müssen häufiger gewechselt werden: Der RT muss den Receiver ständig empfangsbereit halten. Außerdem wachen bei jedem Burst ''alle'' Burst-Empfänger auf – egal an wen die Kommunikation gerichtet war.

'''Burst – wie es funktioniert'''

Schickt ein Sender eine burst Sequenz, wachen alle burst-Empfänger auf und prüfen die Message.
Wenn sie betroffen sind bleiben sie eine Zeit lang wach, ansonsten schlafen sie wieder ein.
Man beachte also, dass Senden eines Burst Energie in ALLEN burst-Empfängern verbraucht, egal ob sie angesprochen sind.

'''HMLAN und burst'''

[[HMLAN]] hat ein Sendebudget das über eine Stunde berechnet wird. Burst belastet dieses Konto deutlich - so können nicht mehr als 100 bursts /h gesendet werden - dann geht HMLAN in overload. Wenn zusätzliche Nachrichten gesendet werden sind es entsprechend weniger.
Es ist nicht vorteilhaft, unnötig bursts zu senden.

'''Burst devices'''

Es gibt Devices, die immer auf burst reagieren und solche bei denen es abgeschaltet werden kann. So reagiert ein Rauchmelder immer auf Burst damit er seine Team-Kollegen hören kann.
Ein TC oder RT hingegen hat diese Funktion abschaltbar. 'Per default ist dies ausgeschaltet um Batterie zu sparen'. Wenn ein VD gesteuert wird ist der TC ja selbst wach. Wird er aber mit einem Fensterkontakt gekoppelt muss es eingeschaltet werden – sonst verpasst er die Nachricht.

'''ConditionalBurst devices'''

Devices mit abschaltbarem Burst wie z.B. der ''HM-CC-RT-DN'' haben ein Register, ''burstRx'', mit dem das burst-Erwachen eingestellt werden kann.
Sendern, die einen burst-Aktor erwecken sollen, muss man sagen, welcher Peer Burst benötigt. Hier kann ggf. das Register ''peerNeedsBurst'' nach dem Peeren gesetzt werden. FHEM versucht dies automatisch beim Peeren zu erledigen. Siehe [[HMInfo]] Befehl ''models'' um herauszufinden, welche Devices welchen Modus unterstützen.

'''Attribut burstAccess'''

Devices, die abschaltbaren burst haben kann man ein attribut burstAccess 1_auto setzen. Es wird beim Abschicken eines Kommandos versucht, das Device mit burst zu wecken. Sollte es nicht funktionieren wird gewartet, bis das Device aufwacht (meist reagieren solche Devices auch auf wakeup). Das Setzen des Attributs ist angenehm – es werden aber ggf. viele bursts gesendet.

'''Kommando burstXmit'''

Mit diesem Kommando, das bei Devices mit conditional-Burst zu Verfügung steht, wird der burst gezielt vom User angestoßen.

Der User schickt erst seine Kommandos an das device. Die Kommandos werden im Command-stack gesammelt.

Dann sendet der User ein set burstXmit.

Es passiert das gleiche wie bei burstAccess.

FHEM versucht mittels burst zu wecken und sendet bei Erfolg die Messages aus dem Kommandostack.

Im Gegensatz zu burstAccess ist burstXmit gezielt einsetzbar und kann sparsamer verwendet werden.

''' FHEM und burst devices'''

FHEM sendet eine burst automatisch mit Kommandos zu Devices, die nur burst unterstützen.

'''So aktiviert man den burst-Betrieb am HM-CC-RT-DN'''

''Burst Mode einschalten'' (der Kanal 4 des Device WZ1 heisst hier WZ1_4)
:<code>set WZ1_4 regSet burstRx on </code>
prüfen mit:
:<code>get WZ1_4 reg burstRx </code>
''Nun in FHEM den Burst mode einschalten (sofern nicht burstXmit verwendet wird)''
:<code>attr WZ1 burstAccess 1_auto</code>

Hinweis: Das Attribut im Device und nicht im Kanal setzen, ansonsten gibt es eine Fehlermeldung.

=== Temperaturlisten ===
Die Temperaturlisten des HM-CC-RT-DN werden identisch mit denen anderer HomeMatic Thermostate verwaltet (siehe [[HomeMatic Type Thermostat#Temperaturlisten|HomeMatic Type Thermostat]]). Beim HM-CC-RT-DN ist der Kanal 4 (_Clima) für die Temperaturlisten zuständig.

==FHEM-Log==
In den folgenden Logs heißt Kanal 4 noch "_ClimRT_tr". Inzwischen würde man dort "_Clima" sehen.

=== Device-Log ===
2013.10.10 20:03:24 3: CUL_HM Unknown device CUL_HM_HM_CC_RT_DN_2212BC, please define it
2013.10.10 20:03:24 2: autocreate: define CUL_HM_HM_CC_RT_DN_2212BC CUL_HM 2212BC A1A0184002212BC0000001000954B4551303531303031375900FFFF
2013.10.10 20:03:24 3: Device CUL_HM_HM_CC_RT_DN_2212BC added to ActionDetector with 000:10 time
2013.10.10 20:03:24 3: CUL_HM pair: CUL_HM_HM_CC_RT_DN_2212BC thermostat, model HM-CC-RT-DN serialNr KEQ0510017
2013.10.10 20:03:24 3: LANCUL pairing (hmPairForSec) not enabled
2013.10.10 20:03:24 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC-%Y.log CUL_HM_HM_CC_RT_DN_2212BC
2013.10.10 20:03:24 3: Device Heizung_Wohnzimmer added to ActionDetector with 000:10 time
2013.10.10 20:03:24 3: CUL_HM pair: Heizung_Wohnzimmer thermostat, model HM-CC-TC serialNr JEQ0044286
2013.10.10 20:03:24 3: Device CUL_HM_HM_CC_RT_DN_2212BC added to ActionDetector with 000:10 time
2013.10.10 20:03:24 3: CUL_HM pair: CUL_HM_HM_CC_RT_DN_2212BC thermostat, model HM-CC-RT-DN serialNr KEQ0510017
2013.10.10 20:03:25 2: autocreate: define CUL_HM_HM_CC_RT_DN_2212BC_Weather CUL_HM 2212BC01
2013.10.10 20:03:25 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_Weather FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_Weather-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_Weather
2013.10.10 20:03:25 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_Weather FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_Weather-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_Weather
2013.10.10 20:03:26 2: autocreate: define CUL_HM_HM_CC_RT_DN_2212BC_Climate CUL_HM 2212BC02
2013.10.10 20:03:26 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_Climate FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_Climate-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_Climate
2013.10.10 20:03:26 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_Climate FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_Climate-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_Climate
2013.10.10 20:03:27 2: autocreate: define CUL_HM_HM_CC_RT_DN_2212BC_WindowRec CUL_HM 2212BC03
2013.10.10 20:03:27 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_WindowRec FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_WindowRec-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_WindowRec
2013.10.10 20:03:27 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_WindowRec FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_WindowRec-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_WindowRec
2013.10.10 20:03:28 2: autocreate: define CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr CUL_HM 2212BC04
2013.10.10 20:03:28 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr
2013.10.10 20:03:28 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr
2013.10.10 20:03:29 2: autocreate: define CUL_HM_HM_CC_RT_DN_2212BC_ClimaTeam CUL_HM 2212BC05
2013.10.10 20:03:29 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_ClimaTeam FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_ClimaTeam-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_ClimaTeam
2013.10.10 20:03:29 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_ClimaTeam FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_ClimaTeam-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_ClimaTeam
2013.10.10 20:03:30 2: autocreate: define CUL_HM_HM_CC_RT_DN_2212BC_remote CUL_HM 2212BC06
2013.10.10 20:03:30 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_remote FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_remote-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_remote
2013.10.10 20:03:30 2: autocreate: define FileLog_CUL_HM_HM_CC_RT_DN_2212BC_remote FileLog /usr/local/FHEM/var/log/CUL_HM_HM_CC_RT_DN_2212BC_remote-%Y.log CUL_HM_HM_CC_RT_DN_2212BC_remote
2013.10.10 20:03:35 3: Device CUL_HM_HM_CC_RT_DN_2212BC added to ActionDetector with 000:10 time
2013.10.10 20:03:40 2: CUL_HM set CUL_HM_HM_CC_RT_DN_2212BC getSerial
2013.10.10 20:03:40 2: CUL_HM set CUL_HM_HM_CC_RT_DN_2212BC getConfig
2013.10.10 20:03:54 3: Device CUL_HM_HM_CC_RT_DN_2212BC added to ActionDetector with 000:10 time

=== Event monitor ===
2013-10-12 12:05:35.610 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr motorErr: ok
2013-10-12 12:05:35.610 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr measured-temp: 18.4
2013-10-12 12:05:35.610 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr desired-temp: 18
2013-10-12 12:05:35.610 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr ValvePosition: 3 %
2013-10-12 12:05:35.610 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr mode: manu
2013-10-12 12:05:35.610 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr unknown0: 24
2013-10-12 12:05:35.610 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC_ClimRT_tr T: 18.4 desired: 18 valve: 3 %
2013-10-12 12:05:35.646 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC battery: ok
2013-10-12 12:05:35.646 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC batteryLevel: 3.1 V
2013-10-12 12:05:35.646 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC measured-temp: 18.4
2013-10-12 12:05:35.646 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC desired-temp: 18
2013-10-12 12:05:35.646 CUL_HM CUL_HM_HM_CC_RT_DN_2212BC actuator: 3 %

== Firmware Update ==
Seit 24.10.2014 gibt es für den HM-CC-RT-DN die neue Firmware Version 1.4. Diese kann von der eQ-3 Webseite heruntergeladen werden. Genauere Informationen gibt es unter [[HomeMatic Firmware Update]].

=== HM-CC-RT-DN spezifische Update Informationen ===
Durch gleichzeitiges Drücken der "Auto-/Manu"-Taste und der "Comfort-/Eco"-Taste am HM-CC-RT-DN während man die Batterien wieder einlegt wird der updatemodus gestartet. Während des Updates steht "FUP" im Display. Nach erfolgreichem Update erscheint "Ins" im Display und es muss eine erneute Adaptierfahrt durch Drücken der Boost-Taste ausgelöst werden. Anschließend sollte der HM-CC-RT-DN wieder normal funktionieren. Die eingestellten Parameter und das Pairing mit FHEM gehen beim Update nicht verloren. Sollte das Update fehlschlagen, erscheint "Err" bzw. "CrC" im Display.

Normalerweise sollte dann durch erneutes Starten der Prozedur am PC und HM-CC-RT-DN das ganze erneut durchführbar sein.

Es gibt einige Readings, die nicht durch ein einfaches ''getConfig'' aktualisiert werden, z.B. "battery"(nicht batteryLevel). Um diese Readings zu bekommen, ist ein
:<code>set Device_Channel04 controlMode auto </code>
notwendig. Daraufhin werden die Readings übertragen/aktualisiert.

Anscheinend ([https://forum.fhem.de/index.php?topic=93074.msg1252268#msg1252268]) benötigt man bei Firmware 1.5 ein weiteres Attribut,<syntaxhighlight>
attr <devicename> commStInChn off
</syntaxhighlight>

== Simulation von Fensterkontakten und externen Temperatursensoren ==
{{Randnotiz|RNTyp=r|RNText=Für jeden separat zu steuernden HM-CC-RT-DN kann nur je ein Kanal eines virtuellen Devices als Temperatur- bzw. Fensterkontakt genutzt werden. Insbesondere die virtuellen Kanäle der VCCU eignen sich nicht dazu, mehrere HM-CC-RT-DN unabhängig voneinander anzusteuern! Hat man mehrere unabhängig arbeitende RT's, muß für jeden auch ein '''eigenes virtuelles Gerät''' angelegt werden!

Die folgenden Beispiele sind nicht für Anfänger und Unwissende geeignet! Es gibt zahlreiche Stolpersteine:
# Die HMId für virtuelle Geräte muss einmalig im System sein. Sie muss selbst gewählt werden und es darf '''keine''' vorhandene ID verwendet werden!
# Es kann vorkommen, das beim Anlegen eines virtual Gerätes kein attr IODev gesetzt wird. Das Attribute ist aber notwendig, sonst arbeitet das Gerät nicht! Bitte kontrollieren und gegebenenfalls per Hand setzen.
}}
Grober Ablauf:
* erstelle ein virtuelles Device
* erstelle dazu einen virtuellen Kanal (bzw. mehrere, wenn sowohl ein virtueller Fensterkontakt wie ein virtueller Temperaturkanal benötigt werden).
* peere den Kanal mit dem RT (als Fenster-Kontakt oder als remote, wenn du willst)
* sende ein postEvent / stelle die neue Temperatur im Kanal ein

=== Fensterkontakte ===
''Angelehnt an diese {{Link2Forum|Topic=31078|Message=236245|LinkText=Forenbeitrag}}''
define virtKitchenSensors CUL_HM 221133
Um das Device als virtuelles zu kennzeichnen benötigt man den folgenden Befehl (legt weitere Attribute an):
attr virtKitchenSensors model VIRTUAL

Kanal bzw. Kanäle erstellen (benötigt uU. einen Neustart von FHEM, bevor der Befehl zur Verfügung steht):
set virtKitchenSensors virtual 1
oder (für das Anlegen je eines Kanals für einen Fenster- und Temperatur-Kanal):
set virtKitchenSensors virtual 2
Als Zwischenergebnis sehen wir in der Detailansicht des ''virtKitchenSensors'' ein bzw. zwei weitere Devices mit Namen ''virtKitchenSensors_Btn1'' bzw. ''virtKitchenSensors_Btn2''.

Umbenennen des 1. Kanals:
rename virtKitchenSensors_Btn1 virtualKitchenDoor

Danach sollte man das webCmd-Attribut wie folgt vergeben:
attr virtualKitchenDoor webCmd postEvent open:postEvent closed

Anschließend peeren und (wer weniger wie den default-Wert von 12°C einstellen möchte) Temperatur festlegen mit:
set virtualKitchenDoor peerChan 0 <Thermostat_Window_Rec> single set
set <Thermostat_Window_Rec> regSet winOpnTemp 5 virtualKitchenDoor

Ggf noch interne "Fenster-auf" Erkennung abschalten
set <HM-CC-RT-DN>_Clima regSet winOpnMode off

Die virtuelle Tür wird dann entsprechend über ein Notify getriggert.
Einfache Form (nur ein Fensterkontakt im Raum):
define notify_virtualKitchenDoor notify Fensterkontakt_1:(open|closed) set virtualKitchenDoor postEvent $EVENT
Komplexere Form (zwei Fensterkontakte):
<nowiki>define notify_virtualKitchenDoor notify (Fensterkontakt_1|Fensterkontakt_2) {if($EVENT eq "open" and Value("virtualKitchenDoor") eq "set_postEvent closed"){fhem("set virtualKitchenDoor postEvent open")} elsif (Value("virtualKitchenDoor") eq "closed" && Value("Fensterkontakt_2") eq "closed") {fhem("set virtualKitchenDoor postEvent closed")}}</nowiki>
{{Hinweis|Die ''postEvent''-Anweisung wird unmittelbar an die Funkschnittstelle weitergegeben und löst einen ''burst'' aus.}}

=== Temperatursensoren ===
''Angelehnt an diesen {{Link2Forum|Topic=19686|Message=233788|LinkText=Forenbeitrag}}''

1. Virtuelles HomeMatic Device mit eigener HM Id definieren, (s.o.), es kann auch ein weiterer Kanal des oben erstellten Devices genutzt werden

2. Dem Device einen virtuellen Kanal (Default ist ein virtueller Button) hinzufügen, wieder mit <code>set virtKitchenSensors virtual 1</code> bzw. <code>set virtKitchenSensors virtual 2</code> (2 geht auch, wenn bereits ein erster Kanal vorhanden war).

3. Es ist kein virtueller Button sondern ein virtueller Temperatursensor - darum rename:
rename virtKitchenSensors_Btn1 Kitchen_vT_Sensor1
bzw. <code>rename virtKitchenSensors_Btn2 Kitchen_vT_Sensor1</code>

4. Virtuellen Peer Sensor mit dem Weather Channel des RT-DN peeren:
set Kitchen_vT_Sensor1 peerChan 0 <RT_DN>_Weather single

5. Peering kontrollieren (Voraussetzung: Device ''hm'' vom Typ [[HMInfo]] existiert):
:<code>set hm peerXref</code>
Beispiel-Ausgabe:
peerXref done:
x-ref list
wz_Thermostat_Weather => Kitchen_vT_Sensor1
Kitchen_vT_Sensor1 => wz_Thermostat_Weather

6. Gemessene Temperatur vom z.B. 1-Wire DS1820 dem virtuellen HM Sensor übergeben. Z.B. bei jeder Aktualisierung des Messwerts per notify:
define at_Kitchen_vT notify myRealKitchenTempSensor:temperature:.* set Kitchen_vT_Sensor1 virtTemp $EVTPART1

{{Hinweis|Die ''virtTemp''-Anweisung ändert zunächst nur den Wert im virtuellen Kanal. Diese wird zu bestimmten Zeiten als ''broadcast'' gesendet. Diese Zeiten kennt der RT und hält sich kurzfristig empfangsbereit.}}
Sollte es Probleme geben, dass der RT des Öfteren wieder auf seine eigenen Messwerte wechselt, weil die von FHEM errechnete Sendezeit und die vom RT errechnete Empfangszeit zu weit auseinanderliegen, sollte das Attr cyclicMsgOffset im Virtuellen Kanal beachtet werden. Näheres dazu ist ca. ab {{Link2Forum|Topic=45735|Message=572806|LinkText=hier}} im Forum zu finden.

7. Sicherstellen, dass nicht längerfristig veraltete Temperaturdaten berücksichtigt werden:
Aufgrund des oben beschriebenen Verfahrens wird der im virtuellen Kanal vorhandene Wert solange immer wieder gesendet, wie dieser dort steht. Fällt z.B. der echte Sensor oder das Interface nicht nur vorübergehend aus, muß der Wert gelöscht werden. Hier ein Vorschlag für ein ''at'', das alle 15 Minuten alle virtuellen Temperaturwerte löscht, die älter als eine Stunde sind, und damit den Rückfall des jeweiligen RT auf seinen internen Sensor bewirkt:
defmod a_delete_outdated_virtTemps at +*00:15 {\
my @vTemps = devspec2array("TYPE=CUL_HM:FILTER=model=VIRTUAL:FILTER=temperature~.+");;\
for my $vTemp (@vTemps) {\
CommandDeleteReading(undef,"$vTemp temperature" ) if ReadingsAge($vTemp,"temperature",0) > HOURSECONDS ;;\
}\
}
Erhält der RT eine gewisse Zeitlang (ca. 15 Minuten) keinen Wert von seinem (virtuellen) Peer, schaltet er auf den internen Temperatursensor zurück und signalisiert dies durch ein blinkendes Funksymbol im Display.

=== Exkurs: HMCCUDEV ===
{{Hinweis|Das Nachfolgende entspricht dem Stand Janaur 2020. Die HMCCU-Module sind jedoch derzeit in der Weiterentwicklung, so dass es sich ggf. empfiehlt, im Forum nachzufragen.}}
Das Nutzen externer Sensoren scheint mit HMCCU nicht möglich zu sein, siehe {{Link2Forum|Topic=107134|LinkText=Forenbeitrag: RaspberryMatic (HMCCU) und LaCrosse Temperature als "Wandthermostat"}}, die Weitergabe eines externen Türkontakts ist eventuell möglich, siehe {{Link2Forum|Topic=106807|LinkText=Forenbeitrag: HMCCU mit Thermostat HM-CC-RT-DN und ZWave Türsensor}}, an anderer Stelle hat der Modulentwickler ausgeführt, es könnten nur {{Link2Forum|Topic=107501|Message=1015944|LinkText=HomeMatic Geräte}} als Sensoren verwendet werden.

== Auflistung und Beschreibung der Readings ==
Einige der Readings können via "regSet" parametriert werden.
Wobei der Registername etwas anders geschrieben wird als der Reading Name (ohne R-).
:<code>set <name> regSet <register> <value> </code>
Beispiel für Reading R-winOpnPeriod erhöhen auf 60 Minuten:
:<code>set EG_Buero_THERMOSTAT_Clima regSet winOpnPeriod 60 </code>

Eine vollständige Liste erhält man auch, wenn man einen falschen Registernamen angibt.
supported register are backOnTime boostPeriod boostPos btnLock btnNoBckLight burstRx cyclicInfoMsg cyclicInfoMsgDis dayTemp daylightSaveTime decalcTime decalcWeekday globalBtnLock localResDis lowBatLimitRT modePrioManu modePrioParty modusBtnLock nightTemp noMinMax4Manu pairCentral regAdaptive reguExtI reguExtP reguExtPstart reguIntI reguIntP reguIntPstart showInfo showWeekday sign tempMax tempMin tempOffset valveErrPos valveMaxPos valveOffsetRt winOpnBoost winOpnDetFall winOpnMode winOpnPeriod winOpnTempI

<table cellspacing="0" border="0">
<tr>
<td style="border-top: 2px solid #ffffff; border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#A6A6A6">Reading</td>
<td style="border-top: 2px solid #ffffff" align="left" valign="middle" bgcolor="#A6A6A6">Beispielwert</td>
<td style="border-top: 2px solid #ffffff" align="left" valign="middle" bgcolor="#A6A6A6">Mögliche Werte</td>
<td style="border-top: 2px solid #ffffff; border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#A6A6A6">Beschreibung</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">CommandAccepted</td>
<td align="left" valign="middle" bgcolor="#111111">yes</td>
<td align="left" valign="middle" bgcolor="#111111">yes; no</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Letztes Kommando akzeptiert (yes/ No)</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-boostPeriod</td>
<td align="left" valign="middle" bgcolor="#333333">5 min</td>
<td align="left" valign="middle" bgcolor="#333333">1 min bis x min</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Zeit wie lange das Ventil im Boost Modus sein soll.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-boostPos</td>
<td align="left" valign="middle" bgcolor="#111111" sdval="0.8" sdnum="1033;0;0%">80%</td>
<td align="left" valign="middle" bgcolor="#111111" sdnum="1033;0;0%">0 bis 100</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Ventilposition die im Boost Modus gesetzt wird.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-btnNoBckLight</td>
<td align="left" valign="middle" bgcolor="#333333">off</td>
<td align="left" valign="middle" bgcolor="#333333">on; off</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="35" align="left" valign="middle" bgcolor="#111111">R-dayTemp</td>
<td align="left" valign="middle" bgcolor="#111111">21 C</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R-tempMin bis R-tempMax</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Solltemperatur die gesetzt werden soll, wenn das Sonnensymbol am Thermostat gedrückt wird. Ebenso wird bei dieser Solltemperatur das Sonnensymbol im Display angezeigt.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-daylightSaveTime</td>
<td align="left" valign="middle" bgcolor="#333333">on</td>
<td align="left" valign="middle" bgcolor="#333333">on; off</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-decalcTime</td>
<td align="left" valign="middle" bgcolor="#111111" sdval="0.458333333333333" sdnum="1033;1033;H:MM">11:00</td>
<td align="left" valign="middle" bgcolor="#111111" sdnum="1033;1033;H:MM">00:00 bis 23:59</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Uhrzeit wann die Entkalkungsfahrt durchgeführt werden soll. </td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-decalcWeekday</td>
<td align="left" valign="middle" bgcolor="#333333">Sat</td>
<td align="left" valign="middle" bgcolor="#333333">Mon; Tue; Wed; Thu; Fri; Sat; Sun</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Tag an dem die Entkalkungsfahrt durchgeführt werden soll.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-modePrioManu</td>
<td align="left" valign="middle" bgcolor="#111111">all</td>
<td align="left" valign="middle" bgcolor="#111111">all; ???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-modePrioParty</td>
<td align="left" valign="middle" bgcolor="#333333">all</td>
<td align="left" valign="middle" bgcolor="#333333">all; ???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="35" align="left" valign="middle" bgcolor="#111111">R-nightTemp</td>
<td align="left" valign="middle" bgcolor="#111111">17 C</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R-tempMin bis R-tempMax</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Solltemperatur die gesetzt werden soll, wenn das Mondsymbol am Thermostat gedrückt wird. Ebenso wird bei dieser Solltemperatur das Mondsymbol im Display angezeigt.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-noMinMax4Manu</td>
<td align="left" valign="middle" bgcolor="#333333">off</td>
<td align="left" valign="middle" bgcolor="#333333">on; off</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-regAdaptive</td>
<td align="left" valign="middle" bgcolor="#111111">on</td>
<td align="left" valign="middle" bgcolor="#111111">on; off</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-reguExtI</td>
<td align="left" valign="middle" bgcolor="#333333" sdval="15" sdnum="1033;">15</td>
<td align="left" valign="middle" bgcolor="#333333">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-reguExtP</td>
<td align="left" valign="middle" bgcolor="#111111" sdval="30" sdnum="1033;">30</td>
<td align="left" valign="middle" bgcolor="#111111">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-reguExtPstart</td>
<td align="left" valign="middle" bgcolor="#333333" sdval="30" sdnum="1033;">30</td>
<td align="left" valign="middle" bgcolor="#333333">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-reguIntI</td>
<td align="left" valign="middle" bgcolor="#111111" sdval="18" sdnum="1033;">18</td>
<td align="left" valign="middle" bgcolor="#111111">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-reguIntP</td>
<td align="left" valign="middle" bgcolor="#333333" sdval="33" sdnum="1033;">33</td>
<td align="left" valign="middle" bgcolor="#333333">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-reguIntPstart</td>
<td align="left" valign="middle" bgcolor="#111111" sdval="44" sdnum="1033;">44</td>
<td align="left" valign="middle" bgcolor="#111111">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-showInfo</td>
<td align="left" valign="middle" bgcolor="#333333">time</td>
<td align="left" valign="middle" bgcolor="#333333">date; time</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Zeige Datum oder Uhrzeit im Display an</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-showWeekday</td>
<td align="left" valign="middle" bgcolor="#111111">off</td>
<td align="left" valign="middle" bgcolor="#111111">on; off</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Zeige den Wochentag im Display an</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-sign</td>
<td align="left" valign="middle" bgcolor="#333333">off</td>
<td align="left" valign="middle" bgcolor="#333333">on; off</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-tempMax</td>
<td align="left" valign="middle" bgcolor="#111111">30.5 C</td>
<td align="left" valign="middle" bgcolor="#111111">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Größte einstellbare Temperatur</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-tempMin</td>
<td align="left" valign="middle" bgcolor="#333333">4.5 C</td>
<td align="left" valign="middle" bgcolor="#333333">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Kleinste einstellbare Temperatur</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-tempOffset</td>
<td align="left" valign="middle" bgcolor="#111111">0.0K</td>
<td align="left" valign="middle" bgcolor="#111111">0.0 bis ???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Temperaturabweichung gemessene Temperatur vs. realer Temperatur in Grad Kelvin. Angabe in 0.5-Schritten ohne Einheitenzeichen, z.B. 0.5 oder -1.0</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-valveErrPos</td>
<td align="left" valign="middle" bgcolor="#333333" sdval="0.15" sdnum="1033;0;0%">15%</td>
<td align="left" valign="middle" bgcolor="#333333" sdnum="1033;0;0%">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-valveMaxPos</td>
<td align="left" valign="middle" bgcolor="#111111" sdval="1" sdnum="1033;0;0%">100%</td>
<td align="left" valign="middle" bgcolor="#111111" sdnum="1033;0;0%">0 bis 100</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Maximale Ventilstellung die das Thermostat fahren darf.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-valveOffsetRt</td>
<td align="left" valign="middle" bgcolor="#333333" sdval="0" sdnum="1033;0;0%">0%</td>
<td align="left" valign="middle" bgcolor="#333333" sdnum="1033;0;0%">0 Bis 100</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">???</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="52" align="left" valign="middle" bgcolor="#111111">R-winOpnBoost</td>
<td align="left" valign="middle" bgcolor="#111111">off</td>
<td align="left" valign="middle" bgcolor="#111111">on; off</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Startet nach dem Fensterschließen die Boostfunktion um unabhängig von der Raumtemperatur den Heizkörper eine Zeit x aufzuheizen. (Siehe R-boostPeriod & R-boostPos)</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-winOpnDetFall</td>
<td align="left" valign="middle" bgcolor="#333333">1.4 K</td>
<td align="left" valign="middle" bgcolor="#333333">0.5 bis 2.5</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Temperatur Sturz zwischen zwei Messungen, die als Fenster offen erkannt werden.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="35" align="left" valign="middle" bgcolor="#111111">R-winOpnMode</td>
<td align="left" valign="middle" bgcolor="#111111">off</td>
<td align="left" valign="middle" bgcolor="#111111">on; off</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Thermostat soll anhand eines schnellen Temperaturabfalls erkennen, dass das Fenster geöffnet ist.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R-winOpnPeriod</td>
<td align="left" valign="middle" bgcolor="#333333">15 min</td>
<td align="left" valign="middle" bgcolor="#333333">1 bis 60 Minuten</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Dauer bis das Signal Fenster offen wieder entfernt wird.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R-winOpnTemp</td>
<td align="left" valign="middle" bgcolor="#111111">12 C</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R-tempMin bis R-tempMax</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Temperatur die eingestellt werden soll, wenn das Fenster als offen erkannt wird.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="104" align="left" valign="middle" bgcolor="#333333">R_0_tempListSat</td>
<td align="left" valign="middle" bgcolor="#333333">07:00 20.0 22:30 22.0 24:00 20.0</td>
<td align="left" valign="middle" bgcolor="#333333">incomplete = Daten werden mit Thermostat abgeglichen Zeit/Temperaturangaben siehe Beispiel</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Tages Solltemperaturen abhängig von der Uhrzeit. - Der Beginn um 00:00 ist nicht einzutragen. - Es sind immer Paare einzutragen (Uhrzeit Temperatur). - Der letzte Eintrag muss an jedem Tag 24:00 sein. - Uhrzeiten sind auf halbe Stunden beschränkt. Einträge 08:00 und 08:30 sind gültig. 08:20 ist ungültig.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R_1_tempListSun</td>
<td align="left" valign="middle" bgcolor="#111111">07:00 20.0 22:00 22.0 24:00 20.0</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R_0_tempListSat</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R_0_tempListSat</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R_2_tempListMon</td>
<td align="left" valign="middle" bgcolor="#333333">04:30 20.0 07:00 22.0 12:45 20.0 22:00 22.0 24:00 20.0</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Siehe R_0_tempListSat</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Siehe R_0_tempListSat</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R_3_tempListTue</td>
<td align="left" valign="middle" bgcolor="#111111">04:30 20.0 07:00 22.0 12:45 20.0 22:00 22.0 24:00 20.0</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R_0_tempListSat</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R_0_tempListSat</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R_4_tempListWed</td>
<td align="left" valign="middle" bgcolor="#333333">04:30 20.0 07:00 22.0 12:45 20.0 22:00 22.0 24:00 20.0</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Siehe R_0_tempListSat</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Siehe R_0_tempListSat</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">R_5_tempListThu</td>
<td align="left" valign="middle" bgcolor="#111111">04:30 20.0 07:00 22.0 12:45 20.0 22:00 22.0 24:00 20.0</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R_0_tempListSat</td>
<td align="left" valign="middle" bgcolor="#111111">Siehe R_0_tempListSat</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">R_6_tempListFri</td>
<td align="left" valign="middle" bgcolor="#333333">04:30 20.0 07:00 22.0 12:45 20.0 22:00 22.0 24:00 20.0</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Siehe R_0_tempListSat</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Siehe R_0_tempListSat</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="35" align="left" valign="middle" bgcolor="#111111">R_tempList_State</td>
<td align="left" valign="middle" bgcolor="#111111">verified</td>
<td align="left" valign="middle" bgcolor="#111111">incomplete = Daten werden mit Thermostat abgeglichen verified = Daten sind mit Thermostat abgeglichen</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Aktualisierungsstatus der Wochen Temperatur Einstellungen</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">ValvePosition</td>
<td align="left" valign="middle" bgcolor="#333333" sdval="36" sdnum="1033;">36</td>
<td align="left" valign="middle" bgcolor="#333333">0 bis 100</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">aktuelle Ventilstellung</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="35" align="left" valign="middle" bgcolor="#111111">boostTime</td>
<td align="left" valign="middle" bgcolor="#111111">-</td>
<td align="left" valign="middle" bgcolor="#111111">- 1 min bis n min</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Zeit wie lange der Boostmodus noch aktiv ist.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="121" align="left" valign="middle" bgcolor="#333333">controlMode</td>
<td align="left" valign="middle" bgcolor="#333333">auto</td>
<td align="left" valign="middle" bgcolor="#333333">auto = Thermostat wird nach der TempListe gesteuert manual = Die eingestellte Temperatur am Thermostat wird nicht verändert, außer bei Verwendung von WinOpn; boost = Thermostat wird in den Boost Modus gesetzt. Siehe R-boostPeriod/Pos day = Thermostat wird auf die eingestellte Tag Temperatur gesetzt (R-dayTemp). night = Thermostat wird auf die eingestellte Nacht Temperatur gesetzt (R-nightTemp).</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Setzt das Thermostat in einen bestimmten Modus</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">desired-temp</td>
<td align="left" valign="middle" bgcolor="#111111" sdval="22" sdnum="1033;">22</td>
<td align="left" valign="middle" bgcolor="#111111">N/A</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Solltemperatur</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">measured-temp</td>
<td align="left" valign="middle" bgcolor="#333333" sdval="23.2" sdnum="1033;">23.2</td>
<td align="left" valign="middle" bgcolor="#333333">N/A</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Isttemperatur</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">partyEnd</td>
<td align="left" valign="middle" bgcolor="#111111">-</td>
<td align="left" valign="middle" bgcolor="#111111">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Ende Datum/Zeit in dem die Party Temperatur (partyTemp) gesetzt sein soll.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">partyStart</td>
<td align="left" valign="middle" bgcolor="#333333">-</td>
<td align="left" valign="middle" bgcolor="#333333">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333">Start Datum/Zeit in dem die Party Temperatur (partyTemp) gesetzt sein soll.</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#111111">partyTemp</td>
<td align="left" valign="middle" bgcolor="#111111">-</td>
<td align="left" valign="middle" bgcolor="#111111">-; 20.0</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Party Temperatur</td>
</tr>
<tr>
<td style="border-left: 2px solid #ffffff" height="21" align="left" valign="middle" bgcolor="#333333">recentStateType</td>
<td align="left" valign="middle" bgcolor="#333333">ack</td>
<td align="left" valign="middle" bgcolor="#333333">???</td>
<td style="border-right: 2px solid #ffffff" align="left" valign="middle" bgcolor="#333333" sdnum="1033;1033;M/D/YYYY H:MM">???</td>
</tr>
<tr>
<td style="border-bottom: 2px solid #ffffff; border-left: 2px solid #ffffff" height="23" align="left" valign="middle" bgcolor="#111111">state</td>
<td style="border-bottom: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">T: 23.2 desired: 22.0 valve: 36</td>
<td style="border-bottom: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111"> </td>
<td style="border-bottom: 2px solid #ffffff" align="left" valign="middle" bgcolor="#111111">Aktuelle Statusinformation</td>
</tr>
</table>

== Bekannte Probleme ==
=== TempList: Bad format ... ===
Wenn Sie beim Setzen einer Temperaturliste nach dem o.a. Schema ("SetTempList...") die Meldung

Bad format, use HH:MM TEMP ......

erhalten, sollten Sie zunächst ein [[update]] von FHEM durchführen.

=== Der Thermostat heizt über die Solltemperatur hinaus ===
In der Regel ist das ein ganz normales Verhalten, wenn der Thermostat nicht mit einem externen Temperaturfühler oder einem Wandthermostat gepeert ist. In dem Fall muss sich der Thermostat auf den eingebauten Temperatursensor verlassen, der sehr nahe an der Heizung selbst sitzt. Dadurch ist die gemessene Temperatur höher, als sie z.B. in der Raummitte wäre. Der Hersteller hat hier einen mehr oder weniger intelligenten Algorithmus eingebaut, um diesen Effekt zu kompensieren. Das sieht dann so aus, als ob der Thermostat nicht richtig regelt.
Dieses Verhalten kann man im Prinzip nur verhindern, indem man einen externen Temperatursensor oder einen Wandthermostat peert. Wie das geht ist hier beschrieben: [[#Channel (Kanal) 01 _Weather]]. Normalerweise regelt der Thermostat dann genau auf die Solltemperatur.
Ansonsten sollte man sich auch fragen, ob das gezeigte Verhalten vielleicht doch gut genug ist. Dazu platziert man irgendein Thermometer möglichst in der Mitte des Raums und beobachtet den Temperaturverlauf eine Weile. Wenn man dann noch eine Abweichung feststellt, kann es sinnvoll sein, diese mittels des Registers R-tempOffset zu beheben.

=== Pairen bei Firmware 1.5 ===
Das nachfolgende Vorgehen bietet sich ab Firmware 1.5 ab, da sonst das pairen nicht erfolgreich sein wird:
# Pairing wie angegeben
# '''''GetConfig''''' erst, nachdem die Zeit von '''''hmPairForSec''''' abgelaufen ist
# burstXmit
# set <gerät> reset
# set <gerät> unpair
# harten HW Reset nach Handbuch am Gerät
# erneut pairen
Der Tipp stammt aus [https://de.elv.com/forum/neue-firmware-1.5-an-fhem-uart-modul-hm-mod-rpi-pcb-mit-firmware-1.4.1-7481 diesem Beitrag] im ELV Forum. Dies Vorgang konnte teilweise auch für Geräte mit Firmware 1.4 bestätigt werden.

Falls es Probleme während der Prozedur gibt, bitte den Abschnitt [[HM-CC-RT-DN Funk-Heizkörperthermostat#HM-CC-RT-DN spezifische Update Informationen|HM-CC-RT-DN_spezifische_Update_Informationen]] beachten.

=== Akkubetrieb ===
Auch frisch geladenen NiMh-Akkus weisen nur eine Zellenspannung von nur ca. 1,2 Volt auf. Deshalb wird schnell die battery:low Warngrenze erreicht, die bei U < 2,4V liegt und mitunter unmittelbar nach dem Einsetzen mit der Kalibierungsfahrt unterschritten wird. Mit ''NiMh-Akkus mit geringer Selbstentladung'' (z.b. Panasonic Eneloop) ist ein Betrieb jedoch sinnvoll möglich, da der Spannungsabfall bei den sehr geringen Entladeströmen im Stellantrieb relativ lange oberhalb 1,3 Volt verläuft.

== Links ==
* [http://www.eq-3.de/produkt-detail-aktoren/items/homematic-funk-heizkoerperthermostat.html Produktinfo bei EQ-3]
* [http://www.eq-3.de/Downloads/eq3/downloads_produktkatalog/homematic/bda/HM-CC-RT-DN_UM_GE_eQ-3_web.pdf Bedienungsanleitung bei EQ-3 (PDF)]
* [http://www.eq-3.de/Downloads/eq3/downloads_produktkatalog/homematic/pdb/Funk-Heizkoerperthermostat_105155_Produktdatenblatt_V2.3.pdf Datenblatt bei EQ-3 (PDF)]
* [http://www.eq-3.de/Downloads/eq3/downloads/Ventilkompatibilitaeten.pdf Ventil-Kompatibilitätsliste bei EQ-3 (zur Zeit nicht verfügbar)]
* {{Link2Forum|Topic=14738|LinkText=Forenthema zum Thermostat}}
* {{Link2Forum|Topic=64446|LinkText=Reparatur einer durch mechanischen Stoß von außen abgerissenen Lichtschranke}}

[[Kategorie:HomeMatic Components]]
[[Kategorie:Heizungsventile]]
[[Kategorie:868MHz]]

MQTT GENERIC BRIDGE

2022-11-30T16:54:09Z

Beta-User: Klarstellung bzgl. ClientID und mosquitto_pub

{{Infobox Modul
|ModPurpose=Stellt für beliebige Geräte eine Schnittstellt zum MQTT-Protokoll zur Verfügung
|ModType=d
|ModCmdRef=MQTT_GENERIC_BRIDGE
|ModForumArea=MQTT
|ModTechName=10_MQTT_GENERIC_BRIDGE.pm
|ModOwner=hexenmeister ({{Link2FU|4065|Forum}}) }}

{{Baustelle}}

==Einführung==

Das Modul ''MQTT_GENERIC_BRIDGE'' stellt eine zentrale Schnittstelle zum MQTT-Protokoll für beliebig viele andere FHEM-Geräte bereit. Es wird für eine FHEM-Installation jeweils nur ein erreichbarer MQTT-Server sowie eine Instanz der ''MQTT_GENERIC_BRIDGE'' benötigt. Es ist aber auch möglich, mehrere Server parallel zu betreiben.

Dieses Modul kann seit November 2018 mit allen drei IO-Modul-Varianten zusammen eingesetzt werden, also sowohl mit {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} bzw. [[MQTT2_CLIENT]] oder [[MQTT (Modul)|MQTT]](00_MQTT.pm), und seit Rev. 23514 (Jan. 2021) wird für ''MQTT_GENERIC_BRIDGE'' iVm. den MQTT2-IO-Modulen keine zusätzliche Software mehr benötigt.

Dabei erfolgt an dem zentralen ''MQTT_GENERIC_BRIDGE''-Gerät selbst nur eine Basiskonfiguration, die Standardwerte für alle anzubindenden Geräte bereitstellt, alle übrigen Einstellungen erfolgen durch Attribute an dem jeweiligs anzubindenden Gerät selbst.

Beispiel: ein Aktor des Typs [[HomeMatic|CUL_HM]] kann über MQTT-Kommandos an den für ihn passenden Topic an- oder ausgeschaltet werden oder auch einfach nur seinen aktuellen Schaltzustand per MQTT-Protokoll publizieren.

==Installation==
===Vorbereitung===
Im folgenden wird als MQTT-Server ''mosquitto'' verwendet, der in aktuellen Linux-Distributionen über die Paketverwaltung angeboten wird. Hier die Installation für Raspberry Pi OS:
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install mosquitto

Es kann aber auch ein bereits vorhandener {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} verwendet werden.

===Grundsätzliche Konfiguration===
Definition der Schnittstelle zum MQTT-Server (hier: auf demselben Raspberry):

defmod mqtt_io MQTT2_CLIENT 127.0.0.1:1883
attr mqtt_io alias MQTT Broker
attr mqtt_io devStateIcon .*active:none:disconnect .*disconnected:none:connect
attr mqtt_io group MQTT
attr mqtt_io icon mqtt
attr mqtt_io room IO_Devices

Wer möchte, kann den Status des FHEM-Servers per MQTT LWT mitteilen:

Für MQTT2_CLIENT:
attr mqtt_io lwt system/<fhem-name>/connection/status connection lost
attr mqtt_io lwtRetain 1
attr mqtt_io msgAfterConnect -r system/<fhem-name>/connection/status connected
attr mqtt_io msgBeforeDisconnect -r system/<fhem-name>/connection/status disconnected

Alternativ: für [[MQTT (Modul)|MQTT]]
attr mqtt last-will retain:1 system/<fhem-name>/connection/status connection lost
attr mqtt on-connect retain:1 {Log3("mqtt",3,"connected to MQTT server");;1} system/<fhem-name>/connection/status connected
attr mqtt on-disconnect retain:1 {Log3("mqtt",3,"disconnected from MQTT server");;1} system/<fhem-name>/connection/status disconnected

===Definition der Generic Bridge===
Der Name ''mqttGenericBridge'' kann dabei frei gewählt werden:
defmod mqttGenericBridge MQTT_GENERIC_BRIDGE
attr mqttGenericBridge IODev mqtt_io
attr mqttGenericBridge alias MQTT generic bridge
attr mqttGenericBridge group MQTT
attr mqttGenericBridge room IO_Devices
attr mqttGenericBridge stateFormat dev: device-count in: incoming-count out: outgoing-count

Damit sind die wesentlichen Vorarbeiten abgeschlossen, und die ''MQTT_GENERIC_BRIDGE'' kann bereits dafür genutzt werden, beliebige Reading- oder Attribut-Änderungen von FHEM-Devices über MQTT zu publishen oder entsprechende Anweisungen umzusetzen. Es wird jedoch empfohlen, zunächst noch einige grundlegende Einstellungen vorzunehmen. Hierfür - sowie dann auch für die Konfiguration der weiteren Devices, die an MQTT angebunden werden sollen, steht als Hilfsmittel [[attrTemplate]] zur Verfügung.

===Basisangaben in der MQTT_GENERIC_BRIDGE selbst===
[[Datei:MGB attrTemplate Base.PNG|400px|thumb|attrTemplate base_settings_to_MQTT_GENERIC_BRIDGE]]Zunächst werden die Basisangaben zur Struktur der zu verwendenden MQTT-Topics sowie - bei Verwendung eines MQTT2-Interface-Moduls - die ''clientOrder'' konfiguriert:
set mqttGenericBridge attrTemplate base_settings_to_MQTT_GENERIC_BRIDGE
Dies kann direkt über die Detailansicht des Geräts mqttGenericBridge erfolgen, siehe der nebenstehende screenshot, aus dem auch zu entnehmen ist, was das attrTemplate an Änderungen der Konfiguration vornehmen wird. Dies sind zwei Aspekte:
Zum einen wird eine Variable namens $base in Sende- und in Empfangsrichtung festgelegt. In Senderichtung (pub:) besteht diese nur aus dem Namen der ''MQTT_GENERIC_BRIDGE'', in Empfangsrichtung (sub:) aus dem Namen sowie dem Topic-Anteil ''set''. Diese Angaben können im Prinzip beliebig geändert werden, es muss lediglich darauf geachtet werden, dass die Angaben unterschiedlich sind, sonst kann es zu unbeabsichtigten Schleifen kommen!
[[Datei:MGB attrTemplate Base M2IO options.PNG|400px|thumb|attrTemplate Anfrage der gewünschten Konfigurationsoption]]Zum anderen wird - sofern ein ''MQTT2_CLIENT'' und ''MQTT2_SERVER'' als Interface verwendet wird - je nach Wahl des Nutzers in dem dann erscheinenden Dialogfeld - die clientOrder festgelegt. Wer hier unschlüssig ist, sollte die empfohlene Variante wählen, um Probleme im Zusammenspiel mit der ''autocreate''-Funktion dieser Interface-Typen möglichst zu vermeiden.

{{Hinweis|In vielen [[Dokumentationsstruktur#Internet, Blogs usw.|im Internet zu findenden Anleitungen]] wird pauschal das Attribut ''globalPublish'' gesetzt. Dieses führt allerdings dazu, dass zum einen sehr viele unwichtige Daten (oder eben ggf. auch unbeabsichtigt: eigentlich besser geheim zu haltende Daten?) an den MQTT-Server übermittelt werden, und zum anderen eine aufwändige Nachbearbeitung auf der Gegenseite erforderlich werden kann. Daher wird hiervon '''ausdrücklich abgeraten!''' Stattdessen kann man relativ einfach über den attrTemplate-Mechanismus (nur) die Informationen über MQTT verfügbar machen, die in der Regel für externe Anwendungen auch benötigt werden.}}

==Basics zur Konfiguration der anzubindenden Geräte==
{{Randnotiz|RNTyp=g|RNText=Auch wer plant, später die Kommandos mit einer ganz anderen Software zu versenden, sollte zunächst den Weg über die Linux-Konsole und die Tools ''mosquitto_sub'' und ''mosquitto_pub'' gehen. So läßt sich die Funktionalität von FHEM und der MQTT_GENERIC_BRIDGE zunächst ohne weitere Störeinflüsse prüfen und andere User können leichter helfen, falls Probleme auftreten sollten.}}
Um gezielt einzelne Werte zu senden und auch nur gewünschte Anweisungen zu erhalten, ist stattdessen eine auf das jeweilige Gerät angepasste Konfiguration der Schnittstelle zu empfehlen. Um die hier dargestellten Schritte und deren Wirksamkeit zu prüfen, sollte der Verkehr von und zum MQTT-Server beobachtet werden. Im Folgenden werden hierfür die Programme ''mosquitto_sub'' und ''mosquitto_pub'' aus dem Paket ''mosquitto-clients'' verwendet. Auf einem ''Raspberry Pi OS'' können diese mit <code>sudo apt-get install mosquitto-clients</code> installiert werden. Beide Programme funktionieren auch mit einem MQTT2_SERVER.

Den Verkehr auf der Linux-Konsole kann man mit
mosquitto_sub -h 127.0.0.1 -i fhem-test -v -t mqttGenericBridge/# -t system/#
verfolgen, gegebenenfalls sind Username und Passwort zu ergänzen, falls die Einstellungen am Server dies erfordern (siehe ''manpage'' zu ''mosquitto_sub'').

===Readingwerte publishen===
====mqttPublish====
{{Randnotiz|RNTyp=y|RNText=Der Name der Attribute kann abweichen, falls ein anderes ''MQTT-Präfix'' über das ''Define'' in der ''MQTT_GENERIC_BRIDGE'' gesetzt ist. Hier wird davon ausgegangen, dass dieses nicht geändert wurde.}}

Um Reading-Werte von einem Gerät zu versenden, wird das Attribut ''mqttPublish'' verwendet. Im einfachsten Fall wird festgelegt, welche Readings versendet werden sollen, und unter welchem Topic. Für einen beliebigen Temperatursensor könnte dies z.B. so aussehen:
attr mySensor mqttPublish temperature:topic={"$base/$device/$name"}
In der Linux.Konsole, in der ''mosquitto_sub'' läuft, sollte jetzt bei jeder Aktualisierung des Sensor-Werts anzeigen, dass eine entsprechende Message an den MQTT-Server gesendet wurde. Dies geschieht [[Event|Event-basiert]], so dass sich hier ggf. auch insbesondere Einstellungen im Attribut [[Event-on-change-reading|event-on-change-reading]] auf die Häufigkeit der Aktualisierung auswirken.

Es können auch mehrere Readings erfasst werden, für einen typischen kombinierten Temperatur- und Luftfeuchtigkeitssensor könnte dies z.B. so aussehen:
attr mySensor mqttPublish temperature|humidity:topic={"$base/$device/$name"}
oder auch so:
attr mySensor mqttPublish temperature|humidity|battery:topic={"$base/$device/$name"}

Falls (!) erforderlich oder gewünscht, kann auch ein ''*'' als ''wildcard'' verwendet werden. Dann werden alle Readings gepublisht:
attr mySensor mqttPublish *:topic={"$base/$device/$name"}

====mqttAlias====
Verfolgt man den Verkehr eine Zeitlang, wird die Bedeutung der Variablen klarer: ''$base'' entspricht der Angabe aus den ''globalDefaults'' an der ''MQTT_GENERIC_BRIDGE'', ''$device'' wird durch den Namen des Geräts in FHEM erstetzt, und ''$name'' entspricht (noch) dem Namen des Readings.
Bis hierhin könnte man also auch statt einer MQTTT_GENERIC_BRIDGE problemlos ein [[notify]] verwenden, um die Events für direkte publish-Anweisungen am jeweiligen Interface-Modul (z.B. MQTT2_CLIENT) auszuwerten.

Eine ''MQTT_GENERIC_BRIDGE'' bietet jedoch auch für das Publishen erweiterte Funktionalitäten an. Die erste: Z.B. kann der Parameter ''$name'' - etwa zur [[DevelopmentGuidelinesReadings|Standardisierung der Namensstruktur der Readings]] - mit Hilfe des Attributs ''mqttAlias'' verändert werden. Durch die folgende Einstellung würde z.B. ein ''battery''-Wert unter dem Topic-Teil ''batteryPercent'' versendet und das Reading ''measured-temp'' unter ''temperature'':
attr mySensor mqttAlias battery=batteryPercent measured-temp=temperature

====state====
Da das Reading ''state'' in FHEM in der Regel eine Art Hauptzustand eines Geräts beschreibt, wird für die weiter unten dargestellten ''attrTemplate'' dieses Reading kein ''$name''-Anteil im Topic versendet. Ein einfaches "ein-aus"-Gerät kann man dieser Vorgabe folgend daher so konfigurieren:
attr myRelay mqttPublish state:topic={"$base/$device"}

Für ein dimmbares Licht (das als Reading ''pct'' kennt) kombiniert man beides:
attr myDimmer mqttPublish state:topic={"$base/$device"} pct:topic={"$base/$device/$name"}

Und zu guter letzt noch als farbiges (mit Reading ''rgb'') und dimmbares Licht:
attr myRGBLight mqttPublish state:topic={"$base/$device"} pct|rgb:topic={"$base/$device/$name"}

===Geräte steuern===
{{Randnotiz|RNTyp=y|RNText=Kommt als MQTT-Server MQTT2_SERVER zum Einsatz, ist beim publishen via ''mosquitto_pub'' zwingend eine ''ClientID'' mit anzugeben, andernfalls werden die so generierten Messages eventuell nicht ausgewertet!}}Um Geräte über die MQTT-Schnittstelle bedienen zu können, wird zum einen eine Software benötigt, mit der man entsprechende publish-Anweisungen generieren kann. Dies kann z.B. das bereits genannte ''mosquitto_pub'' sein.
====mqttSubscribe====
Spiegelbildlich zum o.g. ''mqttPublish''-Attribut wird über das jeweilige ''mqttSubscribe''-Attribut festgelegt, welche Topics für das FHEM-Gerät ausgewertet werden sollen und welchen Readings diese zugeordnet sind.
Für ein einfaches "ein-aus"-Gerät verwendet man daher denselben Attributwert wie für das ''mqttPublish'':
attr myRelay mqttSubscribe state:stopic={"$base/$device"}

Da wir oben in ''globalDefaults'' für ''sub:$base=mqttGenericBridge/set'' festgelegt haben, muss die Schaltanweisung allerdings an einen anderen Topic erfolgen als die Statusmeldung, die wir wegen des ''mqttPublish''-Attributs erhalten - auf diese Weise können unbeabsichtigte Schleifen unterbunden werden.

Um jetzt mit ''mosquitto_pub'' eine passende Anweisung zu erzeugen, benötigen wir eine weitere (ssh-Linux-) Konsole, über die wir dann auf dem MQTT-Weg schalten können - vorausgesetzt, das Gerät ''myRelay'' kann den Befehl <code>set myRelay on</code> (bzw. ''off'') verarbeiten. Auch hier wären ggf. die Zugangsdaten entsprechend der ''manpage'' zu ergänzen:
mosquitto_pub -h 127.0.0.1 -i fhem-test -t mqttGenericBridge/set/myRelay -m on

Bei ''mosquitto_sub'' auf der Linux-Konsole sollte jetzt zunächst die Schaltanweisung (Topic mit ''set-Element'') wie auch die Readingänderung am Device vermeldet werden.

====Geräte mit mehreren Settern====
Das Prinzip dürfte jetzt klarer sein, also versuchen wir es direkt mit unserer farbigen Leuchte:
attr myRGBLight mqttSubscribe state:stopic={"$base/$device"} pct|rgb:stopic={"$base/$device/$name"}
Und schon sollte diese über ''msoquitto_pub'' bzw. MQTT schalt- und dimmbar sein und Farbänderungen entgegennehmen - und natürlich den zugehörigen Status zurückmelden.

====mqttAlias====
Auch bei den Supscriptions besteht die Möglichkeit, ''mqttAlias'' zu verwenden und die Namen über diesen Weg zu verändern. Dies kann insbesondere sinnvoll sein, um in externen Anwendungen dann (dort) dieselben Vorlagen nutzen zu können.

====topic, stopic und atopic====
In obigem Beispiel haben wir in ''mqttSubscribe'' das Schlüsselwort ''stopic'' (die Kurzform von ''set-topic'') verwendet. Dieses bewirkt bei einer entsprechenden MQTT-Nachricht dasselbe wie der FHEM-Befehl <code>set <device> <reading> <value></code>, also <code>set myRGBLight pct 70</code>. Daneben gibt es die weiteren Schlüsselwörter ''topic'' und ''atopic''.
* ''topic'' (Langform: readings-topic) entspicht einer ''setreading''-Anweisung. Dabei wird dann lediglich der Readingwert aktualisiert, allerdings (falls Hardware gesteuert werden könnte) aber kein Schaltbefehl an die Hardware gesendet. In Installationen ohne MQTT2-Interface kann dies dazu genutzt werden, [[Dummy|dummy]]-Geräte ähnlich flexibel zu verwenden wie [[MQTT2_DEVICE]].
* ''atopic'' (Langform: attr-topic) schließlich dient dazu, Attributwerte zu ändern. ''atopic'' kann auch in ''mqttPublish'' eingesetzt werden, um Änderungen der Attribut-Werte an den MQTT-Server zu übermitteln.

===Weitere Optionen===
''MQTT_GENERIC_BRIDGE'' bietet weitere Attribute, die im Zusammenspiel teils sehr umfassende weitere Möglichkeiten ergeben, Geräte an MQTT anzubinden. Einige der Möglichkeiten, insbesondere, über ''expression'' beliebigen Perl-Code zur Auswertung bzw. Strukturierung der Daten zu verwenden, sind in den Grundzügen weiter unten dargestellt.

==Standardisierung via attrTemplate==
Insbesondere zur Anbindung externer Lösungen ist es jedoch häufig ausreichend, die Geräte-Daten in einer etwas strukturierten Weise aufzubereiten. Dies ist das Ziel der für ''MQTT_GENERIC_BRIDGE'' entwickelten ''attrTemplate''.

(tbc)

==Konfigurationsmöglichkeiten für Fortgeschrittene==

===expression===

attr ZWave_THERMOSTAT_20 mqttGB1Alias reportedState=actuator
attr ZWave_THERMOSTAT_20 mqttGB1Publish desired-temp|temperature|reportedState:topic={"$base/$device/$name"} temperature:expression={$value=~m,(-?\d+(\.\d+)?),?::round($1,1):undef} reportedState:expression={$value=~m,dim.(\d+),?$1:undef}
attr ZWave_THERMOSTAT_20 mqttGB1Subscribe desired-temp:stopic={"$base/$device/$name"}

===JSON===
json2nameValue() und toJSON() via expression

===publishes an mehrere Topics===
"das Ausrufezeichen"

(Noch nachzubearbeiten, aus dem Thread Anwendungsfälle und Beispiele für MQTT_GENERIC_BRIDGE - https://forum.fhem.de/index.php/topic,91642.msg841367.html#msg841367)
-----

eine Reading an einem beliebigen Device per MQTT setzen (für State-Reading soll state verwendet werden)
Code: [Auswählen]

attr <device-name> mqttSubscribe <reading-name>:topic=<topic>

(anstatt 'topic' kann für eine bessere Lesbarkeit 'readings-topic' verwendet werden)

ein Set-Befehl an einem beliebigen Device mit dem per MQTT gesendeten Wert ausführen
(für set ohne namen (set on, set off) soll state verwendet werden)
Code: [Auswählen]

attr <device-name> mqttSubscribe <set-befehl>:stopic=<topic>

(anstatt 'stopic' kann für eine bessere Lesbarkeit 'set-topic' verwendet werden)

ein Attribut an einem beliebigen Device per MQTT setzen
Code: [Auswählen]

attr <device-name> mqttSubscribe <attribut-name>:atopic=<topic>

(anstatt 'atopic' kann für eine bessere Lesbarkeit 'attr-topic' verwendet werden)

eine Änderung eines Readings per MQTT senen
Code: [Auswählen]

attr <device-name> mqttPublish <readings-name>:topic=<topic>

eine Änderung eines Attributes per MQTT senen
attr <device-name> mqttPublish <attribut-name>:atopic=<topic>

Verwendung von Variablen
Es können mit dem Attribute mqttDefaults Variablen definiert werden, die in mqttPublish und mqttSubscribe verwendet werden können:
Code: [Auswählen]

attr <device-name> mqttDefaults base={"allgemeinerPfad/"}
...
attr <device-name> mqttPublish <reading-name>:topic={"$base/irgendEinName"}

Weiterhin können in Topics folgende vordefinierte Variablen verwendet werden:
$reading - aktuell zu verarbeitende Reading
$device - aktulles Gerät
$name - Die Variable $name wird im Unterschied zu $reading ggf. ueber die in 'mqttAlias' definierten Aliases beeinflusst. (s. Commandref für mqttAlias)
Code: [Auswählen]

attr <device-name> mqttPublish <reading-name>:topic={"$base/$device/$name"}

Mehrere Readings auf einmal
Es können für einen Topic (sinnigerweise mit Variablen) auch mehrere Readings gleichzeitig angegeben werden. Diese müssen in diesem Fall durch ein | getrennt werden:
Code: [Auswählen]

attr <device-name> mqttPublish <reading-name1>|<reading-name2>:topic={"$base/$device/$name"}

Wildcards
mit einem * kann ein Topic für alle Readings zusammen definiert werden:
Code: [Auswählen]

attr <device-name> mqttPublish *:topic={"$base/$device/$name"}

Beim Subscribe können in der Topic-Definition auch MQTT-Wildcards (+ und #) verwendet werden.
Falls der Reading-Name mit einem '*'-Zeichen am Anfang definiert wird, gilt dieser als 'Platzhalter'. Der tatsaechliche Name der Reading (und ggf. des Geraetes) wird dabei durch Variablen aus dem Topic definiert ($reading, $name). Im Topic wirken diese Variablen als Wildcards, macht natuerlich nur Sinn, wenn Reading-Name auch nicht fest definiert ist (also faengt mit '*' an).

-----------------

Sensoren-Werte von einer FHEM-Instanz in eine andere übertragen

Definition für ein HomeMatic-Device (Dirk's-Sensor + Verwendung von DevPoint-Modul):
(es werden gezielt bestimmte Werte übertragen)
Code: [Auswählen]

defmod <sensor-device-name> CUL_HM xxxxxx
attr <sensor-device-name> model HB-UW-Sen-THPL-I
...
attr <sensor-device-name> mqttDefaults base=haus/wohnzimmer
attr <sensor-device-name> mqttPublish humidity|luminosity|dewpoint|absoluteHumidity:topic={"$base/klima/$name"}

Definition eines Empfänger-Dummy:
(es werden alle Werte bei passenden Topics empfangen)
Code: [Auswählen]

defmod <dummy-device-name> dummy
attr <dummy-device-name> readingList absoluteHumidity dewpoint humidity luminosity temperature vapourPressure
attr <dummy-device-name> mqttDefaults base=haus/wohnzimmer
attr <dummy-device-name> mqttSubscribe *:topic={"$base/klima/$reading"}

« Letzte Änderung: 11 Januar 2019, 21:31:38 von hexenmeister »

-------------------------

Aktoren, die in einer FHEM-Instanz definiert sind, aus einer anderen schalten
Switch

Definition eines Schalters (EnOcean FSR14)
Code: [Auswählen]

defmod <actor-device-name> EnOcean 0000000B
attr <actor-device-name> IODev FGW14
attr <actor-device-name> alias Licht
attr <actor-device-name> devStateIcon off:light_light_dim_00@gray on:light_light_dim_100@yellow .*:hourglass
attr <actor-device-name> eep A5-38-08
attr <actor-device-name> group Beleuchtung
attr <actor-device-name> gwCmd switching
attr <actor-device-name> icon light_downlight
attr <actor-device-name> manufID 00D
attr <actor-device-name> mqttPublish state:topic=haus/wohnzimmer/licht/top/state
attr <actor-device-name> mqttSubscribe state:stopic=haus/wohnzimmer/licht/top/set
attr <actor-device-name> room Wohnzimmer
attr <actor-device-name> subDef 0010000B
attr <actor-device-name> subType gateway
attr <actor-device-name> webCmd on:off

------------------------

Aktoren, die in einer FHEM-Instanz definiert sind, aus einer anderen schalten
Dimmer

Aktor-Definition:
Code: [Auswählen]

defmod <actor-device-name> CUL_HM xxxxxx
attr <actor-device-name> model HM-LC-Dim1TPBU-FM
...
attr <actor-device-name> mqttPublish pct:topic=haus/wohnzimmer/licht/level state:topic=haus/wohnzimmer/licht/state
attr <actor-device-name> mqttSubscribe pct:stopic=haus/wohnzimmer/licht/set

------------------------

Aktoren, die in einer FHEM-Instanz definiert sind, aus einer anderen schalten
Shutters / Blinds

Aktor-Definition:
Code: [Auswählen]

defmod <actor-device-name> CUL_HM xxxxxx
attr <actor-device-name> model HM-LC-Bl1PBU-FM
...
attr <actor-device-name> mqttPublish pct:topic=haus/wohnzimmer/rollo/all/position state:topic=haus/wohnzimmer/rollo/all/state
attr <actor-device-name> mqttSubscribe pct:stopic=haus/wohnzimmer/rollo/all/set

==FAQ==

Das ist so nicht vorgesehen, ein reading = ein Topic.

a) beim device-count werden nur Geräte gezählt, die mit eigenen mqtt*-Attributen versehen sind. Bei einer globalen Definition 'globalPublish' kann die Bridge nicht (ohne weiteres) wissen, welche Geräte angesprochen werden sollen. Daher wird auch nichts gezählt.

b) mqttSubscribe ist gedacht für diejenigen Geräte, die per MQTT 'versorgt' werden sollen. Die Bridge selbst gehört nicht dazu. Aus technischen Gründen kann es sein, dass diese Attribute trotzdem vom FHEM angeboten werden, gesetzt werden können sie jedoch nicht, die Bridge 'währt' sich dagegen.
Ein 'globalSubscribe' gibt es nicht. Ich habe mich entschieden, diese Festure nicht anzubieten. Bei unbedachten Verwendung könnte ein großes Sicherheitsrisiko entstehen. Einfach diese Attribute an den gewünschgten Devices erstellen.

Die Definition lautet 'fhem room=MQTT_BRIDGE_DEVICES'. Der erste Parameter (wie im Commandref steht) ist der Prefix für die Optionsattribute. Ist für Sonderfälle gedacht, wenn mehr als eine Bridge im System vorhanen ist. Deine Parameter heißen also 'fhemSubscribe' etc.

Bin nun draufgekommen das dieses fehlerhafte Verhalten (Bridge geht nicht nach restart so lange bis man im User Interface DEF und "modify" geklickt hat) nur dann auftritt wenn device-count = 0 ist. Nun hab ich ein Device mit einem "fhemSubscribe" Attribut ausgestattet ... und nun lebt die Bridge auch nach einem Restart.

Du kannst aber mit * alle Readings greifen und dann mit Perlmitteln in der expression filtern.

irgendwie so (ungetestet):
Code: [Auswählen]

desired-temp!info:expression={if($reading=~/SMAEM12345678.*/){$value}else{undef})}

== Hinweise ==
<references />

[[Kategorie:HOWTOS]]
[[Kategorie:MQTT]]

RHASSPY/Schnellstart

2022-09-18T09:03:10Z

Beta-User: obsoletes Bild entfernt

[[File:Rhasspy Webinterface.png|thumb|right|Das Rhasspy-Webinterface nach erfolgreicher Installation und Aufruf des ersten Intents (GetTime)]]

==Installation von Rhasspy==
Empfohlen wird, Rhasspy als [https://www.docker.com/ Docker Container] zu installieren. Und zwar aus folgenden Gründen:
* Alle Software-Abhängigkeiten sind aufgelöst
* Es kommt zu keinen Konflikten mit Abhängigkeiten anderer Anwendungen (Python-Version, Paket-Versionen, ...)
* Wird der Container wieder gelöscht, ist Rhasspy vollständig vom System entfernt
Soll Docker verwendet werden, finden sich am [[#Anhang|Ende dieser Anleitung]] zwei Docker-Compose Dateien für den schnellen Einstieg.
Dazu bitte '''mit einer Ausnahme''' der Anleitung in der [https://rhasspy.readthedocs.io/en/latest/#getting-started offiziellen Dokumentation] folgen.
Die Ausnahme ergibt sich daraus, dass für den schnellen Einstieg der ''interne'' MQTT-Server von Rhasspy genutzt werden soll. Dieser ist auf dem Port 12183 erreichbar, der beim Start des Docker Containers auch mit ''exposed'' werden muss.

Das Kommando zum Starten des Docker-Images lautet deshalb korrekterweise

docker run -d -p 12101:12101 -p 12183:12183\
--name rhasspy \
--restart unless-stopped \
-v "$HOME/.config/rhasspy/profiles:/profiles" \
-v "/etc/localtime:/etc/localtime:ro" \
--device /dev/snd:/dev/snd \
rhasspy/rhasspy \
--user-profiles /profiles \
--profile en

Danach bitte alle weiteren in der nachfolgenden Anleitung beschriebenen Schritte ausführen. Der "Schnellstart" ist erst abgeschlossen, wenn im [https://rhasspy.readthedocs.io/en/latest/#web-interface Web-Interface von Rhasspy] der gesprochene Testsatz '''''wie spät ist es''''' erkannt wird und links als erkannter Intent '''''GetTime''''' angezeigt wird.

==Installation des FHEM Moduls==
Das RHASSPY-Modul ist seit Sept. 2022 über das reguläre FHEM-update verfügbar und muss nicht mehr gesondert in das Modulverzeichnis kopiert werden.

==Einrichtung des MQTT2_CLIENT==
[[File:Rhasspy02.png|right|thumb|Ein erfolgreich mit Rhasspy verbundenes MQTT2_CLIENT Device]]
Rhasspy kommuniziert hauptsächlich über das [[MQTT]]-Protokoll, und zwar sowohl Rhasspy-intern, als 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 und die für FHEM relevanten Daten über einen [[MQTT2_CLIENT]] bezogen werden.

Dieses Beispiel geht davon aus, dass Rhasspy auf dem selben Gerät installiert ist, auf dem auch FHEM läuft.

<syntaxhighlight lang="text">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>

Läuft Rhasspy auf einem anderen Server und/oder wird ein anderer Port verwendet, sind die passenden Daten im obigen ''defmod'' entsprechend anzupassen. Typischerweise ist der Rhasspy-interne MQTT-Server eines extern laufenden Rhasspy unter der Portnummer 12183 zu erreichen, die Definition wäre dann also

<syntaxhighlight lang="text">
defmod rhasspyMQTT2 MQTT2_CLIENT <IP-Adresse>:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>

Hat alles funktioniert, steht '''opened''' im ''STATE'' dieses Devices.
 

== Define eines RHASSPY Devices ==
Läuft der Rhasspy-Dienst auf derselben Maschine mit den Standardeinstellungen, genügt für ein erstes Kennenlernen:
define rhasspy RHASSPY
Für einen entfernten Rhasspy-Dienst muss angeben werden, wo dessen '''Web-Interface''' zu erreichen ist:
defmod rhasspy RHASSPY baseUrl=http://192.168.1.210:12101

Dieser Schritt war erfolgreich, wenn
* im Device rhasspy ein Reading '''intents''' vorhanden ist, das z.B. den Wert ''GetTime'' enthält, und
* '''STATE''' dieses Devices auf ''online'' gegangen ist.

==Spracheinstellungen==
===Basissprache===
{{Randnotiz|RNTyp=Info|RNText=Wird die Sprache im Device global nach Definition des RHASSPY-Devices geändert, kann es notwendig sein, die DEF des RHASSPY-Devices einmal ohne Änderungen zu bearbeiten (z.B. ein Leerzeichen anfügen).}}
[[File:Rhasspy05.png|thumb|rhasspy mit deutscher Spracheinstellung]]
In diesem Beispiel soll deutsch mit dem Sprachassistenten gesprochen werden. Das bedeutet
# Rhasspy - also die Anwendung im Docker-Container - muss ein deutsches Profil verwenden
# rhasspy - also das FHEM-Device - muss auf die deutsche Sprache eingestellt sein
# Eine deutsche [[#Sprachdatei|Sprachdatei]] muss installiert sein

Welche Sprache das Device rhasspy verwendet, ist am '''Internal''' ''LANGUAGE'' zu erkennen.

Sollte dieses Internal nicht '''de''' anzeigen, gibt es zwei Möglichkeiten, dies zu ändern:
# im FHEM-Device '''global''' wird das Attribut ''language'' auf ''DE'' eingestellt oder
# die Definition des rhasspy-Devices um ''language=de'' ergänzt.

defmod rhasspy RHASSPY language=de

===Sprachdatei===
Das Modul RHASSPY enthält einige vorgefertigte Antwortsätze für diverse Situationen. Um diese von Englisch auf Deutsch umzustellen, wird eine zusätzliche (Muster-) Sprachdatei benötigt, die man mit folgendem Befehl erhält:
{ Svn_GetFile('contrib/RHASSPY/rhasspy-de.cfg', './rhasspy-de.cfg') }

Ergänzend muss dem Device rhasspy mitgeteilt werden, wo diese zu finden ist:
attr rhasspy languageFile ./rhasspy-de.cfg

Dieser Schritt war erfolgreich, wenn der Befehl <code>list rhasspy</code> einen Abschnitt ''lng'' enthält, der deutsche Antworten auflistet.

== Erste Interaktion ==
[[File:Rhasspy06.png|thumb|Anpassung eines erstens Intents nach der Schnellstart-Anleitung]]
Um dem Sprachassistenten jetzt eine Antwort auf eine Frage zu entlocken, muss zuerst im Webinterface von Rhasspy - also in der Anwendung im Docker-Container - im Menüpunkt [https://rhasspy.readthedocs.io/en/latest/tutorials/#training Sentences] ein Intent erstellt werden. Für diese Schnellstart-Anleitung wird aber einfach der standardmäßig in Rhasspy vorhandene Intent ''[GetTime]'' verwendet. Um diesen aber benutzen zu können, muss er vorher umbenannt werden. Jede Instanz des RHASSPY-Moduls reagiert nur auf Intents, die "für sie" bestimmt und daher entsprechend gekennzeichnet sind. Diese Kennungzeichnung besteht aus:
# dem '''''language''-Kürzel''' (z.B. <code>de</code>),
# der '''''fhemId''''' (z.B. <code>fhem</code>) und
# dem '''Intent-Namen''' (z.B. <code>GetTime</code>).

Der Name des Intents ist daher in der ''sentences.ini'' wie folgt zu ändern:
<syntaxhighlight lang="text">
[de.fhem:GetTime]
wie spät ist es
sag mir die uhrzeit
</syntaxhighlight>

Jetzt kann der Sprachassistent nach der aktuellen Uhrzeit gefragt werden. Ist alles richtig konfiguriert, wird er diese Frage auf deutsch beantworten und die Readings des Moduls werden mit entsprechenden Werten befüllt.

==Ein Gerät mit Rhasspy verbinden==
[[File:Rhasspy08.png|thumb|Erfolgreich befüllter Slot mit dem Alias der Lampe]]
[[File:Rhasspy07.png|thumb|Erfolgreich erstellte Helper für eine Lampe im RHASSPY Modul]]
Wenn nach dieser Anleitung vorgegangen wurde, ist das Modul so konfiguriert, dass es Rhasspy alle FHEM-Devices bekannt macht, bei denen das Attribut '''genericDeviceType''' definiert ist.

Für die Verbindung eines FHEM-Devices mit Rhasspy sind also folgende Schritte auszuführen:
# '''genericDeviceType''' Attribut bei einem Device setzen (z.B. ''switch'')
# einen "sprechbaren" Namen im Attribut '''alias''' vergeben
# <code>set rhasspy update devicemap</code> ausführen, um das Device Rhasspy bekannt zu machen

Anhand einer Lampe "Office", die sich nur ein- und ausschalten lässt, könnte das z.B. so aussehen:
<syntaxhighlight lang="text">
attr Office genericDeviceType switch
attr Office alias Licht
</syntaxhighlight>

Der ''genericDeviceType'' '''switch''' gibt für ein Gerät vor, dass es sich nur ein- und ausschalten lässt. Beim Typ '''light''' z.B. könnte man auch noch die Helligkeit und die Farbe regulieren.
Der ''alias'' '''Licht''' bewirkt, dass in Zukunft einfach "Licht aus" oder "Licht an" gesagt werden kann. Dazu aber später mehr.

Die Lampe ist somit fertig vorbereitet.

Damit Rhasspy auch von diesem Gerät erfährt, muss FHEM ihm davon erzählen. Das passiert, in dem folgender Befehl ausgeführt wird:
set rhasspy update devicemap
Darauf hin werden mehrere Aktionen durchgeführt:
* Es werden in Rhasspy Slots erstellt, die später in Intents verwenden werden können
* Diese Slots werden mit den Daten befüllt, die in FHEM für die Verwendung in Rhasspy konfiguriert wurden. In diesem Fall nur der Alias dieser Lampe
* Ein Training von Rhasspy wird angestoßen, damit Rhasspy das Gerät in gesprochenen Sätzen erkennt

Ob alles funktioniert hat, lässt sich an drei Dingen erkennen:
# Es gibt neue Slots in Rhasspy bzw. bereits vorhandene wurden mit neuen Werten ergänzt
# Ein <code>list rhasspy</code> enthält den Helper '''devicemap''' mit den konfigurierten Geräten und dessen Steuermöglichkeiten (''intents'')
# In den Readings ''udpateSlots'' und ''training'' des Moduls ist kein Fehler zu erkennen (unter Umständen die Seite im Browser aktualisieren, wenn die Readings noch nicht vorhanden sind)

==Einen ersten Intent erstellen==
{{Randnotiz|RNTyp=Info|RNText=Dieses Beispiel enthält bereits einige Sprech-Alternativen und optionale Elemente. Die vorhandenen Möglichkeiten sind zum Einen der offiziellen Dokumentation zu entnehmen, zur Vertiefung gibt es in den Links unten ein sehr informatives Video.}}
[[File:Rhasspy09.png|thumb|Ein erfolgreich von RHASSPY empfangener und umgesetzter Sprachbefehl]]
Um die konfigurierte Lampe schlussendlich auch steuern zu können, muss Rhasspy noch wissen, was nach einem erkannten Sprachbefehl anfangen soll. Dazu werden in Rhasspy Sentences/Intents erstellt. Im Falle dieser Lampe, reicht ein einfacher SetOnOff-Intent. Sie kann ja nicht mehr.

Da der Intent aber potentiell für mehrere Geräte dienen können soll, wird es etwas komplizierter, als beim ''GetTime'' Intent. Allerdings hat dsa Modul schon passende Slots erstellt, die in eigenen Intents verwendet werden können. Zusätzlich müssen aber ''Tags'' verwendet, damit das Modul dann unterscheiden kann, ob ein von Rhasspy geliefertes Wort ein Gerät, ein Raum oder ein Nummernwert ist.

Ein ganz einfacher Intent, um die Lampe ein- und ausschalten zu können, kann z.B. so aussehen:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
schalte das $de.fhem.Device-SetOnOff{Device} ( an{Value:on} | aus{Value:off})
</syntaxhighlight>

Kurz umrissen bedeuten die Teile des Satzes:
* '''$de.fhem.Device-SetOnOff''' ist der Slot, der die Geräte enthält, die mit diesem Intent gesteuert werden sollen. Das Dollarzeichen am Anfang des Slots wird gerne vergessen, darauf also besonders gut aufpassen
* '''{Device}''' ist ein Tag, der dem FHEM-Modul und Rhasspy verrät, dass es sich bei diesem Wort um ein Device handelt. Wichtig bei Tags, die in Verbindung mit diesem Modul verwendet werden ist, dass sie '''immer''' mit einem Großbuchstaben beginnen!
* '''( ... | ... )''' ist eine Gruppe. Wobei die runden Klammern eine Gruppe beschreiben, die einzelnen Mitglieder dieser Gruppe werden durch die "Pipe" getrennt. In diesem konkreten Fall bedeutet es, der Wert kann "an" ODER "aus" sein
*'''{Value:on}'''/'''{Value:off}''' ist wieder ein Tag. Dieser gibt an, dass es sich beim übergebenen Wort um einen Wert handelt. Da das Modul aber die deutschen Wörter "an" und "aus" nicht versteht, müssen hier Synonyme verwendet werden. Das sind jeweils die Werte hinter dem Doppelpunkt.

'''Wichtig:''' Da mit Erstellen des ersten Intents wieder Änderungen an der Konfiguration vorgenommen wurden, muss jetzt wieder ein <code>set rhasspy update all</code> ausgeführt werden. In diesem Fall, damit das Modul vom neuen Intent erfährt.

Ist man dieser Schnellstart-Anleitung gefolgt, können aus diesem Satz mit der vorhandenen Lampe jetzt zwei gesprochene Sätze gebildet werden:
<syntaxhighlight lang="text">
schalte das licht an
schalte das licht aus
</syntaxhighlight>

Die Infos, die daraus resultierend nach einem Sprachbefehl "schalte das licht an" im FHEM-Modul ankommen sind dann unter anderem:
<syntaxhighlight lang="text">
"intent":"SetOnOff"
"Device":"licht"
"Value":"on"
</syntaxhighlight>

==Schlusswort==
Sind alle Punkte dieser Schnellstart-Anleitung erfolgreich abgeschlossen, kann damit begonnen werden, das Device rhasspy auf die eigenen Bedürfnisse anzupassen und weitere Geräte damit zu steuern. Alle Informationen dazu finden sich auf der Hauptseite von [[RHASSPY]] sowie in der [[RHASSPY/Vertiefung]].

==Anhang==
===Docker-Compose File - Base===
<syntaxhighlight lang="yaml">
version: '3'

services:
rhasspy:
image: "rhasspy/rhasspy"
container_name: rhasspy
restart: unless-stopped
volumes:
- ".config/rhasspy/profiles:/profiles"
- /etc/timezone:/etc/timezone:ro
ports:
- "12101:12101"
- "12183:12183"
command: --user-profiles /profiles --profile de
environment:
- TZ=Europe/Berlin
</syntaxhighlight>

===Docker-Compose File - Satellite===
<syntaxhighlight lang="yaml">
version: '3'

services:
rhasspy:
image: "rhasspy/rhasspy"
container_name: rhasspy
restart: unless-stopped
volumes:
- ".config/rhasspy/profiles:/profiles"
- "/etc/localtime:/etc/localtime:ro"
- "/etc/asound.conf:/etc/asound.conf"
ports:
- "12101:12101"
command: --user-profiles /profiles --profile de
devices:
- "/dev/snd:/dev/snd"
ipc: host
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Adroid-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]

[[Category:HOWTOS]]
[[Category:Sprachsteuerung]]

RHASSPY/Schnellstart

2022-09-18T08:56:28Z

Beta-User: /* Installation des FHEM Moduls */

[[File:Rhasspy Webinterface.png|thumb|right|Das Rhasspy-Webinterface nach erfolgreicher Installation und Aufruf des ersten Intents (GetTime)]]

==Installation von Rhasspy==
Empfohlen wird, Rhasspy als [https://www.docker.com/ Docker Container] zu installieren. Und zwar aus folgenden Gründen:
* Alle Software-Abhängigkeiten sind aufgelöst
* Es kommt zu keinen Konflikten mit Abhängigkeiten anderer Anwendungen (Python-Version, Paket-Versionen, ...)
* Wird der Container wieder gelöscht, ist Rhasspy vollständig vom System entfernt
Soll Docker verwendet werden, finden sich am [[#Anhang|Ende dieser Anleitung]] zwei Docker-Compose Dateien für den schnellen Einstieg.
Dazu bitte '''mit einer Ausnahme''' der Anleitung in der [https://rhasspy.readthedocs.io/en/latest/#getting-started offiziellen Dokumentation] folgen.
Die Ausnahme ergibt sich daraus, dass für den schnellen Einstieg der ''interne'' MQTT-Server von Rhasspy genutzt werden soll. Dieser ist auf dem Port 12183 erreichbar, der beim Start des Docker Containers auch mit ''exposed'' werden muss.

Das Kommando zum Starten des Docker-Images lautet deshalb korrekterweise

docker run -d -p 12101:12101 -p 12183:12183\
--name rhasspy \
--restart unless-stopped \
-v "$HOME/.config/rhasspy/profiles:/profiles" \
-v "/etc/localtime:/etc/localtime:ro" \
--device /dev/snd:/dev/snd \
rhasspy/rhasspy \
--user-profiles /profiles \
--profile en

Danach bitte alle weiteren in der nachfolgenden Anleitung beschriebenen Schritte ausführen. Der "Schnellstart" ist erst abgeschlossen, wenn im [https://rhasspy.readthedocs.io/en/latest/#web-interface Web-Interface von Rhasspy] der gesprochene Testsatz '''''wie spät ist es''''' erkannt wird und links als erkannter Intent '''''GetTime''''' angezeigt wird.

==Installation des FHEM Moduls==
[[File:Rhasspy03.png|thumb|right|Installation/Update des RHASSPY Moduls via Kommando-Feld]]
Das RHASSPY-Modul ist seit Sept. 2022 über das reguläre FHEM-update verfügbar und muss nicht mehr gesondert in das Modulverzeichnis kopiert werden.

==Einrichtung des MQTT2_CLIENT==
[[File:Rhasspy02.png|right|thumb|Ein erfolgreich mit Rhasspy verbundenes MQTT2_CLIENT Device]]
Rhasspy kommuniziert hauptsächlich über das [[MQTT]]-Protokoll, und zwar sowohl Rhasspy-intern, als 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 und die für FHEM relevanten Daten über einen [[MQTT2_CLIENT]] bezogen werden.

Dieses Beispiel geht davon aus, dass Rhasspy auf dem selben Gerät installiert ist, auf dem auch FHEM läuft.

<syntaxhighlight lang="text">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>

Läuft Rhasspy auf einem anderen Server und/oder wird ein anderer Port verwendet, sind die passenden Daten im obigen ''defmod'' entsprechend anzupassen. Typischerweise ist der Rhasspy-interne MQTT-Server eines extern laufenden Rhasspy unter der Portnummer 12183 zu erreichen, die Definition wäre dann also

<syntaxhighlight lang="text">
defmod rhasspyMQTT2 MQTT2_CLIENT <IP-Adresse>:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>

Hat alles funktioniert, steht '''opened''' im ''STATE'' dieses Devices.
 

== Define eines RHASSPY Devices ==
Läuft der Rhasspy-Dienst auf derselben Maschine mit den Standardeinstellungen, genügt für ein erstes Kennenlernen:
define rhasspy RHASSPY
Für einen entfernten Rhasspy-Dienst muss angeben werden, wo dessen '''Web-Interface''' zu erreichen ist:
defmod rhasspy RHASSPY baseUrl=http://192.168.1.210:12101

Dieser Schritt war erfolgreich, wenn
* im Device rhasspy ein Reading '''intents''' vorhanden ist, das z.B. den Wert ''GetTime'' enthält, und
* '''STATE''' dieses Devices auf ''online'' gegangen ist.

==Spracheinstellungen==
===Basissprache===
{{Randnotiz|RNTyp=Info|RNText=Wird die Sprache im Device global nach Definition des RHASSPY-Devices geändert, kann es notwendig sein, die DEF des RHASSPY-Devices einmal ohne Änderungen zu bearbeiten (z.B. ein Leerzeichen anfügen).}}
[[File:Rhasspy05.png|thumb|rhasspy mit deutscher Spracheinstellung]]
In diesem Beispiel soll deutsch mit dem Sprachassistenten gesprochen werden. Das bedeutet
# Rhasspy - also die Anwendung im Docker-Container - muss ein deutsches Profil verwenden
# rhasspy - also das FHEM-Device - muss auf die deutsche Sprache eingestellt sein
# Eine deutsche [[#Sprachdatei|Sprachdatei]] muss installiert sein

Welche Sprache das Device rhasspy verwendet, ist am '''Internal''' ''LANGUAGE'' zu erkennen.

Sollte dieses Internal nicht '''de''' anzeigen, gibt es zwei Möglichkeiten, dies zu ändern:
# im FHEM-Device '''global''' wird das Attribut ''language'' auf ''DE'' eingestellt oder
# die Definition des rhasspy-Devices um ''language=de'' ergänzt.

defmod rhasspy RHASSPY language=de

===Sprachdatei===
Das Modul RHASSPY enthält einige vorgefertigte Antwortsätze für diverse Situationen. Um diese von Englisch auf Deutsch umzustellen, wird eine zusätzliche (Muster-) Sprachdatei benötigt, die man mit folgendem Befehl erhält:
{ Svn_GetFile('contrib/RHASSPY/rhasspy-de.cfg', './rhasspy-de.cfg') }

Ergänzend muss dem Device rhasspy mitgeteilt werden, wo diese zu finden ist:
attr rhasspy languageFile ./rhasspy-de.cfg

Dieser Schritt war erfolgreich, wenn der Befehl <code>list rhasspy</code> einen Abschnitt ''lng'' enthält, der deutsche Antworten auflistet.

== Erste Interaktion ==
[[File:Rhasspy06.png|thumb|Anpassung eines erstens Intents nach der Schnellstart-Anleitung]]
Um dem Sprachassistenten jetzt eine Antwort auf eine Frage zu entlocken, muss zuerst im Webinterface von Rhasspy - also in der Anwendung im Docker-Container - im Menüpunkt [https://rhasspy.readthedocs.io/en/latest/tutorials/#training Sentences] ein Intent erstellt werden. Für diese Schnellstart-Anleitung wird aber einfach der standardmäßig in Rhasspy vorhandene Intent ''[GetTime]'' verwendet. Um diesen aber benutzen zu können, muss er vorher umbenannt werden. Jede Instanz des RHASSPY-Moduls reagiert nur auf Intents, die "für sie" bestimmt und daher entsprechend gekennzeichnet sind. Diese Kennungzeichnung besteht aus:
# dem '''''language''-Kürzel''' (z.B. <code>de</code>),
# der '''''fhemId''''' (z.B. <code>fhem</code>) und
# dem '''Intent-Namen''' (z.B. <code>GetTime</code>).

Der Name des Intents ist daher in der ''sentences.ini'' wie folgt zu ändern:
<syntaxhighlight lang="text">
[de.fhem:GetTime]
wie spät ist es
sag mir die uhrzeit
</syntaxhighlight>

Jetzt kann der Sprachassistent nach der aktuellen Uhrzeit gefragt werden. Ist alles richtig konfiguriert, wird er diese Frage auf deutsch beantworten und die Readings des Moduls werden mit entsprechenden Werten befüllt.

==Ein Gerät mit Rhasspy verbinden==
[[File:Rhasspy08.png|thumb|Erfolgreich befüllter Slot mit dem Alias der Lampe]]
[[File:Rhasspy07.png|thumb|Erfolgreich erstellte Helper für eine Lampe im RHASSPY Modul]]
Wenn nach dieser Anleitung vorgegangen wurde, ist das Modul so konfiguriert, dass es Rhasspy alle FHEM-Devices bekannt macht, bei denen das Attribut '''genericDeviceType''' definiert ist.

Für die Verbindung eines FHEM-Devices mit Rhasspy sind also folgende Schritte auszuführen:
# '''genericDeviceType''' Attribut bei einem Device setzen (z.B. ''switch'')
# einen "sprechbaren" Namen im Attribut '''alias''' vergeben
# <code>set rhasspy update devicemap</code> ausführen, um das Device Rhasspy bekannt zu machen

Anhand einer Lampe "Office", die sich nur ein- und ausschalten lässt, könnte das z.B. so aussehen:
<syntaxhighlight lang="text">
attr Office genericDeviceType switch
attr Office alias Licht
</syntaxhighlight>

Der ''genericDeviceType'' '''switch''' gibt für ein Gerät vor, dass es sich nur ein- und ausschalten lässt. Beim Typ '''light''' z.B. könnte man auch noch die Helligkeit und die Farbe regulieren.
Der ''alias'' '''Licht''' bewirkt, dass in Zukunft einfach "Licht aus" oder "Licht an" gesagt werden kann. Dazu aber später mehr.

Die Lampe ist somit fertig vorbereitet.

Damit Rhasspy auch von diesem Gerät erfährt, muss FHEM ihm davon erzählen. Das passiert, in dem folgender Befehl ausgeführt wird:
set rhasspy update devicemap
Darauf hin werden mehrere Aktionen durchgeführt:
* Es werden in Rhasspy Slots erstellt, die später in Intents verwenden werden können
* Diese Slots werden mit den Daten befüllt, die in FHEM für die Verwendung in Rhasspy konfiguriert wurden. In diesem Fall nur der Alias dieser Lampe
* Ein Training von Rhasspy wird angestoßen, damit Rhasspy das Gerät in gesprochenen Sätzen erkennt

Ob alles funktioniert hat, lässt sich an drei Dingen erkennen:
# Es gibt neue Slots in Rhasspy bzw. bereits vorhandene wurden mit neuen Werten ergänzt
# Ein <code>list rhasspy</code> enthält den Helper '''devicemap''' mit den konfigurierten Geräten und dessen Steuermöglichkeiten (''intents'')
# In den Readings ''udpateSlots'' und ''training'' des Moduls ist kein Fehler zu erkennen (unter Umständen die Seite im Browser aktualisieren, wenn die Readings noch nicht vorhanden sind)

==Einen ersten Intent erstellen==
{{Randnotiz|RNTyp=Info|RNText=Dieses Beispiel enthält bereits einige Sprech-Alternativen und optionale Elemente. Die vorhandenen Möglichkeiten sind zum Einen der offiziellen Dokumentation zu entnehmen, zur Vertiefung gibt es in den Links unten ein sehr informatives Video.}}
[[File:Rhasspy09.png|thumb|Ein erfolgreich von RHASSPY empfangener und umgesetzter Sprachbefehl]]
Um die konfigurierte Lampe schlussendlich auch steuern zu können, muss Rhasspy noch wissen, was nach einem erkannten Sprachbefehl anfangen soll. Dazu werden in Rhasspy Sentences/Intents erstellt. Im Falle dieser Lampe, reicht ein einfacher SetOnOff-Intent. Sie kann ja nicht mehr.

Da der Intent aber potentiell für mehrere Geräte dienen können soll, wird es etwas komplizierter, als beim ''GetTime'' Intent. Allerdings hat dsa Modul schon passende Slots erstellt, die in eigenen Intents verwendet werden können. Zusätzlich müssen aber ''Tags'' verwendet, damit das Modul dann unterscheiden kann, ob ein von Rhasspy geliefertes Wort ein Gerät, ein Raum oder ein Nummernwert ist.

Ein ganz einfacher Intent, um die Lampe ein- und ausschalten zu können, kann z.B. so aussehen:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
schalte das $de.fhem.Device-SetOnOff{Device} ( an{Value:on} | aus{Value:off})
</syntaxhighlight>

Kurz umrissen bedeuten die Teile des Satzes:
* '''$de.fhem.Device-SetOnOff''' ist der Slot, der die Geräte enthält, die mit diesem Intent gesteuert werden sollen. Das Dollarzeichen am Anfang des Slots wird gerne vergessen, darauf also besonders gut aufpassen
* '''{Device}''' ist ein Tag, der dem FHEM-Modul und Rhasspy verrät, dass es sich bei diesem Wort um ein Device handelt. Wichtig bei Tags, die in Verbindung mit diesem Modul verwendet werden ist, dass sie '''immer''' mit einem Großbuchstaben beginnen!
* '''( ... | ... )''' ist eine Gruppe. Wobei die runden Klammern eine Gruppe beschreiben, die einzelnen Mitglieder dieser Gruppe werden durch die "Pipe" getrennt. In diesem konkreten Fall bedeutet es, der Wert kann "an" ODER "aus" sein
*'''{Value:on}'''/'''{Value:off}''' ist wieder ein Tag. Dieser gibt an, dass es sich beim übergebenen Wort um einen Wert handelt. Da das Modul aber die deutschen Wörter "an" und "aus" nicht versteht, müssen hier Synonyme verwendet werden. Das sind jeweils die Werte hinter dem Doppelpunkt.

'''Wichtig:''' Da mit Erstellen des ersten Intents wieder Änderungen an der Konfiguration vorgenommen wurden, muss jetzt wieder ein <code>set rhasspy update all</code> ausgeführt werden. In diesem Fall, damit das Modul vom neuen Intent erfährt.

Ist man dieser Schnellstart-Anleitung gefolgt, können aus diesem Satz mit der vorhandenen Lampe jetzt zwei gesprochene Sätze gebildet werden:
<syntaxhighlight lang="text">
schalte das licht an
schalte das licht aus
</syntaxhighlight>

Die Infos, die daraus resultierend nach einem Sprachbefehl "schalte das licht an" im FHEM-Modul ankommen sind dann unter anderem:
<syntaxhighlight lang="text">
"intent":"SetOnOff"
"Device":"licht"
"Value":"on"
</syntaxhighlight>

==Schlusswort==
Sind alle Punkte dieser Schnellstart-Anleitung erfolgreich abgeschlossen, kann damit begonnen werden, das Device rhasspy auf die eigenen Bedürfnisse anzupassen und weitere Geräte damit zu steuern. Alle Informationen dazu finden sich auf der Hauptseite von [[RHASSPY]] sowie in der [[RHASSPY/Vertiefung]].

==Anhang==
===Docker-Compose File - Base===
<syntaxhighlight lang="yaml">
version: '3'

services:
rhasspy:
image: "rhasspy/rhasspy"
container_name: rhasspy
restart: unless-stopped
volumes:
- ".config/rhasspy/profiles:/profiles"
- /etc/timezone:/etc/timezone:ro
ports:
- "12101:12101"
- "12183:12183"
command: --user-profiles /profiles --profile de
environment:
- TZ=Europe/Berlin
</syntaxhighlight>

===Docker-Compose File - Satellite===
<syntaxhighlight lang="yaml">
version: '3'

services:
rhasspy:
image: "rhasspy/rhasspy"
container_name: rhasspy
restart: unless-stopped
volumes:
- ".config/rhasspy/profiles:/profiles"
- "/etc/localtime:/etc/localtime:ro"
- "/etc/asound.conf:/etc/asound.conf"
ports:
- "12101:12101"
command: --user-profiles /profiles --profile de
devices:
- "/dev/snd:/dev/snd"
ipc: host
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Adroid-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]

[[Category:HOWTOS]]
[[Category:Sprachsteuerung]]

RHASSPY

2022-09-18T08:54:48Z

Beta-User: Installation auf reguläres update angepaßt

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung des RHASSPY Moduls ===
Das Modul ist seit September 2022 im regulären FHEM-update enthalten.

== 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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

== Set-Befehle (SET) ==

=== customSlot ===
Erstellt einen neuen - oder überschreibt einen alten - Slot in Rhasspy
* <code>slotname</code> und <code>slotdata</code> sind verpflichtend
* <code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
* <code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

=== fetchSiteIds ===
Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

=== play ===
Sendet eine WAV Datei an Rhasspy, <code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

=== speak ===
Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.

Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!

'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

=== textCommand ===
Sendet ein Text-Kommando an Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>
Mangels siteId erfolgt hier keine Rückmeldung zum ausgeführten Kommando.

=== trainRhasspy ===
Startet das Training von Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

=== update ===
''update'' kennt diverse Abstufungen:

==== update devicemap ====
Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.) und ein Training zu starten. Wenn [[#autoTraining|autoTraining]] nicht deaktiviert wurde, erfolgt dies bei Änderungen an relevanten Attributen nach einiger Zeit zwar automatisch, über diesen Befehl kann aber sichergestellt werden, dass dies unmittelbar und ohne Vergleich mit Alt-Daten erfolgt.

''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap</code>

==== update devicemap_only ====
Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.

'''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap_only</code>

==== update slots ====
Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.

Erstellte/Aktualisierte Slots sind z.B.:
* de.fhem.AllKeywords (Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
* de.fhem.Device
* de.fhem.Device-''genericDeviceType''
* de.fhem.Device-''Intent''
* de.fhem.Group
* de.fhem.Room
* de.fhem.MediaChannels
* de.fhem.Color
* de.fhem.NumericType

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots</code>

==== slots_no_training ====
Wie <code>slots</code>, aber ohne Training nach dem Update.

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots_no_training</code>

==== update language ====
Liest das das Sprach-File (''languageFile'') neu ein.

Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!

'''Beispiel:'''
:<code>set <rhasspyDevice> update language</code>

==== update intent_filter ====
Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.

'''Beispiel:'''
:<code>set <rhasspyDevice> update intent_filter</code>

==== update all ====
Aktualisiert die Devicemap und das languageFile

'''Beispiel:'''
:<code>set <rhasspyDevice> update all</code>

=== volume ===
Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float). Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.

'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist im [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH''' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#rhasspyShortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen|Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===
Um das Verhalten von RHASSPY beeinflussen zu können, können neben den bei den Attributen verfügbaren ''Tweaks'' auch die folgenden Readings genutzt - und v.a. auch im laufenden Betrieb immer weider geändert - werden:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Ein Beispiel, mit dem dies per Sprachkommando erfolgt, ist in ''contrib'' zu finden, mit der mobilen Satelliten per Funktionsaufruf in einem [[#rhasspyIntents|rhasspyIntent]] einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung (bzw. nach Abschluss aller Änderungen) an den folgenden Attributen muss ein <code>[[#update devicemap|update devicemap]]</code> ausgeführt werden. In der Regel wird dies automatisch veranlasst, aber wenn dies deaktiviert sein sollte, würden sonst weder RHASSPY, noch Rhasspy von der Änderung erfahren.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Falls man Slots händisch befüllt, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der ''devspec'' im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

=== genericDeviceType ===
Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels [[#gdt2groups|gdt2groups]] aus [[#rhasspyTweaks|rhasspyTweaks]])
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

=== rhasspyName ===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden, der erste Wert in dieser Liste dient intern als Hauptname (''alias''), z.B. in Auswahldialogen.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

=== rhasspyRoom ===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden (der erste Wert ist wieder der ''Hauptraum'' für Auswahldialoge etc.).

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).

=== rhasspyGroup ===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

=== rhasspyMapping ===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

==== Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings ====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

=== rhasspySpecials ===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

==== rhasspyChannels ====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

==== rhasspyColors ====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

DeviceOverview anpassen

2022-08-04T14:09:32Z

Beta-User: Hinweis auf Vorsicht bei eventMap eingefügt + Beispiel für funktionales devStateIcon

Diese Seite enthält einen systematischen Überblick über die verschiedenen Attribute, mit deren Hilfe das Erscheinungsbild und die Funktionalität eines [[Gerät|Geräts]] in [[FHEMWEB]] eingestellt und verändert werden kann. Dabei geht es im Folgenden um den sogenannten ''deviceOverview'', mit der ein Gerät in der Raumdarstellung erscheint, wobei hier nur das Erscheinungsbild in f18 auf einem großen Bildschirm behandelt wird.

==Überblick==
===Attribute===
Es stehen für alle Geräte in FHEM folgende Attribute zur Verfügung, die sich teilweise wechselseitig beeinflussen und überlagern:
*{{Link2CmdRef|Lang=de|Anker=icon|Label=icon}}
*[[webCmd]]
*[[eventMap]]
*{{Link2CmdRef|Lang=de|Anker=webCmdLabel|Label=webCmdLabel}}
*{{Link2CmdRef|Lang=de|Anker=cmdIcon|Label=cmdIcon}}
*{{Link2CmdRef|Lang=de|Anker=widgetOverride|Label=widgetOverride}}
*{{Link2CmdRef|Lang=de|Anker=stateFormat|Label=stateFormat}}
*[[devStateIcon]]
{{Hinweis|Wer einen schnellen Überblick über die diversen Widgets und webCmdLabel sucht, kann [[FHEMWEB/Widgets|hier]] fündig werden.}}

===Allgemeines zum deviceOverview===
Grundsätzlich ist der deviceOverview in verschiedene '''Bereiche''' eingeteilt, die zum Teil nur mit Inhalten gefüllt werden, wenn auch ein entsprechendes Attribut vorhanden ist.

''icon'' <Gerätename> ''STATE''/''devStateIcon'' ''webCmd''

Beispiele:
* ein ''icon'' wird nur angezeigt, wenn das entsprechende Attribut spezifiziert ist. Ansonsten beginnt der deviceOverview mit dem Gerätenamen.
* ist ein ''devStateIcon'' spezifiziert, verdrängt dieses in der Regel die ''STATE''-Darstellung
* entsprechendes gilt ggf. für eine eventMap
* ist keines der genannten Attribut definiert und vom jeweiligen Modul wird kein ''set'' bereitgestellt, besteht die Ansicht nur aus dem Gerätenamen und dem derzeitigen Inhalt des Internals ''STATE''. ''STATE'' wird dabei mangels stateFormat-Attribut aus dem Reading ''state'' abgeleitet (ggf. unter Berücksichtigung von eventMap) . Ist auch dieses nicht vorhanden, erscheinen drei ???.

==webCmd & Co==
Der rechte Bereich wird mit Hilfe der Attribute webCmd, eventMap, cmdIcon, widgetOverride und webCmdLabel beeinflußt.
Dabei bestimmt webCmd, welche Kommandos angezeigt werden, mit eventMap<ref>dabei sind komplexere Perl-Angaben möglich, z.B. <code> attr tasmota_test eventMap { dev=>{'^(.*)POWER(.?): OFF$'=>'$1POWER$2: off', '^(.*)POWER(.?): ON$'=>'$1POWER$2: on'} }</code> </ref> werden diese intern ggf. in andere (Modul-)Befehle bzw. Reading-Inhalte umgewandelt und cmdIcon ermöglicht es, den Kommando-Text durch Symbole zu ersetzen. Mittels webCmdLabel kann eine Beschriftung vorangestellt werden und widgetOverride ein anderes Widget ausgewählt werden, als das, das für das Setzen eines bestimmten Readings standardmäßig verwendet wird. Weitere Hinweise zu diesen Attributen sind den oben verlinkten Artikeln zu entnehmen.

Hier soll anhand eines virtuellen Tür- oder Fensterkontakts die Funktionsweise der verschiedenen Attribute erläutert werden. Dazu wird zunächst mit <code>define Virtueller_Tuerkontakt CUL_HM 112233</code> ein CUL_HM-Gerät generiert und mit <code>set Virtueller_Tuerkontakt virtual 1</code> ein weiteres CUL_HM-Gerät für dessen ersten Kanal. Diesen <code>Virtueller_Tuerkontakt_Btn1</code> verwenden wir im Folgenden.
{{Hinweis|Die folgenden Ausführungen dienen der Erläuterung! Insbesondere eventMap verändert auch das Verhalten eines Gerätes, was in vielen Fällen nicht in der Form im Voraus bedacht wird. Es ist zwar sprachlich leichter zu erfassen, wenn der Zustand einer Tür als "offen" gekennzeichnet ist, aber eine Sprachsteuerung hat damit möglicherweise das Problem, dass sie nicht feststellen kann, was der Zustand dieser Tür ist. Versieht man das mit einem passenden devStateIcon (s.u.), ist der Zustand auch optisch auf einen Blick gut zu erfassen, und Probleme wie das aufgezeigte lassen sich auf diesem Weg direkt vermeiden.}}
[[Datei:Virtueller Btn 1 neu erstellt.png]]

Dieser hat zunächst einen unbekannten STATE (''???'') und ein bereits gesetzes webCMD-Attribut ''press short:press long''. Für die Verwendung als Tuerkontakt soll dieser jedoch nicht kurze oder lange Tastendrücke als Information versenden, sondern soll offen- bzw. geschlossen-Nachrichten senden. Wir ändern das daher und klicken auf eines der angebotenen webCmd.
attr Virtueller_Tuerkontakt_Btn1 webCmd postEvent open:postEvent closed

[[Datei:Virtueller TK postEvent.png]]

Da dies nicht unbedingt optisch ansprechend ist, und wir vielleicht lieber eine Anzeige in unserer Sprache haben wollen, übersetzten wir das zwischen unserer Sprache und der des Türkontakts. Hierfür ändern wir das webCmd-Attribut auf ''offen:geschlossen'' und ergänzen
attr Virtueller_Tuerkontakt_Btn1 eventMap /postEvent open:offen/postEvent closed:geschlossen/
Da hier die zu übersetzenden Befehle Leerzeichen enthalten, muss statt des eigentlich üblichen Leerzeichens als Trenner zwischen den einzelnen Angaben etwas anderes festgelegt werden, hier wird "/" verwendet. Wenn jetzt ''offen'' gedrückt wird, sehen wir, dass sich nicht nur die Anzeige geändert hat:

[[Datei:WebCmd offen geschlossen.png]]

Jetzt sind auch state bzw. STATE und die Anzeige des entsprechenden Bereichs nicht mehr deckungsgleich. In state ist ''set_postEvent open'' enthalten, in der Anzeige erscheint aber ''set_offen''.
Um statt des Texts ein passendes Symbol anzuzeigen, legen wir nun ein cmdIcon-Attribut fest:
attr Virtueller_Tuerkontakt_Btn1 cmdIcon offen:fts_door_slide_open geschlossen:fts_door_slide

[[Datei:Tuerkontakt cmdIcon.png]]

Wer es farbig mag:
attr Virtueller_Tuerkontakt_Btn1 cmdIcon offen:fts_door_slide_open@red geschlossen:fts_door_slide@green
Mit vorangestellter Beschreibung:
attr Virtueller_Tuerkontakt_Btn1 webCmdLabel Auf:Zu

==STATE==
Ist kein ''stateFormat'' und kein ''devStateIcon'' spezifiziert, enthält der Bereich "STATE" den aktuellen Inhalt des Readings ''state''.
===stateFormat===
Mit diesem Attribut kann festgelegt werden, welcher Textinhalt für ''STATE'' verwendet werden soll. Es kann z.B. einfach eine Einheit hinzugefügt werden:
attr Aussentemperatur_Nord stateFormat state °C

[[Datei:DevState Text mit formatiertem state.png]]

Oder es können die Inhalte mehrerer Readings übernommen und formatiert werden:
attr MYSENSOR_97 stateFormat T: temperature2°C, H: humidity3%rH, P: pressure1 hPa, Status: state

[[Datei:MySensors stateFormat.png]]

Es kann für stateFormat auch Perl-Code festgelegt werden. Auf die geschweiften Klammern achten z.B.:
<nowiki>{if (ReadingsVal("MYSENSOR_97","contact","") =~ "open.*") {"open" . ReadingsTimestamp("MYSENSOR_97","contact","")} else {ReadingsVal("MYSENSOR_97","state","")}}</nowiki>
{{Hinweis|Bei Verwendung von Perl-Code in stateFormat sollte jedoch darauf geachtet werden, dass ein lesbarer Text zurückgeliefert wird! Für grafische Ausgaben soll und kann devStateIcon iVm. Perl-Code verwendet werden.}}

===devStateIcon===
Wird ein devStateIcon spezifiziert, verdrängt dies die Anzeige des STATE<ref>vorausgesetzt, in der Perl-Variante wird ein gültiges Ergebnis zurückgeliefert</ref>.

====Text-Variante====
Es kann zum einen einfach ein bestimmter Text jeweils durch ein passendes Icon ersetzt werden.

1. Beispiel:
attr Virtueller_Tuerkontakt devStateIcon set_offen:fts_door_slide_open set_geschlossen:fts_door_slide
Das ganze kann mit einer Farbangaben kombiniert sein:
attr Virtueller_Tuerkontakt devStateIcon set_offen:fts_door_slide_open@red set_geschlossen:fts_door_slide@green
Schließlich kann man auch noch einen Befehl festlegen, der beim Klicken auf das Symbol ausgeführt werden soll:
attr Virtueller_Tuerkontakt devStateIcon set_offen:fts_door_slide_open:geschlossen set_geschlossen:fts_door_slide:offen
bzw. mit Farbangabe:
attr Virtueller_Tuerkontakt devStateIcon set_offen:fts_door_slide_open@red:geschlossen set_geschlossen:fts_door_slide@green:offen
Damit wäre in obigem Beispiel webCmd und webCmdLabel nicht mehr erforderlich und könnte gelöscht werden.
Die folgenden Attribute sind für eine Bedienung ausreichend:
defmod Virtueller_Tuerkontakt_Btn1 CUL_HM 11223301
attr Virtueller_Tuerkontakt_Btn1 cmdIcon offen:fts_door_slide_open@red geschlossen:fts_door_slide@green
attr Virtueller_Tuerkontakt_Btn1 devStateIcon set_offen:fts_door_slide_open@red:geschlossen set_geschlossen:fts_door_slide@green:offen
attr Virtueller_Tuerkontakt_Btn1 eventMap /postEvent open:offen/postEvent closed:geschlossen/
[[Datei:Tuerkontakt defStateIcon only.png]]

Noch einfacher: Das ganze ohne eventMap-Umbenennungen - dafür mit direkten set-Anweisungen aus dem devStateIcon heraus:
attr Virtueller_Tuerkontakt_EZ devStateIcon .*open:fts_window_1w_open@red:postEvent+closed .*closed:fts_window_1w@green:postEvent+open
attr Virtueller_Tuerkontakt_EZ icon fts_door_right_open
attr Virtueller_Tuerkontakt_EZ webCmd :

2. Beispiel mit Regex<ref>Der Rollladenstatus ist hier invertiert, also 80% entspricht einem leicht geschlossenen Rollladen</ref>:
attr Rollladen devStateIcon 0:fts_shutter_100 100:fts_shutter_10 9\d.*:fts_shutter_10 8\d.*:fts_shutter_20 7\d.*:fts_shutter_30 6\d.*:fts_shutter_40 5\d.*:fts_shutter_50 4\d.*:fts_shutter_60 3\d.*:fts_shutter_70 2\d.*:fts_shutter_80 1\d.*:fts_shutter_90 0\d.*:fts_shutter_100

====Multi-Icon-Variante====
Seit 19.02.2019 ist es möglich, auch mehrere Icons zu nutzen, um den Zustand mehrerer Readings zu visualisieren. Beispiel 1 für den Zustand einer Tür samt Schloß:

[[Datei:Tuer geoeffnet.png]]

[[Datei:Tuer nicht-verschlossen.png]]

[[Datei:Tuer zu.png]]
<pre>defmod keller_flur_tuer ESPEasy 192.168.144.181 80 ESPBridge Keller_Sensoren_flur_holzhalle
attr keller_flur_tuer alias Tür Holzhalle
attr keller_flur_tuer devStateIcon 1.on:fts_door@green 1.off:fts_door_open@red\
2.on:secur_locked@green 2.off:secur_open@red
attr keller_flur_tuer icon hue_room_frontdoor
attr keller_flur_tuer stateFormat 1:mk\
2:rsk
</pre>
Anm.: rsk und mk sind jeweils die Namen der Readings für die Tür bzw. das Schloss

Beispiel 2: holiday-Datei:

[[Datei:Holiday-multiicon.png]]
<pre>defmod ferien holiday
attr ferien alias Ferien Baden-Württemberg
attr ferien devStateIcon [^(none|Heute|Morgen)].*:scene_party none:scene_office
attr ferien icon time_calendar
attr ferien stateFormat Heute: \
state\
Morgen: \
tomorrow
</pre>
Anm.: Die regex beim devStateIcon wandelt alles, das nicht "none", "heute" oder "Morgen" ist in das scene_party-Icon um .

====Perl-Variante====
Schließlich kann in dem Attribut Perl-Code enthalten sein, der dann auch komplexe Anweisungen enthalten kann. Beispiele:

'''Beispiel 1:''' Aufruf von Code aus einem Modul - regelbare Lampe mit toggle beim Klicken:
attr MQTT2_zigbee_0x90fd9ffffe65db16 devStateIcon {zigbee2mqtt_devStateIcon255($name)}

'''Beispiel 2:''' MySensors-Node mit farbiger Anzeige, ob regelmäßig Kontakt besteht<ref>Die Funktion ''FW_makeImage'' ist in der [[DevelopmentFHEMWEB-API]] näher erläutert</ref>:

<pre> attr MYSENSOR_97 devStateIcon {my $alivecolor = 'lan_rs485@red';;$alivecolor='lan_rs485@green' if (ReadingsVal($name, "state", "dead") eq "alive");;"<div>" . FW_makeImage("$alivecolor","lan_rs485") . FW_makeImage("temp_temperature","temp_temperature") . ReadingsVal($name,"temperature2",0) ."°C ". FW_makeImage("humidity","humidity"). ReadingsVal($name,"humidity3",0) . "%rH</div>"}
</pre>[[Datei:MySensors devStateIcon Perl.png]]

'''Beispiel 3:''' 4-Kanaliges Tasmota-Gerät mit Anzeige aller 4 Kanäle und toggle-Funktion auf jedem der Icons:
///tbd

== Weitere Beispiele ==
=== ReadingsProxy für fernotron-Rolladen ===
[[Datei:Fernotron deviceoverview.jpg]]
<pre>defmod Rolladen_Buero readingsProxy Rolladen_Buero
attr Rolladen_Buero alias Büro
attr Rolladen_Buero cmdIcon auf:fts_shutter_up stopp:fts_shutter_manual zu:fts_shutter_down
attr Rolladen_Buero eventMap u:auf d:zu s:stopp
attr Rolladen_Buero room Rolläden
attr Rolladen_Buero setFn { fhem('"sudo /home/pi/fernotron-control/FernotronRemote.sh 2 2 '. $CMD .'"') }
attr Rolladen_Buero setList u d s
attr Rolladen_Buero webCmd auf:stopp:zu</pre>

==Hinweise==
<references />

[[Kategorie:FHEM Frontends]]
[[Kategorie:FHEM-Verwendung]]
[[Kategorie:HOWTOS]]

MQTT2-Module - Praxisbeispiele

2022-07-19T13:57:06Z

Beta-User: Milight: Klarstellung, dass die Hardware an sich funktional sein muss und nicht zwingend alles empfangen werden kann.

== Einführung: MQTT bzw. MQTT2 in FHEM ==
{{Randnotiz|RNTyp=y|RNText=Sollten Sie MQTT2_CLIENT verwenden, beachten Sie bitte, dass der MQTT2_CLIENT die ursprüngliche Herkunft der über MQTT verteilten Informationen nicht kennt. Daher ergeben sich in der Anwendung kleinere Unterschiede, zu deren Verständnis die diesbezüglichen [[MQTT2_CLIENT#Anwendung|Hinweise zu MQTT2_CLIENT]] bekannt sein sollten.}}Zur Einbindung von Geräten, welche zur Nutzung des MQTT-Protokols konfiguriert werden können und darüber mit einem MQTT-Server (früher: Broker) kommunizieren, stehen unter FHEM verschiedene Optionen zur Verfügung, wobei nicht alle Module beliebig miteinander verwendet werden können. Details hierzu sind dieser [[MQTT|Übersicht]] zu entnehmen.

Im Rahmen dieses Artikels wird für die eigentlichen Geräte [[MQTT2 DEVICE|MQTT2_DEVICE]] verwendet, damit wird als IO-Device entweder {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} oder [[MQTT2 CLIENT|MQTT2_CLIENT]] benötigt, mit einem IO-Device des Typs [[MQTT (Modul)|MQTT]] funktioniert die nachfolgende Darstellung dagegen nicht<ref>Allerdings können die Konfigurationen in der Regel recht einfach auf die bisherige MQTT-Implementierung übertragen werden</ref>. MQTT2_DEVICE unterstützt u.a. auch die ''setExtensions'' direkt, also z.B. ''on-for-timer<ref>Beachten Sie bei mehrkanaligen Geräten, dass jeweils nur ein Hauptkanal mittels setExtensions verwaltet werden kann! U.a. aus diesen Grund ist es meist sinnvoller, die ''split''-Varianten der attrTemplate-Einrichtung zu verwenden.</ref>'' sowie ''[[MQTT2-Module - Praxisbeispiele#attrTemplate_2|attrTemplate]]''<ref>Auch MQTT_DEVICE unterstützt SetExtensions, allerdings muss dies dort per Attribut eingeschaltet werden</ref>.

=== Allgemeine Einstellungen und Hinweise ===
{{Randnotiz|RNTyp=r|RNText=Beachten Sie, dass für [[autocreate]] in Verbindung mit MQTT2_SERVER '''zwingend''' jeder über MQTT kommunizierende Client eine ClientID angeben muss. Passen Sie daher ggf. die Einstellungen Ihres Geräts an. Manche Geräte verwenden auch "Wegwerf"-ClientID's. Für diese empfiehlt es sich, ggf. dann die durch autocreate erstellten Geräte nachzubearbeiten und die ClientID-Angabe v.a. aus den Inhalten des readingList-Attributs zu entfernen.}}Die nachfolgenden Beispiele gelingen am einfachsten mit '''MQTT2_SERVER als Server ("Broker")''', für diesen sollte dabei ''autocreate'' '''nicht deaktiviert''' sein, damit die erforderlichen MQTT2_DEVICES soweit möglich automatisiert erstellt werden<ref>Dabei wird vorausgesetzt, dass ein allgemeines {{Link2CmdRef|Anker=autocreate|Lang=en|Label=autocreate}}-Device (''TYPE=autocreate'') ebenfalls aktiv ist.</ref> .

Beispiel<ref>MQTT2_SERVER verwendet als default-Einstellung für ''autocreate'' ''simple'', ohne dass ein entsprechendes Attribut gesetzt werden müsste. Die Einstellung ''complex'' empfiehlt sich in der Regel nicht; diese ist jedoch dann zu empfehlen, wenn das Device entweder verschachtelte JSON-Array-Strukturen liefert oder bestimmte Readings nicht gefüllt werden sollen.</ref>:
define MQTT2_FHEM_Server MQTT2_SERVER 1883 global

Falls der MQTT Broker mit Hilfe von [[allowed]] abgesichert wurde, muss in den Geräten ebenfalls User bzw. Passwort eingetragen werden, damit eine MQTT Kommunikation möglich ist.

{{Hinweis|Die Code-Darstellung in diesem Beitrag entspricht jeweils dem RAW-Format zum [[Import von Code Snippets]]. Wer die Attribute direkt und einzeln bearbeitet, muss ggf. die "\" entfernen!}}

=== MQTT-Einstellungen in den Geräten ===
Die Beispiele gehen davon aus, dass die einzubindenden Geräte '''''mit den default-Einstellungen''''' für MQTT betrieben werden, wenn man von den Angaben zum Server und ggf. der Gerätekennung absieht. Es sollten also insbesondere '''keine Veränderungen der topic-Pfade''' vorgenommen werden.

{{Hinweis|Einige der hier beschriebenen Einstellungen haben Änderungen der sich durch die jeweiligen Automatismen eigentlich jeweils ergebenden Standard-Werte zur Folge, insbesondere, was Reading-Namen und von den Geräten gesendete Werte angeht. Sie sollten daher zunächst die Konfiguration des jeweiligen MQTT2-DEVICE-Geräts abschließen, und erst anschließend die weitere Integration mit Event-Handlern, logging usw. vornehmen. }}

=== auto-Konfigurations-features ===
Viele firmwares und Dienste bieten Möglichkeiten an, einer Controller-Software (insbesondere homeassistant) Hilfsdaten zur automatisierten Konfiguration bereitzustellen. Da FHEM diese Daten nicht zu ihrem ursprünglichen Zweck verwenden kann, werden hierdurch lediglich zusätzliche Readings erzeugt, mit denen man als User in der Regel wenig anfangen kann. Es wird daher empfohlen, derartige features '''abzuschalten'''. Wo dies nicht möglich ist, sollte man eine passende [[MQTT2_CLIENT#ignoreRegexp|ignoreRegexp]] setzen bzw. diese passend erweitern!

=== Schritt für Schritt ===
Hier werden in der Regel fertige Konfigurationen für häufige Anwendungsfälle (beispielhaft) dargestellt. In [[MQTT2_DEVICE - Schritt für Schritt]] ist etwas mehr über die Vorgehensweise bei der Zusammenstellung der verschiedenen Attribute und deren Zusammenwirken zu erfahren.

== zigbee2mqtt ==
[[Bild:MQTT2_zigbee2mqtt_Bulbs.png|400px|thumb|Darstellung in FHEMWEB]]
[https://www.zigbee2mqtt.io zigbee2mqtt] ist ein open-source Projekt, mit dem zigbee-Geräte über MQTT direkt angesprochen werden können, ohne dass hierfür eine Bridge eines Herstellers benötigt wird.

Einzelheiten zur Vorgehensweise sind auf der Detailseite [[Zigbee2mqtt|zigbee2mqtt]] zu finden.

== Tasmota ==
{{Randnotiz|RNTyp=r|RNText=Bitte beachten Sie, dass versicherungsrechtliche Probleme entstehen können, wenn die herstellereigene Firmware ersetzt wird!}}[https://github.com/arendst/Sonoff-Tasmota Tasmota] ('''T'''heo '''A'''rends '''S'''onoff '''M'''QTT '''O'''ver '''T'''he '''A'''ir - einer offenen Firmware von [https://github.com/arendst arendst]) ist eine open-source Software für ESP8266-Geräte, die z.B. statt der originalen Firmware für Sonoff-Geräte und andere ESP8266-basierte WLAN-Steckdosen usw. verwendet werden kann.
{{Hinweis|[[Datei:Tasmota mqtt config.png|120px|thumb|right]]Vor allem, aber nicht nur bei Verwendung des MQTT2_CLIENT als IO, ist es empfehlenswert, in der MQTT-Konfiguration der tasmota-Geräte für den Parameter ''<nowiki>topic = %topic% (tasmota)</nowiki>'' ebenfalls die dynamisch aus der Chip-ID erzeugte Kennung ''DVES_%06X'' zu verwenden. (Kopieren Sie einfach diese Zeichenkette aus dem Eingabefeld für ''"client ..."'', siehe nebenstehende Abbildung). Die eigentliche Umbenennung zu einem "sprechenden Namen" kann dann innerhalb von FHEM - mittels ''rename'' oder ggf. mit einem ''alias'' - erfolgen.}}
=== MQTT2_DEVICE ===
Dieses sollte bei aktiviertem ''autocreate'' am MQTT2_SERVER-Device automatisch angelegt werden, sobald das betreffende Gerät eingesteckt oder neu gestartet oder an einem evtl. vorhandenen Taster geschalten wird. Bislang wurden Tasmota version(en) ab 6.1.1 bis min. 8.1.0 getestet, dies auf verschiedener Hardware, zunächst mit Sonoff Touch und S20, zwischenzeitlich mit einer Vielzahl von Geräten, die per USB-Adapter oder mit der Methode aus dem [https://www.heise.de/ct/artikel/Tuya-Convert-IoT-Geraete-ohne-Loeten-vom-Cloud-Zwang-befreien-4283623.html Tuya-Convert]-Projekt des heise-Verlags auf Tasmota umgeflasht wurden.

=== Manuelle Anpassungen - Schalter ===
Die RAW-Definition kann dann beispielsweise wie folgt ergänzt werden:
<syntaxhighlight lang="perl">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD IODev m2server
attr MQTT2_DVES_9B01BD devStateIcon on:FS20.on:off off:FS20.off:on
attr MQTT2_DVES_9B01BD readingList DVES_9B01BD:tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/LWT:.* LWT\
DVES_9B01BD:tele/DVES_9B01BD/UPTIME:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/SENSOR:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO1:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO2:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO3:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/RESULT:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }
attr MQTT2_DVES_9B01BD room MQTT2_DEVICE
attr MQTT2_DVES_9B01BD setList on cmnd/DVES_9B01BD/POWER on\
off cmnd/DVES_9B01BD/POWER off\
reboot cmnd/DVES_9B01BD/Restart 1
attr MQTT2_DVES_9B01BD webCmd on:off:reboot
</syntaxhighlight>

=== Manuelle Anpassungen - Dimmer ===
{{Randnotiz|RNTyp=r|RNText=Dieses Beispiel ist nur bedingt zur Nachahmung zu empfehlen: Prinzipiell kann man Readings und setter in MQTT2_DEVICE fast nach Belieben benennen. Wählt man allerdings FHEM-typische Namen, kann dies sehr zur Vereinfachung beitragen. Z.B. wird eine Sprachssteuerung bei einem Dimmer üblicherweise automatisch korrekt eingestellt werden, wenn der für die Helligkeit zuständige setter z.B. pct (oder brightness) heißt, oder eine abzufragende Temperatur temperature. Entsprechendes gilt im Rahmen von devspec-Abfragen.}}Bei einem Dimmer sind einige zusätzliche Anpassungen vorzunehmen. Ein Dimmer wird über '''POWER''' geschaltet und über '''Dimmer''' gedimmt. Damit das funktioniert, müssen ein stateFormat und devStateIcon zusammenarbeiten:
<syntaxhighlight lang="perl">
attr MQTT2_DVES_2DF34D devStateIcon 10\d.*:dim100%@orange:off 1\d.*:dim12%@orange:off 2\d.*:dim18%@orange:off 3\d.*:dim31%@orange:off 4\d.*:dim43%@orange:off 5\d.*:dim50%@orange:off 6\d.*:dim62%@orange:off 7\d.*:dim68%@orange:off 8\d.*:dim81%@orange:off 9\d.*:dim93%@orange:off 0:FS20.off:on .*:FS20.off@orange:off
attr MQTT2_DVES_2DF34D stateFormat {if(ReadingsVal($name,"POWER",0)eq"off"){0}else{ReadingsVal($name,"Dimmer",0)}}
</syntaxhighlight>
Nun kann man über das Icon ein- und ausschalten und der Zustand des Dimmers wird korrekt angezeigt.

Es fehlt noch ein Slider, um auch dimmen zu können. Zusätzlich muss setList noch um Dimmer erweitert werden:
<syntaxhighlight lang="text">
attr MQTT2_DVES_2DF34D setList on cmnd/dimmer/POWER on\
off cmnd/dimmer/POWER off\
Dimmer cmnd/dimmer/Dimmer
attr MQTT2_DVES_2DF34D webCmd Dimmer
attr MQTT2_DVES_2DF34D widgetOverride Dimmer:slider,0,1,100
</syntaxhighlight>

=== attrTemplate ===
===== Allgemeines =====
Für gängige Tasmota-Geräte stehen ''templates'' bereit, mit denen sich diese schnell konfigurieren lassen.
Beachten Sie dazu den Abschnitt ''attrTemplate'' in [[MQTT2 DEVICE#attrTemplate|MQTT2_DEVICE]]. Bei Anwendung eines template mit "split" im Namen werden dabei weitere Geräte angelegt und konfiguriert.{{Hinweis|Bitte attrTemplates nicht verwechseln mit templates, die auf den Tasmota- bzw. Blackadder-Seiten angeboten werden, welche zur Konfiguration der firmware genutzt werden können! Es sollte zunächst die firmware korrekt eingerichtet werden, so dass das Gerät selbst direkt auf dessen Web-Interface korrekt bedient werden kann.}}

===== Kein passendes attrTemplate vorhanden? =====
Exisitert (noch) kein passendes attrTemplate, ist zu empfehlen, zunächst das "''tasmota_basic''" anzuwenden. Dieses führt einige Basiskonfigurationen durch, die für FHEM hilfreich sind, z.B. wird die firmware so eingestellt, dass Schaltzustände in Kleinschreibung übermittelt werden, statt der defaults "ON" bzw. "OFF".

Allerdings stellt dieses das ''autocreate'' an dem MQTT2_DEVICE auf 0, was dann nicht optimal ist, wenn man weitere Readings aus dem Gerät erwartet, etwa, weil zusätzliche Sensoren vorhanden sind. In diesem Fall empfiehlt es sich, das ''autocreate''-Attribut an dem MQTT2_DEVICE zu löschen, damit alle weiteren Informationen verarbeitet werden und ggf. im ''jsonMap''-Attribut nur die Angabe "''POWER1:state''" zu belassen.

=== on-for-timer ===
Um z.B. ein Relais nur für einen Zeitraum anzuschalten, kann man bei Tasmota-Geräten zwischen mehrere Varianten wählen. Ohne speziellen ''setter'' in der ''setList'' werden die '''SetExtensions''' verwendet. Timer laufen damit innerhalb FHEM. Da diese intern als temporäres [[at]] ausgeführt werden, sind diese auch noch nach einem FHEM-Neustart vorhanden, sofern FHEM ordnungsgemäß beendet und neu gestartet wird.

Die Tasmota-firmware bietet ergänzend dazu zwei Möglichkeiten an, bei denen der Timer direkt auf dem ESP-Microcontroller verwaltet wird:

==== delay ====
Zeile zur Erweiterung der ''setList'' (Attributeingabe via FHEMWEB!):
on-for-timer {my $duration = $EVTPART1*10; 'cmnd/DVES_575127/Backlog POWER1 1; delay '.$duration.'; POWER1 0'}

Ohne Auswirkungen auf alles, was danach kommt, hat aber den Nachteil, dass die möglichen Zeitspannen auf 3600 1/10 Sekunden begrenzt sind (siehe [https://tasmota.github.io/docs/Commands/#delay Commands - Tasmota Delay]), also 6 Minuten.

====pulseTime ====
Zeile zur Erweiterung der ''setList'' (s.o.):
on-for-timer {my $duration = $EVTPART1 < 11.2 ? $EVTPART1*10 : $EVTPART1+100; 'CMNDTOPIC/Backlog pulseTime1 '.$duration.'; POWER1 1'}
Auch hier sind die möglichen längsten Einschaltdauern begrenzt, allerdings ist diese mit 18h deutlich länger als mit ''delay''. Diese Implementierung hat den Nachteil, dass der ESP-Microcontroller die jeweils letzte pulseTime auch für alle weiteren "normalen" Einschaltvorgänge berücksichtigt, das Relais also ebenfalls nach Ablauf der übermittelten pulseTime abgeschaltet wird; dies gilt allerdings ohne explizites ''save'' nur bis zum nächsten reboot des Microcontrollers.

Da nach dem ersten pulseTime setzten, diese immer benutzt wird, kann man mit einem kleine Workaround das Device normal arbeiten lassen. Dafür wird bei jedem anderem Befehl, aus der PulseTime, der Timer deaktiviert.
Hierfür machen wir uns zu nutzen, dass man mehrere Befehle gleichzeitig an Tasmota senden kann (backlog). Ob diese Lösung auch mit anderen MQTT Firmwares funktioniert, kann ich nicht sagen. Es wurde lediglich mit Tasmota getestet.
Wir senden also, bevor wir den eigentlich Tasmota Befehl zum Ein- oder Ausschalten schicken, einen Befehl zum deaktivieren des Timers: "pulseTime 0"
Hier ein Beispiel: (das entsprechende device "DEV_611F3E" muss gegen das eigene ersetzt werden)
off:noArg cmnd/DVES_611F3E/backlog pulseTime 0; POWER1 0
on:noArg cmnd/DVES_611F3E/backlog pulseTime 0; POWER1 1
toggle:noArg cmnd/DVES_611F3E/backlog pulseTime 0; POWER1 2

=== zigbee2tasmota ===
[https://tasmota.github.io/docs/Zigbee/ zigbee2tasmota] ist eine Erweiterung der Tasmota-firmware für Microcontroller, insbesondere dem ESP8266 (und ESP32)(link), über die einige ZigBee-Chipsätze (insbesondere TI CC2530) als [[ZigBee#Koordinator_.28ZigBee_coordinator.2C_ZC.29|Coordinator]] eingebunden werden können, um ein ZigBee-Netzwerk aufzubauen.
{{Hinweis|Stand 08/2020 war die Einbindung anderer Chipsätze erst in einem Alpha-Stadium; die Zahl der über einen CC2530 einbindbaren ZigBee-Geräte ist daher derzeit relativ begrenzt (ca. 16)!}}
Auch für diese Lösung stehen einige ''attrTemplate'' zur Verfügung. Nähere Informationen hierzu sind dem Artikel [[Zigbee2Tasmota-MQTT]] zu entnehmen.

== ESPurna ==
ESPurna ist eine weitere alternative firmware für ESP8266-basierte Geräte, Details sind der [https://github.com/xoseperez/espurna/wiki Projektseite] zu entnehmen.

Das Format, in dem ESPurna Daten sendet, unterscheidet sich v.a. darin, dass bool'sche Werte als 0 oder 1 gesendet werden, und nicht wie sonst üblich als "on" oder "off" oä.. Es stehen einige Mustertemplates zur Verfügung, um diese Art der Payload in FHEM-konforme Werte zu überführen.

== Shelly ==
=== Vorbemerkung ===
Auch für Shelly-Geräte steht eine Auswahl an [[MQTT2-Module - Praxisbeispiele#attrTemplate_2|templates]] bereit.
Beachten Sie auch hier, dass uU. bei Anwendung eines template mit "split" im Namen weitere Geräte angelegt und konfiguriert werden.

Standardmäßig senden die Shelly-Geräte ihren kompletten Status alle 30 Sekunden. Dies kann man über den Parameter ''mqtt_update_period'' in den ''settings'' ändern, allerdings ist dieser nur über die HTTP-Schnittstelle des Shelly verfügbar. Um diese Statusupdates abzustellen, kann über den Browser folgender Befehl verwendet werden:
http://<ip-des-shelly>/settings?mqtt_update_period=0,
Soweit bekannt, werden dann nur statische updates ausgeschaltet, z.B. für das Relay bzw. angeschlossene Taster oder Schalter; insbesondere Verbrauchswerte werden dennoch aktualisiert.

=== Shelly1 ===

=== Shellybulb ===
Zunächst muss man einen Statusupdate des Shellybulb erzwingen (Aus- und Einschalten, physikalisch oder per Web-UI), damit das Gerät bei eingeschaltetem autocreate angelegt wird. Dies sieht zunächst so aus:
Internals:
CFGFN
CID shellybulb_3CC533
DEF shellybulb_3CC533
DEVICETOPIC MQTT2_shellybulb_3CC533
IODev MQTT2_FHEM_Server
NAME MQTT2_shellybulb_3CC533
NR 246
STATE ???
TYPE MQTT2_DEVICE
READINGS:
2018-12-12 19:28:08 status_blue 0
2018-12-12 19:28:08 status_brightness 61
2018-12-12 19:28:08 status_effect 0
2018-12-12 19:28:08 status_gain 26
2018-12-12 19:28:08 status_green 0
2018-12-12 19:28:08 status_ison true
2018-12-12 19:28:08 status_mode color
2018-12-12 19:28:08 status_red 255
2018-12-12 19:28:08 status_temp 3250
2018-12-12 19:28:08 status_white 0
Attributes:
IODev MQTT2_FHEM_Server
readingList shellybulb_3CC533:shellies/shellybulb-3CC533/color/0/status:.* { json2nameValue($EVENT, 'status_') }
room MQTT2_DEVICE
[[Bild:MQTT2 Shellybulb.png|400px|thumb|Darstellung in FHEMWEB nach Anwendung des template]]Dann bei den set-Anweisungen das attrTemplate "shellybulb" auswählen und setzen. Es erscheint eine Abfrage, ob die vorhandenen Readings gelöscht werden sollen. Diese bitte bestätigen und die Seite neu laden. Danach einmal An- und Ausschalten, damit die Readings auch durch einen neuen Status initialisiert werden und die Seite im Browser neu laden.

=== Shelly Plug S ===
Über die Leistungsmessung des Shelly Plug S lässt sich sehr einfach auch eine Erkennung des Betriebszustandes des angeschlossenen Gerätes realisieren. Dazu stellt man zuerst fest, wieviel Leistung das Gerät in jedem Betriebszustand verbraucht und kann dann z.B. für einen angeschlossenen Fernseher, der im Standby 1 Watt und im Betrieb > 100 Watt verbraucht, den Zustand erkennen und als on/off Status anzeigen. Dazu wird das state Reading wie folgt definiert:
attr readingList shellies/shellyplug-s-123456/relay/0/power:.* { { state => $EVTPART0<100?"off":"on" } }
Der Status des MQTT2 Devices zeigt dann bei <100W "off" und sonst "on" an.

=== HTTP-Commands ===
In diesem {{Link2Forum|Topic=102369|LinkText=Forumsbeitrag}} wird eine Lösung vorgestellt, um über [[99 myUtils anlegen|myUtils-Code]] weitere Kommandos bereitzustellen, die sonst nur direkt über das Web-Interface zu erreichen sind.

== Shelly Gen2 ==
=== Vorbereitung ===
Shelly mit dem WLAN verbinden, entweder über die Shelly APP oder per Laptop auf den Offenen AP des Shelly verbinden und dann übers WebUI des Shelly mit dem Heimischen WLAN verbinden. Über die APP geht dies meist etwas einfach und schneller, besonders wenn man mehrere Shelly Geräte hinzufügen möchte. Durch die BT Unterstützung der Gen2 Geräte, klappt dies meist auch deutlich schneller und zuverlässiger als noch bei Gen 1 Geräten.
Nachdem der Shelly mit dem WLAN verbunden ist, sollte die Firmware überprüft und gegebenenfalls aktualisiert werden (Stand Anfang 2022 scheint die firmware noch nicht voll ausgereift gewesen zu sein, da dass insbesondere die MQTT-Schnittstelle immer wieder überarbeitet wurde). Bitte KEINE BETA Versionen installieren, wenn nicht dazu aufgefordert wurde.
Nach dem, durch das Update ausgelösten, Neustart kurz Prüfen ob die Uhrzeit passt, wenn trotz richtiger Zeitzone die Uhrzeit nicht stimmt hilft ein weiterer Neustart.
Nun auf Networks| Internet (leider in APP und WebUI unterschiedlich), hier auf MQTT und die Einstellungen für den verwendeten MQTT Server treffen. Diese Einstellungen werden auch wieder durch Neustart übernommen.
=== Shelly Plus 1 ===
Zunächst muss man einen Statusupdate des Shelly erzwingen (Aus- und Einschalten, physikalisch oder per Web-UI), damit das Gerät bei eingeschaltetem autocreate angelegt wird. Dies sieht zunächst so aus:
<syntaxhighlight lang="text">
defmod MQTT2_shellyplus1_441793a34044 MQTT2_DEVICE shellyplus1_441793a34044
attr MQTT2_shellyplus1_441793a34044 readingList shellyplus1_441793a34044:shellyplus1-441793a34044/online:.* online\
shellyplus1_441793a34044:shellyplus1-441793a34044/status/mqtt:.* { json2nameValue($EVENT) }\
shellyplus1_441793a34044:shellyplus1-441793a34044/events/rpc:.* { json2nameValue($EVENT) }\
shellyplus1_441793a34044:shellyplus1-441793a34044/status/sys:.* { json2nameValue($EVENT) }\
shellyplus1_441793a34044:shellyplus1-441793a34044/status/switch_0:.* { json2nameValue($EVENT) }
attr MQTT2_shellyplus1_441793a34044 room MQTT2_DEVICE

setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 IODev m2s
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 available_updates_beta_version 0.10.0-beta6
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 cfg_rev 7
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 connected true
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 dst shellyplus1-441793a34044/events
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 fs_free 237568
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 fs_size 458752
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 id 0
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 mac 441793A34044
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 method NotifyStatus
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 online true
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 output false
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_mqtt_connected true
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 params_switch_0_id 0
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 params_switch_0_output false
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 params_switch_0_source WS_in
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_switch_0_temperature_tC 39.88
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_switch_0_temperature_tF 103.78
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 params_sys_available_updates_beta_version 0.10.0-beta6
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 params_ts 1646474952.66
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_wifi_rssi -57
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_wifi_ssid WLAN-Alex
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_wifi_sta_ip 192.168.177.167
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:24 params_wifi_status got ip
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 ram_free 179764
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 ram_size 249456
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 restart_required false
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 source WS_in
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 src shellyplus1-441793a34044
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 temperature_tC 39.9
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:09:12 temperature_tF 103.9
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 time 11:08
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 unixtime 1646474911
setstate MQTT2_shellyplus1_441793a34044 2022-03-05 11:08:31 uptime 7
</syntaxhighlight>

Über die set Anweisung unterhalb der Device Übersicht können wir ein attrTemplate wählen; shellyPlus_1
Es erscheint eine kurze Übersicht was im Template enthalten ist, dieses befindet sich noch im Aufbau und wird aktuell von der Community aufgebaut und weiterentwickelt. Mit einem Klick auf „set“ laden wir das Template und übernehmen die Einstellungen für den Shelly Plus 1.
Damit ist der Shelly bereit, im Status wird neben dem Namen auch der Onlinestatus des Shellys (grüner | roter Punkt) so wie eine Lampe mit Toggle (on | off) Funktion und die Temperatur des Shellys angezeigt. Darüber hinaus verschwindet die Lampe und wird durch einen klickbaren Hinweis ersetzt, wenn ein Neustart des Shellys nötig ist.

=== Tipps ===
{{Randnotiz|RNTyp=g|RNText=So nimmt man bei Verwendung eines normalen Schalters (eine Stellung EIN eine AUS) gerne den „Flip“ Mode – damit wird der Shelly IMMER umgeschaltet, egal in welche Stellung der Schalter sich bewegt („Kreuzschaltung“). Diese Einstellungen trifft man grundlegend im WebUI des Shelly (oder APP) unter „Channel settings“.
Für den „Flip“ müssen wir die Grundeinstellung des „Power on default“ auch ändern (gleiche Seite) - persönlich wähle ich „Restore last“, also: nach Stromausfall wird der letzte Zustand wieder hergestellt; grundsätzlich gehen alle Modi außer „Match input“.
}}
Das aktuelle Template wurde um die Funktion erweitert, den Button Mode umzuschalten. In den meisten Fällen legt man sich auf eine Schaltmethode fest, welche zum Hardware Setup passt.

Manchmal will man aber vielleicht den Hardware Schalter deaktivieren, nennen wir es „Kindersicherung“. Bei Shelly heißt das „detached“.
Diese Funktion wurde ins Template als „in_mode“ Übernommen. Mögliche set Befehle sind „flip“, „detached“ „toggle“. Bedingung zur Verwendung ist: „relay power on default“ darf NICHT „Match input“ sein. Sollte Follow statt Flip bevorzugt werden, müsste entsprechende Zeile in der setList von „flip“ auf „follow“ angepasst werden.

Der Befehlt lässt sich mit dem webCmd in_mode auch schnell zugänglich in die Übersicht vom Shelly setzen, so erhält man neben dem Status ein Dropdown mit flip detached und toggle zum schnellen umschalten. Mit webCmdLabel kann man noch einen Namen für das Dropdown setzen.

== OpenMQTTGateway ==
Um verschiedene Systeme wie BLE usw. auf MQTT zu bringen bietet sich [https://github.com/1technophile/OpenMQTTGateway OpenMQTTGateway] an, z.B. wird für das Auslesen vieler BLE-Seonsoren lediglich ein ESP32-Board ohne Zusatzhardware (ab ca. 5,- Euro in Fernost erhältlich) benötigt, auf das dann eine vorkompilierte firmware geflasht wird (hierfür wird ein USB-seriell-Wandler benötigt).

Nähere Details sind im Artikel [[OpenMQTTGateway]] zu finden.

== 8-Port-Ethernet Board ==
<gallery>
datei:8-relais-ethernetboard closed.jpg|mit Gehäuse
datei:8-Port-MQTT-Relais-Board.jpg|ohne Gehäuse
</gallery>
In diesem {{Link2Forum|Topic=107536|Message=1016379|LinkText=Forenbeitrag}} bzw. dem betreffenden Thread wurde ein Relais-Board vorgestellt, mit dem 8 Relais über Ethernetkabel verbunden werden, die Kommunikation erfolgt dann über MQTT. Über die verwendete Software ist wenig bekannt, es könnte jedoch sein, dass diese Art der Einbindung auch bei weiteren Boards funktioniert, die einen bestimmten Ethernet-Chipset von TI (DP83848) und eine Cortex M3 MCU verwenden.

== Milight-Bridge ==
=== Vorbemerkung ===
Der [https://github.com/sidoh/esp8266_milight_hub esp8266_milight_hub] ist ein open source- Projekt, mit dem auf Basis von ''openmili'' eine Vielzahl von MiLight-Geräten gesteuert werden können. Der MiLight-Hub erstetzt dabei eine beliebige Zahl von Milight-Bridges und ist auch zu verschiedenen Versionen des MiLight-Protokols kompatibel. Allerdings lassen sich manche MiLight-Geräte nicht an die Bridge anlernen, und es werden auch nicht alle Fernbedienungs-Typen voll unterstützt.
Neben MQTT kann dieser auch mit HTTPMOD oder Wifilight (bzw. den MiLight-Modulen) gesteuert werden. Die Hardware entspricht dabei im Wesentlichen einem MySensors-Wifi-Gateway<ref>Es wird lediglich ein anderer CS-PIN genutzt. Dies kann einfach in der Web-Oberfläche der Firmware umgestellt werden.</ref>.
Hier wird vorausgesetzt, dass eine funktionierende Bridge vorhanden ist und die zu steuernden Leuchtmittel mit dem Hub bereits verbunden (gepairt) sind bzw. entsprechende Fernbedienungs-Signale empfangen werden können (bei vorhandenem pairing eines Leuchtmittels an die Fernbedienung).
Der Vorteil der MQTT-Lösung liegt darin, dass man bei kompatiblen Fernbedienungen auch direkt Informationen über Schaltvorgänge erhält, die mit der Fernbedienung ausgelöst werden.

=== Einstellungen am MiLight-Hub ===
Die zum FHEM-Server bzw. dem MQTT2_SERVER passenden Vorgaben sind im Web-Interface des Hub einzustellen. Gegebenenfalls passen Sie die vom Hub zurückzugebenden Elemente im Web-Interface des Hub an.
Die Einstellungen für ''MQTT topic pattern'' usw. können auf den default-Werten<ref>Diese sind: ''milight/:device_id/:device_type/:group_id'' für "topic pattern" ''milight/updates/:hex_device_id/:device_type/:group_id'' für "update topic pattern" ''milight/states/:hex_device_id/:device_type/:group_id'' für "state topic pattern". Der Autor hat derzeit folgende Infotypen zum Senden markiert: "status, brightness, hue, color, mode, color_temp, bulb_mode, computed_color, hex_color" (enthält eventuell zu viele Angaben. Bei einem Eventhandler muss man uU. darauf achten, dass kurz hintereinander zweimal dasselbe Event kommen kann (für ON/OFF)).</ref> belassen werden, für die seit Mitte 2019 vorhandene Option, eine LWT-Message zu senden (''MQTT Client Status Topic''), tragen Sie ''milight/LWT'' ein und aktivieren ''Detailed''.

=== FHEM-Devices ===
[[Bild:MQTT2 MiLight.png|400px|thumb|Milight: Darstellung in FHEMWEB]]
==== Bridge ====
Wird nun über den Hub oder eine von diesem erkannte Fernbedienung ein vorhandenes Leuchtmittel geschaltet, wird bei eingeschaltetem autocreate ein erstes Device erstellt, die zunächst erstellte Definition sieht typischerweise etwa so aus:
defmod MQTT2_milight_hub_1370325 MQTT2_DEVICE milight_hub_1370325
attr MQTT2_milight_hub_1370325 IODev MQTT2_FHEM_Server
attr MQTT2_milight_hub_1370325 readingList milight_hub_1370325:milight/updates/0xBE59/rgbw/1:.* { json2nameValue($EVENT, '1_', $JSONMAP) }
attr MQTT2_milight_hub_1370325 room MQTT2_DEVICE

Auf dieses Device wird nun das ''template'' '''esp_milight_hub_bridge''' angewandt.

==== Einzelne Leuchtmittel ====

Wird nun nochmals das oben verwendete Leuchtmittel geschaltet, erstellt autocreate ein weiteres Device:
defmod MQTT2_milight_0xBE59_1 MQTT2_DEVICE milight_0xBE59_1
attr MQTT2_milight_0xBE59_1 IODev MQTT2_FHEM_Server
attr MQTT2_milight_0xBE59_1 readingList milight/states/0xBE59/rgbw/1:.* { json2nameValue($EVENT, '1_', $JSONMAP) }
attr MQTT2_milight_0xBE59_1 room MQTT2_DEVICE

Auf dieses wird nun eines der Bulb-templates angewendet. Wählt man das template X_01_esp_milight_hub_rgbw_bulb, wird eine einfache Variante erstellt, die neben einem toggelnden Icon nur Regler für Helligkeit, die Farbe und zwei Schaltflächen für den Weiß- und Nachtmodus enthält. Wer mehr oder andere Steuerelemente erhalten möchte, verwendet ein anderes template. Nicht benötigte Elemente kann man dabei einfach aus der Definition löschen.

Alle weiteren Devices werden genauso erstellt.

Um ein Device zu erhalten, mit dem sich alle Kanäle gleichzeitig steuern lassen, kann das template ''X_01a_esp_milight_hub_make_rgbw_group'' verwendet werden. Dieses verändert nicht das aktuelle Device, sondern erstellt '''eine Kopie''', die dann modifiziert wird. Diese Kopie ist unter dem Namen ''milight_<RemoteID>_0'' im selben Raum zu finden wie das Ausgangsgerät und kann ebenfalls an die eigenen Wünsche angepasst werden.

Weitere Beispiele:
Beispiel für ein RGB-CCT-Device:
defmod Licht_Wz_all MQTT2_DEVICE
attr Licht_Wz_all IODev MQTT2_Broker
attr Licht_Wz_all eventMap /set_white:Weiss/night_mode:Nacht/white_mode:white/on:on/off:off/ON:on/OFF:off/next_mode:Mode/mode_speed_up:Up/mode_speed_down:Down/
attr Licht_Wz_all group Licht
attr Licht_Wz_all icon light_control
attr Licht_Wz_all readingList milight/0x5D02/rgb_cct/0:.* { json2nameValue($EVENT) }\
milight/updates/0x5D02/rgb_cct/0:.* { json2nameValue($EVENT) }\
milight/states/0x5D02/rgb_cct/0:.* { json2nameValue($EVENT) }\

attr Licht_Wz_all room Wohnzimmer
attr Licht_Wz_all setList on milight/0x5D02/rgb_cct/0 {"status":"ON"}\
off milight/0x5D02/rgb_cct/0 {"status":"OFF"}\
level milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
hue:colorpicker,HUE,0,1,359 milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
command:uzsuSelectRadio,Weiss,Nacht,Mode,Up,Down milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
brightness:colorpicker,BRI,0,1,255 milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
next_mode milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
mode_speed_up milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
mode_speed_down milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
saturation:colorpicker,BRI,0,1,100 milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
color_temp:colorpicker,CT,153,1,370 milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
device_id milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
effect milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
mode milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}\
commands milight/0x5D02/rgb_cct/0 {"$EVTPART0":"$EVTPART1"}
attr Licht_Wz_all sortby 1
attr Licht_Wz_all webCmd command:brightness:saturation:color_temp:hue
attr Licht_Wz_all webCmdLabel command\
:brightness:saturation\
:color_temp:hue
==== Ein Leuchtmittel, mehrere Fernbedienungen ====
Pairt man mehrere Fernbedienungen mit einem Leuchtmittel, sollten auch alle entsprechenden Fernbedienungscodes in das readingList-Attribut übernommen werden. Dazu übernimmt man am einfachsten die Einträge aus den zusätzlichen MQTT2_DEVICEs. Benötigt man das zusätzliche Device nicht separat, um z.B. eine getrennte Gruppenschaltung zu realisieren, kann man dieses löschen. Beispiel-readingList für ein Device, das auf zwei Fernbedienungscodes und zwei Gruppen "hört":

attr Licht_Wz_all readingList milight/states/0x1234/rgbw/2:.* {json2nameValue($EVENT) }\
milight/updates/0x1234/rgbw/2:.* { json2nameValue($EVENT) }\
milight/states/0x1234/rgbw/0:.* { json2nameValue($EVENT) }\
milight/updates/0x1234/rgbw/0:.* { json2nameValue($EVENT) }\
milight/states/0xABCD/rgbw/0:.* { json2nameValue($EVENT) }\
milight/updates/0xABCD/rgbw/0:.* { json2nameValue($EVENT) }\
milight/states/0xABCD/rgbw/4:.* { json2nameValue($EVENT) }\
milight/updates/0xABCD/rgbw/4:.* { json2nameValue($EVENT) }

==== Fernbedienung als Input-Device nutzen ====
In diesem {{Link2Forum|Topic=103493|LinkText=Thread}} ist dargestellt, wie man eine Fernbedingung des Typs FUT089 dazu verwenden kann, einen [[MPD]] oder Rollladenaktoren zu steuern, oder diese Fernbedienung für [[Hue#HUE-Device|HUEDevice]]-Leuchtmittel zu nutzen.
Um hier nur Differenz-Meldungen direkt an die betreffende myUtils-Funktion zu übergeben und doppelte Events zu verhindern, sollte hier die readingList so angepasst werden, dass nur Messages aus dem "updates"-Zweig ausgewertet werden:
defmod MiLight_RC1_0 MQTT2_DEVICE milight_0xABCD_0
attr MiLight_RC1_0 readingList milight/states/0xABCD/fut089/[0-8]:.* {}
milight/updates/0xABCD/fut089/0:.* { FHEM::attrT_MiLight_Utils::MPDcontrol('myMPD',$EVENT, 'Yamaha_Main') }\
milight/updates/0x5D47/fut089/1:.* { FHEM::attrT_MiLight_Utils::FUT_to_RGBW('Licht_Stehlampe_links',$EVENT) }\
milight/updates/0x5D47/fut089/2:.* { FHEM::attrT_MiLight_Utils::FUT_to_RGBW('Licht_Stehlampe_rechts',$EVENT) }\
milight/updates/0x5D47/fut089/3:.* { FHEM::attrT_MiLight_Utils::four_Lights_matrix($EVENT, 'Licht_WoZi_Vorn_Aussen', 'Licht_WoZi_Vorn_Mitte', 'Licht_WoZi_Hinten_Aussen', 'Licht_WoZi_Hinten_Mitte') }\
milight/updates/0x5D47/fut089/4:.* { FHEM::attrT_MiLight_Utils::shuttercontrol('Jalousie_WZ',$EVENT) }\
milight/updates/0x5D47/fut089/5:.* { FHEM::attrT_MiLight_Utils::shuttercontrol('Rollladen_WZ_SSO',$EVENT) }\
milight/updates/0x5D47/fut089/6:.* { FHEM::attrT_MiLight_Utils::shuttercontrol('Rollladen_WZ_SSW',$EVENT) }\
milight/updates/0x5D47/fut089/7:.* {}\
milight/updates/0x5D47/fut089/8:.* {}
attr MiLight_RC_WZ stateFormat CommandSet

== eBus ==
An dieser Stelle sollen lediglich die Grundzüge erläutert werden, eine ausführliche Anleitung über die Konfiguration des [[EBUS-MQTT2|eBus mit MQTT2 gibt es hier]].

=== Vorbereitung und Definition am eBus ===
Vorausgesetzt wird ein laufender eBus-Dämon. Dessen Einrichtung wird im Artikel [[EBUS#Software|EBUS]] beschrieben.
In der Konfiguration des Dämons ( /etc/default/ebusd ) ist die Kommunikation über MQTT zu aktivieren und die Topic-Struktur festzulegen, z.B. ''ebusd/%circuit/%name''.
--accesslevel=* --mqttport=1883 --mqttjson --mqtthost=IpAdresseMQTTSERVER --mqtttopic=ebusd/%circuit/%name
{{Hinweis|Nachfolgend wird davon ausgegangen, dass als Vorgabe für mqtttopic ''ebusd'' verwendet wurde. Dies kann geändert werden, es wird aber dringend empfohlen, das mqtttopic in jedem Fall mit ''ebus...'' zu beginnen!}}

=== Vorbereitung und Definition in FHEM ===
Unabhängig von dem konkret genutzten IO-Modul (MQTT2_SERVER oder MQTT2_CLIENT) sollte an diesem '''''vor''''' den nachfolgenden Schritten zunächst das autocreate ausgeschaltet werden. Weiter sollte geprüft werden, ob es bereits MQTT2_DEVICE-Geräte gibt, die Einträge in der ''readingList'' enthalten, die vom ebus stammen. Da wir die ''readingList'' anschließend mit erweiterten JSON-Optionen erstellen wollen, müssen zumindest sämtliche ''readingList''-Attribute entsprechend bereinigt oder gelöscht werden; in der Regel ist es einfacher, diese Geräte nach dem Deaktivieren des autocreate am IO zu löschen.
{{Randnotiz|RNTyp=y|RNText=Sollten Sie MQTT2_CLIENT als IO nutzen, sollte für das weitere Vorgehen eine Kopie des MQTT2-"Sammeldevices" genutzt werden, und dessen ''CID'' auf ''ebusd'' geändert werden. Nach Anwendung des ebusd-splitter-templates müssen dann alle den ebus betreffenden Einträge aus der ''readingList'' des "Sammeldevices" gelöscht werden oder diese ganz gelöscht.}}Ist der ebus-Dämon lauffähig und für MQTT konfiguriert, sendet dieser regelmäßige Messages.

Sind die Vorbereitungen abgeschlossen, aktivieren wir ''autocreate'' wieder, allerdings wählen wir als autocreate-Methode ''complex'' aus, da der eBus-Dämon teilweise<ref>Dies betrifft vorrangig die Statusmeldungen</ref> eine weiter verschachtelte JSON-Struktur zum Versenden der Informationen verwendet als üblich. Danach wird wie bei den anderen o.g. Geräten automatisch ein neues MQTT2_DEVICE angelegt<ref>Bei Verwendung des MQTT2_CLIENT wird dann die ''readingList'' am bereits definierten MQTT2_DEVICE aus der Kopie des "Sammeldevice" automatisch wieder erstellt bzw. gefüllt.</ref>

==== "ebus-Bridge" ====
Auf das von ''autocreate'' erstellte MQTT2_DEVICE wird nunmehr das template ''eBus_daemon_splitter'' angewendet. Nach einiger Zeit sollte sowohl die readingList an diesem Device erweitert worden sein, wie auch ein oder mehrere neue MQTT2_DEVICE-Geräte angelegt.
Dieses Device liefert zukünftig Readings zum Dämon selbst, wie dessen ''uptime'', alle weiteren am eBus angeschlossenen Teilnehmer werden dagegen zweckmäßigerweise durch ein oder mehrere weitere MQTT2_DEVICE-Geräte dargestellt.

Das ''attrTemplate'' läd eine weitere ''attrTemplate''-file und [[99 myUtils anlegen|99_myUtils-Code]] vom FHEM-Server nach. Beides steht dann auch unmittelbar zur Nutzung zur Verfügung.
==== "ebusd_bai" und weitere Geräte ====
{{Hinweis|Der eBus-Dämon sendet nicht alle Informationen zu allen am eBus angeschlossenen Geräte automatisch. Diese müssen teilweise erst aktiv angefragt werden. Wie das im einzelnen erfolgen kann, ist dem o.g. Detailartikel zu entnehmen.}}
Funktioniert die Kommunikation zwischen dem eBus-Dämon und FHEM, sollte nach einigen Minuten zumindest ein weiteres Gerät namens ''MQTT2_ebus_bai'' angelegt worden sein.

== Sonos2Mqtt ==
Aus einem Versuch heraus ist ein {{Link2Forum|Topic=111711|LinkText=kleines Projekt}} geworden: Die Sonos Umgebung mit Hilfe von sonos2mqtt als generisches MQTT2_DEVICE komfortabel in FHEM einzubinden.

Mit Hilfe von ein paar Templates ist die grundlegende Einbindung in FHEM nach einer kleinen Installation auf Systemebene schnell erledigt. Es läuft derzeit noch zahlreiche Entwicklung und Ideenfindung, die Fortschritte sind live im Thread oder [[Sonos2mqtt|konsolidiert im Wiki]] zu finden.

=== Setup im System ===
Für dies Funktion wird der nodejs Server [https://github.com/svrooij/sonos2mqtt sonos2mqtt] benötigt. Entweder installiert man den lokal, irgendwo im Netzwerk oder nutzt den [[MQTT2-Module - Praxisbeispiele#Verwendung des Docker Containers|Docker Container.]]

Der nodejs Server sonos2mqtt kann aus Sicht von FHEM irgendwo im Netzwerk stehen - aber er muss im gleichen Netzwerk wie die Sonosplayer stehen. Das UPNP Sonosnetzwerk funktioniert nicht über Netzwerksegmente hinweg.

Eine Beschreibung aller Startparameter für sonos2mqtt findet man [https://svrooij.io/sonos2mqtt/getting-started.html in der offiziellen Doku].

Erreicht der nodejs Server sonos2mqtt den MQTT Server nicht über - default: localhost, Port 1883, keine Anmeldung" - muss der Parameter --mqtt gesetzt werden!

Beispiele:
:<code>--mqtt mqtt://myuser:the_secret_password@192.168.0.3:1800</code> # alles gesetzt
:<code>--mqtt mqtt://192.168.0.3:1800</code> # IP Adresse und Port gesetzt, keine Anmeldung am MQTT Server
:<code>--mqtt mqtt://192.168.0.3</code> # IP Adresse gesetzt, Port ist Standard 1883

Erfolgt der Start mit pm2, werden die Parameter mit einem ''zusätzlichen'' doppelten Bindestrich (--) hinter dem nodejs Modul übergeben.

Beispiel:
<syntaxhighlight lang="perl">
pm2 start sonos2mqtt -- --mqtt mqtt://myuser:the_secret_password@192.168.0.3:1800
</syntaxhighlight>

'''Lokales Setup'''

Voraussetzung: nodejs und pm2 ist installiert und für alle Benutzer verfügbar. <syntaxhighlight lang="bash">
sudo npm install -g sonos2mqtt
</syntaxhighlight>
Je nach Entwicklungsstand sind auch Betaversionen verfügbar. Für aktuelle Betaversionen wird dieser Zusatz beim Setup verwendet. -> sonosmqtt@3.1.0-beta.1

Wird der sonos2mqtt Server auf einer anderen Maschine eingerichtet, ist der Start entsprechend diesem Absatz [[MQTT2-Module - Praxisbeispiele#Autostart von sonos2mqtt im System mit pm2 .28Alternative.29|Autostart von Sonos2mqtt im System mit pm2]] einzurichten.

=== Setup in FHEM ===
Man definiert lediglich ein Bridge Device, der Rest wird automatisch erledigt.

Voraussetzung:
* autocreate im System ist aktiv.
* Der verwendete MQTT2_SERVER steht auf '''autocreate simple''' (default/Standard).
* Templates aktuell - FHEM uptodate oder bei Bedarf in der FHEM Kommandozeile aktualisieren:
<pre>
{ Svn_GetFile("FHEM/lib/AttrTemplate/mqtt2.template", "FHEM/lib/AttrTemplate/mqtt2.template", sub(){ AttrTemplate_Initialize() }) }
</pre>
Bei der Anwendung des Templates für die Bridge wird das Attribut devicetopic ausgelesen oder auf default sonos gesetzt!

Wird ein anderer Devicetopic verwendet, muss der bei der Anlage der Bridge gesetzt werden!

Diese Zeilen einzeln in der FHEM Kommandozeile oder als Block in der Raw Definition. <syntaxhighlight lang="perl">
define SonosBridge MQTT2_DEVICE
attr SonosBridge room MQTT2_DEVICE
set SonosBridge attrTemplate sonos2mqtt_bridge_comfort
</syntaxhighlight>
Das Template sonos2mqtt_bridge_comfort:
* setzt das Template sonos2mqtt_bridge auf das Device,
* lädt die Datei 99_sonos2mqttUtils.pm aus dem contrib Ordner nach,
* definiert ein notify, dies erledigt im weiteren Betrieb die automatische Konfiguration der automatisch erzeugten MQTT2_DEVICEs.
** mit dem Template sonos2mqtt_speaker (das Template kann auch manuell auf vorhandene Player angewendet werden, die automatische Erzeugung der Player wird aber empfohlen)
** Ermittelt Detailinformation des jeweiligen Players (vor allem IP Adresse und Modelnumber)
** Lädt die Sonosgeräte Icons von den UPNP Devices herunter
** erweitert das setList input Kommando um den TV Eingang (HDMI, spdif) bzw. Line_IN Eingang falls vorhanden (Modelnumber)
* Die Player werden automatisch einzeln erzeugt wenn sie mqtt Nachrichten senden (Play/Stop) oder (alle sofort) wenn der sonos2mqtt Server gestartet wird.

==== Wozu dient die Bridge? ====
Sie stellt ein paar wesentliche Funktionen zu Verfügung
# Auffangen von nicht benötigten MQTT Nachrichten.
# Erzeugung/Weiterleitung von Nachrichten für die einzelnen Player - damit auch die Erzeugung von separaten Playern nach dem Schema MQTT2_RINCON12345678901234567.
# Statusanzeige sonos2mqtt als Reading connected (0 offline, 1 connected, 2 Player connected).
Sie kann zusätzlich als zentrales Device verwendet werden, um die Sonos Umgebung abzubilden, z.B. Readings für Favoriten u.ä.

==== Start sonos2mqtt lokal ====
Der Start / Stop des sonos2mqtt Servers innerhalb von FHEM ist nur lokal simpel möglich. Ist der Server irgendwo im Netzwerk oder im Docker Container, muss man andere Möglichkeiten finden. Der Neustart aus FHEM ist zwar praktisch, aber nicht erforderlich.

Wird eine existierenden Sonos Landschaft inhaltlich verändert (Player dazu/weg), muss der Server neu gestartet werden. Werden Player temporär abgeschaltet, merkt das der Server nach einer Zeit selbst, oder man forciert dies mit einem CheckSubscription an der Bridge.

Soll das Modul sonos2mqtt mit seinen default Einstellungen gestartet werden, genügt dieser kurze Befehl (in der FHEM Kommandozeile):
<syntaxhighlight lang="bash">
"pm2 start sonos2mqtt"
</syntaxhighlight>
Tipp: Verwendet man anstatt "Befehl" den Syntax {qx(Befehl)} in der FHEM Kommandozeile, wirkt der Befehl zwar blockierend aber die Ausgabe erfolgt im Browser und nicht im Logfile. Mit dem Parameter -s erfolgt keine Ausgabe.

==== Autostart von sonos2mqtt mit FHEM ====
Der Code startet sowohl das sonso2mqtt Modul sofort und implementiert ein notify für den zukünftigen automatischen Start beim Start von FHEM.
<syntaxhighlight lang="perl">
define n_pm2_sonos notify global:INITIALIZED|n_pm2_sonos:start "pm2 -s start sonos2mqtt"
trigger n_pm2_sonos start
</syntaxhighlight>

=== Autostart von sonos2mqtt im System mit pm2 (Alternative) ===
Der obige Code startet das sonos2mqtt nodejs Modul mit pm2 beim Start von FHEM. Sollte das nicht funktionieren oder nicht ins gesamte Konzept passen (weil z.B. mehrere nodejs Module geladen werden) kann der automatische Start direkt im System erfolgen. Zunächst dafür das oben eventuell schon definierte notify löschen!<syntaxhighlight lang="perl">
delete n_pm2_sonos
</syntaxhighlight>Der Start des Modul muss nicht mit erhöhten Rechten geschehen! Im Terminal folgendes eingeben (unter dem angemeldeten Benutzer wird sonos2mqtt später immer gestartet):<syntaxhighlight lang="bash">
pm2 start sonos2mqtt
pm2 startup
</syntaxhighlight>
Der letzte Befehl "redet", d.h. es gibt eine Ausgabe in der Art:
<syntaxhighlight lang="bash">
[PM2] To setup the Startup Script, copy/paste the following command:
sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u pi --hp /home/pi
</syntaxhighlight>
Man tut einfach genau das, was dasteht: die letzte Zeile kopieren und wieder einfügen und ausführen. Danach muss man die Konfiguration von pm2 noch sichern:
<syntaxhighlight lang="bash">
pm2 save
</syntaxhighlight>

=== Verwendung des Docker Containers ===
Ergänzend zur [https://svrooij.io/sonos2mqtt/getting-started.html#run-sonos2mqtt-in-docker Original Doku:]

Beim Container findet die Konfiguration der Verbindung zum FHEM in den Environment Variablen statt:
<syntaxhighlight lang="perl">
environment:
- SONOS2MQTT_DEVICE=192.168.56.207 # hier muss einer der Sonos Lautsprecher stehen
- SONOS2MQTT_MQTT=mqtt://192.168.56.121:1883 # mqtt2_server FHEM, erweiterter Syntax siehe oben
- SONOS_LISTENER_HOST=192.168.56.121 # Docker host IP
</syntaxhighlight>

=== Sonos2mqtt mit mehr Komfort ===
Im Wiki Artikel [[Sonos2mqtt]] geht es weiter.

== Owntracks GPS Tracking in FHEM ==
Das hier gezeiget Beispiel verwendet eine MQTT Instanz im Internet, die mit einem MQTT2_CLIENT angebunden wird. Da wenig Traffic benötigt wird, genügt z.B. eine kostenfreie Instanz z.B. bei myqtthub (Stand. Dezember 2020)

Alternativ kann man einen MQTT2_SERVER auch direkt verfügbar machen, wenn man sich sicher ist was man da tut! Siehe {{Link2Forum|Topic=99666|Message=1028576|LinkText=diesen Forenbeitrag}}. Das Bridge Device wird dabei genau so benötigt, nur der IODev ist dann der MQTT2_SERVER.

=== owntracks auf dem Smartphone konfigurieren ===
Menü / Einstellung / Verbindung

Dort sind insgesamt 4 Registerkarten mit Werten zu füllen (Beispiel):
* Modus -> MQTT
* Hostname ->
** Hostnamen: host.cloud.com
** Port: 8883
** ClientID: ID vom Provider
** WebSockets (nicht nutzen)
* Identifikation ->
** Benutzername: user-name
** Passwort: user-password
** GeräteID: mi6 (erscheint in FHEM im Device Namen verwendet)
** TrackerID: hk (nur zweistellig, erscheint als ID in der owntracks Karte)
* Sicherheit -> TLS aktivieren
=== Definition in FHEM ===
Der MQTT2_CLIENT wird so eingerichtet, man braucht eine andere ClientID als auf dem Smartphone! Stimmt alles sollte das Gerät sofort open anzeigen.<syntaxhighlight lang="perl">
MQTT2_CLIENT einrichten, autocreate simpel
define mqtt2Cloud MQTT2_CLIENT host.cloud.com:8883
attr mqtt2Cloud SSL 1
attr mqtt2Cloud autocreate simple
attr mqtt2Cloud clientId fhem1
attr mqtt2Cloud room MQTT2_IO
attr mqtt2Cloud username user-name
set mqtt2Cloud password user-password
</syntaxhighlight>Für die automatische Erzeugung der Trackergeräte in FHEM richtig man zuerst ein Bridge Device ein:<syntaxhighlight lang="perl">
define MQTT2_Cloud_bridge MQTT2_DEVICE
attr MQTT2_Cloud_bridge IODev mqtt2Cloud
attr MQTT2_Cloud_bridge autocreate 1
attr MQTT2_Cloud_bridge room MQTT2_DEVICE
</syntaxhighlight>Dies wird entweder mit dem Template allgemein konfiguriert<syntaxhighlight lang="perl">
set MQTT2_Cloud_bridge attrTemplate MQTT2_CLIENT_general_bridge
</syntaxhighlight>oder manuell nur für owntracks eingerichtet<syntaxhighlight lang="perl">
attr MQTT2_Cloud_bridge bridgeRegexp owntracks/[^/]+/([^/:]+).* "owntracks_$1"
</syntaxhighlight>MQTT2 Geräte für owntracks werden jetzt automatisch mit dem Namen MQTT2_owntracks_<GeräteID> erzeugt. Diese werden einfach mit dem Template owntracks_device fertig konfiguriert. Bei einem IOS Gerät kann man danach noch das Template owntracks_device_IOS als Erweiterung anwenden.

==== Anwesenheitserkennung ====
Die Anwesenheit kann im owntracks Device direkt für die selbst definierten Plätze abgelesen werden: entweder steht im reading place der jeweilige Ort oder away. Um hier noch eine gewisse Einheitlichkeit in der Verwendung zu bekommen kann man ein PRESENCE Device verwenden: <syntaxhighlight lang="perl">
define OT_Mi6 PRESENCE event MQTT2_owntracks_mi6:place:.away MQTT2_owntracks_mi6:place:.<Home>
</syntaxhighlight>Im Move Modus erfolgt die Erkennung sehr schnell und damit einige Sekunden eher als eine BT Erkennung im Haus - der Akkuverbrauch steigt enorm. Im Significant Modus kann es schon mal ein paar Minuten dauern - ein relevanter Akku Verbrauch ist nicht erkennbar.

== Allgemeine Hinweise ==
=== MQTT2_SERVER und MQTT2_CLIENT für Debugging nutzen ===
Nutzt man das rawEvents-Attribut am MQTT2-IO<ref>z.B. <code>attr MQTT2_FHEM_Server rawEvents .*</code>, der regex-Filter kann wie üblich angepasst werden</ref>, kann man den Datenverkehr des Servers am Event-Monitor mitschneiden. Dies ist insbesondere für unbekannte Geräte nützlich, deren Topic- und Payload-Struktur noch nicht bekannt ist.
Um den kompletten MQTT Datenaustausch mitzuschneiden, kann man mit <code>attr mqtt2_server verbose 5</code> auch alles ins FHEM-Log schreiben lassen.

=== autocreate funktioniert anscheinend nicht? ===
In der Regel wird bei neu eingehenden MQTT-Messages über ''autocreate'' ein neues Device erstellt, wenn Nachrichten von einem bisher unbekannten Gerät kommen. Geschieht dies nicht, sollten folgende Punkte geprüft werden:
# (nur bei MQTT2_SERVER:) Der Client muss eine ClientID angeben, diese darf nicht den defaults von ''mosquito_sub'' entsprechen.
# Ein allgemeines {{Link2CmdRef|Anker=autocreate|Lang=en|Label=autocreate}}-Device (''TYPE=autocreate'') muss vorhanden und aktiv sein.
# ''autocreate'' am IO muss eingeschaltet sein, was für MQTT2_SERVER bedeutet, dass es nicht auf "0" stehen darf (hier ist dann ''simple'' die aktive Voreinstellung), für MQTT2_CLIENT sollte ebenfalls ''simple'' verwendet werden; dies muss hier allerdings explizit gesetzt werden.

Wird dann immer noch kein Device erstellt, gibt es in aller Regel ein Device, das bereits einen entsprechenden Eintrag in der readingList enthält, oder es sind keine Nachrichten eingegangen. Überprüfen Sie daher dann ggf. die Einstellungen am Client-Gerät (z.B. im Web-Interface des Shelly oder Tasmota-geflashten ESP8266).

Das ''autocreate'' am Device schließlich bestimmt, ob die ''readingsList'' erweitert werden darf, wenn Informationen über bisher nicht über die readingList abgedeckte Topics empfangen werden und vom MQTT2-IO als zu diesem Device/ClientID gehörend identifiziert wurden.

=== attrTemplate ===
{{Randnotiz|RNTyp=Info|RNText=Die per attrTemplate jeweils erzeugten Konfigurationen sind Einrichtungsbeispiele, die v.a. eine in sich konsistenze Zusammenstellung der verschiedenen Attribute enthalten. Es steht jedem User frei, diese Ausgangsbasis dann nach seinem Belieben zu ändern. Spätere Änderungen des verwendeten attrTemplate wirken sich nicht automatisch auf die durch frühere Versionen oder den User nachkonfigurierte Geräte aus! Da es vorkommen kann, dass sich die per MQTT übermittelten Daten und Topics ändern, wenn z.B. eine firmware aktualisiert wurden, kann dies Anpassungen am jeweiligen Template erforderlich machen. Grundsätzlich sollen die per attrTemplate für MQTT2_DEVICE verfügbaren attrTemplate jeweils für die aktuellste verfügbare stabile firmware-Version passen.}}
Zur Konfiguration von MQTT2_DEVICE-Geräten kann die Funktion ''[[AttrTemplate|attrTemplate]]'' genutzt werden.
Die Anwendung für MQTT2_DEVICE ist [[MQTT2 DEVICE#attrTemplate|hier]] beschrieben.

{{Hinweis|In einigen Fällen kann es vorkommen, dass die template-Bezeichnung zwischenzeitlich geändert wurde. Seit 21.09.2019 erfolgt die Sortierung der auswählbaren templates nicht mehr nur nach den Namen, so dass die entsprechenden Namensbestandteile entfallen sind, die einer besseren Sortierung dienten.}}

=== attrTemplate: Es werden nicht alle templates angezeigt ===
Siehe Beitrag [[AttrTemplate#Warum finde ich das Template xyz nicht.3F|AttrTemplate: Warum finde ich das Template xyz nicht.]]

=== attrTemplate und Sprachsteuerung ===
Konfiguriert man MQTT2_DEVICE-Geräte mit attrTemplate, werden in der Regel auch direkt die für die Sprachsteuerung der Geräte erforderlichen Attribute mit gesetzt. Weiterführende Hinweise sind auch zu diesem Teilaspekt von ''[[AttrTemplate|attrTemplate]]'' dem betreffenden Hauptartikel zu entnehmen.

=== bridgeRegexp ===
[[Datei:Mqtt2 server.png|300px|thumb|left|Logische Verortung der bridgeRegexp-Angaben]]{{Randnotiz|RNTyp=y|RNText=Beachten Sie, dass aufgrund des geschilderten Prinzips eine Änderung einer bridgeRegexp bei einem Gerät auch dazu führt, dass alle Readings eines Geräts und alle readingList-Einträge gelöscht werden.}}Üblicherweise werden alle Informationen, die aus einer Quelle stammen auch '''''einem''''' ''MQTT2_DEVICE'' zugeordnet, wobei im Falle des dort nicht aktivierten autocreate-Attributs entsprechende readingList-Einträge erzeugt werden. In dem nebenstehenden Schaubild wären dies die Geräte ''A'' bis ''D''. Das '''Attribut''' ''bridgeRegexp'' kann dazu genutzt werden, um neue, bisher unbekannte Topic-Strukturen im Rahmen des autocreate-Vorgangs anders zu strukturieren. Diese werden dabei im Ergebnis einem '''anderen Device''' (das ggf. erst erstellt wird) zugeschlagen, sollte eine zu der topic-Struktur passende regex in diesem Attribut gesetzt sein. Für dessen CID und die Bildung des Names wird die im 2. Teil jedes Eintrags als ''newClientId'' hinterlegte Angabe verwendet. In nebenstehendem Schaubild ist dies exemplarisch für die Gerätegruppe ''D'' mit dem ''bridge''-Device ''D'' und dessen ''Satelliten'' ''D1'' bis ''D4'' dargestellt.
Dementsprechend sind in den hier aufgeführten Beispielen ''bridgeRegexp''-Attribute immer dort zu finden, wo ein Gerät oder Dienst dazu dient, mit weiteren, ggf. auf andere Weise kommunizierende Geräte oder Baugruppen zu kommunizieren, wie z.B. für über hier dargestellten ''zigbee2mqtt'' oder ''zigbee2tasmota''. Ein Sonderfall hierbei ist das template ''MQTT2_CLIENT_general_bridge'' zur Verwendung mit dem [[MQTT2_CLIENT#Anwendung|MQTT2_CLIENT]], denn aus dessen Sicht stammen alle Informationen aus derselben Quelle, nämlich z.B. dem ''mosquitto''-Server und würden sonst alle einem einem MQTT2_DEVICE zugewiesen.

=== Ständig neue Devices? ===
MQTT2_SERVER kann zwischen verschiedenen Geräten auch anhand der ClientID unterscheiden. Für jedes neu erkannte Gerät wird auch ein eigenes MQTT2_DEVICE angelegt. Abhilfemaßnahmen:
==== Vergabe einer ClientID ====
Die meisten MQTT-fähigen Geräte enthalten Optionen zur Vergabe einer eindeutigen ClientID (siehe das Beispiel des zigbee2mqtt-Dienstes oben).
Wird keine ClientID vergeben, verwenden manche Clients für jede Verbindung wieder neue ID's. Es wird empfohlen, möglichst von diesen Einstelloptionen Gebrauch zu machen.

==== Löschen der ClientID aus der readingList usw. ====
Ist dies nicht möglich oder erwünscht, kann man auch die ClientID aus den readingList-, setList- und getList-Attributen entfernen. Dies ist jedenfalls solange unschädlich als nicht mehrere Geräte identische Topic-Pfade verwenden (daher die Empfehlung, insbesondere bei Tasmota-Geräten den ''default'' "sonoff" zu ändern).
Beispielsweise wäre <code>attr Milight_Bridge readingList milight_hub_1370325:milight/LWT:.* {json2nameValue($EVENT) }</code> zu ändern in <code>attr Milight_Bridge readingList milight/LWT:.* {json2nameValue($EVENT) }</code>
Die über ''attrTemplate'' verfügbaren Konfigurationen verwenden in der Regel keine ClientID's bzw. entfernen diese.

=== Wildcards in readingList und setList ===
Auch in readingList und in setList sollten sich sog. wildcards verwenden lassen. Die Vorgehensweise ist jedoch unterschiedlich:

In ''readingList'' werden normale regex-Ausdrücke verwendet. Ein Punkt steht daher z.B. für ein beliebiges Zeichen, alles zwischen zwei Topic-Tree-Elementen (getrennt typischerweise durch einen "/") kann man so schreiben: "[^/]+" (entspricht: "Mindestens ein Zeichen, das kein Schrägstrich ist"). Ergänzender Hinweis: Will man z.B. Informationen aus einem beliebigen Teil des Topic-trees extrahieren und als Reading-Namen verwenden, kann dies im Rahmen eines Perl-Aufrufs geschehen. Beispiele aus der mqtt2.template-file: OpenMQTTGateway_BT_scanner und OpenMQTTGateway_BT_gtag (letzteres überführt die Information, über welches Gateway bestimmte Informationen eingegangen ist jeweils in eigene Readings pro Gateway).

In ''setList'' gelten dagegen die wildcard-Konventionen aus der MQTT-Welt. Dort steht "+" für einen austauschbaren Teil des Topic-Trees (zwischen zwei Schrägstrichen). Anmerkung: Bitte vorher prüfen, ob es wirklich sinnvoll ist, derart unspezifische Publishes vorzunehmen. Meist gibt es "Gruppen-Topics", auf die mehrere Geräte eines bestimmten Typs hören bzw. man kann dies dort (in der firmware bzw. auf den Konfigurationsseiten der Geräte) einstellen.

=== Die JSON-Daten sollen ausnahmsweise nicht ausgepackt werden ===
In manchen Fällen ist das automatische Auspacken der JSON-Payload nicht erwünscht. In diesen Fällen kann man einfach den gewünschten Reading-Namen in die readingList eintragen, statt der Anweisung, den JSON an json2NameValue() zu übergeben. Aus
<pre>
attr MQTT_OwnTracks readingList owntracks/clouduser/mi6:.* { json2nameValue($EVENT) }\
owntracks/clouduser/mi6/waypoints:.* { json2nameValue($EVENT) }\
owntracks/clouduser/mi6/event:.* { json2nameValue($EVENT) }
</pre>
wird dann:
<pre>
attr MQTT_OwnTracks readingList owntracks/clouduser/mi6:.* json_mi6\
owntracks/clouduser/mi6/waypoints:.* json_waypoints\
owntracks/clouduser/mi6/event:.* json_event
</pre>
Erforderlichenfalls kann man die Einträge auch doppelt erstellen, um sowohl den JSON wie auch die ausgepackten Readings zu erhalten.

=== Die JSON-Daten vor dem auspacken manipulieren ===
Aus diversen Gründen kann es zweckmäßig sein, einen bestimmten Wert der JSON-Payload zu ignorieren.
Z.B. sendet ein Client statt eines Messwertes die Info "bad". Dieser Fehlerwert soll aus der JSON-Payload "ausgefiltert" werden:
<pre>
attr DEVICE readingList <your topic>:.* { my $rets = json2nameValue($EVENT,'',$JSONMAP);; my %cleaned = map { $_,$rets->{$_} } grep { 'bad' ne $rets->{$_} } keys %{$rets};; return \%cleaned }
</pre>

Oder auch einen Wert umzubenennen wenn die JSON-Payload nur ein Objekt beinhaltet:
<pre>
attr DEVICE readingList <your topic>:.* {my %h=(0=>'SofortLaden',1=>'MinPV',2=>'NurPV',3=>'Stop',4=>'Standby');; return {ChargeMode=>$h{$EVENT}}}
</pre>

=== Unnötige Konfigurationsinformationen verwerfen ===
Siehe Einleitung und den [[MQTT2_CLIENT#ignoreRegexp|ignoreRegexp-Abschnitt zu MQTT2_CLIENT]].

=== Weiterführende Themen ===
==== Verbinden mehrerer FHEM-Instanzen über MQTT ====
Wie im Hauptartikel zu [[MQTT#Kommunikation zu sonstigen FHEM-Geräten über MQTT|MQTT]] erläutert, gibt es mehrere Varianten, wie man mit Hilfe von FHEM aus Events an beliebigen Geräten MQTT-Messages erzeugen kann. So kann man z.B. Messdaten eines Systems über ein ''notify'' iVm. einer einfachen ''publish''-Anweisung an ein zweites FHEM schicken, das diese Daten dann z.B. mit Hilfe der MQTT2-Module auswerten kann.
Damit dabei Nachrichten unterschiedlicher Quellen auch als getrennte Readings bzw. ggf. auch gesonderten MQTT2_DEVICE-Instanzen zugeordnet werden, sollte man entsprechende Topic-Strukturen wählen, die dann auch mit Hilfe einer geeigneten ''bridgeRegexp'' automatisiert ausgewertet werden kann, siehe z.B. dieser {{Link2Forum|Topic=107145|LinkText=Forumsthread}}:
attr MQTT2_myMqttServer bridgeRegexp \
SmartHome/MqttGenericBridge2/([A-Za-z0-9]*)/.*:.* "mgb2_$1"
Dabei werden die betreffenden Informationen der entfernten FHEM-Instanz alle nach dem Schema ''SmartHome/MqttGenericBridge2/<Device-Name>/<Reading-Name>'' versendet.

==== Umstellung von MQTT_DEVICE (und Derivaten wie XiaomiMQTTDevice) zu MQTT2_DEVICE ====
Wer beabsichtigt, von der Implementierung MQTT+MQTT_DEVICE zu MQTT2-IO und MQTT2_DEVICE zu wechseln, sollte einige Punkte beachten. Viele diesbezügliche Fragen sind vor allem in {{Link2Forum|Topic=103762|LinkText=diesem Foren-Thread}}

näher erläutert.

== Links ==
* {{Link2Forum|Topic=91394|LinkText=Thread, aus dem diese Anleitung ursprünglich entstanden ist}}
* {{Link2Forum|Topic=91807|LinkText=Thread zum Tasmota-Device}}
* {{Link2Forum|Topic=97989|LinkText=Thread, aus dem diese Anleitung für den eBus ursprünglich entstanden ist}}
* {{Link2Forum|Topic=94495|LinkText=Neue templates einreichen}}
* {{Link2Forum|Topic=94494|LinkText=Fragen, Wünsche und Kritik zu mqtt2.template}}
* {{Link2Forum|Topic=116162|LinkText=Der MQTT-Workshop für MQTT2-Module}}

== Hinweise ==
<references />
[[Kategorie:HOWTOS]]
[[Kategorie:MQTT]]
[[Kategorie:IP Components|IP Komponenten]]
[[Kategorie:Other Components]]
[[Kategorie:Interfaces]]

Blocking Call

2022-07-18T08:29:52Z

Beta-User: typo

Dieser Artikel soll Hinweise und Best Practices im Umgang mit dem Modul Blocking.pm und den daraus bereitgestellten Funktionen bieten.

= Allgemein =

Das Modul Blocking.pm wurde von Rudolf König entwickelt, um in FHEM Funktionsaufrufe zu ermöglichen, die relativ viel Zeit in Anspruch nehmen und normalerweise FHEM damit zum Stillstand (für die Dauer der Ausführung der Funktion) bringen würde.

Um so etwas zu verhindern, kann man mit Hilfe von Blocking.pm eine Funktion über einen Fork des Hauptprozesses unabhängig davon abarbeiten und das Ergebnis dieser Funktion optional an den Hauptprozess übergeben.

= Benutzung =

Das Modul stellt primär die Funktion BlockingCall() zur Verfügung um eine Perl-Funktion "non-blocking" auszuführen.

'''BlockingCall($blockingFn, $arg, $finishFn, $timeout, $abortFn, $abortArg);'''

{| class="wikitable"
|-
! Argument !! Optional !! Beispiel !! Beschreibung
|-
| '''<code>$blockingFn</code>''' || nein || "speedtest_DoSpeedtest" || Der Name der Perlfunktion, die "non-blocking" ausgeführt werden soll (ohne Klammern, nur der reine Funktionsname).
|-
| '''<code>$arg</code>''' || nein || <nowiki>"DeviceName|Argument1|Argument2"</nowiki> || Das Funktionsargument, das der blockingFn übergeben werden soll.
|-
| '''<code>$finishFn</code>''' || ja || "speedtest_SpeedtestDone" || Die Funktion, die mit dem Funktionsergebnis der blockingFn als Parameter aufgerufen werden soll, sobald diese zuende ist. Diese Funktion wird dabei mit dem Returnwert als erstes Argument aufgerufen.
|-
| '''<code>$timeout</code>''' || ja || 120 || Sofern eine finishFn verwendet wird, kann ein optionales Timeout gesetzt werden, sobald der Aufruf abgebrochen wird, sobald dieser timeout in Sekunden verstrichen ist.
|-
| '''<code>$abortFn</code>''' || ja|| speedtest_SpeedtestAborted|| Wenn der Aufruf aufgrund eines überschrittenen Timeouts abgebrochen wird, so wird die abortFn aufgerufen, sofern eine definiert ist.
|-
| '''<code>$abortArg</code>''' || ja|| $hash || Im Falle eines Abruchs soll die abortFn mit diesem Argument aufgerufen werden. (Dient primär der Zuordnung eines solchen Abbruchs für Modulentwickler.
|}

Die Funktion BlockingCall() gibt bei Erfolg eine Hashreferenz mit mehreren Items zurück. Dieser Hash ist folgendermaßen aufgebaut.

{|
|-
| '''<code>$hash->{pid}</code>''' || → Die Prozess-Id, unter der dieser Aufruf abgearbeitet wird.
|-
| '''<code>$hash->{fn}</code>''' || → Der Name der blockigen, der mit diesem Aufruf abgearbeitet wird.
|-
| '''<code>$hash->{finishFn}</code>''' || → Der Name der finishFn, die diesen Aufruf nach Erfolg verarbeiten wird.
|-
| '''<code>$hash->{abortFn}</code>''' || → Der Name der abortFn, die im Fehlerfall aufgerufen wird.
|-
| '''<code>$hash->{abortArg}</code>''' || → Das Argument, das im Fehlerfall an die abortFn übergeben werden soll.
|}

= Einschränkungen =

Aktuell sind beim Einsatz von Blocking.pm folgende Einschränkungen zu beachten.

* Veränderungen an internen Variablen von FHEM (Device Hashes, Timers, usw.) werden innerhalb eines BlockingCalls durchgeführt und sind dort auch sichtbar, haben aber keinerlei Einfluss auf den eigentlichen FHEM Hauptprozess und alle Definitionen. Solche Veränderungen müssen an die finishFn delegiert werden (z.B. durch zusätzliche Rückgabewerte), da es sich um einen Fork-Prozess handelt, der sich nach Abschluss des BlockingCall selbst zerstört.
* Wenn viele Definitionen aktiv sind, welche BlockingCalls parallel starten kann es zu einem relativ hohen Memory-Footprint kommen aufgrund mehrfach laufenden Fork-Prozessen. Dies kann auf schwachbrüstiger Hardware zu Speicherengpässen führen. Ab FHEM Revision 11917 lassen sich die maximal parallel laufenden BlockingCalls durch das globale Attribut <code>blockingCallMax</code> begrenzen (Standardwert: ''unbegrenzt''). Sofern die maximale parallele Anzahl an BlockingCalls erreicht ist, werden weitere Calls in eine Warteschlange eingereiht und ausgeführt, sobald laufende Calls beendet werden.

= Blocking.pm für Modulentwickler =

Blocking.pm ist aktuell sowohl für Enduser, als auch für Modulentwickler gedacht. Die Benutzung in einem Modul birgt allerdings einige Stolperfallen, auf die hier näher eingegangen wird.

== return-Wert von BlockingCall immer in $hash abspeichern ==

Die Funktion BlockingCall() gibt als return-Wert einen Hash mit mehreren Informationen zurück. Dieser Ergebnis-Hash ist in mehrerer Hinsicht sehr wichtig für die Benutzung in einem Modul, dazu in den folgenden Punkten mehr.

Eine gute Möglichkeit ist es dieses Ergebnis unterhalb von $hash->{helper} zu platzieren. So sieht es der Enduser nicht, kann aber bei Bedarf via list-Befehl angezeigt werden.

Beispiel:

$hash->{helper}{RUNNING_PID} = BlockingCall( … );

== Sicherstellen, dass immer nur ein BlockingCall gleichzeitig läuft ==

Sobald ein BlockingCall läuft könnte man rein theoretisch direkt einen weiteren BlockingCall starten usw. Dadurch würden mehrer parallele Durchläufe nebenher laufen und könnten den FHEM-Server dadurch unnötig belasten oder sogar auch überlasten. Daher sollte man immer beim Start eines BlockingCall prüfen, ob bereits ein weiterer BlockingCall läuft oder bei mehreren parallelen Blocking Calls eine entsprechende Prüfung einführen um die maximale Anzahl an gleichzeitigen BlockingCalls innerhalb einer Definition zu begrenzen.

$hash->{helper}{RUNNING_PID} = BlockingCall(…) unless(exists($hash->{helper}{RUNNING_PID}));
Dies funktioniert nur dann, wenn man in der finishFn (und später auch abortFn) $hash->{helper}{RUNNING_PID} wieder löscht. Somit ist immer sichergestellt, dass nur ein BlockingCall zur gleichen Zeit läuft. Wenn gerade ein BlockingCall aktiv ist aufgrund eines Set-Befehls, könnte man eine Meldung ausgeben.

Beispiel:

BlockingCall("speedtest_DoSpeedtest", $name."|".$server, "speedtest_SpeedtestDone", 120, …);

speedtest_SpeedtestDone($)
{
…
delete($hash->{helper}{RUNNING_PID});
…
}

== Nutzung von abortFn und abortArg ==

Mal angenommen man führt einen BlockingCall aus und dieser wird innerhalb des gesetzten Timeouts von 5 Sekunden nicht durchgeführt. Dann erhält man kein Ergebnis via der gesetzten finishFn. Das kann dazu führen, das ein InternalTimer nicht mehr neu gestartet werden kann, der zyklisch diesen BlockingCall ausführen soll um Daten zu ermitteln oder einen Status.

Um einen solchen Abbruch aufgrund des erreichten Timeouts innerhalb eines Moduls zu erkennen, muss der BlockingCall mit einer abortFn und einem abortArg gestartet werden.

* '''abortFn''' - die Funktion die im Falle eines Abbruch des Aufrufs gestartet werden soll
* '''abortArg''' - das Argument mit der diese Funktion aufgerufen werden soll. Dies díent in einer Modulumgebung der Zuordnung des korrekten Devices bei mehreren Definitionen. Üblicherweise wird hierfür $hash verwendet.

BlockingCall("speedtest_DoSpeedtest", $name."|".$server,"speedtest_SpeedtestDone", 120, "speedtest_SpeedtestAborted", $hash);

sub
speedtest_SpeedtestAborted($)
{
my ($hash) = @_;

delete($hash->{helper}{RUNNING_PID});

Log3 $hash->{NAME}, 3, "BlockingCall for ".$hash->{NAME}." was aborted";

RemoveInternalTimer($hash);
InternalTimer(gettimeofday()+10, …) # falls mit disable-Attribut gearbeitet wird, muss dieses hier geprüft werden
}

== BlockingCall muss als Argument eine Referenz auf das Ursprungs-Device enthalten ==

Um später die Ergebnisse korrekt zuordnen zu können, ist es wichtig das korrekte Device zu kennen. Normalerweise wird in FHEM dazu der $hash-Zeiger verwendet um auf das entsprechende Device zu verweisen. Als Argumente für die BlockingFn können Hashes, Zeiger und sonstiges verwendet werden. Wichtig dabei ist, dass man aus den Argumenten irgendwie den Device-Namen ableiten kann, da man diesen später in der finishFn über die Variable $defs{…} wieder in die $hash-Referenz umwandeln kann.

Beispiel

BlockingCall("speedtest_DoSpeedtest", $hash->{NAME}."|".$server,…);

sub
speedtest_DoSpeedtest($)
{
my ($string) = @_;
my ($name, $server) = split("\\|", $string);

…

return "$name|$speedarr[0]|$speedarr[1]|$speedarr[2]";
}

sub
speedtest_SpeedtestDone($)
{
my ($string) = @_;

return unless(defined($string));

my @a = split("\\|",$string);
my $hash = $defs{$a[0]};

…
}

== Rückgabewerte des BlockingCalls nur als Einzeiler-String ==

Bei Funktionen die mit BlockingCall aufgerufen werden muss der Rückgabewert entweder eine Zahl, oder ein einzeiliger String sein, da dieser über den Telnetprompt als Perl-Befehl ( ''{finishFn("returnvalue")}'' ) zurückgegeben wird.

Wenn man mehrere separate Werte zurückgeben möchte, kann man diese entweder mit einem Trennzeichen (z.B. Pipe) versehen, oder bei einem Text mit Zeilenumbrüchen alles mit Base64 oder Hex encoden.

So kann man z.B. den Rückgabestring "Wert1|Wert2|Wert3" verwenden und diesen anschließend mit split() wieder in ein Array verwandeln und dann via Index gezielt darauf zugreifen.

Eine weitere Möglichkeit auch kompliziertere Datenstrukturen zurückzugeben ist <code>JSON->new->encode()</code> (Perl-Modul JSON) oder <code>toJSON</code> (aus fhem.pl) zum serialisieren und <code>JSON->new->decode()</code> zum deserialisieren zu verwenden. Achtung: Man kann hierfür zwar auch <code>encode_json</code> bzw. <code>decode_json</code> aus dem Perl-Modul JSON verwenden, sollte dabei aber beachten, dass hierdurch auch das encoding geändert wird! Außerdem führen unerwartete Rückgaben (mit Ausnahme von der Serialisierung durch <code>toJSON</code>) ggf. dazu, dass FHEM komplett beendet wird; alle decoding- und encoding-Anweisungen aus dem JSON-Modul sollten daher unbedingt durch eine (Block-) <code>eval</code>-Anweisung geschützt werden:
<syntaxhighlight lang="Perl">
my $decoded;
if ( !eval { $decoded = JSON->new->decode($content) ; 1 } ) {
Log3($hash->{NAME}, 1, "JSON decoding error in BlockingCall return: $@");
#weiterer Code für Fehlerbehandlung...
return;
}
</syntaxhighlight>

== Rückgabewert muss unbedingt den Namen des Devices enthalten, von dem der Call gestartet wurde ==

Um einen Rückgabewert dem korrekten Device zuordnen zu können muss im Rückgabewert der Funktion, die mit BlockingCall gestartet wird, der Device-Name enthalten sein, um damit die Referenz auf das richtige Device herstellen zu können.

z.B. als Returnstring "Devicenamen|Readingwert1|Readingwert2|…"

Daher ist es wichtig, den Devicenamen beim Start des Blockingcalls zu übergeben.

== Verwenden einer UndefFn und ShutdownFn um laufende BlockingCalls zu beenden ==

Wenn gerade ein BlockingCall läuft und man will FHEM herunterfahren oder neustarten kann das problematisch werden, da ja immer noch Unterprozesse laufen und so einen kompletten Stop verhindern können.

Daher muss in der [[DevelopmentModuleIntro#X_Undef|UndefFn]] und [[DevelopmentModuleIntro#X_Shutdown|ShutdownFn]] des Moduls sichergestellt werden, dass ein laufender BlockingCall beendet wird. Dazu wird als Argument der Return-Hash von BlockingCall benötigt in dem unter anderem die PID des Unterprozesses enthalten ist. Die Funktion BlockingKill() erledigt dann den Rest.

Beispiel

sub
speedtest_Undefine($$)
{
my ($hash, $arg) = @_;

RemoveInternalTimer($hash);

BlockingKill($hash->{helper}{RUNNING_PID}) if(defined($hash->{helper}{RUNNING_PID}));

return undef;
}

= Anzeige der laufenden Blocking Calls =

Mit dem FHEM-Befehl <code>blockinginfo</code> lassen sich die laufenden [[Blocking Call|Blocking Calls]] anzeigen.

= Begrenzen der Blocking Calls =

Mit dem globalen [[Attribute|Attribut]] <code>blockingCallMax</code> können die gleichzeitig laufenden [[Blocking Call|Blocking Calls]] begrenzt werden.

= Module, die Blocking.pm verwenden =

Folgende Module verwenden aktuell Blocking.pm um langwierige Funktionalitäten auszulagern:

* '''10_pilight_ctrl.pm'''
* '''23_KOSTALPIKO.pm'''
* '''23_LUXTRONIK2.pm'''
* '''38_JawboneUp.pm'''
* '''42_SYSMON.pm'''
* '''55_GDS.pm'''
* '''59_OPENWEATHER.pm'''
* '''59_PROPLANTA.pm'''
* '''70_EFR.pm'''
* '''70_JSONMETER.pm'''
* '''70_Jabber.pm'''
* '''70_SML.pm'''
* '''72_FRITZBOX.pm'''
* '''73_MPD.pm'''
* '''73_PRESENCE.pm''' (siehe dazu [[Anwesenheitserkennung]])
* '''76_SMAInverter.pm'''
* '''93_DbLog.pm''' (nicht alle Funktionen)
* '''93_DbRep.pm'''
* '''98_HMinfo.pm'''
* '''98_Text2Speech.pm'''
* '''98_UbiquitiMP.pm'''
* '''98_WOL.pm'''
* '''98_update.pm'''

[[Kategorie:Development]]

Blocking Call

2022-07-18T08:29:03Z

Beta-User: encode_json/decode_json durch JSON->new-> Methoden ergänzt; Forum #126088

Dieser Artikel soll Hinweise und Best Practices im Umgang mit dem Modul Blocking.pm und den daraus bereitgestellten Funktionen bieten.

= Allgemein =

Das Modul Blocking.pm wurde von Rudolf König entwickelt, um in FHEM Funktionsaufrufe zu ermöglichen, die relativ viel Zeit in Anspruch nehmen und normalerweise FHEM damit zum Stillstand (für die Dauer der Ausführung der Funktion) bringen würde.

Um so etwas zu verhindern, kann man mit Hilfe von Blocking.pm eine Funktion über einen Fork des Hauptprozesses unabhängig davon abarbeiten und das Ergebnis dieser Funktion optional an den Hauptprozess übergeben.

= Benutzung =

Das Modul stellt primär die Funktion BlockingCall() zur Verfügung um eine Perl-Funktion "non-blocking" auszuführen.

'''BlockingCall($blockingFn, $arg, $finishFn, $timeout, $abortFn, $abortArg);'''

{| class="wikitable"
|-
! Argument !! Optional !! Beispiel !! Beschreibung
|-
| '''<code>$blockingFn</code>''' || nein || "speedtest_DoSpeedtest" || Der Name der Perlfunktion, die "non-blocking" ausgeführt werden soll (ohne Klammern, nur der reine Funktionsname).
|-
| '''<code>$arg</code>''' || nein || <nowiki>"DeviceName|Argument1|Argument2"</nowiki> || Das Funktionsargument, das der blockingFn übergeben werden soll.
|-
| '''<code>$finishFn</code>''' || ja || "speedtest_SpeedtestDone" || Die Funktion, die mit dem Funktionsergebnis der blockingFn als Parameter aufgerufen werden soll, sobald diese zuende ist. Diese Funktion wird dabei mit dem Returnwert als erstes Argument aufgerufen.
|-
| '''<code>$timeout</code>''' || ja || 120 || Sofern eine finishFn verwendet wird, kann ein optionales Timeout gesetzt werden, sobald der Aufruf abgebrochen wird, sobald dieser timeout in Sekunden verstrichen ist.
|-
| '''<code>$abortFn</code>''' || ja|| speedtest_SpeedtestAborted|| Wenn der Aufruf aufgrund eines überschrittenen Timeouts abgebrochen wird, so wird die abortFn aufgerufen, sofern eine definiert ist.
|-
| '''<code>$abortArg</code>''' || ja|| $hash || Im Falle eines Abruchs soll die abortFn mit diesem Argument aufgerufen werden. (Dient primär der Zuordnung eines solchen Abbruchs für Modulentwickler.
|}

Die Funktion BlockingCall() gibt bei Erfolg eine Hashreferenz mit mehreren Items zurück. Dieser Hash ist folgendermaßen aufgebaut.

{|
|-
| '''<code>$hash->{pid}</code>''' || → Die Prozess-Id, unter der dieser Aufruf abgearbeitet wird.
|-
| '''<code>$hash->{fn}</code>''' || → Der Name der blockigen, der mit diesem Aufruf abgearbeitet wird.
|-
| '''<code>$hash->{finishFn}</code>''' || → Der Name der finishFn, die diesen Aufruf nach Erfolg verarbeiten wird.
|-
| '''<code>$hash->{abortFn}</code>''' || → Der Name der abortFn, die im Fehlerfall aufgerufen wird.
|-
| '''<code>$hash->{abortArg}</code>''' || → Das Argument, das im Fehlerfall an die abortFn übergeben werden soll.
|}

= Einschränkungen =

Aktuell sind beim Einsatz von Blocking.pm folgende Einschränkungen zu beachten.

* Veränderungen an internen Variablen von FHEM (Device Hashes, Timers, usw.) werden innerhalb eines BlockingCalls durchgeführt und sind dort auch sichtbar, haben aber keinerlei Einfluss auf den eigentlichen FHEM Hauptprozess und alle Definitionen. Solche Veränderungen müssen an die finishFn delegiert werden (z.B. durch zusätzliche Rückgabewerte), da es sich um einen Fork-Prozess handelt, der sich nach Abschluss des BlockingCall selbst zerstört.
* Wenn viele Definitionen aktiv sind, welche BlockingCalls parallel starten kann es zu einem relativ hohen Memory-Footprint kommen aufgrund mehrfach laufenden Fork-Prozessen. Dies kann auf schwachbrüstiger Hardware zu Speicherengpässen führen. Ab FHEM Revision 11917 lassen sich die maximal parallel laufenden BlockingCalls durch das globale Attribut <code>blockingCallMax</code> begrenzen (Standardwert: ''unbegrenzt''). Sofern die maximale parallele Anzahl an BlockingCalls erreicht ist, werden weitere Calls in eine Warteschlange eingereiht und ausgeführt, sobald laufende Calls beendet werden.

= Blocking.pm für Modulentwickler =

Blocking.pm ist aktuell sowohl für Enduser, als auch für Modulentwickler gedacht. Die Benutzung in einem Modul birgt allerdings einige Stolperfallen, auf die hier näher eingegangen wird.

== return-Wert von BlockingCall immer in $hash abspeichern ==

Die Funktion BlockingCall() gibt als return-Wert einen Hash mit mehreren Informationen zurück. Dieser Ergebnis-Hash ist in mehrerer Hinsicht sehr wichtig für die Benutzung in einem Modul, dazu in den folgenden Punkten mehr.

Eine gute Möglichkeit ist es dieses Ergebnis unterhalb von $hash->{helper} zu platzieren. So sieht es der Enduser nicht, kann aber bei Bedarf via list-Befehl angezeigt werden.

Beispiel:

$hash->{helper}{RUNNING_PID} = BlockingCall( … );

== Sicherstellen, dass immer nur ein BlockingCall gleichzeitig läuft ==

Sobald ein BlockingCall läuft könnte man rein theoretisch direkt einen weiteren BlockingCall starten usw. Dadurch würden mehrer parallele Durchläufe nebenher laufen und könnten den FHEM-Server dadurch unnötig belasten oder sogar auch überlasten. Daher sollte man immer beim Start eines BlockingCall prüfen, ob bereits ein weiterer BlockingCall läuft oder bei mehreren parallelen Blocking Calls eine entsprechende Prüfung einführen um die maximale Anzahl an gleichzeitigen BlockingCalls innerhalb einer Definition zu begrenzen.

$hash->{helper}{RUNNING_PID} = BlockingCall(…) unless(exists($hash->{helper}{RUNNING_PID}));
Dies funktioniert nur dann, wenn man in der finishFn (und später auch abortFn) $hash->{helper}{RUNNING_PID} wieder löscht. Somit ist immer sichergestellt, dass nur ein BlockingCall zur gleichen Zeit läuft. Wenn gerade ein BlockingCall aktiv ist aufgrund eines Set-Befehls, könnte man eine Meldung ausgeben.

Beispiel:

BlockingCall("speedtest_DoSpeedtest", $name."|".$server, "speedtest_SpeedtestDone", 120, …);

speedtest_SpeedtestDone($)
{
…
delete($hash->{helper}{RUNNING_PID});
…
}

== Nutzung von abortFn und abortArg ==

Mal angenommen man führt einen BlockingCall aus und dieser wird innerhalb des gesetzten Timeouts von 5 Sekunden nicht durchgeführt. Dann erhält man kein Ergebnis via der gesetzten finishFn. Das kann dazu führen, das ein InternalTimer nicht mehr neu gestartet werden kann, der zyklisch diesen BlockingCall ausführen soll um Daten zu ermitteln oder einen Status.

Um einen solchen Abbruch aufgrund des erreichten Timeouts innerhalb eines Moduls zu erkennen, muss der BlockingCall mit einer abortFn und einem abortArg gestartet werden.

* '''abortFn''' - die Funktion die im Falle eines Abbruch des Aufrufs gestartet werden soll
* '''abortArg''' - das Argument mit der diese Funktion aufgerufen werden soll. Dies díent in einer Modulumgebung der Zuordnung des korrekten Devices bei mehreren Definitionen. Üblicherweise wird hierfür $hash verwendet.

BlockingCall("speedtest_DoSpeedtest", $name."|".$server,"speedtest_SpeedtestDone", 120, "speedtest_SpeedtestAborted", $hash);

sub
speedtest_SpeedtestAborted($)
{
my ($hash) = @_;

delete($hash->{helper}{RUNNING_PID});

Log3 $hash->{NAME}, 3, "BlockingCall for ".$hash->{NAME}." was aborted";

RemoveInternalTimer($hash);
InternalTimer(gettimeofday()+10, …) # falls mit disable-Attribut gearbeitet wird, muss dieses hier geprüft werden
}

== BlockingCall muss als Argument eine Referenz auf das Ursprungs-Device enthalten ==

Um später die Ergebnisse korrekt zuordnen zu können, ist es wichtig das korrekte Device zu kennen. Normalerweise wird in FHEM dazu der $hash-Zeiger verwendet um auf das entsprechende Device zu verweisen. Als Argumente für die BlockingFn können Hashes, Zeiger und sonstiges verwendet werden. Wichtig dabei ist, dass man aus den Argumenten irgendwie den Device-Namen ableiten kann, da man diesen später in der finishFn über die Variable $defs{…} wieder in die $hash-Referenz umwandeln kann.

Beispiel

BlockingCall("speedtest_DoSpeedtest", $hash->{NAME}."|".$server,…);

sub
speedtest_DoSpeedtest($)
{
my ($string) = @_;
my ($name, $server) = split("\\|", $string);

…

return "$name|$speedarr[0]|$speedarr[1]|$speedarr[2]";
}

sub
speedtest_SpeedtestDone($)
{
my ($string) = @_;

return unless(defined($string));

my @a = split("\\|",$string);
my $hash = $defs{$a[0]};

…
}

== Rückgabewerte des BlockingCalls nur als Einzeiler-String ==

Bei Funktionen die mit BlockingCall aufgerufen werden muss der Rückgabewert entweder eine Zahl, oder ein einzeiliger String sein, da dieser über den Telnetprompt als Perl-Befehl ( ''{finishFn("returnvalue")}'' ) zurückgegeben wird.

Wenn man mehrere separate Werte zurückgeben möchte, kann man diese entweder mit einem Trennzeichen (z.B. Pipe) versehen, oder bei einem Text mit Zeilenumbrüchen alles mit Base64 oder Hex encoden.

So kann man z.B. den Rückgabestring "Wert1|Wert2|Wert3" verwenden und diesen anschließend mit split() wieder in ein Array verwandeln und dann via Index gezielt darauf zugreifen.

Eine weitere Möglichkeit auch kompliziertere Datenstrukturen zurückzugeben ist <code>JSON->new->encode()</code> (Perl-Modul JSON) oder <code>toJSON</code> (aus fhem.pl) zum serialisieren und <code>JSON->new->decode()</code> zum deserialisieren zu verwenden. Achtung: Man kann hierfür zwar auch <code>encode_json</code> bzw. <code>decode_json</code> aus dem Perl-Modul JSON verwenden, sollte dabei aber beachten, dass hierdurch auch das encoding geändert wird! Außerdem führen unerwartete Rückgaben (mit Ausnahme von der Serialisierung durch <code>toJSON</code>) ggf. dazu, dass FHEM komplett beendet wird; alle decoding- und encoding-Anweisungen aus dem JSON-Modul sollten daher unbedingt durch eine (Block-) <code>eval</code>-Anweisung geschützt werden:
<syntaxhighlight lang="Perl">
my $decoded;
if ( !eval { $decoded = JSON->new->decode($content) ; 1 } ) {
Log3($hash->{NAME}, 1, "JSON decoding error in Blocking call return: $@");
#weiterer Code für Fehlerbehandlung...
return;
}
</syntaxhighlight>

== Rückgabewert muss unbedingt den Namen des Devices enthalten, von dem der Call gestartet wurde ==

Um einen Rückgabewert dem korrekten Device zuordnen zu können muss im Rückgabewert der Funktion, die mit BlockingCall gestartet wird, der Device-Name enthalten sein, um damit die Referenz auf das richtige Device herstellen zu können.

z.B. als Returnstring "Devicenamen|Readingwert1|Readingwert2|…"

Daher ist es wichtig, den Devicenamen beim Start des Blockingcalls zu übergeben.

== Verwenden einer UndefFn und ShutdownFn um laufende BlockingCalls zu beenden ==

Wenn gerade ein BlockingCall läuft und man will FHEM herunterfahren oder neustarten kann das problematisch werden, da ja immer noch Unterprozesse laufen und so einen kompletten Stop verhindern können.

Daher muss in der [[DevelopmentModuleIntro#X_Undef|UndefFn]] und [[DevelopmentModuleIntro#X_Shutdown|ShutdownFn]] des Moduls sichergestellt werden, dass ein laufender BlockingCall beendet wird. Dazu wird als Argument der Return-Hash von BlockingCall benötigt in dem unter anderem die PID des Unterprozesses enthalten ist. Die Funktion BlockingKill() erledigt dann den Rest.

Beispiel

sub
speedtest_Undefine($$)
{
my ($hash, $arg) = @_;

RemoveInternalTimer($hash);

BlockingKill($hash->{helper}{RUNNING_PID}) if(defined($hash->{helper}{RUNNING_PID}));

return undef;
}

= Anzeige der laufenden Blocking Calls =

Mit dem FHEM-Befehl <code>blockinginfo</code> lassen sich die laufenden [[Blocking Call|Blocking Calls]] anzeigen.

= Begrenzen der Blocking Calls =

Mit dem globalen [[Attribute|Attribut]] <code>blockingCallMax</code> können die gleichzeitig laufenden [[Blocking Call|Blocking Calls]] begrenzt werden.

= Module, die Blocking.pm verwenden =

Folgende Module verwenden aktuell Blocking.pm um langwierige Funktionalitäten auszulagern:

* '''10_pilight_ctrl.pm'''
* '''23_KOSTALPIKO.pm'''
* '''23_LUXTRONIK2.pm'''
* '''38_JawboneUp.pm'''
* '''42_SYSMON.pm'''
* '''55_GDS.pm'''
* '''59_OPENWEATHER.pm'''
* '''59_PROPLANTA.pm'''
* '''70_EFR.pm'''
* '''70_JSONMETER.pm'''
* '''70_Jabber.pm'''
* '''70_SML.pm'''
* '''72_FRITZBOX.pm'''
* '''73_MPD.pm'''
* '''73_PRESENCE.pm''' (siehe dazu [[Anwesenheitserkennung]])
* '''76_SMAInverter.pm'''
* '''93_DbLog.pm''' (nicht alle Funktionen)
* '''93_DbRep.pm'''
* '''98_HMinfo.pm'''
* '''98_Text2Speech.pm'''
* '''98_UbiquitiMP.pm'''
* '''98_WOL.pm'''
* '''98_update.pm'''

[[Kategorie:Development]]

Msg

2022-07-13T12:52:01Z

Beta-User: Formatierung

{{SEITENTITEL:msg}}{{Infobox Modul
|ModPurpose=Versenden von Nachrichten der Typen Audio, Text, Mail, Push, Light, Screen
|ModType=cmd
|ModForumArea=Automatisierung
|ModFTopic=39983
|ModCmdRef=MSG
|ModTechName=75_MSG.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
Der FHEM-Befehl [[msg]] kann dazu benutzt werden, Benachrichtigungen auszugeben.

Der Befehl unterstützt die Nachrichtentypen
* text: Textnachrichten per Push- oder E-Mail-Dienst auf mobile Geräte verschicken
* audio: Sprachnachrichten und akustische Signale über Lautsprecher in der Wohnung ausgeben
* light: optische Signale durch Lampen in der Wohnung anzeigen
* screen: Nachrichten auf einem Bildschirm, etwa einem Fernsehgerät in der Wohnung, anzeigen
und kann an ein FHEM Gerät oder an eine eMail Adresse geschickt werden.

Weitere Details zu den Funktionen und zur Benutzung dieses Befehls finden sich im ersten Beitrag {{Link2Forum|Topic=39983|LinkText=dieser Diskussion}} im Forum.

Der Befehl '''msg''' ersetzt ausserdem das vormals verfügbare Modul '''MSG'''. Benutzer des alten Moduls müssen ihre Devices auf '''MSGFile''' und/oder '''MSGMail''' umstellen; bitte dafür das Forenthema {{Link2Forum|Topic=43447|LinkText="Benutzer von 75_MSG.pm: Aktion notwendig vor Update ab dem 04.11.2015"}} beachten!

===Vorteil===
Der Hauptvorteil ist, dass man hier an zentraler Stelle definiert, wie Nachrichten verteilt und zugestellt werden sollen und sich später auch jederzeit zentral anpassen lasst.
Dazu muss man dann nicht mehr jedes einzelne Notify, DOIF oder was auch immer anpassen (beispielsweise weil sich der Empfänger geändert hat oder man nun statt dem einen FHEM Modul ein anderes Modul für die Zustellung der Nachricht verwenden möchte).

Gesteuert wird das ganze über das setzen von Attributen. Zum einen am Device "globalMsg" für die Anpassung des Routing Verhaltens sowie einiger Attribute an einem beliebigen FHEM Device, welches die Adressierung des Bewohners oder der Bewohnergruppe ermöglicht. (Für die Profis: Alle globalen Attribute kann man auch per userattr an jedes beliebige Device hinzufügen; es erhält dort dann Vorrang).

Es können auch globale Empfänger konfiguriert werden, dann wird die Angabe eines Empfängers bei den neuen Kommandos optional und sollte einmal ein Empfänger angegeben werden, der keine Kontaktmöglichkeit für Text, Audio oder Visual hinterlegt hat, gibt es einen Fallback auf die globalen Einstellungen (also quasi eine Art Catch-All). Im Falle eines Fallbacks gibt es einen entsprechenden Logeintrag und eine Textnachricht wird entsprechend mit einem Hinweis ergänzt.

===Übertragungsmethoden===
====text====
Sendet eine Textnachricht per Push oder E-Mail. Je nach Priorität wird gepusht, gemailt oder beides. E-Mails werden mit der entsprechenden Priorität im Header markiert (dafür sind bei High und Low Prio HTML Mails zwingend erforderlich. Normale Mails werden als Nur-Text gesendet).

Die Befehle, wie gepusht oder gemailt werden soll, können über Attribute am Device "globalMsg" für die Prioritäts-Kategorien "High", "Normal" und "Low" angepasst werden. Standardmäßig wird für Push das Pushover Modul sowie für E-Mail system() per /usr/bin/mail verwendet.

Die Sub-Typen "mail" und "push" können auch explizit für sich aufgerufen werden.

====audio====
Gibt die Nachricht zunächst als Sprachnachricht weiter. Je nach Priorität wird die Nachricht auch per Text weitergeleitet. Auch kann optional die Anwesenheit des Bewohners berücksichtigt werden (follow me) und die Nachricht wird dann auch als Text weitergeleitet.
Außerdem kann über einen Dummy-Switcher gesteuert werden, ob Audio Nachrichten komplett wiedergegeben werden sollen, nur in einer gekürzten Fassung oder gerade überhaupt nicht (Emergency-Prio Nachrichten werden trotzdem immer wiedergegeben). Ich nutze das beispielsweise dafür, dass ich den Switcher auf "short" setze, wenn meine Wohnungstür offen steht, damit meine Nachbarn nicht meine gesamten Audio Benachrichtigungen zu hören kriegen ;)

Die Befehle zur Audio Wiedergabe können über Attribute am Device "globalMsg" für die Kategorien "Long", "Short with Priority" und "Short" angepasst werden. Der Nachrichtentitel wird hier als |Titel| mit übergeben.

Bei Verwendung von SONOSPLAYER gilt: Ist eine entsprechende Audio-Datei hinterlegt, wird diese dann vor der Nachricht mit eingebunden (Details siehe SONOS Doku). Ich nutze das, um meinen Audio-Nachrichten verschiedene Varianten von einem Gong voran zu stellen (z.B. wie im Flugzeug), damit sich die Bewohner bei einer plötzlichen Ansage nicht so erschrecken 8) Definiert man den Audio-Titel zentral über das Attribut msgTitleAudio, statt ihn in jedem msg-Kommando explizit anzugeben, kann man später auch zentral ändern, welche Sounddatei den Nachrichten vorangestellt werden soll und muss dann nicht überall Anpassungen vornehmen.
Weitere Audio-Dateien können natürlich wie in der SONOS Doku beschrieben in den Text über |Dateiname| aufgenommen werden.

====light====
Verwendet die Nachricht zunächst nur, um eine Leuchte anzusteuern (z.B. HUE). Je nach Priorität (hoch oder normal) kann die Leuchte anders geschaltet werden. Ist die Priorität hoch genug, wird die Nachricht zusätzlich auch per Audio wiedergegeben (dort greifen dann die Routing-Methoden für Audio). Auch hier kann optional die Anwesenheit des Bewohners berücksichtigt werden und die Nachricht alternativ als Text zugestellt werden, sofern die Priorität hoch genug ist.

Die Befehle zur visuellen Wiedergabe können über Attribute am Device "globaMsgl" für die Kategorien "High" und "Normal" angepasst werden. Standardmäßig wird ein einfaches Kommando für HUE Geräte verwendet (select und lselect zum kurzen bzw. längeren blinken).

====screen====
Ähnlich wie der Typ "light". Standardmäßig wird ein Text an eine ENIGMA2 Box geschickt.

===Verwendung===
'''Eine Liste der direkt unterstützten Module, ohne dass man diese händisch einbinden muss, kann man über den get-Befehl "routeCmd" beim Helfer-Device "globalMsg" (sofern es nicht umbenannt wurde) erhalten.'''
'''Dort kann man auch sehen, mit welcher Syntax ein bestimmtes Modul angesprochen wird und das ggf. als Vorlage für eine eigene Definition per msgCmd-Attribut nehmen.'''

Die Syntax ist sehr einfach gehalten:

:<code>msg [<type>] [<@device|e-mail address>] [<priority>] [|<title>|] <message></code>

Type kann auch weggelassen werden und ist dann automatisch auf "text" gesetzt.
Wenn kein Device und keine E-Mail Adresse angegeben wurden, dann wird automatisch an das globale msgConfig Device (globalMsg) verschickt (ansonsten gibt es eine Fehlermeldung, wenn dort kein passendes msgContact-Attribut gefunden wurde).

Auch können mehrere Typen oder Empfänger durch Komma getrennt angegeben werden (Und-Verknüpfung).
Eine Oder-Verknüpfung ist ebenso möglich und wird mit einer Pipe (|) zwischen Type und/oder Empfänger gemacht (Oder-Verknüpfung lässt sich auch mit Und-Verknüpfung kombinieren). Bei einer Oder-Verknüpfung wird nur zum nächsten Adressaten gesprungen, sofern für den vorigen keine der angegebenen Nachrichtentypen zugestellt werden konnte. Damit wird auch die automatische Eskalation zu einem anderen Nachrichten-Typ beeinflusst. Diese wird immer nur für den jeweils letzten Eintrag angewendet.

Grundsätzlich sind alle Syntax-Angaben, die oben in eckigen Klammern (also []) stehen, optional. Es wird dann auf entsprechende Standardwerte zurückgegriffen, die entweder über Attribute am Device oder global gesetzt wurden. Ist auch global nichts vorhanden, wird auf interne Standardwerte zurückgegriffen (gilt natürlich nicht für ein Device, denn irgendwo muss man ja immer einen Empfänger angeben ;) ).

Der Wertebereich für Priorität orientiert sich dabei an der Pushover API mit -2 bis 2. Es kann jedoch grundsätzlich jeder beliebige Wert verwendet werden. Es ist dann Sache des FHEM Moduls, ob der Wertebereich richtig ist oder ob er dort automatisch begrenzt wird (sofern ein FHEM Modul von der Priorität Gebrauch macht, ansonsten wird sie in erster Linie für das Routing innnerhalb des msg-Befehls benutzt).

Sowohl Und-Verknüpfung als auch Oder-Verknüpfung lassen sich ebenfalls in den Contact- und Recipient-Attributen anwenden. Somit bestehen eine Vielzahl von Möglichkeiten für die Adressierung von Empfängern und das Routing über bestimmte Nachrichtentypen.

===Konfiguration===

Sämtliche Einstellungen werden über Attribute vorgenommen. Dazu gibt es ein Konfigurationsdevice globalMsg in dem die Defaultwerte festgelegt werden. Alles andere passiert durch setzen von Attributen in den einzelnen Devices. Das Device globalMsg wird automatisch bei erster Verwendung von msg angelegt, sofern es nicht gefunden wurde.
Alternativ kann es mit
:<code>define globalMsg msgConfig </code>
angelegt werden

====Attribute für das Device "msgConfig"====
=====msgCmdAudio (Standard ohne Verwendung Attribut msgSwitcherDev)=====
Kommando für das "verschicken" von (langen) Audio Mitteilungen.
Entweder FHEM-Befehl oder in {} eingeschlossener Perl Befehl.

Verfügbare Variablen:
*%DEVICE%
*%RECIPIENT% (abhängig davon, ob das Modul optional oder verpflichtend eine gesonderte Adressierung des Empfängers vorsieht)
*%TITLE%
*%MSG%
*%PRIORITY%

=====msgCmdAudioShortPrio (nur in Verbindung mit msgSwitcherDev)=====
Kommando für das "verschicken" von Audio Mitteilungen mit Switcher Einstellung "short" und einer Prio höher/gleich msgFwPrioEmergencyAudio.
Entweder FHEM-Befehl oder in {} eingeschlossener Perl Befehl.

Verfügbare Variablen:
*%DEVICE%
*%RECIPIENT% (abhängig davon, ob das Modul optional oder verpflichtend eine gesonderte Adressierung des Empfängers vorsieht)
*%TITLE%
*%MSG%
*%PRIORITY%

=====msgCmdAudioShort (nur in Verbindung mit msgSwitcherDev)=====
Kommando für das "verschicken" von (gekürzten) Audio Mitteilungen mit Switcher Einstellung "short" unabhängig von der Priorität.
Entweder FHEM-Befehl oder in {} eingeschlossener Perl Befehl.

Verfügbare Variablen:
*%DEVICE%
*%RECIPIENT% (abhängig davon, ob das Modul optional oder verpflichtend eine gesonderte Adressierung des Empfängers vorsieht)
*%TITLE%
*%MSG%
*%PRIORITY%

=====msgCmd<TYPE><PrioCat>=====
Kommando für den jeweilige Nachrichten-Typen und der entsprechenden Nachrichten-Prioritätskategorie

=====msgFwPrioAbsent<TYPE>=====
Schwellenwert, ab dem Nachrichten diesen Typs bei kurzer Abwesenheit aller Bewohner per Text weitergeleitet werden sollen.
Voreinstellung: 0

=====msgFwPrioEmergency<TYPE>=====
Schwellenwert, ab dem Nachrichten diesen Typs als Emergency Prio behandelt werden.
Diese Nachrichten werden immer wiedergegeben, unabhängig der Abwesenheit oder der Einstellung long/short am aSwitcherDev Dummy.
Voreinstellung: 2

=====msgFwPrioGone<TYPE>=====
Schwellenwert, ab dem Nachrichten diesen Typs bei längerer Abwesenheit aller Bewohner per Text weitergeleitet werden sollen.
Voreinstellung: 1

=====msgPriority<TYPE>=====
Standard Priorität für Nachrichten diesen Typs, sofern nicht in der Nachricht angegeben.
Voreinstellung: 0

=====msgTitle<TYPE><PrioCat>=====
Standard Betreff für Nachrichten diesen Typs, sofern in der Nachricht keiner angegeben wurde.

=====msgResidentsDev=====
FHEM Gerätename, welcher für die Anwesenheit aller Bewohner verwendet wird. Auf dieses Device wird zurückgegriffen, sofern für das Empfänger-Device die entsprechenden Readings nicht vorhanden sind.
Bei Verwendung von ROOMMATE, GUEST oder RESIDENTS Devices als Empfänger wird dieses Attribut ignoriert.
Das in diesem Attribut angegebene Device muss die Readings "presence" und "state" haben. Es wird die Verwendung eines Devices vom FHEM Typ RESIDENTS empfohlen.
Über "presence" wird generell An/Abwesenheit bewertet. Hat "state" den Wert "gone", wird eine längere Abwesenheit angenommen.
Für das Weiterleiten von Nachrichten bei längerer Abwesenheit muss die Nachrichten Priorität höher sein, als wenn die Bewohner nur übergangsweise abwesend sind.
Siehe auch entsprechende Readings msgFwPrioGone<TYPE> msgFwPrioAbsent<TYPE>.

Readings Wertebereich:
presence: present|absent
state: gone|*

=====msgSwitcherDev=====
FHEM Gerätename, welcher für die Beeinflussung der Länge von Audio Nachrichten verwendet werden soll.
Bei "off" findet auch keine visuelle Benachrichtigung mehr statt. Screen Nachrichten sind nicht betroffen.
Hier bietet sich ein Dummy Device wie dieses hier an:

<pre>define HouseAnn dummy
attr HouseAnn alias Announcements
attr HouseAnn devStateIcon aktiv:general_an@90EE90 active:general_an@90EE90 lang:general_an@green:off aus:general_aus@red:long kurz:general_an@orange:long visuell:general_an@orange:long
attr HouseAnn event-on-change-reading state
attr HouseAnn eventMap active:aktiv long:lang short:kurz visual:visuell off:aus
attr HouseAnn group Automation
attr HouseAnn icon audio_volume_mid
attr HouseAnn room Apartment
attr HouseAnn setList state:lang,kurz,visuell,aus
attr HouseAnn webCmd state</pre>

====Attribute für alle FHEM Devices====
*Für die Verwendung der Fallback und Catchall-Zustellung von Nachrichten können diese Attribute im Device "global" gesetzt werden.
* Nahezu alle globalen Attribute können auch auf ein Device angewendet werden (Ausnahme: msgResidentsDev). Sie tauchen allerdings dort aus Gründen der Übersicht nicht standardmäßig auf. Man muss sie deshalb zuvor als userattr (entweder beim Device oder eben global) hinzufügen, damit man sie setzen kann.

=====msgContact<TYPE> (zwingend für Nachrichten diesen Typs)=====
FHEM Gerätename, welcher zur Übermittlung von Nachrichten diesen Typs angesprochen werden soll.
Muss bei Audio Nachrichten ohne eigene Definition von msgCmdAudio* ein Gerät vom Typ SONOSPLAYER sein.
Muss bei Screen Nachrichten ohne eigene Definition von msgCmdScreen* ein Gerät vom Typ ENIGMA2 sein.
Muss bei Light Nachrichten ohne eigene Definition von msgCmdLight* ein Gerät vom Typ HUEDevice sein.
Muss bei Push Nachrichten ohne eigene Definition von msgCmdPush* ein Gerät vom Typ Pushover sein.
Muss bei Mail Nachrichten eine oder mehrere gültige E-Mail Adressen enthalten.
Bei FHEM Gerätenamen, über die mehrere Empfänger adressiert werden können, kann der Empfänger mittels Doppelpunkt getrennt vom FHEM Gerätenamen angegeben werden. Je nach Modul ist das optional oder verbindlich.

=====msgRecipient<TYPE>=====
Leitet Nachrichten, die an dieses Gerät adressiert werden, auf ein anderes FHEM Device um.
Es wird dann der Wert von msgContact<TYPE> des anderen Gerätes für die Übermittlung der Nachricht verwendet.
Bei Nutzung des Attributs mit Typangabe werden nur Nachrichten des entsprechenden Typs umgeleitet.
Kombination von msgRecipient mit msgRecipient<TYPE> führt dazu, dass msgRecipient<TYPE> bevorzugt wird.

===Follow-Me Funktion===
Sobald ein Device, an welches man eine Nachricht schickt, ein Reading "location" beinhaltet, wird geprüft, ob es für diese Lokation eine speziell hinterlegte Kontaktmöglichkeit gibt (z.B. also eine genaue SONOS Soundbox in dem Raum, wo der Bewohner sich gerade befindet).

Gebraucht wird hierfür ein iBeacon zusammen mit dem GEOFANCY Modul. ich empfehle außerdem den Einsatz des ROOMMATE Moduls dazu, weil es die Handhabung der Location gleich mitbringt (Einrichtung siehe Wiki). Man kann aber auch jede andere Möglichkeit der Raumortung nutzen, es muss nur in einem Reading namens "location" enden.

Über das Attribut "msgLocationDevs" können Devices mit Komma getrennt angegeben werden, welche dann für je einen Raum stehen und welche dann dort die msgContact* Attribute hinterlegt haben (Delegationen mittels msgRecipient* funktionieren dort auch).
Am einfachsten ist es also pro Raum ein Dummy-Device anzulegen und dieses dann unter dem globalen Attribut "msgLocationDevs" mit aufzuführen.

Wichtig ist, dass dieses Dummy ein Attribut "msgLocationName" enthält, welches dann den exakt gleichen Wortlaut enthalten muss, wie auch im Reading "location" bei dem ROOMMATE Device (also genau der Lokationsname, den ihr z.B. in eurer Geofency.app angegeben habt). Zusätzlich dann eben noch die Type-Contacts. Hier ein Beispiel für Wohnzimmer und Schlafzimmer:

<pre>define msgRoom_Living dummy
attr msgRoom_Living msgContactAudio Sonos_Living_Room
attr msgRoom_Living msgContactLight LR_Ceilling,LR_FloorLamp,LR_SofaCorner,LR_DinnerCorner
attr msgRoom_Living msgLocationName Living
attr msgRoom_Living userattr msgLocationName

define msgRoom_Bedroom dummy
attr msgRoom_Bedroom msgContactAudio Sonos_Bedroom
attr msgRoom_Bedroom msgContactLight BR_FloorLamp
attr msgRoom_Bedroom msgLocationName Bedroom
attr msgRoom_Bedroom userattr msgLocationName</pre>

Beide Devices sind als globales Attribut verlinkt:

:<code>attr globalMsg msgLocationDevs msgRoom_Living,msgRoom_Bedroom</code>

Wenn ich nun einen msg-Audio Befehl absetze während ich im Schlafzimmer oder Wohnzimmer bin (Reading ist gleich "Living" oder "Bedroom"), wird die Nachricht auf demjenigen Gerät abgespielt, welches ich für den Raum hinterlegt habe (gleiches gilt für Light-Nachrichten). Wechsle ich den Raum und führe den Befehl nochmal aus, folgt mir auch die Wiedergabe der Nachricht

===Beispiele===
Bei der ersten Verwendung von msg wird das Konfigurationsdevice globalMsg angelegt. Es kann aber auch vorher manuell angelegt werden.

====Pushover====
Um mit msg Pushovernachrichten zu versenden ist vorher die Konfiguration eines [[Pushover|Pushoverdevices]] notwendig. Dieses wird dann mit
:<code>attr globalMsg msgContactPush <Pushoverdevice></code>
dem globalMsg als Standardpushoverdevice hinzugefügt.

anschließend kann der Befehl
:<code>msg test</code>
verwendet werden. Folgendes passiert:
Das msg-Modul erkennt dass eine Nachricht verschickt werden soll. Da kein Übertragungsweg angegeben ist, wird der Standardweg genommen, nämlich text. Bei text wird eine Mail und ein Push verschickt. Da Mail nicht näher definiert ist, wird nur der Push genommen. Da bei Push kein expliziter Empfänger angegeben ist, wird der Empfänger aus dem Attribut von msgContactPush genommen.

Alternativ kann auch direkt ein Push an einen definiertes Pushoverdevice gesendet werden:
:<code>msg push @<Pushoverdevice> 1 |FHEM| test</code>
hier wird eine Pushnachricht ein ein definiertes Pushoverdivce mit der Priorität 1, dem Titel FHEM und der Nachricht test gesendet

Bei '''mehreren''' Pushover Empfängern muss man nicht mehr für jeden Empfänger ein einzelnes Pushover-Device anlegen. Es genügt auch ein Gerät, man kann die Empfänger dann einfach als Sub-Empfänger ansprechen:
:<code>msg push @PushoverDevice:uQiRzpo4DXghDmr9QzzfQu27cmVRsG Dies ist eine Nachricht</code>
Wie man sieht kann man einfach den User-Identifier (oder natürlich Group-Identifier) anhängen und adressiert somit einen alternativen Empfänger. Der im define des Device "PushoverDevice" angegebene User ist dann nur noch der Default-Empfänger.
Man kann auch an ein spezielles Endgerät adressieren:
:<code>msg push @PushoverDevice:uQiRzpo4DXghDmr9QzzfQu27cmVRsG:iPhone Dies ist eine Nachricht, die nur an das iPhone geschickt wird.</code>
Natürlich kann man das auch in ein msgContactPush Attribut schreiben...
:<code>attr myDevice msgContactPush PushoverDevice:uQiRzpo4DXghDmr9QzzfQu27cmVRsG</code>
...und anschließend so wie gewohnt über die Device-Adressierung verschicken:
:<code>msg push @myDevice Nachrichtentext</code>

====Telegram====
Der Versand von Nachrichten über Telegram kann anlog zu Pushover verwendet werden. Zunächst muss auch hier ein [[TelegramBot|Telegram-Device]] angelegt werden.

Anschließend kann dieses in globalMsg als Standardevice festgelgt werden:
:<code>attr globalMsg msgContactPush <Telegramdevice></code>

anschließend kann der Befehl
:<code>msg test</code>
verwendet werden. Folgendes passiert:

Alternativ kann auch direkt ein Push an einen definiertes Telegramdevice gesendet werden:
:<code>msg push @<Telegramdevice> test</code>

Im vergleich zu Pushover werden Titel und Priorität ignoriert, da Telegram damit nicht umgehen kann.

==== msg in Verbindung mit ROOMMATES====
Werden ROOMMates verwendet dann können jedem ROOMMATE Kontaktdevices hinzugefügt werden.
Analog zu diesem Beispiel kann msg nicht nur bei ROOMMATES sondern bei jedem beliebigen FHEM-Device angewendet werden.
:<code>attr <ROOMMATEDEVICE> msgContactPush <Pushdevice(s)> </code>
oder konkret:
:<code>attr rr_Michael msgContactPush PushoverMichael</code>
bzw. für Telegram:
:<code>attr rr_Michael msgContactPush Telegram</code>
bzw. für beide:
:<code>attr rr_Michael msgContactPush Telegram,PushoverMichael</code>

Somit kann ich dann ganz einfach über
:<code> msg push @rr_Michael |FHEM| Dies ist eine Testnachricht für Michael!</code>
Michael eine Pushnachricht über das in dem Attribut für ihn definierte Device schicken.
Sollte sich der ROOMMATE nun dazu entschließen Pushover nicht mehr zu verwenden, so muss nicht an jeder Stelle im Code wo ein Push abgesetzt wird das Device geändert werden, sondern nur an einer Zentralen Stellen, nämlich beim ROOMMATE durch ändern des Attributes.

Falls es '''mehrere''' Roommates gibt, die (separat) mit Telegram angeschrieben werden sollen, sollte man für Telegram folgende Syntax für die Eintragung bei jedem Roommate verwenden:
:<code>attr rr_KONTAKT msgContactPush <NAME-DES-TELEGRAMBOT>:@<ID-NR-DES-KONTAKT></code>

==== msg in Verbindung mit RESIDENTS====
Möchte man dynamisch Nachrichten an z.B. alle Personen schicken, die gerade zuhause sind, dann kann man sich das RESIDENTS-Modul und die darin vorhandenen Readings zu nutze machen. Alle Anwesenden Personen stehen in dem Reading residentsHomeDevs bzw. residentsTotalRoommatesPresentDevs wenn man zwischen ROOMMATES und GUESTs unterscheidet. Hier sollte man immer das Dev-Reading nutzen, da dort das ROOMMATE-Device angesprochen wird und nicht ggf. ein Alias.
Eine Nachricht an alle anwesenden Personen könnte als Beispielsweise so verschickt werden:
:<code>msg [msg-typ] @[r<resident-Device>:<Reading des Resident-Devices>] Du bist zuhause</code>
oder konkret
:<code>msg push @[rgr_Bewohner:residentsHomeDevs] Du bist zuhause</code>

Es gilt die normale Syntax von MSG. Typ ist beispielsweise Optional und ein Titel kann auch mitgegeben werden.
Das Routing des MSG-Moduls Teil dann das Reading in die einzelnen Empfänger auf und schickt in diesem Fall eine Push-Nachricht an die entsprechenden Personen

==== Lautstärkeanpassung bei Audionachrichten====
Um die Lautstärke einer Audioausgabe beim Absetzen des MSG-Befehls anzupassen (wenn diese von den Defaultwerten des msg-Schemas abweichen soll) kann am Ende der Nachricht ein JSON mit Variablen angehangen werden, welche vom Schema (siehe "get globalMsg routeCmd") unterstützt wird oder welche du selbst in einem msgCmd* Attribut verwendest. Für eine Sonos-Nachricht sieht das dann z.B. so aus:
:<code> msg audio @Sonos_Bedroom |Hint| Gute Nacht! O[{"VOLUME":"8"}] </code>

{{Hinweis| Standardmäßig wird bei angegebenem Betreff nach einer Audiodatei mit dem Namen des Betreffs (hier: Hint.mp3) in der Sonosfreigabe (bsp.: SonosSpeak) gesucht und diese vor der Nachricht abgespielt. Ist die Datei nicht vorhanden, dann kommt es zu 2 Fehlermeldungen vom Sonos-Modul im Log. Die anschließende Sprachnachricht wird aber trotzdem abgespielt.}}

====Jabber====
Der Versand der Nachrichten über Jabber ist ähnlich dem Versand über Telegram.
Natürlich muss auch hier zunächst das [[Jabber|Jabber-Device]] eingerichtet werden.

Im msgConfig ist folgendes Attribut zu ergänzen:
:<code>attr globalMsg msgContactPush jabberdevice:jabberkontact</code>

Um Nachrichten zu versenden, reicht nun
:<code>msg test</code>

Sollen Nachrichten an eine Konferenz/an einem Raum gesendet werden, muss nur der Parameter ''Jabber_MTYPE=muc'' mit angegeben werden.
:<code>msg Jabber_MTYPE=muc test</code>
bzw. - sollte msgContactPush nicht definiert sein - ganz ausgeschrieben:
:<code>msg push Jabber_MTYPE=muc @JabberClient:raum@conference.jabber.xy Das ist eine Nachricht</code>

Ist ein standardmäßiger Versand an einen Raum gewünscht, kann dieser Parameter auch im Device ''globalMsg'' als Attribut ''msgParamsPush'' hinterlegt werden
:<code>attr globalMsg msgParamsPush Jabber_MTYPE=muc</code>
Danach reicht dann wieder das bekannte
:<code>msg test</code>

{{Hinweis| Weitere Beispiele folgen.}}

[[Kategorie:E-Mail]]
[[Kategorie:Telegram]]
[[Kategorie:Jabber]]

OpenMultiroom

2022-07-12T13:40:36Z

Beta-User: Maintainer update, Hinweis auf akutelleres Modul

<div style="float:right">{{Infobox Modul
|ModPurpose=Steuern der einzelnen Multiroom-Systemkomponenten
|ModType=d
|ModCmdRef=OpenMultiroom
|ModForumArea=Multimedia
|ModTechName=98_OpenMultiroom.pm
|ModOwner=unimatrix
}}
{{Infobox Modul
|ModPurpose=Steuern eines Snapcast-Servers
|ModType=d
|ModCmdRef=Snapcast
|ModForumArea=Multimedia
|ModTechName=96_Snapcast.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]])
}}
[[Datei:OpenMultiroomOverview.png|mini|400px|Schaubild des Zusammenspiels der einzelnen Komponenten eines Multiroomsystems mit den Backends {{Link2Forum|Topic=18517|LinkText=MPD}} und {{Link2Forum|Topic=62389|LinkText=Snapcast}} sowie der Nutzung von Text2Speech]]
</div>

Achtung: Das Modul ist noch in der Entwicklung und bisher nur im {{Link2Forum|Topic=65785|LinkText=Forum}} bzw. auf dem [https://github.com/unimatrix27/fhemmodules/blob/master/98_OpenMultiroom.pm Github des ursprünglichen Autors] (beide veraltet) oder aktualisiert im {{Link2Forum|Topic=128206|LinkText=Forum}} verfügbar.

'''OpenMultiroom''' ist ein Steuerungsmodul sowie auch ein Gesamtkonzept zur Realisierung eines Multiroom-Audio-Systems unter Nutzung von ausschließlich frei verfügbarer Software und ohne Bezug auf die Hardware eines bestimmten Herstellers. Es ist so ausgelegt, dass es prinzipiell flexibel bezüglich der Auswahl der Backendsysteme ist. Zurzeit ist es für die Nutzung mit [https://www.musicpd.org/ MPD] bzw. [https://www.mopidy.com/ Mopidy] und [https://github.com/badaix/snapcast Snapcast] implementiert. Daher wird in diesem WIKI-Eintrag immer von diesen Systemen gesprochen. Einen grundsätzlichen Überblick über das Konzept bietet das Schaubild.

== Grobe Übersicht des Funktionsumfangs der Gesamtlösung==
=== Features ===
* Integrierte Steuerung des Musikplayers über das [[MPD]]-Modul sowie des Multiroom-System {{Link2Forum|Topic=62389|LinkText=Snapcast}} in einem einzigen Modul
* Implementierung einer Schnittstelle gemäß [[DevelopmentGuidelinesAV]] als Basis für eine Visualisierung mit z.B. [[SmartVISU]] oder [[FHEM Tablet UI]]
* Synchrones Playback auf z.B. Raspberry Pi oder Android-Geräten (Snapcast-Feature)
* optionale Komprimierung der Soundübertragung als OGG oder FLAC (Snapcast-Feature)
* Möglichkeit der Bedienung völlig ohne Display über eine Fernbedienung und entsprechender Text2Speech Rückmeldung, insbesondere
** Durschalten von Playlisten mit entsprechenden Channel - Tasten unter Nutzung von raumspezifischen Filtern
** Forward und Rewind mit definierbaren Sprungweiten (implementiert direkt im [[MPD]]-Modul)
** Direktanwahl von Playlisten, Tracks oder Trackpositionen durch Zifferneingabe und anschließende Funktionstaste
** Abfrage von Statusinformationen durch Funktionstasten und Text2Speech Rückmeldungen
** Mithören in anderen Räumen und Übernahme des Playerzustandes anderer Räume durch Nutzung von Funktionstasten
** Einschlaftimer per Zifferneingabe oder per vordefinierten Zeitabständen, hierbei wird auch die Restlaufzeit des aktuellen Tracks angeboten.
* manuelles oder automatisches Speichern und Laden von Playlistbookmarks (implementiert direkt im [[MPD]]-Modul)
* Möglichkeit der Festlegung von tageszeit- und tagestypabhängigen Lautstärkebegrenzungen bis auf 0% z.B. für Kinderzimmer
* individuelles Verwalten von Playlisten für verschiedene Familienmitglieder
* Nutzung des Audiosystems für systemunabhängige FHEM-Announcements. Ein entsprechendes Announcement-Modul ist in Planung. Dabei können mehrere Räume gleichzeitig oder auch getrennt angesprochen werden

=== Anwendungszweck und Kurzbeschreibung der Funktionsweise ===
Wie der Name des Systems vermuten lässt, ist die Lösung vor allem dann sinnvoll einzusetzen, wenn Audiodateien in mindestens 2 verschiedenen Räumen oder "Zonen" sowohl synchron als auch unabhängig abgespielt werden soll und wenn hierzu eine komfortable und integrierte Steuerung über FHEM verwendet werden soll. Mit Einschränkungen ist die Lösung auch dann sinnvoll, wenn es nur um das Abspielen in einem Raum geht. Hier kann dann z.B. die Steuerung über eine Fernbedienung mit Hilfe des '''OpenMultiroom'''-Moduls genutzt werden, die über eine reine Nutzung des MPD-Moduls hinausgeht.

Für die Nutzung ist nicht zwingend ein zentraler Server notwendig. Diese Rolle kann auch von einem der Clients übernommen werden, z.B. einem Pi. Zur einfacheren Darstellung wird in diesem Eintrag jedoch immer von der Nutzung eines Servers ausgegangen, der nicht gleichzeitig auch Client ist.

Das Abspielen von Audio funktioniert prinzipiell in 2 Stufen:
# Nutzung von MPD oder einem MPD-kompatiblen Player zum direkten Abspielen von Sounddateien. Pro existierendem Raum gibt es mindestens eine Instanz von MPD. Hier wird davon ausgegangen, dass es genau eine Instanz pro Raum gibt. Jeder Raum hat also "seinen" MPD.
# Nutzung von Snapcast zur Verteilung des von MPD abgespielten Sounds an den entsprechenden Raum. Snapcast übernimmt hierbei die zeitliche Synchronisation

Durch das Modul '''OpenMultiroom''' steuert der Nutzer sowohl MPD als auch Snapcast. Für jeden Raum wird eine Instanz des Moduls definiert.

=== Verwendete Komponenten ===
Folgende Komponenten kommen zum Einsatz:

==== Server: ====
* MPD oder Mopidy oder ein anderer MPD-kompatibler Player. 1 Instanz pro Raum
* Snapserver
* mplayer (bei Nutzung von Text 2 Speech)
* Optional Pulseaudio (im System-Mode) bei Nutzung von Text 2 Speech oder erweiterten Konfigurationen. Hierbei wird Pulseaudio zwischen MPD und Snapcast geschaltet.
* Optional Anbindung an Subsonic oder Libresonic (hier zurzeit nicht beschrieben) zur Synchronisation von Playlisten uvm.
* FHEM: Modul 98_OpenMultiroom.pm
* FHEM: Modul 96_Snapcast.pm
* FHEM: Modul [[MPD|73_MPD.pm]]
* FHEM: Optional Modul 98_Text2Speech.pm

==== Client: ====
* Linux: Alsa oder Pulseaudio zur Soundwiedergabe
* Linux: Snapclient
* Android: Nur der Android Snapclient
* Webbrowser zur Steuerung per Visualisierung
* ggf. Infrarot oder Funkfernbedienung. In diesem Artikel wird das Beispiel anhand der Nutzung von X10-Funkfernbedienungen gezeigt, diese gibt es sehr günstig in der Bucht o.ä.
* Vision: Nutzung von Tastern und Display am PI oder Nutzung eines Steuergerätes mit Tastern und Display auf Basis eines Arduino mit WLAN, z.B. im alten Gehäuse eines Küchenradios usw.

== Aufbau anhand einer vollständigen Beispielkonfiguration ==

In diesem Artikel soll beispielhaft eine vollständige Konfiguration gezeigt werden. Jeder Nutzer muss diese Konfiguration an seine eigenen Bedürfnisse anpassen. Es seien folgende Komponenten vorhanden:

* Server mit Ubuntu 16.04, hier befindet sich eine MP3-Sammlung
* Kind1: Raspberry Pi Model 1 mit Raspbian
* Kind2: BananaPi mit Ubuntu, an diesem Pi ist auch ein X10 Empfänger angeschlossen, da er zentral im Haus positioniert ist
* Wohnzimmer: Raspberry Pi3 mit OSMC und KODI, wird primär zum Fernsehen verwendet
* Küche: Raspberry Pi Model 1 mit Raspbian

Anmerkung: Es ist möglich, mehrere Räume mit nur einem physikalischen Client zu bedienen. Hierbei werden auf einem Client mehrere Instanzen des Snapclients laufen gelassen. Der physikalische Client hat dann z.B. mehrere USB Soundkarten, dessen Audioausgänge in verschiedene Räume verkabelt sind. Dies wird hier zurzeit nicht näher beschrieben.

=== Pulseaudio Konfiguration ===
Will man Pulseaudio verwenden, z.B. um Text2Speech Nachrichten in laufende Musik einzublenden, sollte dieses am besten zuerst konfiguriert werden. Pulseaudio muss hierzu im System-Mode laufen. Dies ist auf einem Headless-Server kein Problem. Bei Ubuntu 16.10 wird dies durch folgenden Inhalt in ''/etc/systemd/system/pulseaudio.service'' erreicht:
<syntaxhighlight lang="bash">
[Unit]
Description=PA
After=network.target sound.target

[Service]
ExecStart=/usr/bin/pulseaudio --system

# allow MPD to use real-time priority 50
LimitRTPRIO=50
LimitRTTIME=infinity

# disallow writing to /usr, /bin, /sbin, ...
ProtectSystem=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>
Weiterhin ist der Befehl
<syntaxhighlight lang="bash">sudo systemctl enable pulseaudio</syntaxhighlight>
einzugeben, um Pulseaudio beim Systemstart automatisch zu starten.

Ausgehend von der Standardkonfiguration werden nun in ''/etc/pulse/system.pa'' die benötigten Module eingetragen
<syntaxhighlight lang="bash">
load-module module-pipe-sink file=/tmp/wohn.fifo sink_name=wohn
load-module module-pipe-sink file=/tmp/kind1.fifo sink_name=kind1
load-module module-pipe-sink file=/tmp/kind2.fifo sink_name=kind2
load-module module-pipe-sink file=/tmp/kueche.fifo sink_name=kueche

load-module module-combine-sink slaves=kind1,kind2 sink_name=kinder
load-module module-combine-sink slaves=wohn,kueche sink_name=unten
load-module module-combine-sink slaves=wohn,kueche,kind1,kind2 sink_name=alle

pactl load-module module-role-ducking trigger_roles=announcement ducking_roles=music
</syntaxhighlight>
Snapcast benötigt die Audioquelle in Form von FIFOs. Daher wird hier in den erstem 4 Zeilen je ein FIFO von Pulseaudio erzeugt. Der sink_name wird später bei der Konfiguration von MPD als Ausgang verwendet. In den 3 weiteren Zeilen werden noch 3 Sinks als Combine-Sinks erstellt. Diese erzeugen keine neuen FIFOs, sondern machen unter entsprechenden Sink-Namen eine vorgegebene Kombination von Räumen nach außen hin verfügbar. Der Sink "alle" kann also genutzt werden, um Audio auf allen 4 FIFOs gleichzeitig abzuspielen (und somit später potentiell in allen Räumen gleichzeitig). Dies kann für Announcements sinnvoll sein. Die Nutzung dieser Combine-Sinks ist optional. Ebenso optional ist das Laden des Ducking-Moduls am Ende. Das Ducking Modul führt dazu, dass Pulseaudio automatisch die Lautstärke der durch MPD abgespielten Tracks absenkt, wenn etwas über die Text2Speech-Module abgespielt wird. Ohne dies sind die Ausgaben speziell über die Google API unter Umständen nur schwer hörbar.

=== Snapcast Konfiguration ===
[https://github.com/badaix/snapcast Snapcast] muss entsprechend der Angaben auf der Webseite installiert werden. Auf dem Server muss logischerweise die Serverkomponente und auf den Clients die Clientkomponente installiert werden. Bei Android-Clients wird die auf der Webseite zur Verfügung gestellt APK installiert. Snapcast befindet sich selbst noch in fortlaufender Entwicklung. Die hier vorgestellte Lösung ist mit [https://github.com/badaix/snapcast/tree/98be8a58d945f84af50e40ebcf8a774592dd6e7b dieser Version] kompatibel und getestet.

Die Konfiguration des Servers beschränkt sich auf die Definition der Streams in ''/etc/default/snapserver''
<syntaxhighlight lang="bash">
START_SNAPSERVER=true
SNAPSERVER_OPTS="-d -s pipe:///tmp/kind1.fifo?name=kind1&mode=read -s pipe:///tmp/kind2.fifo?name=kind2&mode=read -s pipe:///tmp/wohn.fifo?name=wohn&mode=read -s pipe:///tmp/kueche.fifo?name=kueche&mode=read"
</syntaxhighlight>
Hier werden die 4 Streams erstellt, diese entsprechen vom Dateinamen her der Pulseaudiokonfiguration. Der hier verwendete Name kann später in FHEM oder auch im Android-Client angezeigt werden. Die Option <pre>mode=read</pre> ist wichtig, weil Pulseaudio meckert, wenn es die FIFO-Dateien nicht selbst anlegen darf.

Auf der Clientseite sieht die Datei ''/etc/default/snapclient'' dann so aus:
<syntaxhighlight lang="bash">
START_SNAPCLIENT=true
SNAPCLIENT_OPTS="-d -s dmix:CARD=Aureon51MkII,DEV=0"
</syntaxhighlight>
Den Server findet der Snapclient automatisch, er kann aber auch angegeben werden. Wie hier zu sehen kann ein spezielles Output-Device angegeben werden. Dies ist bei den PIs mit externer USB-Soundkarte meistens notwendig, da ansonsten der interne Sound genutzt würde. Eine Liste der verfügbaren Devices wird mit dem Aufruf von <pre>snapclient -l</pre> ausgegeben, hier muss dann das passende genommen werden. GGf. so lange ausprobieren, bis der Sound an der richtigen Stelle rauskommt.

In der hier betrachteten Konfiguration soll auf dem Wohnzimmer-PI ein Snapclient laufen, dieser wird aber normalerweise zum TV und Filme schauen mit KODI verwendet. Sowohl KODI als auch der Snapclient blockieren aber das ALSA-Device und funktionieren beide meistens entweder gar nicht oder nicht richtig zusammen, insbesondere dann nicht, wenn von KODI Mehrkanalsound oder sogar Passthrough ausgegeben wird. Die Entwicklung eines nativen Snapcast-Clients innerhalb von KODI wird gerade an verschiedenen Stellen diskutiert, z.B. [https://github.com/badaix/snapcast/issues/155 hier]. Bis dahin kann ein kleiner Workaround Abhilfe schaffen. Mit folgendem (nur rudimentär getesteten) [https://github.com/unimatrix27/snapcast/commit/88e42a2ecc8b44223701e18abb63af04b673b67b Hack] für den Snapcast-Client wird erreicht, dass der Client das ALSA-Device frei gibt, sobald er über den Server auf Mute gestellt wird. KODI selbst gibt das Device ebenfalls frei, wenn es im Zustand "Stop" ist. Bei dieser Lösung kann der Snapclient auf dem KODI-Rechner immer laufen gelassen werde. Es ist jedoch in der Verantwortung des Benutzers, den Client zu "muten". Vergisst er dies, wird ggf. die Wiedergabe in KODI nicht möglich sein.

Nach Abschluss der Snapcastkonfiguration und dem Starten von Server und den Clients empfiehlt es sich, die Android-App ebenfalls zu verwenden, da diese einen schnellen Überblick über den Zustand des Servers, der konfigurierten Streams und der Clients bietet.

=== Mopidy Konfiguration ===

In diesem Beispiel wird Mopidy als MPD-Ersatz verwendet, genau so gut kann aber auch direkt MPD verwendet werden. Die genauen Konfigurationsoptionen sind natürlich anders, und jeweils in entsprechenden Tutorials oder Dokumentationen beschrieben. Mopidy ist relativ umfangreich und modular aufgebaut, es bietet u.a. die Möglichkeit, neben lokal gespeicherten Dateien auch Dateien von verschiedenen, teilweise kommerziellen, Streamingdiensten abzuspielen. Die Detailkonfiguration all dieser Komponenten geht über diesen Artikel hinaus. Entscheidend hier ist die Konfiguration in einer Weise, so dass mehrere Mopidy-Instanzen gleichzeitig ausgeführt werden können und dann auf unterschiedlichen Ports zur Verfügung stehen.

Nach Installation von Mopidy findet sich die Konfiguration in der Datei ''/etc/mopidy/mopidy.cfg''. Mopidy unterstützt hierarische Konfigurationen, es reicht also, den für jede Instanz spezifischen Teil aus dieser allgemeinen Konfiguration zu entfernen und in jeweils eigene Dateien zu verschieben. In diesem Beispiel sollen das die Dateien ''/etc/mopidy/kind1.conf'' bis ''/etc/mopidy/kueche.conf'' sein. Die folgenden Zeilen gehören jeweils in diese 4 Dateien und werden dort entsprechend angepasst. Hier das Beispiel für Kind2:

<syntaxhighlight lang="bash">
[logging]
config_file = /etc/mopidy/logging_kind2.conf
debug_file = /var/log/mopidy/mopidy-debug_kind2.log

[audio]
output = audioresample ! audioconvert ! audio/x-raw,rate=48000,channels=2,format=S16LE ! pulsesink device=kind2 stream-properties="props,media.role=music"

[mpd]
enabled = true
hostname = 0.0.0.0
port=6601

[http]
enabled = true
hostname = 0.0.0.0
port=6681
zeroconf = Musik Kind2
</syntaxhighlight>

Im Audioteil wird der entsprechende Sink aus der Pulseaudiokonfiguration genommen. Die Angabe von stream-properties ermöglicht dem Duck-Modul den Stream als Musik zu erkennen und beim Abspielen von Announcements in der Lautstärke abzusenken. Beim MPD muss der Port für jede Instanz unterschiedlich sein, ebenso beim HTTP-Modul für die Weboberfläche der jeweiligen Instanz. Der Zerokonfname sollte auch eindeutig sein. Neben dieser Datei ist noch die dazu passende logging-Konfiguration anzulegen, hier also ''/etc/mopidy/logging_kind2.conf''. Dazu wird die Standarddatei kopiert und darin nur der Name der Logdatei angepasst.

Um nun auch die entsprechende Anzahl Instanzen automatisch zu starten, sind die entsprechenden Startdateien anzulegen. Dazu kann die Datei ''/etc/systemd/system/mopidy.cfg'' z.B. in ''/etc/systemd/system/mopidy_kind1.cfg'' umbenannt werden und dann 3 mal mit den Endungen der anderen Instanzen kopiert werden. Der Inhalt ist dann wie folgt:

<syntaxhighlight lang="bash">
[Unit]
Description=Mopidy_kind1
After=network.target sound.target

[Service]
EnvironmentFile=/etc/default/mopidy
ExecStart=/usr/bin/mopidy --quiet --config /etc/mopidy/kind1.conf

# allow MPD to use real-time priority 50
LimitRTPRIO=50
LimitRTTIME=infinity

# disallow writing to /usr, /bin, /sbin, ...
ProtectSystem=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Abschließend sollten die 4 Instanzen durch den Aufruf von <pre>systemctl enable mopidy_kind1</pre> usw. aktiviert werden. Es empfiehlt sich nach dem Start von Mopidy die korrekte Funtkionsweise mit dem [https://www.musicpd.org/clients/mpc/ MPC]-Client oder mit [http://rybczak.net/ncmpcpp/ NCMPCPP] auf der Konsole zu testen.

Hierbei sollte es dann bereits möglich sein, die Multiroom-Fähigkeiten von Snapcast mit Hilfe des Android-Clients von Snapcast zu testen und so auch festzustellen, dass die restliche Konfiguration von Snapcast und Pulseaudio korrekt sind.

=== FHEM ===

In FHEM sind nun in der ''fhem.cfg'' die entsprechenden Module einzurichten:
* Ein Snapcast-Modul im Server Modus
* Pro Raum ein Snapcast-Modul im Clientmodus
* Pro Raum ein MPD-Modul
* Pro Raum ein OpenMultiroom-Modul
* Optional pro Raum ein Text2Speech-Modul
* weitere Text2Speech-Module, falls man diese in Pulseaudio mit dem per Combine-Sink vorgesehen hat.

<syntaxhighlight lang="bash">
define scs.snap Snapcast

define scc.kind1 Snapcast client scs.snap b827eb9aec84
attr scc.kind1 constraintDummy freestring
attr scc.kind1 constraints standard|07:00 0 20:00 100 21:00 50 21:30 30 24:00 0,beforefree|07:00 0 21:00 100 22:00 50 23:00 30 24:00 0,beforeschool|07:00 0 08:30 50 20:00 100 21:00 50 21:30 30 24:00 0,free|07:00 0 08:30 50 21:00 100 22:00 50 23:00 30 24:00 0

define scc.kind2 Snapcast client scs.snap 025009413c29
attr scc.kind2 constraintDummy freestring
attr scc.kind2 constraints standard|07:00 0 20:15 100 20:30 50 24:00 0,beforefree|07:00 0 21:00 100 22:30 50 24:00 0,beforeschool|07:00 0 08:30 50 20:15 100 20:30 50 24:00 0,free|07:00 0 08:30 50 21:00 100 22:30 50 24:00 0

define scc.kueche Snapcast client scs.snap b827eb9a2ad3

define scc.wohn Snapcast client scs.snap 00aefa4aa3a9
</syntaxhighlight>

Oben zu sehen ist das define für das Server-Modul. Ohne Parameter verbindet sich mit localhost auf dem Standardport 1705. Es folgt die Definition von 2 Clients. Der erste Parameter "client" versetzt das Snapcastmodul in den Clientmodus. Der zweite Parameter verweist auf das Servermodul, der dritte Parameter ist die Client-ID. Diese besteht bei der aktuellen Snapcast-Version meistens aus der MAC-Adresse des Clients. Für die Kinder werden noch die Attribute constraintDummy ond constraints vergeben. Hiermit wird eine tagestyp- und tageszeitabhängige Lautstärkebegrenzung konfiguriert. Für die vier Tagestypen "standard", "beforefree", "beforeschool" und "free" wird ein jeweils anderes Lautstärkezeitprofil definiert.

Das Zeitprofil wird hier nach dem gleichen Muster wie die Temperaturlisten der Homematic-Thermostate, erklärt hier: [HomeMatic_Type_Thermostat]. Für den Tagestyp wird zusätzlich das Attribut constraintDummy verwendet. Es definiert, dass in dem Dummy "freestring" jeweils drin steht, welcher Tagestyp gerade ist. Diese Variable wirkt somit als Selektor auf die Liste der erlaubten Maximallautstärken. Wie eine solche Dummyvariable jeweils mit einem entsprechenden Wert befüllt werden kann, z.B. abhängig vom Wochentag, von Schulferien oder Feiertagen, wird hier nicht erläutert. Es ist auch möglich, nur ein Lautstärkeprofil anzugeben. Ohne dass ein Attribut constraintDummy gesetzt ist, verwendet das Snapcastmodul immer den Wert "standard". Wie man hier sehen kann, gibt es im Beispiel 4 Typen, hierbei fallen Freitage normalerweise in die Kategorie "beforefree" (es sind Tage, bevor dann frei ist, es kann also typischerweise länger und lauter Musik gehört werden), Samstage normalerweise in die Kategorie "free" und Sonntage in die Kategorie "beforeschool", ebenso landen dort Feiertage vor Schultagen usw.

<syntaxhighlight lang="bash">
define tts.wohn Text2Speech pulsewohn
attr tts.wohn TTS_FileTemplateDir /data/misc/announcements/
attr tts.wohn TTS_UseMP3Wrap true
attr tts.wohn TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120

define tts.kind1 Text2Speech pulsekind1
attr tts.kind1 TTS_FileTemplateDir /data/misc/announcements/
attr tts.kind1 TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kind1 TTS_UseMP3Wrap true

define tts.kind2 Text2Speech pulsekind2
attr tts.kind2 TTS_FileTemplateDir /data/misc/announcements/
attr tts.kind2 TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kind2 TTS_UseMP3Wrap true

define tts.kueche Text2Speech pulsekueche
attr tts.kueche TTS_FileTemplateDir /data/misc/announcements/
attr tts.kueche TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kueche TTS_UseMP3Wrap true

define tts.kinder Text2Speech pulsekinder
attr tts.kinder TTS_FileTemplateDir /data/misc/announcements/
attr tts.kinder TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kinder TTS_UseMP3Wrap true

define tts.unten Text2Speech pulseunten
attr tts.unten TTS_FileTemplateDir /data/misc/announcements/
attr tts.unten TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.unten TTS_UseMP3Wrap true

define tts.alle Text2Speech pulsealle
attr tts.alle TTS_FileTemplateDir /data/misc/announcements/
attr tts.alle TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.alle TTS_UseMP3Wrap true
</syntaxhighlight>
Hier sind die Definitionen der Text2Speech Module zu sehen (optional). Sie werden jeweils mit den in Pulseaudio definierten Sinks verbunden. Die Nutzung eines TemplateDirs ist ebenfalls optional, hier können bereits fertige MP3s verwendet werden, die dann anstelle der von der Google TTS API erzeugten Dateien benutzt werden. Dies können auch Bestätigungs und Fehlertöne sein, die bei Benutzern ohne Display, die rein mit Fernbedienung arbeiten, auf Fehlbedienungen etc. aufmerksam zu omrhen. Der Aufruf von mplayer wird noch modifiziert, um dafür zu sorgen, dass die Ausgabe bei Pulseaudio als media.role "announcement" eingehen. Dies wird dann vom duck-Modul erkannt, und führt dazu, dass die Lautstärke der ggf. ablaufenden Musik, etc. abgesenkt wird, so lange die tts-Ausgabe läuft.

<syntaxhighlight lang="bash">
define mpd.kind1 MPD 192.168.2.2 6600
attr mpd.kind1 player mopidy
attr mpd.kind1 bookmarkDir mpdstates
attr mpd.kind1 autoBookmark 1

define mpd.kind2 MPD 192.168.2.2 6702
attr mpd.kind2 player mopidy
attr mpd.kind2 bookmarkDir mpdstates
attr mpd.kind2 autoBookmark 1

define mpd.kueche MPD 192.168.2.2 6703
attr mpd.kueche player mopidy
attr mpd.kueche bookmarkDir mpdstates
attr mpd.kueche autoBookmark 1

define mpd.wohn MPD 192.168.2.2 6704
attr mpd.wohn player mopidy
attr mpd.wohn bookmarkDir mpdstates
attr mpd.wohn autoBookmark 1
</syntaxhighlight>
Pro laufender MPD oder Mopidy-Instanz wird ein MPD-Modul eingerichtet. Der Hostname und die Ports sind entsprechend anzupassen. Durch die bookmarkDir und autoBookmark - Attribute wird erreicht, dass der Zustand von Playlisten beim Wechsel derselben gespeichert und später wiederhergestellt werden kann. So lässt sich das Hören eines Hörbuchs unterbrechen, auf z.B. eine Radiostreamplayliste schalten, um dann später zur gleichen Stelle im Hörbuch zurückzukehren.

<syntaxhighlight lang="bash">
define omr.kind1 OpenMultiroom
attr omr.kind1 mr scc.kind1
attr omr.kind1 soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kind1 playlistPattern kind1
attr omr.kind1 ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kind1 defaultTts tts.kind1
attr omr.kind1 defaultStream kind1
attr omr.kind1 defaultSound mpd.kind1

define omr.kind2 OpenMultiroom
attr omr.kind2 mr scc.kind2
attr omr.kind2 soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kind2 playlistPattern kind2
attr omr.kind2 ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kind2 defaultTts tts.kind2
attr omr.kind2 defaultStream kind2
attr omr.kind2 defaultSound mpd.kind2

define omr.kueche OpenMultiroom
attr omr.kueche mr scc.kueche
attr omr.kueche soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kueche playlistPattern wohn
attr omr.kueche ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kueche defaultTts tts.kueche
attr omr.kueche defaultStream kueche
attr omr.kueche defaultSound mpd.kueche

define omr.wohn OpenMultiroom
attr omr.wohn mr scc.wohn
attr omr.wohn soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.wohn playlistPattern wohn
attr omr.wohn ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.wohn defaultTts tts.wohn
attr omr.wohn defaultStream wohn
attr omr.wohn defaultSound mpd.wohn
</syntaxhighlight>
Die Konfiguration der OpenMultiroom-Module schließt die Einrichtung von FHEM ab. Jede Instanz benötigt mindestens das "mr"- und das "soundMapping"-Attribut. Nur so kann sich das Modul mit den entsprechenden Snapcast und MPD-Modulen verbinden. Durch das "mr"-Attribut wird ein OpenMultiroom-Modul einem Snapcast-Client-Modul fest zugeordnet. Das Soundmapping ordnet die in Snapcast definierten Streams (siehe oben, Konfiguration vom Snapserver) den entsprechenden Instanzen des MPD-Moduls zu. Dadurch weiß FHEM, welcher MPD auf welchem Stream abspielt und kann je nachdem, welchem Stream ein Raum gerade zuhört, den dazu passenden MPD steuern und seine Readings durchreichen. Das OpenMultiroom-Modul bildet alle Readings des MPD-Moduls nochmal direkt ab. Wechselt ein Benutzer aber den Stream, dem er zuhört, aktualisieren sich auch alle Readings dementsprechend mit denen des dann aktuellen MPD-Moduls.

Das Attribut playlistPattern ist optional und sorgt dafür, dass beim Durchschalten der Playlists mit den Kommandos "channelUp" und "channelDown" nur diejenigen Playlists berücksichtigt werden, die auf das Pattern passen.

Analog zum soundMapping definiert das Attribut ttsMapping die Zuordnung der TTS-Module zu den Streams. Beim Ausgeben von Announcement kann so das OpenMultiroom-Modul ermitteln, auf welchem Stream welcher Raum gerade zuhört, und wo dementsprechend die TTS-Ausgaben zu erzeugen sind, damit sie auch in den gewünschten Räumen ankommen. Dieser Umweg ist zurzeit nötig, da ein Snapcast-Client nur auf einem einzigen Stream lauschen kann. Lauschen noch andere Clients auf demselben Stream, hören sie allerdings zwangsweise auch die Announcements.

Die 3 Default-Attribute legen fest, welche der TTS-Module, welcher Stream und welcher MPD dem entsprechenden Modul fest zugeordnet sind. Dies wird u.a. von einer Resetfunktion im Modul verwendet.

== Bedienung des OpenMultiroom-Moduls ==

=== set-Kommandos ===

=== Readings ===

=== Attribute ===

== Anbindung einer Fernbedienung an ein OpenMultiroom-Modul ==

=== Konfiguration von LIRC und IRExec ===

=== Zuordnung der Tasten: Beispiel ===

[[Category:Examples]]
[[Category:HOWTOS]]
[[Category:Unterhaltungselektronik]]

99 myUtils anlegen

2022-07-07T11:34:36Z

Beta-User: id bzgl. Doku

Die Speicherung von Perl-Code unmittelbar in [[Eventhandler|Eventhandlern]], [[Timehandler|Timehandlern]] oder anderen Geräten in der [[Konfiguration]], in denen Perl-Ausdrücke angegeben werden können, wird mit wachsender Zahl von Geräten und Logiken eventuell unübersichtlich. Um z.B. Doppelungen zu vermeiden und Logikbausteine zentral vorzuhalten, kann man eine oder mehrere eigene Programmdateien erzeugen, in der diese als kleine Programme gesammelt und dann aus entsprechenden Geräten aufgerufen werden können.
== Eine neue Programmdatei erzeugen ==
FHEM enthält eine Vorlage ''myUtilsTemplate.pm'', die zur Erzeugung von Programmdateien genutzt werden sollte; nachfolgend soll beispielhaft eine Datei namens ''99_myUtils.pm'' verwendet werden.
Vorgehensweise:
* FHEM-Menüpunkt {{Taste|Edit files}} anklicken
* Weblink ''myUtilsTemplate.pm'' anklicken
* Im Textfeld hinter ''Save as'' den Dateinamen ''99_myUtils.pm'' für die Programmdatei eintragen
: Hinweis: Wenn ein anderer Dateiname angegeben wird, muss der Name Initialize-Routine entsprechend angepasst werden (siehe nachfolgende Erläuterung zur Grundstruktur unter Nr. 3)
* {{Taste|Save as}} anklicken
Nun ist die eigene Programmdatei ''99_myUtils.pm'' mit der notwendigen Grundstruktur unter dem Menüpunkt ''Edit files'' zur Bearbeitung mit dem [[codemirror|Integrierter Editor]] zu finden. Für eine einfache und fehlerminimierende Bearbeitung sollten die [[Konfiguration#Syntaxhervorhebung|Syntaxhervorhebungs-, Befehlsauswahl- und Befehlsvervollständigungsfunktionen]] im Integrierten Editor eingeschaltet sein.

{{Randnotiz|RNTyp=g|RNText=Nutzt man {{Link2CmdRef|Lang=en|Anker=configDB|Label=configDB}}, können (bzw. sollten) die eigenen Programmdateien in die Datenbank importiert werden, statt unmittelbar im Dateisystem gespeichert zu bleiben. Sie können dann weiter über {{Taste|Edit files}} bearbeitet werden, stehen dann aber z.B. bei einem Umzug oder Neuaufsetzen des Systems direkt wieder zur Verfügung.}}
Die Programmdateien können zwar auch mit einem [[Konfiguration#Externer Editor|externen Editor]] bearbeitet werden, diese Vorgehensweise wird jedoch nicht empfohlen, da dies insbesondere Einsteigern das debugging erschwert.

Eine ‚leere‘ Programmdatei muss grundsätzlich folgenden Grundstruktur besitzen:

<source lang="perl">
package main;
use strict;
use warnings;

sub
myUtils_Initialize($$)
{
my ($hash) = @_;
}
1;
</source>

Folgende Dinge sind für eigene Programmdateien besonders zu beachten:

# Der Dateiname muss mit 99_ beginnen. FHEM lädt beim Start alle Programmdateien mit dem prefix 99_. Andere Programmdateien werden erst dann geladen, wenn sie durch eine define-Anweisung in der [[Konfiguration]] angefordert werden. So wird z.B. 10_FS20.pm erst geladen, wenn beim Einlesen der Konfiguration das erste define für ein FS20-device abgearbeitet wird. Da Ihre eigene Programmsammlung wahrscheinlich kein neues Gerät mit einem zugehörigen define-Befehl implementiert, würde sie also nie geladen, wenn ihr Name nicht mit 99_ beginnt.
# Damit die neue Datei bei ''Edit files'' angezeigt wird, muss sie mit ''.pm'' enden und den Bestandteil ''Utils'' enthalten. Also zum Beispiel ''99_meineUtils.pm'' oder ''99_myUtils_Homematic.pm''.
# Der Name der Programmdatei muss mit dem Namen der Initialize-Routine übereinstimmen. Wenn Sie Ihr Programm also 99_Werkzeugkasten.pm nennen, muss die im code dargestellte initialize-Routine sub Werkzeugkasten_Initialize heißen.
# Die Zeile <code> 1; </code> muss immer die letzte Programmzeile sein. Wenn Sie also eigene Routinen in Ihre Programmsammlung einfügen, tragen Sie diese zwischen dem Ende der Initialize-Routine und der abschließenden Zeile <code> 1; </code> ein.

== Eigene Routinen einfügen ==
Als Beispiel dient das Umsetzen von FS20 toggle-Events aus dem Artikel "[[FS20 Toggle Events auf On/Off umsetzen]]".
Das gesamte Programm sieht dann folgendermaßen aus:

<source lang="perl">
package main;
use strict;
use warnings;

sub
myUtils_Initialize($$)
{
my ($hash) = @_;
}
##########################################################
# Untoggle
# toggle-Vorgänge in den Status on/off umsetzen
sub Untoggle($) {
my ($obj) = @_;

if( Value($obj) eq "toggle" ){
if( OldValue($obj) eq "off" ) {
fhem( "setstate $obj on" );
}
else {
fhem( "setstate $obj off" );
}
}
else {
fhem( "setstate $obj ".Value($obj) );
}
}
1;</source>
Der Aufruf erfolgt dann z.B. so:

<pre>#fhem.cfg
define lampe_untoggle notify lampe {Untoggle("$NAME")}</pre>
Der Aufruf aus einem notify (oder at) erfolgt als Perl-code, muss also in geschweiften Klammern stehen. Der Aufruf erfolgt durch Angabe des Namens der Routine (Untoggle) unter Angabe der zu übergebenden Parameter (hier "$NAME").
Im Programm wurde die Routine Untoggle mit '''einem''' Parameter definiert ( Untoggle($) , die Anzahl der $-Zeichen bestimmt die Anzahl der zu übergebenden Parameter). Der Wert des übergebenen Parameters wird in der ersten Programmzeile in die Variable $obj übernommen (my ($obj) = @_; ).
Der Aufruf erfolgt mit Untoggle(„$NAME“) . Der Platzhalter $NAME in fhem steht für den Namen des Geräts. Im o.g. Beispiel erfolgt der Aufruf also eigentlich mit Untoggle(„lampe“). Natürlich können beim Aufruf auch feste Werte ( „lampe1“ ) oder Variablen ( $hour ) übergeben werden.

=== Routinen mit mehreren Parametern ===
In der Definition der Routine geben Sie außerdem an, wieviele Parameter übergeben werden sollen, für 2 Parameter z.B. so:

<source lang="perl">define test at *09:00 { wakeup($we, "Schlafzimmerlampe") }</source>
Die Deklaration der Routine in Ihrer Programmdatei muss dann so beginnen:

<source lang="perl">#Nur am Wochenende eingeschaltet
sub wakeup($$) {
my ($wochenende, $device) = @_;
if ($wochenende) {
fhem( "set $device on" );
}
else {
fhem( "set $device off" );
}
}</source>
Durch die Anzahl der $-Zeichen in der Routinen-Deklaration wird also die Anzahl der Parameter festgelegt. In der ersten Programmzeile Ihrer Routine übernehmen Sie dann die übergebenen Parameterwerte in lokale Variablen. Wie beim Routinen-Aufruf muss auch hierbei die Anzahl der Parameter mit der Routinen-Deklaration (also Anzahl der $-Zeichen) übereinstimmen<ref>Mehr zu diesen sog. prototypes ist z.B. [https://perldoc.perl.org/perlsub.html#Prototypes hier] nachzulesen; auch [[fhem.pl]] beginnt mit einer Liste der prototyes der darin enthaltenen Funktionen. Da diese Funktionen auch innerhalb der myUtils verwendet werden können, empfiehlt es sich, zunächst dort nachzusehen, ob eventuell bereits hilfreiche Funktionen für das zu lösende Problem vorhanden sind.</ref>.

=== Routinen ohne Parameter ===
Auch Routinen ohne Parameter sind natürlich möglich. Definition und Aufruf sehen dann folgendermassen aus:

<source lang="perl">sub parameterlos() {
...
}</source>
{ parameterlos() }

== Eigene Programmdatei laden ==
Die Programmdatei wird beim FHEM-Start immer automatisch geladen.

Bei Änderungen an der Programmdatei bei laufendem FHEM ist bezüglich Neuladen ohne FHEM-Neustart zwischen den verschiedenen Bearbeitungsvarianten der Progammdatei zu unterscheiden.

Bei der Bearbeitung über den '''Integrierten Editor''' wird die Programmdatei beim Abspeichern automatisch mit den Änderungen neu geladen.

Bei der nicht empfohlenen Bearbeitung der Programmdatei mit einem '''externen Editor''' muss FHEM manuell angewiesen werden, die Programmdatei mit den Änderungen zu laden. Also bearbeiten Sie Ihr Programm, speichern die Programmdatei, und weisen FHEM dann explizit an, die Programmdatei erneut zu laden. Der Befehl dazu, der in das Befehls-Eingabefeld eingegeben wird, lautet: <code>reload 99_myUtils.pm</code>

Treten beim Laden (Syntax)fehler auf, werden diese am Bildschirm wie auch im Log angezeigt. Da der Ladevorgang fehlgeschlagen ist, stehen Ihre eigenen Routinen nun nicht zur Verfügung (bzw. in der zuletzt erfolgreich geladenen Version). Es empfiehlt sich daher bei der Entwicklung neuer Code-Teile v.a. für "Einsteiger", diese zunächst in einer separaten myUtils-Datei zu entwickeln und erst dann in die für den "produktiven Betrieb" genutzten myUtils-Dateien zu übernehmen, wenn sie als funktional getestet anzusehen sind.
== Eigene Programmdatei dokumentieren ==
In der lokalen Commandref kann man die eigenen Routinen auch dokumentieren.
Dazu muss am Ende der 99_myUtils folgender Codeblock eingefügt werden
<source lang="perl">
=pod
=begin html

<a id="myUtils"></a>
<h3>myUtils</h3>
<ul>
Name
 
Text 
Examples:
<ul>
<code>Example Code </code> 
</ul>
</ul>

=end html
=begin html_DE

<a id="myUtils"></a>
<h3>myUtils</h3>

=end html_DE
=cut
</source>

Der a Tag stellt einen Verweis dar, der h3 Tag kennzeichnet die Überschrift. Beide Tags müssen sein, ansonsten kann FHEM die Doku nicht in die commandref einbinden. Der Abschnitt für die deutsche Doku kann komplett fehlen. Die Beschreibungen der einzelnen Routinen werden mit ul Tags geklammert und eventuell mit ul Tags weiter untergliedert. Dabei entsteht ein eingerückter Text. Beispiele können mit dem code Tag formatiert werden.

Mit diesem Befehl kann die Erzeugung des Commandrefeintrages initiiert und getestet werden:
<source lang="perl">{system("/usr/bin/perl ./contrib/commandref_join.pl")}</source>
Für eine schnelle Überprüfung des Commandrefeintrages können Sie auch <source lang="perl">help myUtils</source> (bzw. statt myUtils den Namen Ihrer Utils-Datei) eingeben.

Weiterführende Hinweise sind in den [[Guidelines zur Dokumentation]] zu finden.

== Weitere Informationen ==
=== Globale Ablage von Daten ===
Um Daten zentral zwischenzuspeichern, kann man
* die Funktionen ''[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]'' bzw. ''getKeyValue()'' nutzen, um die Daten im Dateisystem abzulegen;
* in den globalen Hash ''%data schreiben'', wie in diesem {{Link2Forum|Topic=63737|LinkText=Forumsbeitrag}} erläutert.

=== Vertiefende Informationen ===
Weiterführende Hinweise, z.B. wie aus einer Sammlung kleiner Tools ggf. ein eigenes Modul entstehen kann, sind der [[DevelopmentModuleIntro]] zu entnehmen. Dort sind v.a. auch einige häufig benötigte Funktionen aus fhem.pl dokumentiert.

== Links ==
* Eine Zusammenstellung wichtiger Funktionen ist in den Perl specials der {{Link2CmdRef|Anker=perl|Label=commandref}} enthalten.
* Eine weitere Sammlung hilfreicher "Helferlein" samt Hilfe enthält [https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm 99_Utils.pm].
* Hilfsfunktionen für Farboperationen: [[Color]].
* [[Zeitangaben, rechnen mit|Wiki-Beitrag zum Rechnen mit Zeitangaben]]
* [[Gleitende Mittelwerte berechnen und loggen]]
* Beispiele für Geräteüberwachungen: [[EBUS#Mithilfe von FHEM|EBUS]], [[Netzwerkgeräte:_Verfügbarkeit_prüfen#Erweiterung 99 myUtils|Netzwerkgeräte]], {{Link2Forum|Topic=51267|Message=935071|LinkText=Nextion-Display bei Inaktivität zurücksetzen}}, {{Link2Forum|Topic=97173|Message=917347|LinkText=devStateIcon für das Modul ''monitoring''}}
* [[Batterieüberwachung#Alternativ per Skript|Batterieüberwachung]]
* Routine zum [[E-Mail_senden#Raspberry Pi|E-Mail senden]] aus FHEM heraus
* [[E-Mail per notify nach Zeitablauf erneut senden|Beispiel]], wie ggf. an mehreren Stellen relevante Variablen zentral zur Verfügung gestellt werden können.
* [[Plot-Abriss_vermeiden#Implementierung|Plot-Abrisse vermeiden]]
* Formatierungsanweisungen auslagern: [[ReadingsGroup#Enigma_Receiver|ReadingsGroup]], [[Spritpreismonitor#Farbliche_Hervorhebung|Spritpreismonitor]], [[EBUS-MQTT2#myUtils-Code|Balkenanzeige]] (hier: für EBUS)
* Befehle an ein Netzwerkgerät senden: [[Listenlive#Der Code|Listenlive]]
* [[HM-Dis-WM55_Funk_Statusanzeige#99_myUtils|Homematic-Display]] mit Informationen versorgen
* {{Link2Forum|Topic=34363|Message=266811|LinkText=Zeit- und Datumsvariablen $hour, $wday, $month, ... in 99_myUtils.pm verfügbar machen}}
* {{Link2Forum|Topic=36504|Message=287778|LinkText=Globale und flexible Fenster- und Türüberwachung}}
* {{Link2Forum|Topic=87895|Message=803439|LinkText=57_CALENDAR.pm - events mit deviceNames nutzen}}
* {{Link2Forum|Topic=96959|Message=901268|LinkText=Konstanten für das Rechnen mit Zeiten}}
* {{Link2Forum|Topic=97430|Message=906576|LinkText=devStateIcon-Code für Homematic-Thermostate}}
* {{Link2Forum|Topic=86073|Message=836537|LinkText=php-Script aufrufen und Rückgabewert in einen dummy schreiben}} (hier: Viessmann Heizung))
* {{Link2Forum|Topic=84831|Message=771485|LinkText=Windchill und Hitzeindex berechnen}}
* {{Link2Forum|Topic=84016|Message=762888|LinkText=Countdown Timer}}

<references />
[[Kategorie:Code Snippets]]
[[Kategorie:HOWTOS]]
[[Kategorie:Perl]]

OpenMultiroom

2022-06-24T12:00:51Z

Beta-User: Typo

<div style="float:right">{{Infobox Modul
|ModPurpose=Steuern der einzelnen Multiroom-Systemkomponenten
|ModType=d
|ModCmdRef=OpenMultiroom
|ModForumArea=Multimedia
|ModTechName=98_OpenMultiroom.pm
|ModOwner=unimatrix
}}
{{Infobox Modul
|ModPurpose=Steuern eines Snapcast-Servers
|ModType=d
|ModCmdRef=Snapcast
|ModForumArea=Multimedia
|ModTechName=96_Snapcast.pm
|ModOwner=orphan/rudolphkoenig
}}
[[Datei:OpenMultiroomOverview.png|mini|400px|Schaubild des Zusammenspiels der einzelnen Komponenten eines Multiroomsystems mit den Backends {{Link2Forum|Topic=18517|LinkText=MPD}} und {{Link2Forum|Topic=62389|LinkText=Snapcast}} sowie der Nutzung von Text2Speech]]
</div>

Achtung: Das Modul ist noch sehr neu und bisher nur im {{Link2Forum|Topic=65785|LinkText=Forum}} bzw. auf dem [https://github.com/unimatrix27/fhemmodules/blob/master/98_OpenMultiroom.pm Github des Autors] verfügbar. Sobald alles stabil ist, wird es im SVN eingestellt.

'''OpenMultiroom''' ist ein Steuerungsmodul sowie auch ein Gesamtkonzept zur Realisierung eines Multiroom-Audio-Systems unter Nutzung von ausschließlich frei verfügbarer Software und ohne Bezug auf die Hardware eines bestimmten Herstellers. Es ist so ausgelegt, dass es prinzipiell flexibel bezüglich der Auswahl der Backendsysteme ist. Zurzeit ist es für die Nutzung mit [https://www.musicpd.org/ MPD] bzw. [https://www.mopidy.com/ Mopidy] und [https://github.com/badaix/snapcast Snapcast] implementiert. Daher wird in diesem WIKI-Eintrag immer von diesen Systemen gesprochen. Einen grundsätzlichen Überblick über das Konzept bietet das Schaubild.

== Grobe Übersicht des Funktionsumfangs der Gesamtlösung==
=== Features ===
* Integrierte Steuerung des Musikplayers über das [[MPD]]-Modul sowie des Multiroom-System {{Link2Forum|Topic=62389|LinkText=Snapcast}} in einem einzigen Modul
* Implementierung einer Schnittstelle gemäß [[DevelopmentGuidelinesAV]] als Basis für eine Visualisierung mit z.B. [[SmartVISU]] oder [[FHEM Tablet UI]]
* Synchrones Playback auf z.B. Raspberry Pi oder Android-Geräten (Snapcast-Feature)
* optionale Komprimierung der Soundübertragung als OGG oder FLAC (Snapcast-Feature)
* Möglichkeit der Bedienung völlig ohne Display über eine Fernbedienung und entsprechender Text2Speech Rückmeldung, insbesondere
** Durschalten von Playlisten mit entsprechenden Channel - Tasten unter Nutzung von raumspezifischen Filtern
** Forward und Rewind mit definierbaren Sprungweiten (implementiert direkt im [[MPD]]-Modul)
** Direktanwahl von Playlisten, Tracks oder Trackpositionen durch Zifferneingabe und anschließende Funktionstaste
** Abfrage von Statusinformationen durch Funktionstasten und Text2Speech Rückmeldungen
** Mithören in anderen Räumen und Übernahme des Playerzustandes anderer Räume durch Nutzung von Funktionstasten
** Einschlaftimer per Zifferneingabe oder per vordefinierten Zeitabständen, hierbei wird auch die Restlaufzeit des aktuellen Tracks angeboten.
* manuelles oder automatisches Speichern und Laden von Playlistbookmarks (implementiert direkt im [[MPD]]-Modul)
* Möglichkeit der Festlegung von tageszeit- und tagestypabhängigen Lautstärkebegrenzungen bis auf 0% z.B. für Kinderzimmer
* individuelles Verwalten von Playlisten für verschiedene Familienmitglieder
* Nutzung des Audiosystems für systemunabhängige FHEM-Announcements. Ein entsprechendes Announcement-Modul ist in Planung. Dabei können mehrere Räume gleichzeitig oder auch getrennt angesprochen werden

=== Anwendungszweck und Kurzbeschreibung der Funktionsweise ===
Wie der Name des Systems vermuten lässt, ist die Lösung vor allem dann sinnvoll einzusetzen, wenn Audiodateien in mindestens 2 verschiedenen Räumen oder "Zonen" sowohl synchron als auch unabhängig abgespielt werden soll und wenn hierzu eine komfortable und integrierte Steuerung über FHEM verwendet werden soll. Mit Einschränkungen ist die Lösung auch dann sinnvoll, wenn es nur um das Abspielen in einem Raum geht. Hier kann dann z.B. die Steuerung über eine Fernbedienung mit Hilfe des '''OpenMultiroom'''-Moduls genutzt werden, die über eine reine Nutzung des MPD-Moduls hinausgeht.

Für die Nutzung ist nicht zwingend ein zentraler Server notwendig. Diese Rolle kann auch von einem der Clients übernommen werden, z.B. einem Pi. Zur einfacheren Darstellung wird in diesem Eintrag jedoch immer von der Nutzung eines Servers ausgegangen, der nicht gleichzeitig auch Client ist.

Das Abspielen von Audio funktioniert prinzipiell in 2 Stufen:
# Nutzung von MPD oder einem MPD-kompatiblen Player zum direkten Abspielen von Sounddateien. Pro existierendem Raum gibt es mindestens eine Instanz von MPD. Hier wird davon ausgegangen, dass es genau eine Instanz pro Raum gibt. Jeder Raum hat also "seinen" MPD.
# Nutzung von Snapcast zur Verteilung des von MPD abgespielten Sounds an den entsprechenden Raum. Snapcast übernimmt hierbei die zeitliche Synchronisation

Durch das Modul '''OpenMultiroom''' steuert der Nutzer sowohl MPD als auch Snapcast. Für jeden Raum wird eine Instanz des Moduls definiert.

=== Verwendete Komponenten ===
Folgende Komponenten kommen zum Einsatz:

==== Server: ====
* MPD oder Mopidy oder ein anderer MPD-kompatibler Player. 1 Instanz pro Raum
* Snapserver
* mplayer (bei Nutzung von Text 2 Speech)
* Optional Pulseaudio (im System-Mode) bei Nutzung von Text 2 Speech oder erweiterten Konfigurationen. Hierbei wird Pulseaudio zwischen MPD und Snapcast geschaltet.
* Optional Anbindung an Subsonic oder Libresonic (hier zurzeit nicht beschrieben) zur Synchronisation von Playlisten uvm.
* FHEM: Modul 98_OpenMultiroom.pm
* FHEM: Modul 96_Snapcast.pm
* FHEM: Modul [[MPD|73_MPD.pm]]
* FHEM: Optional Modul 98_Text2Speech.pm

==== Client: ====
* Linux: Alsa oder Pulseaudio zur Soundwiedergabe
* Linux: Snapclient
* Android: Nur der Android Snapclient
* Webbrowser zur Steuerung per Visualisierung
* ggf. Infrarot oder Funkfernbedienung. In diesem Artikel wird das Beispiel anhand der Nutzung von X10-Funkfernbedienungen gezeigt, diese gibt es sehr günstig in der Bucht o.ä.
* Vision: Nutzung von Tastern und Display am PI oder Nutzung eines Steuergerätes mit Tastern und Display auf Basis eines Arduino mit WLAN, z.B. im alten Gehäuse eines Küchenradios usw.

== Aufbau anhand einer vollständigen Beispielkonfiguration ==

In diesem Artikel soll beispielhaft eine vollständige Konfiguration gezeigt werden. Jeder Nutzer muss diese Konfiguration an seine eigenen Bedürfnisse anpassen. Es seien folgende Komponenten vorhanden:

* Server mit Ubuntu 16.04, hier befindet sich eine MP3-Sammlung
* Kind1: Raspberry Pi Model 1 mit Raspbian
* Kind2: BananaPi mit Ubuntu, an diesem Pi ist auch ein X10 Empfänger angeschlossen, da er zentral im Haus positioniert ist
* Wohnzimmer: Raspberry Pi3 mit OSMC und KODI, wird primär zum Fernsehen verwendet
* Küche: Raspberry Pi Model 1 mit Raspbian

Anmerkung: Es ist möglich, mehrere Räume mit nur einem physikalischen Client zu bedienen. Hierbei werden auf einem Client mehrere Instanzen des Snapclients laufen gelassen. Der physikalische Client hat dann z.B. mehrere USB Soundkarten, dessen Audioausgänge in verschiedene Räume verkabelt sind. Dies wird hier zurzeit nicht näher beschrieben.

=== Pulseaudio Konfiguration ===
Will man Pulseaudio verwenden, z.B. um Text2Speech Nachrichten in laufende Musik einzublenden, sollte dieses am besten zuerst konfiguriert werden. Pulseaudio muss hierzu im System-Mode laufen. Dies ist auf einem Headless-Server kein Problem. Bei Ubuntu 16.10 wird dies durch folgenden Inhalt in ''/etc/systemd/system/pulseaudio.service'' erreicht:
<syntaxhighlight lang="bash">
[Unit]
Description=PA
After=network.target sound.target

[Service]
ExecStart=/usr/bin/pulseaudio --system

# allow MPD to use real-time priority 50
LimitRTPRIO=50
LimitRTTIME=infinity

# disallow writing to /usr, /bin, /sbin, ...
ProtectSystem=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>
Weiterhin ist der Befehl
<syntaxhighlight lang="bash">sudo systemctl enable pulseaudio</syntaxhighlight>
einzugeben, um Pulseaudio beim Systemstart automatisch zu starten.

Ausgehend von der Standardkonfiguration werden nun in ''/etc/pulse/system.pa'' die benötigten Module eingetragen
<syntaxhighlight lang="bash">
load-module module-pipe-sink file=/tmp/wohn.fifo sink_name=wohn
load-module module-pipe-sink file=/tmp/kind1.fifo sink_name=kind1
load-module module-pipe-sink file=/tmp/kind2.fifo sink_name=kind2
load-module module-pipe-sink file=/tmp/kueche.fifo sink_name=kueche

load-module module-combine-sink slaves=kind1,kind2 sink_name=kinder
load-module module-combine-sink slaves=wohn,kueche sink_name=unten
load-module module-combine-sink slaves=wohn,kueche,kind1,kind2 sink_name=alle

pactl load-module module-role-ducking trigger_roles=announcement ducking_roles=music
</syntaxhighlight>
Snapcast benötigt die Audioquelle in Form von FIFOs. Daher wird hier in den erstem 4 Zeilen je ein FIFO von Pulseaudio erzeugt. Der sink_name wird später bei der Konfiguration von MPD als Ausgang verwendet. In den 3 weiteren Zeilen werden noch 3 Sinks als Combine-Sinks erstellt. Diese erzeugen keine neuen FIFOs, sondern machen unter entsprechenden Sink-Namen eine vorgegebene Kombination von Räumen nach außen hin verfügbar. Der Sink "alle" kann also genutzt werden, um Audio auf allen 4 FIFOs gleichzeitig abzuspielen (und somit später potentiell in allen Räumen gleichzeitig). Dies kann für Announcements sinnvoll sein. Die Nutzung dieser Combine-Sinks ist optional. Ebenso optional ist das Laden des Ducking-Moduls am Ende. Das Ducking Modul führt dazu, dass Pulseaudio automatisch die Lautstärke der durch MPD abgespielten Tracks absenkt, wenn etwas über die Text2Speech-Module abgespielt wird. Ohne dies sind die Ausgaben speziell über die Google API unter Umständen nur schwer hörbar.

=== Snapcast Konfiguration ===
[https://github.com/badaix/snapcast Snapcast] muss entsprechend der Angaben auf der Webseite installiert werden. Auf dem Server muss logischerweise die Serverkomponente und auf den Clients die Clientkomponente installiert werden. Bei Android-Clients wird die auf der Webseite zur Verfügung gestellt APK installiert. Snapcast befindet sich selbst noch in fortlaufender Entwicklung. Die hier vorgestellte Lösung ist mit [https://github.com/badaix/snapcast/tree/98be8a58d945f84af50e40ebcf8a774592dd6e7b dieser Version] kompatibel und getestet.

Die Konfiguration des Servers beschränkt sich auf die Definition der Streams in ''/etc/default/snapserver''
<syntaxhighlight lang="bash">
START_SNAPSERVER=true
SNAPSERVER_OPTS="-d -s pipe:///tmp/kind1.fifo?name=kind1&mode=read -s pipe:///tmp/kind2.fifo?name=kind2&mode=read -s pipe:///tmp/wohn.fifo?name=wohn&mode=read -s pipe:///tmp/kueche.fifo?name=kueche&mode=read"
</syntaxhighlight>
Hier werden die 4 Streams erstellt, diese entsprechen vom Dateinamen her der Pulseaudiokonfiguration. Der hier verwendete Name kann später in FHEM oder auch im Android-Client angezeigt werden. Die Option <pre>mode=read</pre> ist wichtig, weil Pulseaudio meckert, wenn es die FIFO-Dateien nicht selbst anlegen darf.

Auf der Clientseite sieht die Datei ''/etc/default/snapclient'' dann so aus:
<syntaxhighlight lang="bash">
START_SNAPCLIENT=true
SNAPCLIENT_OPTS="-d -s dmix:CARD=Aureon51MkII,DEV=0"
</syntaxhighlight>
Den Server findet der Snapclient automatisch, er kann aber auch angegeben werden. Wie hier zu sehen kann ein spezielles Output-Device angegeben werden. Dies ist bei den PIs mit externer USB-Soundkarte meistens notwendig, da ansonsten der interne Sound genutzt würde. Eine Liste der verfügbaren Devices wird mit dem Aufruf von <pre>snapclient -l</pre> ausgegeben, hier muss dann das passende genommen werden. GGf. so lange ausprobieren, bis der Sound an der richtigen Stelle rauskommt.

In der hier betrachteten Konfiguration soll auf dem Wohnzimmer-PI ein Snapclient laufen, dieser wird aber normalerweise zum TV und Filme schauen mit KODI verwendet. Sowohl KODI als auch der Snapclient blockieren aber das ALSA-Device und funktionieren beide meistens entweder gar nicht oder nicht richtig zusammen, insbesondere dann nicht, wenn von KODI Mehrkanalsound oder sogar Passthrough ausgegeben wird. Die Entwicklung eines nativen Snapcast-Clients innerhalb von KODI wird gerade an verschiedenen Stellen diskutiert, z.B. [https://github.com/badaix/snapcast/issues/155 hier]. Bis dahin kann ein kleiner Workaround Abhilfe schaffen. Mit folgendem (nur rudimentär getesteten) [https://github.com/unimatrix27/snapcast/commit/88e42a2ecc8b44223701e18abb63af04b673b67b Hack] für den Snapcast-Client wird erreicht, dass der Client das ALSA-Device frei gibt, sobald er über den Server auf Mute gestellt wird. KODI selbst gibt das Device ebenfalls frei, wenn es im Zustand "Stop" ist. Bei dieser Lösung kann der Snapclient auf dem KODI-Rechner immer laufen gelassen werde. Es ist jedoch in der Verantwortung des Benutzers, den Client zu "muten". Vergisst er dies, wird ggf. die Wiedergabe in KODI nicht möglich sein.

Nach Abschluss der Snapcastkonfiguration und dem Starten von Server und den Clients empfiehlt es sich, die Android-App ebenfalls zu verwenden, da diese einen schnellen Überblick über den Zustand des Servers, der konfigurierten Streams und der Clients bietet.

=== Mopidy Konfiguration ===

In diesem Beispiel wird Mopidy als MPD-Ersatz verwendet, genau so gut kann aber auch direkt MPD verwendet werden. Die genauen Konfigurationsoptionen sind natürlich anders, und jeweils in entsprechenden Tutorials oder Dokumentationen beschrieben. Mopidy ist relativ umfangreich und modular aufgebaut, es bietet u.a. die Möglichkeit, neben lokal gespeicherten Dateien auch Dateien von verschiedenen, teilweise kommerziellen, Streamingdiensten abzuspielen. Die Detailkonfiguration all dieser Komponenten geht über diesen Artikel hinaus. Entscheidend hier ist die Konfiguration in einer Weise, so dass mehrere Mopidy-Instanzen gleichzeitig ausgeführt werden können und dann auf unterschiedlichen Ports zur Verfügung stehen.

Nach Installation von Mopidy findet sich die Konfiguration in der Datei ''/etc/mopidy/mopidy.cfg''. Mopidy unterstützt hierarische Konfigurationen, es reicht also, den für jede Instanz spezifischen Teil aus dieser allgemeinen Konfiguration zu entfernen und in jeweils eigene Dateien zu verschieben. In diesem Beispiel sollen das die Dateien ''/etc/mopidy/kind1.conf'' bis ''/etc/mopidy/kueche.conf'' sein. Die folgenden Zeilen gehören jeweils in diese 4 Dateien und werden dort entsprechend angepasst. Hier das Beispiel für Kind2:

<syntaxhighlight lang="bash">
[logging]
config_file = /etc/mopidy/logging_kind2.conf
debug_file = /var/log/mopidy/mopidy-debug_kind2.log

[audio]
output = audioresample ! audioconvert ! audio/x-raw,rate=48000,channels=2,format=S16LE ! pulsesink device=kind2 stream-properties="props,media.role=music"

[mpd]
enabled = true
hostname = 0.0.0.0
port=6601

[http]
enabled = true
hostname = 0.0.0.0
port=6681
zeroconf = Musik Kind2
</syntaxhighlight>

Im Audioteil wird der entsprechende Sink aus der Pulseaudiokonfiguration genommen. Die Angabe von stream-properties ermöglicht dem Duck-Modul den Stream als Musik zu erkennen und beim Abspielen von Announcements in der Lautstärke abzusenken. Beim MPD muss der Port für jede Instanz unterschiedlich sein, ebenso beim HTTP-Modul für die Weboberfläche der jeweiligen Instanz. Der Zerokonfname sollte auch eindeutig sein. Neben dieser Datei ist noch die dazu passende logging-Konfiguration anzulegen, hier also ''/etc/mopidy/logging_kind2.conf''. Dazu wird die Standarddatei kopiert und darin nur der Name der Logdatei angepasst.

Um nun auch die entsprechende Anzahl Instanzen automatisch zu starten, sind die entsprechenden Startdateien anzulegen. Dazu kann die Datei ''/etc/systemd/system/mopidy.cfg'' z.B. in ''/etc/systemd/system/mopidy_kind1.cfg'' umbenannt werden und dann 3 mal mit den Endungen der anderen Instanzen kopiert werden. Der Inhalt ist dann wie folgt:

<syntaxhighlight lang="bash">
[Unit]
Description=Mopidy_kind1
After=network.target sound.target

[Service]
EnvironmentFile=/etc/default/mopidy
ExecStart=/usr/bin/mopidy --quiet --config /etc/mopidy/kind1.conf

# allow MPD to use real-time priority 50
LimitRTPRIO=50
LimitRTTIME=infinity

# disallow writing to /usr, /bin, /sbin, ...
ProtectSystem=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Abschließend sollten die 4 Instanzen durch den Aufruf von <pre>systemctl enable mopidy_kind1</pre> usw. aktiviert werden. Es empfiehlt sich nach dem Start von Mopidy die korrekte Funtkionsweise mit dem [https://www.musicpd.org/clients/mpc/ MPC]-Client oder mit [http://rybczak.net/ncmpcpp/ NCMPCPP] auf der Konsole zu testen.

Hierbei sollte es dann bereits möglich sein, die Multiroom-Fähigkeiten von Snapcast mit Hilfe des Android-Clients von Snapcast zu testen und so auch festzustellen, dass die restliche Konfiguration von Snapcast und Pulseaudio korrekt sind.

=== FHEM ===

In FHEM sind nun in der ''fhem.cfg'' die entsprechenden Module einzurichten:
* Ein Snapcast-Modul im Server Modus
* Pro Raum ein Snapcast-Modul im Clientmodus
* Pro Raum ein MPD-Modul
* Pro Raum ein OpenMultiroom-Modul
* Optional pro Raum ein Text2Speech-Modul
* weitere Text2Speech-Module, falls man diese in Pulseaudio mit dem per Combine-Sink vorgesehen hat.

<syntaxhighlight lang="bash">
define scs.snap Snapcast

define scc.kind1 Snapcast client scs.snap b827eb9aec84
attr scc.kind1 constraintDummy freestring
attr scc.kind1 constraints standard|07:00 0 20:00 100 21:00 50 21:30 30 24:00 0,beforefree|07:00 0 21:00 100 22:00 50 23:00 30 24:00 0,beforeschool|07:00 0 08:30 50 20:00 100 21:00 50 21:30 30 24:00 0,free|07:00 0 08:30 50 21:00 100 22:00 50 23:00 30 24:00 0

define scc.kind2 Snapcast client scs.snap 025009413c29
attr scc.kind2 constraintDummy freestring
attr scc.kind2 constraints standard|07:00 0 20:15 100 20:30 50 24:00 0,beforefree|07:00 0 21:00 100 22:30 50 24:00 0,beforeschool|07:00 0 08:30 50 20:15 100 20:30 50 24:00 0,free|07:00 0 08:30 50 21:00 100 22:30 50 24:00 0

define scc.kueche Snapcast client scs.snap b827eb9a2ad3

define scc.wohn Snapcast client scs.snap 00aefa4aa3a9
</syntaxhighlight>

Oben zu sehen ist das define für das Server-Modul. Ohne Parameter verbindet sich mit localhost auf dem Standardport 1705. Es folgt die Definition von 2 Clients. Der erste Parameter "client" versetzt das Snapcastmodul in den Clientmodus. Der zweite Parameter verweist auf das Servermodul, der dritte Parameter ist die Client-ID. Diese besteht bei der aktuellen Snapcast-Version meistens aus der MAC-Adresse des Clients. Für die Kinder werden noch die Attribute constraintDummy ond constraints vergeben. Hiermit wird eine tagestyp- und tageszeitabhängige Lautstärkebegrenzung konfiguriert. Für die vier Tagestypen "standard", "beforefree", "beforeschool" und "free" wird ein jeweils anderes Lautstärkezeitprofil definiert.

Das Zeitprofil wird hier nach dem gleichen Muster wie die Temperaturlisten der Homematic-Thermostate, erklärt hier: [HomeMatic_Type_Thermostat]. Für den Tagestyp wird zusätzlich das Attribut constraintDummy verwendet. Es definiert, dass in dem Dummy "freestring" jeweils drin steht, welcher Tagestyp gerade ist. Diese Variable wirkt somit als Selektor auf die Liste der erlaubten Maximallautstärken. Wie eine solche Dummyvariable jeweils mit einem entsprechenden Wert befüllt werden kann, z.B. abhängig vom Wochentag, von Schulferien oder Feiertagen, wird hier nicht erläutert. Es ist auch möglich, nur ein Lautstärkeprofil anzugeben. Ohne dass ein Attribut constraintDummy gesetzt ist, verwendet das Snapcastmodul immer den Wert "standard". Wie man hier sehen kann, gibt es im Beispiel 4 Typen, hierbei fallen Freitage normalerweise in die Kategorie "beforefree" (es sind Tage, bevor dann frei ist, es kann also typischerweise länger und lauter Musik gehört werden), Samstage normalerweise in die Kategorie "free" und Sonntage in die Kategorie "beforeschool", ebenso landen dort Feiertage vor Schultagen usw.

<syntaxhighlight lang="bash">
define tts.wohn Text2Speech pulsewohn
attr tts.wohn TTS_FileTemplateDir /data/misc/announcements/
attr tts.wohn TTS_UseMP3Wrap true
attr tts.wohn TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120

define tts.kind1 Text2Speech pulsekind1
attr tts.kind1 TTS_FileTemplateDir /data/misc/announcements/
attr tts.kind1 TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kind1 TTS_UseMP3Wrap true

define tts.kind2 Text2Speech pulsekind2
attr tts.kind2 TTS_FileTemplateDir /data/misc/announcements/
attr tts.kind2 TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kind2 TTS_UseMP3Wrap true

define tts.kueche Text2Speech pulsekueche
attr tts.kueche TTS_FileTemplateDir /data/misc/announcements/
attr tts.kueche TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kueche TTS_UseMP3Wrap true

define tts.kinder Text2Speech pulsekinder
attr tts.kinder TTS_FileTemplateDir /data/misc/announcements/
attr tts.kinder TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kinder TTS_UseMP3Wrap true

define tts.unten Text2Speech pulseunten
attr tts.unten TTS_FileTemplateDir /data/misc/announcements/
attr tts.unten TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.unten TTS_UseMP3Wrap true

define tts.alle Text2Speech pulsealle
attr tts.alle TTS_FileTemplateDir /data/misc/announcements/
attr tts.alle TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.alle TTS_UseMP3Wrap true
</syntaxhighlight>
Hier sind die Definitionen der Text2Speech Module zu sehen (optional). Sie werden jeweils mit den in Pulseaudio definierten Sinks verbunden. Die Nutzung eines TemplateDirs ist ebenfalls optional, hier können bereits fertige MP3s verwendet werden, die dann anstelle der von der Google TTS API erzeugten Dateien benutzt werden. Dies können auch Bestätigungs und Fehlertöne sein, die bei Benutzern ohne Display, die rein mit Fernbedienung arbeiten, auf Fehlbedienungen etc. aufmerksam zu omrhen. Der Aufruf von mplayer wird noch modifiziert, um dafür zu sorgen, dass die Ausgabe bei Pulseaudio als media.role "announcement" eingehen. Dies wird dann vom duck-Modul erkannt, und führt dazu, dass die Lautstärke der ggf. ablaufenden Musik, etc. abgesenkt wird, so lange die tts-Ausgabe läuft.

<syntaxhighlight lang="bash">
define mpd.kind1 MPD 192.168.2.2 6600
attr mpd.kind1 player mopidy
attr mpd.kind1 bookmarkDir mpdstates
attr mpd.kind1 autoBookmark 1

define mpd.kind2 MPD 192.168.2.2 6702
attr mpd.kind2 player mopidy
attr mpd.kind2 bookmarkDir mpdstates
attr mpd.kind2 autoBookmark 1

define mpd.kueche MPD 192.168.2.2 6703
attr mpd.kueche player mopidy
attr mpd.kueche bookmarkDir mpdstates
attr mpd.kueche autoBookmark 1

define mpd.wohn MPD 192.168.2.2 6704
attr mpd.wohn player mopidy
attr mpd.wohn bookmarkDir mpdstates
attr mpd.wohn autoBookmark 1
</syntaxhighlight>
Pro laufender MPD oder Mopidy-Instanz wird ein MPD-Modul eingerichtet. Der Hostname und die Ports sind entsprechend anzupassen. Durch die bookmarkDir und autoBookmark - Attribute wird erreicht, dass der Zustand von Playlisten beim Wechsel derselben gespeichert und später wiederhergestellt werden kann. So lässt sich das Hören eines Hörbuchs unterbrechen, auf z.B. eine Radiostreamplayliste schalten, um dann später zur gleichen Stelle im Hörbuch zurückzukehren.

<syntaxhighlight lang="bash">
define omr.kind1 OpenMultiroom
attr omr.kind1 mr scc.kind1
attr omr.kind1 soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kind1 playlistPattern kind1
attr omr.kind1 ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kind1 defaultTts tts.kind1
attr omr.kind1 defaultStream kind1
attr omr.kind1 defaultSound mpd.kind1

define omr.kind2 OpenMultiroom
attr omr.kind2 mr scc.kind2
attr omr.kind2 soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kind2 playlistPattern kind2
attr omr.kind2 ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kind2 defaultTts tts.kind2
attr omr.kind2 defaultStream kind2
attr omr.kind2 defaultSound mpd.kind2

define omr.kueche OpenMultiroom
attr omr.kueche mr scc.kueche
attr omr.kueche soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kueche playlistPattern wohn
attr omr.kueche ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kueche defaultTts tts.kueche
attr omr.kueche defaultStream kueche
attr omr.kueche defaultSound mpd.kueche

define omr.wohn OpenMultiroom
attr omr.wohn mr scc.wohn
attr omr.wohn soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.wohn playlistPattern wohn
attr omr.wohn ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.wohn defaultTts tts.wohn
attr omr.wohn defaultStream wohn
attr omr.wohn defaultSound mpd.wohn
</syntaxhighlight>
Die Konfiguration der OpenMultiroom-Module schließt die Einrichtung von FHEM ab. Jede Instanz benötigt mindestens das "mr"- und das "soundMapping"-Attribut. Nur so kann sich das Modul mit den entsprechenden Snapcast und MPD-Modulen verbinden. Durch das "mr"-Attribut wird ein OpenMultiroom-Modul einem Snapcast-Client-Modul fest zugeordnet. Das Soundmapping ordnet die in Snapcast definierten Streams (siehe oben, Konfiguration vom Snapserver) den entsprechenden Instanzen des MPD-Moduls zu. Dadurch weiß FHEM, welcher MPD auf welchem Stream abspielt und kann je nachdem, welchem Stream ein Raum gerade zuhört, den dazu passenden MPD steuern und seine Readings durchreichen. Das OpenMultiroom-Modul bildet alle Readings des MPD-Moduls nochmal direkt ab. Wechselt ein Benutzer aber den Stream, dem er zuhört, aktualisieren sich auch alle Readings dementsprechend mit denen des dann aktuellen MPD-Moduls.

Das Attribut playlistPattern ist optional und sorgt dafür, dass beim Durchschalten der Playlists mit den Kommandos "channelUp" und "channelDown" nur diejenigen Playlists berücksichtigt werden, die auf das Pattern passen.

Analog zum soundMapping definiert das Attribut ttsMapping die Zuordnung der TTS-Module zu den Streams. Beim Ausgeben von Announcement kann so das OpenMultiroom-Modul ermitteln, auf welchem Stream welcher Raum gerade zuhört, und wo dementsprechend die TTS-Ausgaben zu erzeugen sind, damit sie auch in den gewünschten Räumen ankommen. Dieser Umweg ist zurzeit nötig, da ein Snapcast-Client nur auf einem einzigen Stream lauschen kann. Lauschen noch andere Clients auf demselben Stream, hören sie allerdings zwangsweise auch die Announcements.

Die 3 Default-Attribute legen fest, welche der TTS-Module, welcher Stream und welcher MPD dem entsprechenden Modul fest zugeordnet sind. Dies wird u.a. von einer Resetfunktion im Modul verwendet.

== Bedienung des OpenMultiroom-Moduls ==

=== set-Kommandos ===

=== Readings ===

=== Attribute ===

== Anbindung einer Fernbedienung an ein OpenMultiroom-Modul ==

=== Konfiguration von LIRC und IRExec ===

=== Zuordnung der Tasten: Beispiel ===

[[Category:Examples]]
[[Category:HOWTOS]]
[[Category:Unterhaltungselektronik]]

OpenMultiroom

2022-06-22T09:58:47Z

Beta-User: Typos

<div style="float:right">{{Infobox Modul
|ModPurpose=Steuern der einzelnen Multiroom-Systemkomponenten
|ModType=d
|ModCmdRef=OpenMultiroom
|ModForumArea=Multimedia
|ModTechName=98_OpenMultiroom.pm
|ModOwner=unimatrix
}}
{{Infobox Modul
|ModPurpose=Steuern eines Snapcast-Servers
|ModType=d
|ModCmdRef=Snapcast
|ModForumArea=Multimedia
|ModTechName=96_Snapcast.pm
|ModOwner=orphan/rudolphkoenig
}}
[[Datei:OpenMultiroomOverview.png|mini|400px|Schaubild des Zusammenspiels der einzelnen Komponenten eines Multiroomsystems mit den Backends {{Link2Forum|Topic=18517|LinkText=MPD}} und {{Link2Forum|Topic=62389|LinkText=Snapcast}} sowie der Nutzung von Text2Speech]]
</div>

Achtung: Das Modul ist noch sehr neu und bisher nur im {{Link2Forum|Topic=65785|LinkText=Forum}} bzw. auf dem [https://github.com/unimatrix27/fhemmodules/blob/master/98_OpenMultiroom.pm Github des Autors] verfügbar. Sobald alles stabil ist, wird es im SVN eingestellt.

'''OpenMultiroom''' ist ein Steuerungsmodul sowie auch ein Gesamtkonzept zur Realisierung eines Multiroom-Audio-Systems unter Nutzung von ausschließlich frei verfügbarer Software und ohne Bezug auf die Hardware eines bestimmten Herstellers. Es ist so ausgelegt, dass es prinzipiell flexibel bezüglich der Auswahl der Backendsysteme ist. Zurzeit ist es für die Nutzung mit [https://www.musicpd.org/ MPD] bzw. [https://www.mopidy.com/ Mopidy] und [https://github.com/badaix/snapcast Snapcast] implementiert. Daher wird in diesem WIKI-Eintrag immer von diesen Systemen gesprochen. Einen grundsätzlichen Überblick über das Konzept bietet das Schaubild.

== Grobe Übersicht des Funktionsumfangs der Gesamtlösung==
=== Features ===
* Integrierte Steuerung des Musikplayers über das [[MPD]]-Modul sowie des Multiroom-System {{Link2Forum|Topic=62389|LinkText=Snapcast}} in einem einzigen Modul
* Implementierung einer Schnittstelle gemäß [[DevelopmentGuidelinesAV]] als Basis für eine Visualisierung mit z.B. [[SmartVISU]] oder [[FHEM Tablet UI]]
* Synchrones Playback auf z.B. Raspberry Pi oder Android-Geräten (Snapcast-Feature)
* optionale Komprimierung der Soundübertragung als OGG oder FLAC (Snapcast-Feature)
* Möglichkeit der Bedienung völlig ohne Display über eine Fernbedienung und entsprechender Text2Speech Rückmeldung, insbesondere
** Durschalten von Playlisten mit entsprechenden Channel - Tasten unter Nutzung von raumspezifischen Filtern
** Forward und Rewind mit definierbaren Sprungweiten (implementiert direkt im [[MPD]]-Modul)
** Direktanwahl von Playlisten, Tracks oder Trackpositionen durch Zifferneingabe und anschließende Funktionstaste
** Abfrage von Statusinformationen durch Funktionstasten und Text2Speech Rückmeldungen
** Mithören in anderen Räumen und Übernahme des Playerzustandes anderer Räume durch Nutzung von Funktionstasten
** Einschlaftimer per Zifferneingabe oder per vordefinierten Zeitabständen, hierbei wird auch die Restlaufzeit des aktuellen Tracks angeboten.
* manuelles oder automatisches Speichern und Laden von Playlistbookmarks (implementiert direkt im [[MPD]]-Modul)
* Möglichkeit der Festlegung von tageszeit- und tagestypabhängigen Lautstärkebegrenzungen bis auf 0% z.B. für Kinderzimmer
* individuelles Verwalten von Playlisten für verschiedene Familienmitglieder
* Nutzung des Audiosystems für systemunabhängige FHEM-Announcements. Ein entsprechendes Announcement-Modul ist in Planung. Dabei können mehrere Räume gleichzeitig oder auch getrennt angesprochen werden

=== Anwendungszweck und Kurzbeschreibung der Funktionsweise ===
Wie der Name des Systems vermuten lässt, ist die Lösung vor allem dann sinnvoll einzusetzen, wenn Audiodateien in mindestens 2 verschiedenen Räumen oder "Zonen" sowohl synchron als auch unabhängig abgespielt werden soll und wenn hierzu eine komfortable und integrierte Steuerung über FHEM verwendet werden soll. Mit Einschränkungen ist die Lösung auch dann sinnvoll, wenn es nur um das Abspielen in einem Raum geht. Hier kann dann z.B. die Steuerung über eine Fernbedienung mit Hilfe des '''OpenMultiroom'''-Moduls genutzt werden, die über eine reine Nutzung des MPD-Moduls hinausgeht.

Für die Nutzung ist nicht zwingend ein zentraler Server notwendig. Diese Rolle kann auch von einem der Clients übernommen werden, z.B. einem Pi. Zur einfacheren Darstellung wird in diesem Eintrag jedoch immer von der Nutzung eines Servers ausgegangen, der nicht gleichzeitig auch Client ist.

Das Abspielen von Audio funktioniert prinzipiell in 2 Stufen:
# Nutzung von MPD oder einem MPD-kompatiblen Player zum direkten Abspielen von Sounddateien. Pro existierendem Raum gibt es mindestens eine Instanz von MPD. Hier wird davon ausgegangen, dass es genau eine Instanz pro Raum gibt. Jeder Raum hat also "seinen" MPD.
# Nutzung von Snapcast zur Verteilung des von MPD abgespielten Sounds an den entsprechenden Raum. Snapcast übernimmt hierbei die zeitliche Synchronisation

Durch das Modul '''OpenMultiroom''' steuert der Nutzer sowohl MPD als auch Snapcast. Für jeden Raum wird eine Instanz des Moduls definiert.

=== Verwendete Komponenten ===
Folgende Komponenten kommen zum Einsatz:

==== Server: ====
* MPD oder Mopidy oder ein anderer MPD-kompatibler Player. 1 Instanz pro Raum
* Snapserver
* mplayer (bei Nutzung von Text 2 Speech)
* Optional Pulseaudio (im System-Mode) bei Nutzung von Text 2 Speech oder erweiterten Konfigurationen. Hierbei wird Pulseaudio zwischen MPD und Snapcast geschaltet.
* Optional Anbindung an Subsonic oder Libresonic (hier zurzeit nicht beschrieben) zur Synchronisation von Playlisten uvm.
* FHEM: Modul 98_OpenMultiroom.pm
* FHEM: Modul 96_Snapcast.pm
* FHEM: Modul [[MPD|73_MPD.pm]]
* FHEM: Optional Modul 98_Text2Speech.pm

==== Client: ====
* Linux: Alsa oder Pulseaudio zur Soundwiedergabe
* Linux: Snapclient
* Android: Nur der Android Snapclient
* Webbrowser zur Steuerung per Visualisierung
* ggf. Infrarot oder Funkfernbedienung. In diesem Artikel wird das Beispiel anhand der Nutzung von X10-Funkfernbedienungen gezeigt, diese gibt es sehr günstig in der Bucht o.ä.
* Vision: Nutzung von Tastern und Display am PI oder Nutzung eines Steuergerätes mit Tastern und Display auf Basis eines Arduino mit WLAN, z.B. im alten Gehäuse eines Küchenradios usw.

== Aufbau anhand einer vollständigen Beispielkonfiguration ==

In diesem Artikel soll beispielhaft eine vollständige Konfiguration gezeigt werden. Jeder Nutzer muss diese Konfiguration an seine eigenen Bedürfnisse anpassen. Es seien folgende Komponenten vorhanden:

* Server mit Ubuntu 16.04, hier befindet sich eine MP3-Sammlung
* Kind1: Raspberry Pi Model 1 mit Raspbian
* Kind2: BananaPi mit Ubuntu, an diesem Pi ist auch ein X10 Empfänger angeschlossen, da er zentral im Haus positioniert ist
* Wohnzimmer: Raspberry Pi3 mit OSMC und KODI, wird primär zum Fernsehen verwendet
* Küche: Raspberry Pi Model 1 mit Raspbian

Anmerkung: Es ist möglich, mehrere Räume mit nur einem physikalischen Client zu bedienen. Hierbei werden auf einem Client mehrere Instanzen des Snapclients laufen gelassen. Der physikalische Client hat dann z.B. mehrere USB Soundkarten, dessen Audioausgänge in verschiedene Räume verkabelt sind. Dies wird hier zurzeit nicht näher beschrieben.

=== Pulseaudio Konfiguration ===
Will man Pulseaudio verwenden, z.B. um Text2Speech Nachrichten in laufende Musik einzublenden, sollte dieses am besten zuerst konfiguriert werden. Pulseaudio muss hierzu im System-Mode laufen. Dies ist auf einem Headless-Server kein Problem. Bei Ubuntu 16.10 wird dies durch folgenden Inhalt in ''/etc/systemd/system/pulseaudio.server'' erreicht:
<syntaxhighlight lang="bash">
[Unit]
Description=PA
After=network.target sound.target

[Service]
ExecStart=/usr/bin/pulseaudio --system

# allow MPD to use real-time priority 50
LimitRTPRIO=50
LimitRTTIME=infinity

# disallow writing to /usr, /bin, /sbin, ...
ProtectSystem=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>
Weiterhin ist der Befehl
<syntaxhighlight lang="bash">sudo systemctl enable pulseaudio</syntaxhighlight>
einzugeben, um Pulseaudio beim Systemstart automatisch zu starten.

Ausgehend von der Standardkonfiguration werden nun in ''/etc/pulse/system.pa'' die benötigten Module eingetragen
<syntaxhighlight lang="bash">
load-module module-pipe-sink file=/tmp/wohn.fifo sink_name=wohn
load-module module-pipe-sink file=/tmp/kind1.fifo sink_name=kind1
load-module module-pipe-sink file=/tmp/kind2.fifo sink_name=kind2
load-module module-pipe-sink file=/tmp/kueche.fifo sink_name=kueche

load-module module-combine-sink slaves=kind1,kind2 sink_name=kinder
load-module module-combine-sink slaves=wohn,kueche sink_name=unten
load-module module-combine-sink slaves=wohn,kueche,kind1,kind2 sink_name=alle

pactl load-module module-role-ducking trigger_roles=announcement ducking_roles=music
</syntaxhighlight>
Snapcast benötigt die Audioquelle in Form von FIFOs. Daher wird hier in den erstem 4 Zeilen je ein FIFO von Pulseaudio erzeugt. Der sink_name wird später bei der Konfiguration von MPD als Ausgang verwendet. In den 3 weiteren Zeilen werden noch 3 Sinks als Combine-Sinks erstellt. Diese erzeugen keine neuen FIFOs, sondern machen unter entsprechenden Sink-Namen eine vorgegebene Kombination von Räumen nach außen hin verfügbar. Der Sink "alle" kann also genutzt werden, um Audio auf allen 4 FIFOs gleichzeitig abzuspielen (und somit später potentiell in allen Räumen gleichzeitig). Dies kann für Announcements sinnvoll sein. Die Nutzung dieser Combine-Sinks ist optional. Ebenso optional ist das Laden des Ducking-Moduls am Ende. Das Ducking Modul führt dazu, dass Pulseaudio automatisch die Lautstärke der durch MPD abgespielten Tracks absenkt, wenn etwas über die Text2Speech-Module abgespielt wird. Ohne dies sind die Ausgaben speziell über die Google API unter Umständen nur schwer hörbar.

=== Snapcast Konfiguration ===
[https://github.com/badaix/snapcast Snapcast] muss entsprechend der Angaben auf der Webseite installiert werden. Auf dem Server muss logischerweise die Serverkomponente und auf den Clients die Clientkomponente installiert werden. Bei Android-Clients wird die auf der Webseite zur Verfügung gestellt APK installiert. Snapcast befindet sich selbst noch in fortlaufender Entwicklung. Die hier vorgestellte Lösung ist mit [https://github.com/badaix/snapcast/tree/98be8a58d945f84af50e40ebcf8a774592dd6e7b dieser Version] kompatibel und getestet.

Die Konfiguration des Servers beschränkt sich auf die Definition der Streams in ''/etc/default/snapserver''
<syntaxhighlight lang="bash">
START_SNAPSERVER=true
SNAPSERVER_OPTS="-d -s pipe:///tmp/kind1.fifo?name=kind1&mode=read -s pipe:///tmp/kind2.fifo?name=kind2&mode=read -s pipe:///tmp/wohn.fifo?name=wohn&mode=read -s pipe:///tmp/kueche.fifo?name=kueche&mode=read"
</syntaxhighlight>
Hier werden die 4 Streams erstellt, diese entsprechen vom Dateinamen her der Pulseaudiokonfiguration. Der hier verwendete Name kann später in FHEM oder auch im Android-Client angezeigt werden. Die Option <pre>mode=read</pre> ist wichtig, weil Pulseaudio meckert, wenn es die FIFO-Dateien nicht selbst anlegen darf.

Auf der Clientseite sieht die Datei ''/etc/default/snapclient'' dann so aus:
<syntaxhighlight lang="bash">
START_SNAPCLIENT=true
SNAPCLIENT_OPTS="-d -s dmix:CARD=Aureon51MkII,DEV=0"
</syntaxhighlight>
Den Server findet der Snapclient automatisch, er kann aber auch angegeben werden. Wie hier zu sehen kann ein spezielles Output-Device angegeben werden. Dies ist bei den PIs mit externer USB-Soundkarte meistens notwendig, da ansonsten der interne Sound genutzt würde. Eine Liste der verfügbaren Devices wird mit dem Aufruf von <pre>snapclient -l</pre> ausgegeben, hier muss dann das passende genommen werden. GGf. so lange ausprobieren, bis der Sound an der richtigen Stelle rauskommt.

In der hier betrachteten Konfiguration soll auf dem Wohnzimmer-PI ein Snapclient laufen, dieser wird aber normalerweise zum TV und Filme schauen mit KODI verwendet. Sowohl KODI als auch der Snapclient blockieren aber das ALSA-Device und funktionieren beide meistens entweder gar nicht oder nicht richtig zusammen, insbesondere dann nicht, wenn von KODI Mehrkanalsound oder sogar Passthrough ausgegeben wird. Die Entwicklung eines nativen Snapcast-Clients innerhalb von KODI wird gerade an verschiedenen Stellen diskutiert, z.B. [https://github.com/badaix/snapcast/issues/155 hier]. Bis dahin kann ein kleiner Workaround Abhilfe schaffen. Mit folgendem (nur rudimentär getesteten) [https://github.com/unimatrix27/snapcast/commit/88e42a2ecc8b44223701e18abb63af04b673b67b Hack] für den Snapcast-Client wird erreicht, dass der Client das ALSA-Device frei gibt, sobald er über den Server auf Mute gestellt wird. KODI selbst gibt das Device ebenfalls frei, wenn es im Zustand "Stop" ist. Bei dieser Lösung kann der Snapclient auf dem KODI-Rechner immer laufen gelassen werde. Es ist jedoch in der Verantwortung des Benutzers, den Client zu "muten". Vergisst er dies, wird ggf. die Wiedergabe in KODI nicht möglich sein.

Nach Abschluss der Snapcastkonfiguration und dem Starten von Server und den Clients empfiehlt es sich, die Android-App ebenfalls zu verwenden, da diese einen schnellen Überblick über den Zustand des Servers, der konfigurierten Streams und der Clients bietet.

=== Mopidy Konfiguration ===

In diesem Beispiel wird Mopidy als MPD-Ersatz verwendet, genau so gut kann aber auch direkt MPD verwendet werden. Die genauen Konfigurationsoptionen sind natürlich anders, und jeweils in entsprechenden Tutorials oder Dokumentationen beschrieben. Mopidy ist relativ umfangreich und modular aufgebaut, es bietet u.a. die Möglichkeit, neben lokal gespeicherten Dateien auch Dateien von verschiedenen, teilweise kommerziellen, Streamingdiensten abzuspielen. Die Detailkonfiguration all dieser Komponenten geht über diesen Artikel hinaus. Entscheidend hier ist die Konfiguration in einer Weise, so dass mehrere Mopidy-Instanzen gleichzeitig ausgeführt werden können und dann auf unterschiedlichen Ports zur Verfügung stehen.

Nach Installation von Mopidy findet sich die Konfiguration in der Datei ''/etc/mopidy/mopidy.cfg''. Mopidy unterstützt hierarische Konfigurationen, es reicht also, den für jede Instanz spezifischen Teil aus dieser allgemeinen Konfiguration zu entfernen und in jeweils eigene Dateien zu verschieben. In diesem Beispiel sollen das die Dateien ''/etc/mopidy/kind1.conf'' bis ''/etc/mopidy/kueche.conf'' sein. Die folgenden Zeilen gehören jeweils in diese 4 Dateien und werden dort entsprechend angepasst. Hier das Beispiel für Kind2:

<syntaxhighlight lang="bash">
[logging]
config_file = /etc/mopidy/logging_kind2.conf
debug_file = /var/log/mopidy/mopidy-debug_kind2.log

[audio]
output = audioresample ! audioconvert ! audio/x-raw,rate=48000,channels=2,format=S16LE ! pulsesink device=kind2 stream-properties="props,media.role=music"

[mpd]
enabled = true
hostname = 0.0.0.0
port=6601

[http]
enabled = true
hostname = 0.0.0.0
port=6681
zeroconf = Musik Kind2
</syntaxhighlight>

Im Audioteil wird der entsprechende Sink aus der Pulseaudiokonfiguration genommen. Die Angabe von stream-properties ermöglicht dem Duck-Modul den Stream als Musik zu erkennen und beim Abspielen von Announcements in der Lautstärke abzusenken. Beim MPD muss der Port für jede Instanz unterschiedlich sein, ebenso beim HTTP-Modul für die Weboberfläche der jeweiligen Instanz. Der Zerokonfname sollte auch eindeutig sein. Neben dieser Datei ist noch die dazu passende logging-Konfiguration anzulegen, hier also ''/etc/mopidy/logging_kind2.conf''. Dazu wird die Standarddatei kopiert und darin nur der Name der Logdatei angepasst.

Um nun auch die entsprechende Anzahl Instanzen automatisch zu starten, sind die entsprechenden Startdateien anzulegen. Dazu kann die Datei ''/etc/systemd/system/mopidy.cfg'' z.B. in ''/etc/systemd/system/mopidy_kind1.cfg'' umbenannt werden und dann 3 mal mit den Endungen der anderen Instanzen kopiert werden. Der Inhalt ist dann wie folgt:

<syntaxhighlight lang="bash">
[Unit]
Description=Mopidy_kind1
After=network.target sound.target

[Service]
EnvironmentFile=/etc/default/mopidy
ExecStart=/usr/bin/mopidy --quiet --config /etc/mopidy/kind1.conf

# allow MPD to use real-time priority 50
LimitRTPRIO=50
LimitRTTIME=infinity

# disallow writing to /usr, /bin, /sbin, ...
ProtectSystem=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Abschließend sollten die 4 Instanzen durch den Aufruf von <pre>systemctl enable mopidy_kind1</pre> usw. aktiviert werden. Es empfiehlt sich nach dem Start von Mopidy die korrekte Funtkionsweise mit dem [https://www.musicpd.org/clients/mpc/ MPC]-Client oder mit [http://rybczak.net/ncmpcpp/ NCMPCPP] auf der Konsole zu testen.

Hierbei sollte es dann bereits möglich sein, die Multiroom-Fähigkeiten von Snapcast mit Hilfe des Android-Clients von Snapcast zu testen und so auch festzustellen, dass die restliche Konfiguration von Snapcast und Pulseaudio korrekt sind.

=== FHEM ===

In FHEM sind nun in der ''fhem.cfg'' die entsprechenden Module einzurichten:
* Ein Snapcast-Modul im Server Modus
* Pro Raum ein Snapcast-Modul im Clientmodus
* Pro Raum ein MPD-Modul
* Pro Raum ein OpenMultiroom-Modul
* Optional pro Raum ein Text2Speech-Modul
* weitere Text2Speech-Module, falls man diese in Pulseaudio mit dem per Combine-Sink vorgesehen hat.

<syntaxhighlight lang="bash">
define scs.snap Snapcast

define scc.kind1 Snapcast client scs.snap b827eb9aec84
attr scc.kind1 constraintDummy freestring
attr scc.kind1 constraints standard|07:00 0 20:00 100 21:00 50 21:30 30 24:00 0,beforefree|07:00 0 21:00 100 22:00 50 23:00 30 24:00 0,beforeschool|07:00 0 08:30 50 20:00 100 21:00 50 21:30 30 24:00 0,free|07:00 0 08:30 50 21:00 100 22:00 50 23:00 30 24:00 0

define scc.kind2 Snapcast client scs.snap 025009413c29
attr scc.kind2 constraintDummy freestring
attr scc.kind2 constraints standard|07:00 0 20:15 100 20:30 50 24:00 0,beforefree|07:00 0 21:00 100 22:30 50 24:00 0,beforeschool|07:00 0 08:30 50 20:15 100 20:30 50 24:00 0,free|07:00 0 08:30 50 21:00 100 22:30 50 24:00 0

define scc.kueche Snapcast client scs.snap b827eb9a2ad3

define scc.wohn Snapcast client scs.snap 00aefa4aa3a9
</syntaxhighlight>

Oben zu sehen ist das define für das Server-Modul. Ohne Parameter verbindet sich mit localhost auf dem Standardport 1705. Es folgt die Definition von 2 Clients. Der erste Parameter "client" versetzt das Snapcastmodul in den Clientmodus. Der zweite Parameter verweist auf das Servermodul, der dritte Parameter ist die Client-ID. Diese besteht bei der aktuellen Snapcast-Version meistens aus der MAC-Adresse des Clients. Für die Kinder werden noch die Attribute constraintDummy ond constraints vergeben. Hiermit wird eine tagestyp- und tageszeitabhängige Lautstärkebegrenzung konfiguriert. Für die vier Tagestypen "standard", "beforefree", "beforeschool" und "free" wird ein jeweils anderes Lautstärkezeitprofil definiert.

Das Zeitprofil wird hier nach dem gleichen Muster wie die Temperaturlisten der Homematic-Thermostate, erklärt hier: [HomeMatic_Type_Thermostat]. Für den Tagestyp wird zusätzlich das Attribut constraintDummy verwendet. Es definiert, dass in dem Dummy "freestring" jeweils drin steht, welcher Tagestyp gerade ist. Diese Variable wirkt somit als Selektor auf die Liste der erlaubten Maximallautstärken. Wie eine solche Dummyvariable jeweils mit einem entsprechenden Wert befüllt werden kann, z.B. abhängig vom Wochentag, von Schulferien oder Feiertagen, wird hier nicht erläutert. Es ist auch möglich, nur ein Lautstärkeprofil anzugeben. Ohne dass ein Attribut constraintDummy gesetzt ist, verwendet das Snapcastmodul immer den Wert "standard". Wie man hier sehen kann, gibt es im Beispiel 4 Typen, hierbei fallen Freitage normalerweise in die Kategorie "beforefree" (es sind Tage, bevor dann frei ist, es kann also typischerweise länger und lauter Musik gehört werden), Samstage normalerweise in die Kategorie "free" und Sonntage in die Kategorie "beforeschool", ebenso landen dort Feiertage vor Schultagen usw.

<syntaxhighlight lang="bash">
define tts.wohn Text2Speech pulsewohn
attr tts.wohn TTS_FileTemplateDir /data/misc/announcements/
attr tts.wohn TTS_UseMP3Wrap true
attr tts.wohn TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120

define tts.kind1 Text2Speech pulsekind1
attr tts.kind1 TTS_FileTemplateDir /data/misc/announcements/
attr tts.kind1 TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kind1 TTS_UseMP3Wrap true

define tts.kind2 Text2Speech pulsekind2
attr tts.kind2 TTS_FileTemplateDir /data/misc/announcements/
attr tts.kind2 TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kind2 TTS_UseMP3Wrap true

define tts.kueche Text2Speech pulsekueche
attr tts.kueche TTS_FileTemplateDir /data/misc/announcements/
attr tts.kueche TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kueche TTS_UseMP3Wrap true

define tts.kinder Text2Speech pulsekinder
attr tts.kinder TTS_FileTemplateDir /data/misc/announcements/
attr tts.kinder TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kinder TTS_UseMP3Wrap true

define tts.unten Text2Speech pulseunten
attr tts.unten TTS_FileTemplateDir /data/misc/announcements/
attr tts.unten TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.unten TTS_UseMP3Wrap true

define tts.alle Text2Speech pulsealle
attr tts.alle TTS_FileTemplateDir /data/misc/announcements/
attr tts.alle TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.alle TTS_UseMP3Wrap true
</syntaxhighlight>
Hier sind die Definitionen der Text2Speech Module zu sehen (optional). Sie werden jeweils mit den in Pulseaudio definierten Sinks verbunden. Die Nutzung eines TemplateDirs ist ebenfalls optional, hier können bereits fertige MP3s verwendet werden, die dann anstelle der von der Google TTS API erzeugten Dateien benutzt werden. Dies können auch Bestätigungs und Fehlertöne sein, die bei Benutzern ohne Display, die rein mit Fernbedienung arbeiten, auf Fehlbedienungen etc. aufmerksam zu omrhen. Der Aufruf von mplayer wird noch modifiziert, um dafür zu sorgen, dass die Ausgabe bei Pulseaudio als media.role "announcement" eingehen. Dies wird dann vom duck-Modul erkannt, und führt dazu, dass die Lautstärke der ggf. ablaufenden Musik, etc. abgesenkt wird, so lange die tts-Ausgabe läuft.

<syntaxhighlight lang="bash">
define mpd.kind1 MPD 192.168.2.2 6600
attr mpd.kind1 player mopidy
attr mpd.kind1 bookmarkDir mpdstates
attr mpd.kind1 autoBookmark 1

define mpd.kind2 MPD 192.168.2.2 6702
attr mpd.kind2 player mopidy
attr mpd.kind2 bookmarkDir mpdstates
attr mpd.kind2 autoBookmark 1

define mpd.kueche MPD 192.168.2.2 6703
attr mpd.kueche player mopidy
attr mpd.kueche bookmarkDir mpdstates
attr mpd.kueche autoBookmark 1

define mpd.wohn MPD 192.168.2.2 6704
attr mpd.wohn player mopidy
attr mpd.wohn bookmarkDir mpdstates
attr mpd.wohn autoBookmark 1
</syntaxhighlight>
Pro laufender MPD oder Mopidy-Instanz wird ein MPD-Modul eingerichtet. Der Hostname und die Ports sind entsprechend anzupassen. Durch die bookmarkDir und autoBookmark - Attribute wird erreicht, dass der Zustand von Playlisten beim Wechsel derselben gespeichert und später wiederhergestellt werden kann. So lässt sich das Hören eines Hörbuchs unterbrechen, auf z.B. eine Radiostreamplayliste schalten, um dann später zur gleichen Stelle im Hörbuch zurückzukehren.

<syntaxhighlight lang="bash">
define omr.kind1 OpenMultiroom
attr omr.kind1 mr scc.kind1
attr omr.kind1 soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kind1 playlistPattern kind1
attr omr.kind1 ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kind1 defaultTts tts.kind1
attr omr.kind1 defaultStream kind1
attr omr.kind1 defaultSound mpd.kind1

define omr.kind2 OpenMultiroom
attr omr.kind2 mr scc.kind2
attr omr.kind2 soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kind2 playlistPattern kind2
attr omr.kind2 ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kind2 defaultTts tts.kind2
attr omr.kind2 defaultStream kind2
attr omr.kind2 defaultSound mpd.kind2

define omr.kueche OpenMultiroom
attr omr.kueche mr scc.kueche
attr omr.kueche soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kueche playlistPattern wohn
attr omr.kueche ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kueche defaultTts tts.kueche
attr omr.kueche defaultStream kueche
attr omr.kueche defaultSound mpd.kueche

define omr.wohn OpenMultiroom
attr omr.wohn mr scc.wohn
attr omr.wohn soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.wohn playlistPattern wohn
attr omr.wohn ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.wohn defaultTts tts.wohn
attr omr.wohn defaultStream wohn
attr omr.wohn defaultSound mpd.wohn
</syntaxhighlight>
Die Konfiguration der OpenMultiroom-Module schließt die Einrichtung von FHEM ab. Jede Instanz benötigt mindestens das "mr"- und das "soundMapping"-Attribut. Nur so kann sich das Modul mit den entsprechenden Snapcast und MPD-Modulen verbinden. Durch das "mr"-Attribut wird ein OpenMultiroom-Modul einem Snapcast-Client-Modul fest zugeordnet. Das Soundmapping ordnet die in Snapcast definierten Streams (siehe oben, Konfiguration vom Snapserver) den entsprechenden Instanzen des MPD-Moduls zu. Dadurch weiß FHEM, welcher MPD auf welchem Stream abspielt und kann je nachdem, welchem Stream ein Raum gerade zuhört, den dazu passenden MPD steuern und seine Readings durchreichen. Das OpenMultiroom-Modul bildet alle Readings des MPD-Moduls nochmal direkt ab. Wechselt ein Benutzer aber den Stream, dem er zuhört, aktualisieren sich auch alle Readings dementsprechend mit denen des dann aktuellen MPD-Moduls.

Das Attribut playlistPattern ist optional und sorgt dafür, dass beim Durchschalten der Playlists mit den Kommandos "channelUp" und "channelDown" nur diejenigen Playlists berücksichtigt werden, die auf das Pattern passen.

Analog zum soundMapping definiert das Attribut ttsMapping die Zuordnung der TTS-Module zu den Streams. Beim Ausgeben von Announcement kann so das OpenMultiroom-Modul ermitteln, auf welchem Stream welcher Raum gerade zuhört, und wo dementsprechend die TTS-Ausgaben zu erzeugen sind, damit sie auch in den gewünschten Räumen ankommen. Dieser Umweg ist zurzeit nötig, da ein Snapcast-Client nur auf einem einzigen Stream lauschen kann. Lauschen noch andere Clients auf demselben Stream, hören sie allerdings zwangsweise auch die Announcements.

Die 3 Default-Attribute legen fest, welche der TTS-Module, welcher Stream und welcher MPD dem entsprechenden Modul fest zugeordnet sind. Dies wird u.a. von einer Resetfunktion im Modul verwendet.

== Bedienung des OpenMultiroom-Moduls ==

=== set-Kommandos ===

=== Readings ===

=== Attribute ===

== Anbindung einer Fernbedienung an ein OpenMultiroom-Modul ==

=== Konfiguration von LIRC und IRExec ===

=== Zuordnung der Tasten: Beispiel ===

[[Category:Examples]]
[[Category:HOWTOS]]
[[Category:Unterhaltungselektronik]]

OpenMultiroom

2022-06-21T12:05:49Z

Beta-User: maintainer update; links ergänzt

<div style="float:right">{{Infobox Modul
|ModPurpose=Steuern der einzelnen Multiroom-Systemkomponenten
|ModType=d
|ModCmdRef=OpenMultiroom
|ModForumArea=Multimedia
|ModTechName=98_OpenMultiroom.pm
|ModOwner=unimatrix
}}
{{Infobox Modul
|ModPurpose=Steuern eines Snapcast-Servers
|ModType=d
|ModCmdRef=Snapcast
|ModForumArea=Multimedia
|ModTechName=96_Snapcast.pm
|ModOwner=orphan/rudolphkoenig
}}
[[Datei:OpenMultiroomOverview.png|mini|400px|Schaubild des Zusammenspiels der einzelnen Komponenten eines Multiroomsystems mit den Backends {{Link2Forum|Topic=18517|LinkText=MPD}} und {{Link2Forum|Topic=62389|LinkText=Snapcast}} sowie der Nutzung von Text2Speech]]
</div>

Achtung: Das Modul ist noch sehr neu und bisher nur im {{Link2Forum|Topic=65785|LinkText=Forum}} bzw. auf dem [https://github.com/unimatrix27/fhemmodules/blob/master/98_OpenMultiroom.pm Github des Autors] verfügbar. Sobald alles stabil ist, wird es im SVN eingestellt.

'''OpenMultiroom''' ist ein Steuerungsmodul sowie auch ein Gesamtkonzept zur Realisierung eines Multiroom-Audio-Systems unter Nutzung von ausschließlich frei verfügbarer Software und ohne Bezug auf die Hardware eines bestimmten Herstellers. Es ist so ausgelegt, dass es prinzipiell flexibel bezüglich der Auswahl der Backendsysteme ist. Zurzeit ist es für die Nutzung mit [https://www.musicpd.org/ MPD] bzw. [https://www.mopidy.com/ Mopidy] und [https://github.com/badaix/snapcast Snapcast] implementiert. Daher wird in diesem WIKI-Eintrag immer von diesen Systemen gesprochen. Einen grundsätzlichen Überblick über das Konzept bietet das Schaubild.

== Grobe Übersicht des Funktionsumfangs der Gesamtlösung==
=== Features ===
* Integrierte Steuerung des Musikplayers über das [[MPD]]-Modul sowie des Multiroom-System {{Link2Forum|Topic=62389|LinkText=Snapcast}} in einem einzigen Modul
* Implementierung einer Schnittstelle gemäß [[DevelopmentGuidelinesAV]] als Basis für eine Visualisierung mit z.B. [[SmartVISU]] oder [[FHEM Tablet UI]]
* Synchrones Playback auf z.B. Raspberry Pi oder Android-Geräten (Snapcast-Feature)
* optionale Komprimierung der Soundübertragung als OGG oder FLAC (Snapcast-Feature)
* Möglichkeit der Bedienung völlig ohne Display über eine Fernbedienung und entsprechender Text2Speech Rückmeldung, insbesondere
** Durschalten von Playlisten mit entsprechenden Channel - Tasten unter Nutzung von raumspezifischen Filtern
** Forward und Rewind mit definierbaren Sprungweiten (implementiert direkt im [[MPD]]-Modul)
** Direktanwahl von Playlisten, Tracks oder Trackpositionen durch Zifferneingabe und anschließende Funktionstaste
** Abfrage von Statusinformationen durch Funktionstasten und Text2Speech Rückmeldungen
** Mithören in anderen Räumen und Übernahme des Playerzustandes anderer Räume durch Nutzung von Funktionstasten
** Einschlaftimer per Zifferneingabe oder per vordefinierten Zeitabständen, hierbei wird auch die Restlaufzeit des aktuellen Tracks angeboten.
* manuelles oder automatisches Speichern und Laden von Playlistbookmarks (implementiert direkt im [[MPD]]-Modul)
* Möglichkeit der Festlegung von tageszeit- und tagestypabhängigen Lautstärkebegrenzungen bis auf 0% z.B. für Kinderzimmer
* individuelles Verwalten von Playlisten für verschiedene Familienmitglieder
* Nutzung des Audiosystems für systemunabhängige FHEM-Announcements. Ein entsprechendes Announcement-Modul ist in Planung. Dabei können mehrere Räume gleichzeitig oder auch getrennt angesprochen werden

=== Anwendungszweck und Kurzbeschreibung der Funktionsweise ===
Wie der Name des Systems vermuten lässt, ist die Lösung vor allem dann sinnvoll einzusetzen, wenn Audiodateien in mindestens 2 verschiedenen Räumen oder "Zonen" sowohl synchron als auch unabhängig abgespielt werden soll und wenn hierzu eine komfortable und integrierte Steuerung über FHEM verwendet werden soll. Mit Einschränkungen ist die Lösung auch dann sinnvoll, wenn es nur um das Abspielen in einem Raum geht. Hier kann dann z.B. die Steuerung über eine Fernbedienung mit Hilfe des '''OpenMultiroom'''-Moduls genutzt werden, die über eine reine Nutzung des MPD-Moduls hinausgeht.

Für die Nutzung ist nicht zwingend ein zentraler Server notwendig. Diese Rolle kann auch von einem der Clients übernommen werden, z.B. einem Pi. Zur einfacheren Darstellung wird in diesem Eintrag jedoch immer von der Nutzung eines Servers ausgegangen, der nicht gleichzeitig auch Client ist.

Das Abspielen von Audio funktioniert prinzipiell in 2 Stufen:
# Nutzung von MPD oder einem MPD-kompatiblen Player zum direkten Abspielen von Sounddateien. Pro existierendem Raum gibt es mindestens eine Instanz von MPD. Hier wird davon ausgegangen, dass es genau eine Instanz pro Raum gibt. Jeder Raum hat also "seinen" MPD.
# Nutzung von Snapcast zur Verteilung des von MPD abgespielten Sounds an den entsprechenden Raum. Snapcast übernimmt hierbei die zeitliche Synchronisation

Durch das Modul '''OpenMultiroom''' steuert der Nutzer sowohl MPD als auch Snapcast. Für jeden Raum wird eine Instanz des Moduls definiert.

=== Verwendete Komponenten ===
Folgende Komponenten kommen zum Einsatz:

==== Server: ====
* MPD oder Mopidy oder ein anderer MPD-kompatibler Player. 1 Instanz pro Raum
* Snapserver
* mplayer (bei Nutzung von Text 2 Speech)
* Optional Pulseaudio (im System-Mode) bei Nutzung von Text 2 Speech oder erweiterten Konfigurationen. Hierbei wird Pulseaudio zwischen MPD und Snapcast geschaltet.
* Optional Anbindung an Subsonic oder Libresonic (hier zurzeit nicht beschrieben) zur Synchronisation von Playlisten uvm.
* FHEM: Modul 98_OpenMultiroom.pm
* FHEM: Modul 96_Snapcast.pm
* FHEM: Modul [[MPD|73_MPD.pm]]
* FHEM: Optional Modul 98_Text2Speech.pm

==== Client: ====
* Linux: Alsa oder Pulseaudio zur Soundwiedergabe
* Linux: Snapclient
* Android: Nur der Android Snapclient
* Webbrowser zur Steuerung per Visualisierung
* ggf. Infrarot oder Funkfernbedienung. In diesem Artikel wird das Beispiel anhand der Nutzung von X10-Funkfernbedienungen gezeigt, diese gibt es sehr günstig in der Bucht o.ä.
* Vision: Nutzung von Tastern und Display am PI oder Nutzung eines Steuergerätes mit Tastern und Display auf Basis eines Arduino mit WLAN, z.B. im alten Gehäuse eines Küchenradios usw.

== Aufbau anhand einer vollständigen Beispielkonfiguration ==

In diesem Artikel soll beispielhaft eine vollständige Konfiguration gezeigt werden. Jeder Nutzer muss diese Konfiguration an seine eigenen Bedürfnisse anpassen. Es seien folgende Komponenten vorhanden:

* Server mit Ubuntu 16.04, hier befindet sich eine MP3-Sammlung
* Kind1: Raspberry Pi Model 1 mit Raspbian
* Kind2: BananaPi mit Ubuntu, an diesem Pi ist auch ein X10 Empfänger angeschlossen, da er zentral im Haus positioniert ist
* Wohnzimmer: Raspberry Pi3 mit OSMC und KODI, wird primär zum Fernsehen verwendet
* Küche: Raspberry Pi Model 1 mit Raspbian

Anmerkung: Es ist möglich, mehrere Räume mit nur einem physikalischen Client zu bedienen. Hierbei werden auf einem Client mehrere Instanzen des Snapclients laufen gelassen. Der physikalische Client hat dann z.B. mehrere USB Soundkarten, dessen Audioausgänge in verschiedene Räume verkabelt sind. Dies wird hier zurzeit nicht näher beschrieben.

=== Pulseaudio Konfiguration ===
Will man Pulseaudio verwenden, z.B. um Text2Speech Nachrichten in laufende Musik einzublenden, sollte dieses am besten zuerst konfiguriert werden. Pulseaudio muss hierzu im System-Mode laufen. Dies ist auf einem Headless-Server kein Problem. Bei Ubuntu 16.10 wird dies durch folgenden Inhalt in ''/etc/systemd/system/pulseaudio.server'' erreicht:
<syntaxhighlight lang="bash">
[Unit]
Description=PA
After=network.target sound.target

[Service]
ExecStart=/usr/bin/pulseaudio --system

# allow MPD to use real-time priority 50
LimitRTPRIO=50
LimitRTTIME=infinity

# disallow writing to /usr, /bin, /sbin, ...
ProtectSystem=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>
Weiterhin ist der Befehl
<syntaxhighlight lang="bash">sudo systemctl enable pulseaudio</syntaxhighlight>
einzugeben, um Pulseaudio beim Systemstart automatisch zu starten.

Ausgehend von der Standardkonfiguration werden nun in ''/etc/pulse/system.pa'' die benötigten Module eingetragen
<syntaxhighlight lang="bash">
load-module module-pipe-sink file=/tmp/wohn.fifo sink_name=wohn
load-module module-pipe-sink file=/tmp/kind1.fifo sink_name=kind1
load-module module-pipe-sink file=/tmp/kind2.fifo sink_name=kind2
load-module module-pipe-sink file=/tmp/kueche.fifo sink_name=kueche

load-module module-combine-sink slaves=kind1,kind2 sink_name=kinder
load-module module-combine-sink slaves=wohn,kueche sink_name=unten
load-module module-combine-sink slaves=wohn,kueche,kind1,kind2 sink_name=alle

pactl load-module module-role-ducking trigger_roles=announcement ducking_roles=music
</syntaxhighlight>
Snapcast benötigt die Audioquelle in Form von FIFOs. Daher wird hier in den erstem 4 Zeilen je ein FIFO von Pulseaudio erzeugt. Der sink_name wird später bei der Konfiguration von MPD als Ausgang verwendet. In den 3 weiteren Zeilen werden noch 3 Sinks als Combine-Sinks erstellt. Diese erzeugen keine neuen FIFOs, sondern omrhen under entsprechenden Sink-Namen eine vorgegebene Kombination von Räumen nach außen hin verfügbar. Der Sink "alle" kann also genutzt werden, um Audio auf allen 4 FIFOs gleichzeitig abzuspielen (und somit später potentiall in allen Räumen gleichzeitig). Dies kann für Announcements sinnvoll sein. Die Nutzung dieser Combine-Sinks ist optional. Ebenso optional ist das Laden des Ducking-Moduls am Ende. Das Ducking Modul führt dazu, dass Pulseaudio automatisch die Lautstärke der durch MPD abgespielten Tracks absenkt, wenn etwas über die Text2Speech-Module abgespielt wird. Ohne dies sind die Ausgaben speziell über die Google API unter Umständen nur schwer hörbar.

=== Snapcast Konfiguration ===
[https://github.com/badaix/snapcast Snapcast] muss entsprechend der Angaben auf der Webseite installiert werden. Auf dem Server muss logischerweise die Serverkomponente und auf den Clients die Clientkomponente installiert werden. Bei Android-Clients wird die auf der Webseite zur Verfügung gestellt APK installiert. Snapcast befindet sich selbst noch in fortlaufender Entwicklung. Die hier vorgestellte Lösung ist mit [https://github.com/badaix/snapcast/tree/98be8a58d945f84af50e40ebcf8a774592dd6e7b dieser Version] kompatibel und getestet.

Die Konfiguration des Servers beschränkt sich auf die Definition der Streams in ''/etc/default/snapserver''
<syntaxhighlight lang="bash">
START_SNAPSERVER=true
SNAPSERVER_OPTS="-d -s pipe:///tmp/kind1.fifo?name=kind1&mode=read -s pipe:///tmp/kind2.fifo?name=kind2&mode=read -s pipe:///tmp/wohn.fifo?name=wohn&mode=read -s pipe:///tmp/kueche.fifo?name=kueche&mode=read"
</syntaxhighlight>
Hier werden die 4 Streams erstellt, diese entsprechen vom Dateinamen her der Pulseaudiokonfiguration. Der hier verwendete Name kann später in FHEM oder auch im Android-Client angezeigt werden. Die Option <pre>mode=read</pre> ist wichtig, weil Pulseaudio meckert, wenn es die FIFO-Dateien nicht selbst anlegen darf.

Auf der Clientseite sieht die Datei ''/etc/default/snapclient'' dann so aus:
<syntaxhighlight lang="bash">
START_SNAPCLIENT=true
SNAPCLIENT_OPTS="-d -s dmix:CARD=Aureon51MkII,DEV=0"
</syntaxhighlight>
Den Server findet der Snapclient automatisch, er kann aber auch angegeben werden. Wie hier zu sehen kann ein spezielles Output-Device angegeben werden. Dies ist bei den PIs mit externer USB-Soundkarte meistens notwendig, da ansonsten der interne Sound genutzt würde. Eine Liste der verfügbaren Devices wird mit dem Aufruf von <pre>snapclient -l</pre> ausgegeben, hier muss dann das passende genommen werden. GGf. so lange ausprobieren, bis der Sound an der richtigen Stelle rauskommt.

In der hier betrachteten Konfiguration soll auf dem Wohnzimmer-PI ein Snapclient laufen, dieser wird aber normalerweise zum TV und Filme schauen mit KODI verwendet. Sowohl KODI als auch der Snapclient blockieren aber das ALSA-Device und funktionieren beide meistens entweder gar nicht oder nicht richtig zusammen, insbesondere dann nicht, wenn von KODI Mehrkanalsound oder sogar Passthrough ausgegeben wird. Die Entwicklung eines nativen Snapcast-Clients innerhalb von KODI wird gerade an verschiedenen Stellen diskutiert, z.B. [https://github.com/badaix/snapcast/issues/155 hier]. Bis dahin kann ein kleiner Workaround Abhilfe schaffen. Mit folgendem (nur rudimentär getesteten) [https://github.com/unimatrix27/snapcast/commit/88e42a2ecc8b44223701e18abb63af04b673b67b Hack] für den Snapcast-Client wird erreicht, dass der Client das ALSA-Device frei gibt, sobald er über den Server auf Mute gestellt wird. KODI selbst gibt das Device ebenfalls frei, wenn es im Zustand "Stop" ist. Bei dieser Lösung kann der Snapclient auf dem KODI-Rechner immer laufen gelassen werde. Es ist jedoch in der Verantwortung des Benutzers, den Client zu "muten". Vergisst er dies, wird ggf. die Wiedergabe in KODI nicht möglich sein.

Nach Abschluss der Snapcastkonfiguration und dem Starten von Server und den Clients empfiehlt es sich, die Android-App ebenfalls zu verwenden, da diese einen schnellen Überblick über den Zustand des Servers, der konfigurierten Streams und der Clients bietet.

=== Mopidy Konfiguration ===

In diesem Beispiel wird Mopidy als MPD-Ersatz verwendet, genau so gut kann aber auch direkt MPD verwendet werden. Die genauen Konfigurationsoptionen sind natürlich anders, und jeweils in entsprechenden Tutorials oder Dokumentationen beschrieben. Mopidy ist relativ umfangreich und modular aufgebaut, es bietet u.a. die Möglichkeit, neben lokal gespeicherten Dateien auch Dateien von verschiedenen, teilweise kommerziellen, Streamingdiensten abzuspielen. Die Detailkonfiguration all dieser Komponenten geht über diesen Artikel hinaus. Entscheidend hier ist die Konfiguration in einer Weise, so dass mehrere Mopidy-Instanzen gleichzeitig ausgeführt werden können und dann auf unterschiedlichen Ports zur Verfügung stehen.

Nach Installation von Mopidy findet sich die Konfiguration in der Datei ''/etc/mopidy/mopidy.cfg''. Mopidy unterstützt hierarische Konfigurationen, es reicht also, den für jede Instanz spezifischen Teil aus dieser allgemeinen Konfiguration zu entfernen und in jeweils eigene Dateien zu verschieben. In diesem Beispiel sollen das die Dateien ''/etc/mopidy/kind1.conf'' bis ''/etc/mopidy/kueche.conf'' sein. Die folgenden Zeilen gehören jeweils in diese 4 Dateien und werden dort entsprechend angepasst. Hier das Beispiel für Kind2:

<syntaxhighlight lang="bash">
[logging]
config_file = /etc/mopidy/logging_kind2.conf
debug_file = /var/log/mopidy/mopidy-debug_kind2.log

[audio]
output = audioresample ! audioconvert ! audio/x-raw,rate=48000,channels=2,format=S16LE ! pulsesink device=kind2 stream-properties="props,media.role=music"

[mpd]
enabled = true
hostname = 0.0.0.0
port=6601

[http]
enabled = true
hostname = 0.0.0.0
port=6681
zeroconf = Musik Kind2
</syntaxhighlight>

Im Audioteil wird der entsprechende Sink aus der Pulseaudiokonfiguration genommen. Die Angabe von stream-properties ermöglicht dem Duck-Modul den Stream als Musik zu erkennen und beim Abspielen von Announcements in der Lautstärke abzusenken. Beim MPD muss der Port für jede Instanz unterschiedlich sein, ebenso beim HTTP-Modul für die Weboberfläche der jeweiligen Instanz. Der Zerokonfname sollte auch eindeutig sein. Neben dieser Datei ist noch die dazu passende logging-Konfiguration anzulegen, hier also ''/etc/mopidy/logging_kind2.conf''. Dazu wird die Standarddatei kopiert und darin nur der Name der Logdatei angepasst.

Um nun auch die entsprechende Anzahl Instanzen automatisch zu starten, sind die entsprechenden Startdateien anzulegen. Dazu kann die Datei ''/etc/systemd/system/mopidy.cfg'' z.B. in ''/etc/systemd/system/mopidy_kind1.cfg'' umbenannt werden und dann 3 mal mit den Endungen der anderen Instanzen kopiert werden. Der Inhalt ist dann wie folgt:

<syntaxhighlight lang="bash">
[Unit]
Description=Mopidy_kind1
After=network.target sound.target

[Service]
EnvironmentFile=/etc/default/mopidy
ExecStart=/usr/bin/mopidy --quiet --config /etc/mopidy/kind1.conf

# allow MPD to use real-time priority 50
LimitRTPRIO=50
LimitRTTIME=infinity

# disallow writing to /usr, /bin, /sbin, ...
ProtectSystem=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Abschließend sollten die 4 Instanzen durch den Aufruf von <pre>systemctl enable mopidy_kind1</pre> usw. aktiviert werden. Es empfiehlt sich nach dem Start von Mopidy die korrekte Funtkionsweise mit dem [https://www.musicpd.org/clients/mpc/ MPC]-Client oder mit [http://rybczak.net/ncmpcpp/ NCMPCPP] auf der Konsole zu testen.

Hierbei sollte es dann bereits möglich sein, die Multiroom-Fähigkeiten von Snapcast mit Hilfe des Android-Clients von Snapcast zu testen und so auch festzustellen, dass die restliche Konfiguration von Snapcast und Pulseaudio korrekt sind.

=== FHEM ===

In FHEM sind nun in der ''fhem.cfg'' die entsprechenden Module einzurichten:
* Ein Snapcast-Modul im Server Modus
* Pro Raum ein Snapcast-Modul im Clientmodus
* Pro Raum ein MPD-Modul
* Pro Raum ein OpenMultiroom-Modul
* Optional pro Raum ein Text2Speech-Modul
* weitere Text2Speech-Module, falls man diese in Pulseaudio mit dem per Combine-Sink vorgesehen hat.

<syntaxhighlight lang="bash">
define scs.snap Snapcast

define scc.kind1 Snapcast client scs.snap b827eb9aec84
attr scc.kind1 constraintDummy freestring
attr scc.kind1 constraints standard|07:00 0 20:00 100 21:00 50 21:30 30 24:00 0,beforefree|07:00 0 21:00 100 22:00 50 23:00 30 24:00 0,beforeschool|07:00 0 08:30 50 20:00 100 21:00 50 21:30 30 24:00 0,free|07:00 0 08:30 50 21:00 100 22:00 50 23:00 30 24:00 0

define scc.kind2 Snapcast client scs.snap 025009413c29
attr scc.kind2 constraintDummy freestring
attr scc.kind2 constraints standard|07:00 0 20:15 100 20:30 50 24:00 0,beforefree|07:00 0 21:00 100 22:30 50 24:00 0,beforeschool|07:00 0 08:30 50 20:15 100 20:30 50 24:00 0,free|07:00 0 08:30 50 21:00 100 22:30 50 24:00 0

define scc.kueche Snapcast client scs.snap b827eb9a2ad3

define scc.wohn Snapcast client scs.snap 00aefa4aa3a9
</syntaxhighlight>

Oben zu sehen ist das define für das Server-Modul. Ohne Parameter verbindet sich mit localhost auf dem Standardport 1705. Es folgt die Definition von 2 Clients. Der erste Parameter "client" versetzt das Snapcastmodul in den Clientmodus. Der zweite Parameter verweist auf das Servermodul, der dritte Parameter ist die Client-ID. Diese besteht bei der aktuellen Snapcast-Version meistens aus der MAC-Adresse des Clients. Für die Kinder werden noch die Attribute constraintDummy ond constraints vergeben. Hiermit wird eine tagestyp- und tageszeitabhängige Lautstärkebegrenzung konfiguriert. Für die vier Tagestypen "standard", "beforefree", "beforeschool" und "free" wird ein jeweils anderes Lautstärkezeitprofil definiert.

Das Zeitprofil wird hier nach dem gleichen Muster wie die Temperaturlisten der Homematic-Thermostate, erklärt hier: [HomeMatic_Type_Thermostat]. Für den Tagestyp wird zusätzlich das Attribut constraintDummy verwendet. Es definiert, dass in dem Dummy "freestring" jeweils drin steht, welcher Tagestyp gerade ist. Diese Variable wirkt somit als Selektor auf die Liste der erlaubten Maximallautstärken. Wie eine solche Dummyvariable jeweils mit einem entsprechenden Wert befüllt werden kann, z.B. abhängig vom Wochentag, von Schulferien oder Feiertagen, wird hier nicht erläutert. Es ist auch möglich, nur ein Lautstärkeprofil anzugeben. Ohne dass ein Attribut constraintDummy gesetzt ist, verwendet das Snapcastmodul immer den Wert "standard". Wie man hier sehen kann, gibt es im Beispiel 4 Typen, hierbei fallen Freitage normalerweise in die Kategorie "beforefree" (es sind Tage, bevor dann frei ist, es kann also typischerweise länger und lauter Musik gehört werden), Samstage normalerweise in die Kategorie "free" und Sonntage in die Kategorie "beforeschool", ebenso landen dort Feiertage vor Schultagen usw.

<syntaxhighlight lang="bash">
define tts.wohn Text2Speech pulsewohn
attr tts.wohn TTS_FileTemplateDir /data/misc/announcements/
attr tts.wohn TTS_UseMP3Wrap true
attr tts.wohn TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120

define tts.kind1 Text2Speech pulsekind1
attr tts.kind1 TTS_FileTemplateDir /data/misc/announcements/
attr tts.kind1 TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kind1 TTS_UseMP3Wrap true

define tts.kind2 Text2Speech pulsekind2
attr tts.kind2 TTS_FileTemplateDir /data/misc/announcements/
attr tts.kind2 TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kind2 TTS_UseMP3Wrap true

define tts.kueche Text2Speech pulsekueche
attr tts.kueche TTS_FileTemplateDir /data/misc/announcements/
attr tts.kueche TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kueche TTS_UseMP3Wrap true

define tts.kinder Text2Speech pulsekinder
attr tts.kinder TTS_FileTemplateDir /data/misc/announcements/
attr tts.kinder TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.kinder TTS_UseMP3Wrap true

define tts.unten Text2Speech pulseunten
attr tts.unten TTS_FileTemplateDir /data/misc/announcements/
attr tts.unten TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.unten TTS_UseMP3Wrap true

define tts.alle Text2Speech pulsealle
attr tts.alle TTS_FileTemplateDir /data/misc/announcements/
attr tts.alle TTS_MplayerCall PULSE_PROP='media.role=announcement' /usr/bin/mplayer -softvol -volume 120
attr tts.alle TTS_UseMP3Wrap true
</syntaxhighlight>
Hier sind die Definitionen der Text2Speech Module zu sehen (optional). Sie werden jeweils mit den in Pulseaudio definierten Sinks verbunden. Die Nutzung eines TemplateDirs ist ebenfalls optional, hier können bereits fertige MP3s verwendet werden, die dann anstelle der von der Google TTS API erzeugten Dateien benutzt werden. Dies können auch Bestätigungs und Fehlertöne sein, die bei Benutzern ohne Display, die rein mit Fernbedienung arbeiten, auf Fehlbedienungen etc. aufmerksam zu omrhen. Der Aufruf von mplayer wird noch modifiziert, um dafür zu sorgen, dass die Ausgabe bei Pulseaudio als media.role "announcement" eingehen. Dies wird dann vom duck-Modul erkannt, und führt dazu, dass die Lautstärke der ggf. ablaufenden Musik, etc. abgesenkt wird, so lange die tts-Ausgabe läuft.

<syntaxhighlight lang="bash">
define mpd.kind1 MPD 192.168.2.2 6600
attr mpd.kind1 player mopidy
attr mpd.kind1 bookmarkDir mpdstates
attr mpd.kind1 autoBookmark 1

define mpd.kind2 MPD 192.168.2.2 6702
attr mpd.kind2 player mopidy
attr mpd.kind2 bookmarkDir mpdstates
attr mpd.kind2 autoBookmark 1

define mpd.kueche MPD 192.168.2.2 6703
attr mpd.kueche player mopidy
attr mpd.kueche bookmarkDir mpdstates
attr mpd.kueche autoBookmark 1

define mpd.wohn MPD 192.168.2.2 6704
attr mpd.wohn player mopidy
attr mpd.wohn bookmarkDir mpdstates
attr mpd.wohn autoBookmark 1
</syntaxhighlight>
Pro laufender MPD oder Mopidy-Instanz wird ein MPD-Modul eingerichtet. Der Hostname und die Ports sind entsprechend anzupassen. Durch die bookmarkDir und autoBookmark - Attribute wird erreicht, dass der Zustand von Playlisten beim Wechsel derselben gespeichert und später wiederhergestellt werden kann. So lässt sich das Hören eines Hörbuchs unterbrechen, auf z.B. eine Radiostreamplayliste schalten, um dann später zur gleichen Stelle im Hörbuch zurückzukehren.

<syntaxhighlight lang="bash">
define omr.kind1 OpenMultiroom
attr omr.kind1 mr scc.kind1
attr omr.kind1 soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kind1 playlistPattern kind1
attr omr.kind1 ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kind1 defaultTts tts.kind1
attr omr.kind1 defaultStream kind1
attr omr.kind1 defaultSound mpd.kind1

define omr.kind2 OpenMultiroom
attr omr.kind2 mr scc.kind2
attr omr.kind2 soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kind2 playlistPattern kind2
attr omr.kind2 ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kind2 defaultTts tts.kind2
attr omr.kind2 defaultStream kind2
attr omr.kind2 defaultSound mpd.kind2

define omr.kueche OpenMultiroom
attr omr.kueche mr scc.kueche
attr omr.kueche soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.kueche playlistPattern wohn
attr omr.kueche ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.kueche defaultTts tts.kueche
attr omr.kueche defaultStream kueche
attr omr.kueche defaultSound mpd.kueche

define omr.wohn OpenMultiroom
attr omr.wohn mr scc.wohn
attr omr.wohn soundMapping kind1:mpd.kind1,kind2:mpd.kind2,kueche:mpd.kueche,wohn:mpd.wohn
attr omr.wohn playlistPattern wohn
attr omr.wohn ttsMapping kind1:tts.kind1,kind2:tts.kind2,kueche:tts.kueche,wohn:tts.wohn
attr omr.wohn defaultTts tts.wohn
attr omr.wohn defaultStream wohn
attr omr.wohn defaultSound mpd.wohn
</syntaxhighlight>
Die Konfiguration der OpenMultiroom-Module schließt die Einrichtung von FHEM ab. Jede Instanz benötigt mindestens das "mr"- und das "soundMapping"-Attribut. Nur so kann sich das Modul mit den entsprechenden Snapcast und MPD-Modulen verbinden. Durch das "mr"-Attribut wird ein OpenMultiroom-Modul einem Snapcast-Client-Modul fest zugeordnet. Das Soundmapping ordnet die in Snapcast definierten Streams (siehe oben, Konfiguration vom Snapserver) den entsprechenden Instanzen des MPD-Moduls zu. Dadurch weiß FHEM, welcher MPD auf welchem Stream abspielt und kann je nachdem, welchem Stream ein Raum gerade zuhört, den dazu passenden MPD steuern und seine Readings durchreichen. Das OpenMultiroom-Modul bildet alle Readings des MPD-Moduls nochmal direkt ab. Wechselt ein Benutzer aber den Stream, dem er zuhört, aktualisieren sich auch alle Readings dementsprechend mit denen des dann aktuellen MPD-Moduls.

Das Attribut playlistPattern ist optional und sorgt dafür, dass beim Durchschalten der Playlists mit den Kommandos "channelUp" und "channelDown" nur diejenigen Playlists berücksichtigt werden, die auf das Pattern passen.

Analog zum soundMapping definiert das Attribut ttsMapping die Zuordnung der TTS-Module zu den Streams. Beim Ausgeben von Announcement kann so das OpenMultiroom-Modul ermitteln, auf welchem Stream welcher Raum gerade zuhört, und wo dementsprechend die TTS-Ausgaben zu erzeugen sind, damit sie auch in den gewünschten Räumen ankommen. Dieser Umweg ist zurzeit nötig, da ein Snapcast-Client nur auf einem einzigen Stream lauschen kann. Lauschen noch andere Clients auf demselben Stream, hören sie allerdings zwangsweise auch die Announcements.

Die 3 Default-Attribute legen fest, welche der TTS-Module, welcher Stream und welcher MPD dem entsprechenden Modul fest zugeordnet sind. Dies wird u.a. von einer Resetfunktion im Modul verwendet.

== Bedienung des OpenMultiroom-Moduls ==

=== set-Kommandos ===

=== Readings ===

=== Attribute ===

== Anbindung einer Fernbedienung an ein OpenMultiroom-Modul ==

=== Konfiguration von LIRC und IRExec ===

=== Zuordnung der Tasten: Beispiel ===

[[Category:Examples]]
[[Category:HOWTOS]]
[[Category:Unterhaltungselektronik]]

Wochenende, Feiertage und Schulferien

2022-06-20T17:32:16Z

Beta-User: Calendar: notify angepaßt, forum #128094

FHEM bietet die Möglichkeit, Komponenten in Abhängigkeit von Wochenenden und Schulferien sowie Feiertagen zu steuern. Hier soll beschrieben werden, wie Schulferien einbezogen werden.

== Wochenendermittlung mit $we ==
Um am Wochenende (Samstag und Sonntag) länger schlafen zu können, kann diese Steuerung durch Nutzung der Variable ''$we'' erweitert werden.
Diese hat am Wochenende den Wert ''1'', an sonstigen Tagen den Wert ''0''. In if-Abfragen wird die 0 als ''false/falsch'' interpretiert, andere numerische Werte als ''true/wahr''. Man kann mittels ''if ($we)'' also ganz einfach prüfen, ob Wochenende ist und entsprechend steuern (oder auch nicht).

Eine simple Rollladensteuerung um 7 Uhr morgens für jeden Tag sieht beispielsweise wie folgt aus:

define RolloHoch at *07:00 set Rollo hoch

Dieses Beispiel kann entsprechend ergänzt werden, so dass am Wochenende nicht um 7 Uhr das Rollo nach oben gefahren wird:

define RolloHoch at *07:00 { if (!($we)) { fhem("set Rollo hoch");; } }

Das ''!'' in der if-Abfrage negiert den dahinter folgenden Ausdruck in der Klammer, ist also "nicht Wochenende". Der Inhalt der äußeren geschweiften Klammern stellt echten Perl-Code dar (der hinter jeder Anweisung gerne ein Semikolon stehen hat, das in FHEM durch ein weiteres Semikolon [http://de.wikipedia.org/wiki/Maskierungszeichen maskiert/escaped] werden muss). Aus dem Perl-Code kann man mittels des Befehls ''fhem()'' wiederum FHEM-Code ausführen (hier der Befehl, um das Rollo nach oben zu fahren). Das (Doppel-)Semikolon ist in diesem Beispiel nicht zwingend notwendig, da es sich nur um eine einzige (und somit letzte) Anweisung handelt - man sollte sich jedoch aneignen, jede Anweisung im Perl-Code mit einem (Doppel-)Semikolon abzuschließen (eine schließende geschweifte Klammer stellt auch das Ende eine Anweisung bzw. eines Anweisungsblocks dar).

Intern wird für die Ermittlung, ob die FHEM-Variable $we wahr ist, die Funktion IsWe() verwendet.

== IsWe() ==
Statt der obigen Schreibweise kann man auch direkt die Funktion IsWe() aufrufen. Eine andere Schreibweise für obiges Beispiel wäre daher:
define RolloHoch at *07:00 { if (!(IsWe())) { fhem("set Rollo hoch");; } }

Der Vorteil dieser Vorgehensweise ist, dass IsWe() weitere Parameter kennt. Es kann zum einen nicht nur für den heutigen Tag (''IsWe()''), sondern auch für gestern (''IsWe("yesterday")'') und morgen (''IsWe("tomorrow")'') abgefragt werden. Dabei werden die in holiday2we angegebenen Geräte nacheinander durchgegangen und ermittelt, ob ein Reading mit diesem Namen vorhanden ist und etwas anderes liefert als "none". ''IsWe()'' ohne Parameter fragt den Inhalt des Readings "state" ab, für eigene Routinen kann auch ''IsWe("today")'' verwendet werden. Die Funktionsweise ist dann identisch zu den Abfragen nach "yesterday" und "tomorrow".

Ebenso kann die Behandlung von Samstagen und Sonntagen durch Verwendung eines zweiten Arguments mit einer Zahl >6 abgeschaltet werden, so dass nur noch ein positives Ergebnis zurückgeliefert wird, wenn tatsächlich ein Feiertag ist (siehe nachfolgenden Abschnitt):

''{IsWe("tomorrow",7)}'' ist also nur dann wahr, wenn morgen ein Feiertag in einem in ''holiday2we'' angegebenen Device eingetragen ist.

''(Fehlt: was passiert bei Angabe von kleineren Zahlen?)''

''IsWe()'' ohne Parameter wird intern von diversen Modulen verwendet, um den Wert von $we zu ermitteln, u.a. von [[AutoShuttersControl]], [[DOIF]] und [[WeekdayTimer]].

== Feiertage mittels holiday-Datei ==
=== Allgemeines zu holiday2we ===
Samstags und Sonntags bleibt das Rollo nun unten und man kann länger schlafen. Um diesen Komfort auch an Feiertagen zu haben, können in FHEM mittels ''holiday''-Dateien Feiertage definiert werden. Sinnvollerweise erstellt man sich für sein jeweiliges Bundesland eine eigene Datei, die Definitionen für feste Feiertage (z.B. Weihnachten oder der Tag der Deutschen Einheit) und solche in Abhängigkeit zu Ostern (z.B. Ostermontag oder Pfingsten, im Rheinland auch der Karneval) beinhaltet. Eine gutes Beispiel mit Erklärung findet sich in der [http://fhem.de/Heimautomatisierung-mit-fhem.pdf FHEM-Übersicht für Anfänger].
Nachdem beispielsweise die ''BW_Feiertag.holiday''-Datei im FHEM-Ordner erstellt/abgelegt wurde, kann diese in die Konfiguration eingebunden werden. Mittels ''holiday2we'' können die darin definierten Feiertage mit der Variable ''$we'' "verheiratet" werden. ''if ($we)'' ist danach immer wahr, sobald Wochenende oder ein Feiertag ist:

attr global holiday2we BW_Feiertag
define BW_Feiertag holiday

In dem Attribut können mehrere Geräte angegeben werden:
attr global holiday2we BW_Feiertag,meinUrlaubsdummy,Schulferien

Dabei wird bei echten ''holiday''-Dateien (die auch seit Ende 2018 auch rechnen können<ref>{{Link2Forum|Topic=93303|LinkText=Forum-Thread}}</ref>) jeweils eine entsprechende Auswertung durchgeführt, für alle anderen Devices (wie z.B. einem Dummy) wird entweder ''state'' für heute verwendet oder die Readings ''"tomorrow"'' bzw. ''"yesterday"'', wenn diese vorhanden sind. Dabei werden nicht vorhandene Werte als ''"kein Feiertag"'' behandelt, und alle anderen Werte mit Ausnahme von ''"none"'' als Feiertag.

=== weekEnd und noWeekend ===
Dies sind spezielle Einträge in holiday2we:
Das Wort weekEnd als Eintrag bewirkt, dass grundsätzlich Samstage und Sonntage nicht mehr als ''$we'' angesehen werden, sondern nur noch die in einem der angegebenen Devices (mit Ausnahme von ''noWeekEnd'') eingetragenen Feiertage bzw. Rückmeldungen für gestern, heute und morgen berücksichtigt werden. weekEnd selbst kann, muß aber nicht zugleich ein [[Gerät]] des Typs ''holiday'' sein.
Ein ''noWeekEnd''-Eintrag sollte dagegen mit einem Device verknüpft sein, denn alle Tage, die von diesem Gerät nach der üblichen Syntax als Treffer zurückgeliefert werden, werden abschließend als ''kein Feiertag' behandelt. Damit könnte man z.B. den ersten Weihnachtsfeiertag zum normalen Wochentag machen, egal, was andere ''holiday2we'-Einträge dazu melden, und auch gleichgültig, ob dies zugleich ein Sonntag ist.

=== Mitgelieferte holiday-Dateien ===
FHEM liefert eine Reihe von vordefinierten holiday-Dateien mit:

* Dateien für die deutschen Bundesländer (abgekürzt laut [https://www.bmel-statistik.de/footernavigation/archiv/statistischer-monatsbericht/abkuerzungen-der-bundeslaender/ amtlicher Liste]), z.B. ''hh.holiday'' für Hamburg.
* Feiertage in Österreich: ''aut.holiday''
* Feiertage im Vereinigten Königreich und Nordirland: ''en.holiday''
* Islamische Feiertage: ''islam20xx.holiday''

== Feiertage mittels Internet-Kalender ==
{{Randnotiz|RNText=Alle x Stunden -wie hier dargestellt- einen unveränderten Jahres-Ferienkalender aus dem Internet erneut abzurufen ist nicht sinnvoll, da unnötige Abhängigkeiten des FHEM-Servers zur Verfügbarkeit des externen Servers entstehen. Zudem erzeugt dies unnötige Last auf dem externen Server. Besser ist es, nur einmal jährlich den Ferienkalender abzurufen und auf dem eigenen FHEM-Server zu speichern. Das Vorgehen ist beispielhaft in {{Link2Forum|Topic=36244|Message=299631}} beschrieben.}}
Theoretisch kann man in o.a. Datei auch seine persönlichen Urlaube oder die Schulferien definieren. Hier eignet sich jedoch die ''Calendar''-Funktion wesentlich besser. V.a. die Schulferien der einzelnen Bundesländer sind im Internet (z.B. unter [http://www.ferienwiki.de ferienwiki.de]) als iCal-Datei verfügbar und können wie folgt in FHEM eingebunden werden:<syntaxhighlight lang="perl">
define BW_Ferien Calendar ical url https://www.ferienwiki.de/exports/ferien/2020/de/baden-wuerttemberg 86400

</syntaxhighlight>Das Intervall von 86400 Sekunden (entspricht 24 Stunden) für die Aktualisierung der Schulferien sollte im Normalbetrieb mehr als ausreichen. Wenn eigene Kalender (z.B. bei Google) für Urlaubstage genutzt werden, muss man individuell abwägen, wie oft dieser aktualisiert werden soll.

Nach dem Einbinden des Kalenders kann man sich die Termine anzeigen lassen:<syntaxhighlight lang="perl">
get BW_Ferien events
</syntaxhighlight>Den Kalender kann man nun z.B. nutzen, um einen dummy zu setzen, der später entsprechend abgefragt werden kann. Man braucht dazu noch ein notify, welches direkt auf die Events des Kalenders reagiert.<syntaxhighlight lang="perl">
define Ferientag dummy

define n_Ferien notify BW_Ferien:changed:.*start|BW_Ferien:changed:.*end {\
my $stat=($EVTPART2 eq "start")?1:0;;\
fhem("set Ferientag $stat") if defined fhem('get '.$NAME.' events filter:uid=="'.\
$EVTPART1.'",field(summary)=~"(?i)ferien" limit:count=1',1)\
}
</syntaxhighlight>Der ''Ferientag'' ist in diesem Beispiel der angesprochene ''dummy'' und kann mittels ''Value("Ferientag")'' abgefragt werden. Im ''notify'' wird der Wert auf 1 gesetzt, sobald der Kalenderevent startet und auf 0 sobald der Event endet. (vgl. {{Link2CmdRef|Anker=Calendar}} )

Um die Funktion zu testen, kann man sich aus dem Kalender Reading modeUpcoming die erste ID herauskopieren (Beispiel im April, Kalender 2020 Baden-Würtemberg) und mit dem trigger Befehl die Events des Calendar Devices einmal simulieren.
<pre>
trigger BW_Ferien changed: 28f0d17b082149c3a6ef99c04153e937 start
trigger BW_Ferien changed: 28f0d17b082149c3a6ef99c04153e937 end
</pre>

Um ein Rollo nun weder am Wochenende, an Feiertagen, noch zu Schulferien morgens hochfahren zu lassen, lautet das Beispiel:

define RolloHoch at *07:00 { if ( !($we) && !(Value("Ferientag")) ) { fhem("set Rollo hoch");; } }

Ausgehend von diesem Artikel ist unter [[Google-Kalender zur Steuerung von Dummies]] eine Vorgehensweise zur
Steuerung von FHEM mit dem Google-Kalender veröffentlicht.

Diese Methode unterstützt jedoch nicht die Feiertagserkennung des {{Link2CmdRef|Lang=de|Anker=DOIF|Label=DOIF}}-Moduls, speziell im Abschnitt {{Link2CmdRef|Lang=de|Anker=DOIF_Wochentagsteuerung|Label=Wochentagssteuerung}}. Hier wird nur der Status der ''$we''-Variable abgefragt und die Methode mit dem eigenen Holiday-Kalender empfohlen.

== Links / Referenzen ==
<references />

[[Kategorie:Code Snippets]]
[[Kategorie:HOWTOS]]

RHASSPY

2022-05-24T15:32:19Z

Beta-User: FHEM-Devices für die Verwendung mit Rhasspy konfigurieren - Korrekturen

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

== Set-Befehle (SET) ==

=== customSlot ===
Erstellt einen neuen - oder überschreibt einen alten - Slot in Rhasspy
* <code>slotname</code> und <code>slotdata</code> sind verpflichtend
* <code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
* <code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

=== fetchSiteIds ===
Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

=== play ===
Sendet eine WAV Datei an Rhasspy, <code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

=== speak ===
Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.

Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!

'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

=== textCommand ===
Sendet ein Text-Kommando an Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>
Mangels siteId erfolgt hier keine Rückmeldung zum ausgeführten Kommando.

=== trainRhasspy ===
Startet das Training von Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

=== update ===
''update'' kennt diverse Abstufungen:

==== update devicemap ====
Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.) und ein Training zu starten. Wenn [[#autoTraining|autoTraining]] nicht deaktiviert wurde, erfolgt dies bei Änderungen an relevanten Attributen nach einiger Zeit zwar automatisch, über diesen Befehl kann aber sichergestellt werden, dass dies unmittelbar und ohne Vergleich mit Alt-Daten erfolgt.

''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap</code>

==== update devicemap_only ====
Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.

'''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap_only</code>

==== update slots ====
Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.

Erstellte/Aktualisierte Slots sind z.B.:
* de.fhem.AllKeywords (Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
* de.fhem.Device
* de.fhem.Device-''genericDeviceType''
* de.fhem.Device-''Intent''
* de.fhem.Group
* de.fhem.Room
* de.fhem.MediaChannels
* de.fhem.Color
* de.fhem.NumericType

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots</code>

==== slots_no_training ====
Wie <code>slots</code>, aber ohne Training nach dem Update.

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots_no_training</code>

==== update language ====
Liest das das Sprach-File (''languageFile'') neu ein.

Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!

'''Beispiel:'''
:<code>set <rhasspyDevice> update language</code>

==== update intent_filter ====
Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.

'''Beispiel:'''
:<code>set <rhasspyDevice> update intent_filter</code>

==== update all ====
Aktualisiert die Devicemap und das languageFile

'''Beispiel:'''
:<code>set <rhasspyDevice> update all</code>

=== volume ===
Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float). Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.

'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH''' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#rhasspyShortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen|Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===
Um das Verhalten von RHASSPY beeinflussen zu können, können neben den bei den Attributen verfügbaren ''Tweaks'' auch die folgenden Readings genutzt - und v.a. auch im laufenden Betrieb immer weider geändert - werden:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Ein Beispiel, mit dem dies per Sprachkommando erfolgt, ist in ''contrib'' zu finden, mit der mobilen Satelliten per Funktionsaufruf in einem [[#rhasspyIntents|rhasspyIntent]] einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung (bzw. nach Abschluss aller Änderungen) an den folgenden Attributen muss ein <code>[[#update devicemap|update devicemap]]</code> ausgeführt werden. In der Regel wird dies automatisch veranlasst, aber wenn dies deaktiviert sein sollte, würden sonst weder RHASSPY, noch Rhasspy von der Änderung erfahren.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Falls man Slots händisch befüllt, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der ''devspec'' im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

=== genericDeviceType ===
Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels [[#gdt2groups|gdt2groups]] aus [[#rhasspyTweaks|rhasspyTweaks]])
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

=== rhasspyName ===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden, der erste Wert in dieser Liste dient intern als Hauptname (''alias''), z.B. in Auswahldialogen.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

=== rhasspyRoom ===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden (der erste Wert ist wieder der ''Hauptraum'' für Auswahldialoge etc.).

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).

=== rhasspyGroup ===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

=== rhasspyMapping ===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

==== Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings ====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

=== rhasspySpecials ===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

==== rhasspyChannels ====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

==== rhasspyColors ====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T15:18:44Z

Beta-User: Link

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

== Set-Befehle (SET) ==

=== customSlot ===
Erstellt einen neuen - oder überschreibt einen alten - Slot in Rhasspy
* <code>slotname</code> und <code>slotdata</code> sind verpflichtend
* <code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
* <code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

=== fetchSiteIds ===
Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

=== play ===
Sendet eine WAV Datei an Rhasspy, <code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

=== speak ===
Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.

Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!

'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

=== textCommand ===
Sendet ein Text-Kommando an Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>
Mangels siteId erfolgt hier keine Rückmeldung zum ausgeführten Kommando.

=== trainRhasspy ===
Startet das Training von Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

=== update ===
''update'' kennt diverse Abstufungen:

==== update devicemap ====
Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.) und ein Training zu starten. Wenn [[#autoTraining|autoTraining]] nicht deaktiviert wurde, erfolgt dies bei Änderungen an relevanten Attributen nach einiger Zeit zwar automatisch, über diesen Befehl kann aber sichergestellt werden, dass dies unmittelbar und ohne Vergleich mit Alt-Daten erfolgt.

''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap</code>

==== update devicemap_only ====
Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.

'''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap_only</code>

==== update slots ====
Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.

Erstellte/Aktualisierte Slots sind z.B.:
* de.fhem.AllKeywords (Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
* de.fhem.Device
* de.fhem.Device-''genericDeviceType''
* de.fhem.Device-''Intent''
* de.fhem.Group
* de.fhem.Room
* de.fhem.MediaChannels
* de.fhem.Color
* de.fhem.NumericType

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots</code>

==== slots_no_training ====
Wie <code>slots</code>, aber ohne Training nach dem Update.

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots_no_training</code>

==== update language ====
Liest das das Sprach-File (''languageFile'') neu ein.

Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!

'''Beispiel:'''
:<code>set <rhasspyDevice> update language</code>

==== update intent_filter ====
Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.

'''Beispiel:'''
:<code>set <rhasspyDevice> update intent_filter</code>

==== update all ====
Aktualisiert die Devicemap und das languageFile

'''Beispiel:'''
:<code>set <rhasspyDevice> update all</code>

=== volume ===
Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float). Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.

'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH''' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#rhasspyShortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen|Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===
Um das Verhalten von RHASSPY beeinflussen zu können, können neben den bei den Attributen verfügbaren ''Tweaks'' auch die folgenden Readings genutzt - und v.a. auch im laufenden Betrieb immer weider geändert - werden:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Ein Beispiel, mit dem dies per Sprachkommando erfolgt, ist in ''contrib'' zu finden, mit der mobilen Satelliten per Funktionsaufruf in einem [[#rhasspyIntents|rhasspyIntent]] einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T15:16:19Z

Beta-User: Benutzerdefinierte Readings - Übersetzung/Klarstellung

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

== Set-Befehle (SET) ==

=== customSlot ===
Erstellt einen neuen - oder überschreibt einen alten - Slot in Rhasspy
* <code>slotname</code> und <code>slotdata</code> sind verpflichtend
* <code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
* <code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

=== fetchSiteIds ===
Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

=== play ===
Sendet eine WAV Datei an Rhasspy, <code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

=== speak ===
Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.

Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!

'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

=== textCommand ===
Sendet ein Text-Kommando an Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>
Mangels siteId erfolgt hier keine Rückmeldung zum ausgeführten Kommando.

=== trainRhasspy ===
Startet das Training von Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

=== update ===
''update'' kennt diverse Abstufungen:

==== update devicemap ====
Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.) und ein Training zu starten. Wenn [[#autoTraining|autoTraining]] nicht deaktiviert wurde, erfolgt dies bei Änderungen an relevanten Attributen nach einiger Zeit zwar automatisch, über diesen Befehl kann aber sichergestellt werden, dass dies unmittelbar und ohne Vergleich mit Alt-Daten erfolgt.

''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap</code>

==== update devicemap_only ====
Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.

'''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap_only</code>

==== update slots ====
Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.

Erstellte/Aktualisierte Slots sind z.B.:
* de.fhem.AllKeywords (Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
* de.fhem.Device
* de.fhem.Device-''genericDeviceType''
* de.fhem.Device-''Intent''
* de.fhem.Group
* de.fhem.Room
* de.fhem.MediaChannels
* de.fhem.Color
* de.fhem.NumericType

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots</code>

==== slots_no_training ====
Wie <code>slots</code>, aber ohne Training nach dem Update.

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots_no_training</code>

==== update language ====
Liest das das Sprach-File (''languageFile'') neu ein.

Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!

'''Beispiel:'''
:<code>set <rhasspyDevice> update language</code>

==== update intent_filter ====
Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.

'''Beispiel:'''
:<code>set <rhasspyDevice> update intent_filter</code>

==== update all ====
Aktualisiert die Devicemap und das languageFile

'''Beispiel:'''
:<code>set <rhasspyDevice> update all</code>

=== volume ===
Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float). Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.

'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH''' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#rhasspyShortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen|Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===
Um das Verhalten von RHASSPY beeinflussen zu können, können neben den bei den Attributen verfügbaren ''Tweaks'' auch die folgenden Readings genutzt - und v.a. auch im laufenden Betrieb immer weider geändert - werden:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Ein Beispiel, mit dem dies per Sprachkommando erfolgt, ist in ''contrib'' zu finden, mit der mobilen Satelliten per Funktionsaufruf in einem [[#rhasspyIntent|rhasspyIntent]] einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T15:08:19Z

Beta-User: Formatierung

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

== Set-Befehle (SET) ==

=== customSlot ===
Erstellt einen neuen - oder überschreibt einen alten - Slot in Rhasspy
* <code>slotname</code> und <code>slotdata</code> sind verpflichtend
* <code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
* <code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

=== fetchSiteIds ===
Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

=== play ===
Sendet eine WAV Datei an Rhasspy, <code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

=== speak ===
Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.

Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!

'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

=== textCommand ===
Sendet ein Text-Kommando an Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>
Mangels siteId erfolgt hier keine Rückmeldung zum ausgeführten Kommando.

=== trainRhasspy ===
Startet das Training von Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

=== update ===
''update'' kennt diverse Abstufungen:

==== update devicemap ====
Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.) und ein Training zu starten. Wenn [[#autoTraining|autoTraining]] nicht deaktiviert wurde, erfolgt dies bei Änderungen an relevanten Attributen nach einiger Zeit zwar automatisch, über diesen Befehl kann aber sichergestellt werden, dass dies unmittelbar und ohne Vergleich mit Alt-Daten erfolgt.

''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap</code>

==== update devicemap_only ====
Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.

'''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap_only</code>

==== update slots ====
Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.

Erstellte/Aktualisierte Slots sind z.B.:
* de.fhem.AllKeywords (Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
* de.fhem.Device
* de.fhem.Device-''genericDeviceType''
* de.fhem.Device-''Intent''
* de.fhem.Group
* de.fhem.Room
* de.fhem.MediaChannels
* de.fhem.Color
* de.fhem.NumericType

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots</code>

==== slots_no_training ====
Wie <code>slots</code>, aber ohne Training nach dem Update.

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots_no_training</code>

==== update language ====
Liest das das Sprach-File (''languageFile'') neu ein.

Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!

'''Beispiel:'''
:<code>set <rhasspyDevice> update language</code>

==== update intent_filter ====
Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.

'''Beispiel:'''
:<code>set <rhasspyDevice> update intent_filter</code>

==== update all ====
Aktualisiert die Devicemap und das languageFile

'''Beispiel:'''
:<code>set <rhasspyDevice> update all</code>

=== volume ===
Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float). Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.

'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH''' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#rhasspyShortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen|Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T15:07:34Z

Beta-User: links repariert

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

== Set-Befehle (SET) ==

=== customSlot ===
Erstellt einen neuen - oder überschreibt einen alten - Slot in Rhasspy
* <code>slotname</code> und <code>slotdata</code> sind verpflichtend
* <code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
* <code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

=== fetchSiteIds ===
Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

=== play ===
Sendet eine WAV Datei an Rhasspy, <code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

=== speak ===
Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.

Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!

'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

=== textCommand ===
Sendet ein Text-Kommando an Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>
Mangels siteId erfolgt hier keine Rückmeldung zum ausgeführten Kommando.

=== trainRhasspy ===
Startet das Training von Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

=== update ===
''update'' kennt diverse Abstufungen:

==== update devicemap ====
Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.) und ein Training zu starten. Wenn [[#autoTraining|autoTraining]] nicht deaktiviert wurde, erfolgt dies bei Änderungen an relevanten Attributen nach einiger Zeit zwar automatisch, über diesen Befehl kann aber sichergestellt werden, dass dies unmittelbar und ohne Vergleich mit Alt-Daten erfolgt.

''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap</code>

==== update devicemap_only ====
Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.

'''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap_only</code>

==== update slots ====
Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.

Erstellte/Aktualisierte Slots sind z.B.:
* de.fhem.AllKeywords (Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
* de.fhem.Device
* de.fhem.Device-''genericDeviceType''
* de.fhem.Device-''Intent''
* de.fhem.Group
* de.fhem.Room
* de.fhem.MediaChannels
* de.fhem.Color
* de.fhem.NumericType

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots</code>

==== slots_no_training ====
Wie <code>slots</code>, aber ohne Training nach dem Update.

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots_no_training</code>

==== update language ====
Liest das das Sprach-File (''languageFile'') neu ein.

Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!

'''Beispiel:'''
:<code>set <rhasspyDevice> update language</code>

==== update intent_filter ====
Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.

'''Beispiel:'''
:<code>set <rhasspyDevice> update intent_filter</code>

==== update all ====
Aktualisiert die Devicemap und das languageFile

'''Beispiel:'''
:<code>set <rhasspyDevice> update all</code>

=== volume ===
Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float). Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.

'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH'' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#rhasspyShortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen|Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T15:05:07Z

Beta-User: volume =

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

== Set-Befehle (SET) ==

=== customSlot ===
Erstellt einen neuen - oder überschreibt einen alten - Slot in Rhasspy
* <code>slotname</code> und <code>slotdata</code> sind verpflichtend
* <code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
* <code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

=== fetchSiteIds ===
Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

=== play ===
Sendet eine WAV Datei an Rhasspy, <code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

=== speak ===
Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.

Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!

'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

=== textCommand ===
Sendet ein Text-Kommando an Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>
Mangels siteId erfolgt hier keine Rückmeldung zum ausgeführten Kommando.

=== trainRhasspy ===
Startet das Training von Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

=== update ===
''update'' kennt diverse Abstufungen:

==== update devicemap ====
Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.) und ein Training zu starten. Wenn [[#autoTraining|autoTraining]] nicht deaktiviert wurde, erfolgt dies bei Änderungen an relevanten Attributen nach einiger Zeit zwar automatisch, über diesen Befehl kann aber sichergestellt werden, dass dies unmittelbar und ohne Vergleich mit Alt-Daten erfolgt.

''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap</code>

==== update devicemap_only ====
Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.

'''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap_only</code>

==== update slots ====
Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.

Erstellte/Aktualisierte Slots sind z.B.:
* de.fhem.AllKeywords (Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
* de.fhem.Device
* de.fhem.Device-''genericDeviceType''
* de.fhem.Device-''Intent''
* de.fhem.Group
* de.fhem.Room
* de.fhem.MediaChannels
* de.fhem.Color
* de.fhem.NumericType

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots</code>

==== slots_no_training ====
Wie <code>slots</code>, aber ohne Training nach dem Update.

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots_no_training</code>

==== update language ====
Liest das das Sprach-File (''languageFile'') neu ein.

Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!

'''Beispiel:'''
:<code>set <rhasspyDevice> update language</code>

==== update intent_filter ====
Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.

'''Beispiel:'''
:<code>set <rhasspyDevice> update intent_filter</code>

==== update all ====
Aktualisiert die Devicemap und das languageFile

'''Beispiel:'''
:<code>set <rhasspyDevice> update all</code>

=== volume ===
Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float). Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.

'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH'' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#attr-rhasspyshortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T15:04:18Z

Beta-User: Set-Befehle (SET) - Ergänzungen + Formatierung

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

== Set-Befehle (SET) ==

=== customSlot ===
Erstellt einen neuen - oder überschreibt einen alten - Slot in Rhasspy
* <code>slotname</code> und <code>slotdata</code> sind verpflichtend
* <code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
* <code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

=== fetchSiteIds ===
Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

=== play ===
Sendet eine WAV Datei an Rhasspy, <code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

=== speak ===
Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.

Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!

'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

=== textCommand ===
Sendet ein Text-Kommando an Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>
Mangels siteId erfolgt hier keine Rückmeldung zum ausgeführten Kommando.

=== trainRhasspy ===
Startet das Training von Rhasspy.

'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

=== update ===
''update'' kennt diverse Abstufungen:

==== update devicemap ====
Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.) und ein Training zu starten. Wenn [[#autoTraining|autoTraining]] nicht deaktiviert wurde, erfolgt dies bei Änderungen an relevanten Attributen nach einiger Zeit zwar automatisch, über diesen Befehl kann aber sichergestellt werden, dass dies unmittelbar und ohne Vergleich mit Alt-Daten erfolgt.

''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap</code>

==== update devicemap_only ====
Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.

'''Beispiel:'''
:<code>set <rhasspyDevice> update devicemap_only</code>

==== update slots ====
Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.

Erstellte/Aktualisierte Slots sind z.B.:
* de.fhem.AllKeywords (Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
* de.fhem.Device
* de.fhem.Device-''genericDeviceType''
* de.fhem.Device-''Intent''
* de.fhem.Group
* de.fhem.Room
* de.fhem.MediaChannels
* de.fhem.Color
* de.fhem.NumericType

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots</code>

==== slots_no_training ====
Wie <code>slots</code>, aber ohne Training nach dem Update.

'''Beispiel:'''
:<code>set <rhasspyDevice> update slots_no_training</code>

==== update language ====
Liest das das Sprach-File (''languageFile'') neu ein.

Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!

'''Beispiel:'''
:<code>set <rhasspyDevice> update language</code>

==== update intent_filter ====
Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.

'''Beispiel:'''
:<code>set <rhasspyDevice> update intent_filter</code>

==== update all ====
Aktualisiert die Devicemap und das languageFile

'''Beispiel:'''
:<code>set <rhasspyDevice> update all</code>

=== volume ====
Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float). Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.

'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH'' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#attr-rhasspyshortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T13:30:46Z

Beta-User: Factor bei SetNumeric ergänzt

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

==Set-Befehle (SET)==

;<code id="set-customslot">customSlot</code>
:Erstellt einen neue - oder überschreibt einen alten - Slot in Rhasspy
:<code>slotname</code> und <code>slotdata</code> sind verpflichtend
:<code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
:<code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

:'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

;<code id="set-fetchsiteids">fetchSiteIds</code>
:Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
:Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
:'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

;<code id="set-play">play</code>
:Sendet eine WAV Datei an Rhasspy.
:<code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

;<code id="set-speak">speak</code>
:Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.
:Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!
:'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

;<code id="set-textcommand">textCommand</code>
:Sendet ein Text-Kommando an Rhasspy.
:'''Example:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>

;<code id="set-trainrhasspy">trainRhasspy</code>
:Startet das Training von Rhasspy.
:'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

;<code id="set-update">update</code>
:;<code id="set-update-devicemap">devicemap</code>
::Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.), ein Training zu starten, etc.
::''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap</code>

:;<code id="set-update-devicemaponly">devicemap_only</code>
::Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap_only</code>

:;<code id="set-update-slots">slots</code>
::Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.
::Erstellte/Aktualisierte Slots sind z.B.:
::*de.fhem.AllKeywords
::*de.fhem.Device
::*de.fhem.Device-''genericDeviceType''
::*de.fhem.Device-''Intent''
::*de.fhem.Group
::*de.fhem.Room
::*de.fhem.MediaChannels
::*de.fhem.Color
::*de.fhem.NumericType
::(Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots</code>

:;<code id="set-update-slotsnotraining">slots_no_training</code>
::Wie <code>slots</code>, aber ohne Training nach dem Update.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots_no_training</code>

:;<code id="set-update-language">language</code>
::Liest das das Sprach-File (''languageFile'') neu ein.
::Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!
::'''Beispiel:'''
::<code>set <rhasspyDevice> update language</code>

:;<code id="set-udpate-intentfilter">intent_filter</code>
::Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update intent_filter</code>

:;<code id="set-update-all">all</code>
::Aktualisiert die Devicemap und das languageFile
::'''Beispiel:'''
::<code>set <rhasspyDevice> update all</code>

;<code id="set-volume">volume</code>
::Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float).
::Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.
::'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH'' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#attr-rhasspyshortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
\[deutlich{Factor:2}] ( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>
*<code>Factor</code> Dieser Wert wird mit der Standard-Schrittweite (<code>step</code> im Mapping) multipliziert

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T13:10:58Z

Beta-User: Sprachliche Korrekturen, Verweise

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say</syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
* 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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>), oder können auf den automatisch vergebenen Werten belassen werden. 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden und <code>siteId</code>, das für Tests und andere Text-Eingabemöglichkeiten wichtig ist.

=== 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
''devspec'' der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== 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|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

=== autoTraining ===
Da Änderungen auf der FHEM-Seite (z.B. bei Änderungen der rhasspyNames) auch Rhasspy bekannt gemacht werden müssen und anschließend ein Training erfolgen muss, damit Rhasspy diese Änderugnen ebenfalls berücksichtigt, übergibt RHASSPY derartige Änderungen nach Ablauf von einer Minute seit der letzten Änderung an Rhasspy und initiiert dann ein Training. Setzt man diesen Schlüssel auf "0", wird diese Funktion deaktiviert, alle anderen numerischen Werte werden als Änderung dieses Timeouts (in Sekunden) interpretiert
Default ist <code>autoTraining=60</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

==Set-Befehle (SET)==

;<code id="set-customslot">customSlot</code>
:Erstellt einen neue - oder überschreibt einen alten - Slot in Rhasspy
:<code>slotname</code> und <code>slotdata</code> sind verpflichtend
:<code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
:<code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

:'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

;<code id="set-fetchsiteids">fetchSiteIds</code>
:Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
:Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
:'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

;<code id="set-play">play</code>
:Sendet eine WAV Datei an Rhasspy.
:<code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

;<code id="set-speak">speak</code>
:Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.
:Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!
:'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

;<code id="set-textcommand">textCommand</code>
:Sendet ein Text-Kommando an Rhasspy.
:'''Example:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>

;<code id="set-trainrhasspy">trainRhasspy</code>
:Startet das Training von Rhasspy.
:'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

;<code id="set-update">update</code>
:;<code id="set-update-devicemap">devicemap</code>
::Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.), ein Training zu starten, etc.
::''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap</code>

:;<code id="set-update-devicemaponly">devicemap_only</code>
::Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap_only</code>

:;<code id="set-update-slots">slots</code>
::Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.
::Erstellte/Aktualisierte Slots sind z.B.:
::*de.fhem.AllKeywords
::*de.fhem.Device
::*de.fhem.Device-''genericDeviceType''
::*de.fhem.Device-''Intent''
::*de.fhem.Group
::*de.fhem.Room
::*de.fhem.MediaChannels
::*de.fhem.Color
::*de.fhem.NumericType
::(Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots</code>

:;<code id="set-update-slotsnotraining">slots_no_training</code>
::Wie <code>slots</code>, aber ohne Training nach dem Update.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots_no_training</code>

:;<code id="set-update-language">language</code>
::Liest das das Sprach-File (''languageFile'') neu ein.
::Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!
::'''Beispiel:'''
::<code>set <rhasspyDevice> update language</code>

:;<code id="set-udpate-intentfilter">intent_filter</code>
::Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#intentFilter|intentFilter]] im ''rhasspyTweaks''-Attribut.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update intent_filter</code>

:;<code id="set-update-all">all</code>
::Aktualisiert die Devicemap und das languageFile
::'''Beispiel:'''
::<code>set <rhasspyDevice> update all</code>

;<code id="set-volume">volume</code>
::Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float).
::Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.
::'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 sollte, v.a. wenn das [[#autoTraining|autoTraining]] in der DEF deaktiviert wurde!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen (z.B. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge'').

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als Dateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH'' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#attr-rhasspyshortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T12:35:31Z

Beta-User: Get-Befehle eingefügt

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say </syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
*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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>). 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 <code>language</code>, 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
devspec der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== handleHotword ===
Triggert das Reading ''hotword'', wenn ein Hotword erkannt wurde (und erstellt das Reading, falls noch nicht vorhanden). Weitere Informationen dazu stehen beim Attribut [[#attr-rhasspyhotwords|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

==Set-Befehle (SET)==

;<code id="set-customslot">customSlot</code>
:Erstellt einen neue - oder überschreibt einen alten - Slot in Rhasspy
:<code>slotname</code> und <code>slotdata</code> sind verpflichtend
:<code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
:<code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

:'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

;<code id="set-fetchsiteids">fetchSiteIds</code>
:Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
:Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
:'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

;<code id="set-play">play</code>
:Sendet eine WAV Datei an Rhasspy.
:<code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

;<code id="set-speak">speak</code>
:Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.
:Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!
:'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

;<code id="set-textcommand">textCommand</code>
:Sendet ein Text-Kommando an Rhasspy.
:'''Example:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>

;<code id="set-trainrhasspy">trainRhasspy</code>
:Startet das Training von Rhasspy.
:'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

;<code id="set-update">update</code>
:;<code id="set-update-devicemap">devicemap</code>
::Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.), ein Training zu starten, etc.
::''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap</code>

:;<code id="set-update-devicemaponly">devicemap_only</code>
::Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap_only</code>

:;<code id="set-update-slots">slots</code>
::Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.
::Erstellte/Aktualisierte Slots sind z.B.:
::*de.fhem.AllKeywords
::*de.fhem.Device
::*de.fhem.Device-''genericDeviceType''
::*de.fhem.Device-''Intent''
::*de.fhem.Group
::*de.fhem.Room
::*de.fhem.MediaChannels
::*de.fhem.Color
::*de.fhem.NumericType
::(Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots</code>

:;<code id="set-update-slotsnotraining">slots_no_training</code>
::Wie <code>slots</code>, aber ohne Training nach dem Update.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots_no_training</code>

:;<code id="set-update-language">language</code>
::Liest das das Sprach-File (''languageFile'') neu ein.
::Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!
::'''Beispiel:'''
::<code>set <rhasspyDevice> update language</code>

:;<code id="set-udpate-intentfilter">intent_filter</code>
::Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#attr-rhasspytweaks-intentfilter|intentFilter]] im ''rhasspyTweaks''-Attribut.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update intent_filter</code>

:;<code id="set-update-all">all</code>
::Aktualisiert die Devicemap und das languageFile
::'''Beispiel:'''
::<code>set <rhasspyDevice> update all</code>

;<code id="set-volume">volume</code>
::Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float).
::Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.
::'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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!}}

== Get-Befehle (GET) ==
=== export_mapping ===
Liefert für das angegebene Device ein "klassisches" ''rhasspyMapping'', das dann als Basis für eigene Weiterentwicklungen genutzt werden kann. Funktioniert ggf. nicht in allen Fällen, v.a. bei ''SetScene'' und dem Szenen-Format für ''HUEBridge''.

=== test_file ===
Anzugeben ist der Dateiname (einschl. Pfad)

Die Datei wird zeilenweise eingelesen und an die Rhasspy-Komponente für die Intent-Erkennung übergeben. Das Ergebnis der Analyse wird in eine File geschrieben, die auf '_result.txt' endet. ''stop'' als ateiname unterbricht einen laufenden Test. Die ggf. abgeleiteten Kommandos werden nicht ausgeführt, FHEM wird während eines laufende Tests auch keine anderen Kommandos von der Rhasspy-Seite her annehmen.
Für diese Funktion ist es zwingend erforderlich, dass die ''siteId'' der RHASSPY-Instanz bei der Intent-Recognition-Komponente in Rhasspy als Satellit angegeben wurde.

=== test_sentence ===
Es kann ein beliebiger einzelner Satz eingegeben werden, die Ausgabe erfolgt dann in einem eigenen Dialogfeld, ansonsten gilt sinngemäß dasselbe wie bei ''test_file''.

==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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH'' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#attr-rhasspyshortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T12:23:28Z

Beta-User: /* Definition von RHASSPY (DEF) */

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say </syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
*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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <siteId> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <autoTraining> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>). 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 <code>language</code>, 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 <code>baseUrl=http://127.0.0.1:12101</code>.

=== devspec ===
devspec der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec 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 <code>defaultRoom=default</code>.

=== language ===
Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.

=== 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 <code>fhemId=fhem</code>.
{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== siteId ===
Wenn bestimmte Funktionen genutzt werden sollen, muss die RHASSPY-Instanz für Rhasspy als ''Satellit'' eigenständig angesprochen werden können. Hierzu muss dann eine eindeutige Kennung vergeben werden, und diese ist insbesondere dann auch in der für die Intent Recognition zuständigen Rhasspy-Komponente als Satellit anzugeben. Wird diese nicht explizit gesetzt, wird diese aus dem ''language''-Kürzel und der ''fhemId'' zusammengesetzt.
{{Hinweis|Für die Funktionalitäten ''test_sentence'', ''test_file'', ''msgDialog'' und ''AMAD.*'' ist es '''zwingend erforderlich''', die siteId in der Rhasspy-Intent-Recognition-Komponente einzutragen!}}

=== 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 <code>prefix=rhasspy</code>.

=== 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 und die automatisierte Eigenschaftenerkennung. Default ist <code>useGenericAttrs=1</code>.

=== encoding ===
Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.

=== handleHotword ===
Triggert das Reading ''hotword'', wenn ein Hotword erkannt wurde (und erstellt das Reading, falls noch nicht vorhanden). Weitere Informationen dazu stehen beim Attribut [[#attr-rhasspyhotwords|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

==Set-Befehle (SET)==

;<code id="set-customslot">customSlot</code>
:Erstellt einen neue - oder überschreibt einen alten - Slot in Rhasspy
:<code>slotname</code> und <code>slotdata</code> sind verpflichtend
:<code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
:<code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

:'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

;<code id="set-fetchsiteids">fetchSiteIds</code>
:Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
:Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
:'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

;<code id="set-play">play</code>
:Sendet eine WAV Datei an Rhasspy.
:<code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

;<code id="set-speak">speak</code>
:Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.
:Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!
:'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

;<code id="set-textcommand">textCommand</code>
:Sendet ein Text-Kommando an Rhasspy.
:'''Example:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>

;<code id="set-trainrhasspy">trainRhasspy</code>
:Startet das Training von Rhasspy.
:'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

;<code id="set-update">update</code>
:;<code id="set-update-devicemap">devicemap</code>
::Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.), ein Training zu starten, etc.
::''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap</code>

:;<code id="set-update-devicemaponly">devicemap_only</code>
::Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap_only</code>

:;<code id="set-update-slots">slots</code>
::Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.
::Erstellte/Aktualisierte Slots sind z.B.:
::*de.fhem.AllKeywords
::*de.fhem.Device
::*de.fhem.Device-''genericDeviceType''
::*de.fhem.Device-''Intent''
::*de.fhem.Group
::*de.fhem.Room
::*de.fhem.MediaChannels
::*de.fhem.Color
::*de.fhem.NumericType
::(Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots</code>

:;<code id="set-update-slotsnotraining">slots_no_training</code>
::Wie <code>slots</code>, aber ohne Training nach dem Update.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots_no_training</code>

:;<code id="set-update-language">language</code>
::Liest das das Sprach-File (''languageFile'') neu ein.
::Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!
::'''Beispiel:'''
::<code>set <rhasspyDevice> update language</code>

:;<code id="set-udpate-intentfilter">intent_filter</code>
::Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#attr-rhasspytweaks-intentfilter|intentFilter]] im ''rhasspyTweaks''-Attribut.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update intent_filter</code>

:;<code id="set-update-all">all</code>
::Aktualisiert die Devicemap und das languageFile
::'''Beispiel:'''
::<code>set <rhasspyDevice> update all</code>

;<code id="set-volume">volume</code>
::Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float).
::Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.
::'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH'' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#attr-rhasspyshortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]

RHASSPY

2022-05-24T12:06:49Z

Beta-User: Einrichtung MQTT2_CLIENT subscriptions ergänzt

{{Baustelle}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 10_RHASSPY.pm.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an den Rhasspy Sprachassistenten
|ModType=contrib
|ModCmdRef=RHASSPY
|ModForumArea=Frontends/Sprachsteuerung
|ModFTopic=119447
|ModTechName=10_RHASSPY.pm
|ModOwner=Beta-User ({{Link2FU|9229|Forum}}/[[Benutzer Diskussion:Beta-User|Wiki]]), drhirn ({{Link2FU|15727|Forum}}/[[Benutzer Diskussion:Drhirn|Wiki]])
}}
[[File:Rhasspy_fhem.png|thumb|right|Schematische Darstellung von Rhasspy und FHEM/RHASSPY]]
== Einleitung ==
[https://github.com/rhasspy/rhasspy Rhasspy] ist eine Open Source Server-Lösung für Spracherkennung und Sprachsteuerung, welche auf einem RaspBerry Pi oder einem anderen Debian-basierten Serversystem lauffähig ist. Es handelt sich dabei um eine Sammlung von Programmen (=Skripten in der Python-Sprechweise), die unter einer einheitlichen und sehr flexiblen Benutzungsoberfläche zusammengefasst sind. Die Besonderheit an Rhasspy ist, dass es nach der Installation komplett offline betrieben werden kann. Es werden also keine Daten 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, etc.). Alle diese Module kommunizieren miteinander über das [[MQTT|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 Text-to-Speech auszugeben.

RHASSPY verwendet das Modul 00_MQTT2_CLIENT.pm um Nachrichten zu empfangen und zu senden. Daher ist es notwendig, eine Instanz dieses Moduls als FHEM-Device zu erstellen, bevor RHASSPY verwendet werden kann.

Hervorgegangen ist RHASSPY aus dem Snips-Modul, nachdem Snips an Sonos verkauft und anschließend eingestellt wurde. Danke also an Thyraz, der die grundlegenden Arbeiten erledigt hat!

=== Konventionen ===
{{Hinweis| In diesem Artikel und der CommandRef werden folgende Schreibweisen verwendet:
* '''[[RHASSPY]]''' bezieht sich auf das FHEM-Modul
* '''rhasspy''' bezieht sich auf das das FHEM-Device
* '''Rhasspy''' bezeichnet die (zentrale) Serverinstallation}}

{{Hinweis|Dialoge werden in RHASSPY verwaltet wie [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager hier] beschrieben. Dialoge werden also nicht funktionieren, sobald für das Dialogue-Management etwas anderes als ''RHASSPY'' eingestellt ist}}

=== Erste Schritte ===
Die Installation und Erstinbetriebnahme von Rhasspy wird in einer Schnellstart-Anleitung erklärt: [[RHASSPY/Schnellstart]] Diese Anleitung sollte auch befolgt werden, wenn man sich sehr gut mit FHEM auskennt. Wer dies erfolgreich absolviert hat, kann gleich zu Abschnitt [[#Set-Befehle_.28SET.29|Set-Befehle (SET)]] weiterspringen, und/oder die [[RHASSPY/Vertiefung|Vertiefung]] durcharbeiten.

=== Details zur Verwaltung 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.

*Im Subversion Repository, kurz 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, heruntergeladen werden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/10_RHASSPY.pm', 'FHEM/10_RHASSPY.pm') }</syntaxhighlight>
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 bzw. zu aktualisieren, kann der ''update''-Mechanismus von FHEM genutzt werden. Dazu muss das Repository in der Liste der vom update-Befehl verarbeiteten Repositorien aufgenommen werden:
<syntaxhighlight lang="perl">update add https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

Anschließend kann mit folgendem Befehl das Modul installiert oder aktualisiert werden:
<syntaxhighlight lang="perl">update all https://raw.githubusercontent.com/fhem/fhem-rhasspy/main/controls_fhem-rhasspy.txt</syntaxhighlight>

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 [https://fhem.de/commandref.html#update CommandRef] oder im [[Update|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:
<syntaxhighlight lang="perl">define <deviceName> MQTT2_CLIENT <ip-oder-hostname-des-mqtt-servers>:<port></syntaxhighlight>

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 <code>RHASSPY</code>. Ansonsten müssen noch alle anderen Devices (z.B. <code>MQTT_GENERIC_BRIDGE</code>, <code>MQTT2_DEVICE</code>) angegeben werden.
<syntaxhighlight lang="perl">attr <deviceName> clientOrder RHASSPY [device2] [device3]</syntaxhighlight>

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 <code>setByTheProgram</code>. Ansonsten müssen alle für RHASSPY notwendigen Topics eingefügt werden.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions setByTheProgram</syntaxhighlight>
bzw.
<syntaxhighlight lang="perl">attr <deviceName> subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say </syntaxhighlight>

;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.
<syntaxhighlight lang="perl">
defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram
</syntaxhighlight>
*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.
<syntaxhighlight lang="perl">
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 hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say [zusätzliche Subscriptions für andere MQTT-Module]
</syntaxhighlight>

== Definition von RHASSPY (DEF)==
<syntaxhighlight lang="perl">define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <encoding></syntaxhighlight>
{{Randnotiz|RNTyp=Info|RNText=RHASSPY 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.).}}{{Randnotiz|RNTyp=Info|RNText=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.}}
Alle Parameter sind '''optional'''. Die meisten werden im Normalfall gar nicht benötigt (z.B. <code>fhemId</code>, <code>prefix</code>). 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 <code>language</code>, möchte man eine andere Sprache als Englisch oder Deutsch verwenden.

;<code id="def-baseurl">baseUrl</code>
: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 <code>baseUrl=http://127.0.0.1:12101</code>.
;<code id="def-devspec">devspec</code>
:devspec der Geräte, die mit Rhasspy gesteuert werden sollen. Wenn der ''genericDeviceType''-Support aktiviert ist, ist der Default <code>devspec=genericDeviceType=.+</code>, sonst wird <code>devspec=room=Rhasspy</code> 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. <code>devspec=room=livingroom,room=bathroom,bedroomlamp</code>) verwendet werden können, finden sich in der [https://commandref.fhem.de/commandref.html#devspec CommandRef].
;<code id="def-defaultroom">defaultRoom</code>
: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 <code>defaultRoom=default</code>.
;<code id="def-language">language</code>
:Sprache, in der mit Rhasspy gesprochen wird. Der Standard-Wert hängt vom ''global''-Device ab. Dieser ist standardmäßig <code>language=en</code>.
;<code id="def-fhemid">fhemId</code>
: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 <code>fhemId=fhem</code>.
;<code id="def-prefix">prefix</code>
: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 <code>prefix=rhasspy</code>.
;<code id="def-usegenericattrs">'''useGenericAttrs'''</code>
:Ü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 <code>useGenericAttrs=1</code>.
;<code id="def-encoding">encoding</code>
:Sollte es Probleme mit Umlauten geben, kann das Character-Encoding geändert werden. Default ist <code>encoding=utf8</code>.
;<code id="handlehotword">handleHotword</code>
:Triggert das Reading ''hotword'', wenn ein Hotword erkannt wurde (und erstellt das Reading, falls noch nicht vorhanden). Weitere Informationen dazu stehen beim Attribut [[#attr-rhasspyhotwords|''rhasspyHotwords'']]. Default ist <code>handleHotword=0</code>

{{Hinweis|Nach dem Definieren eines RHASSPY-Modules sollte das IODev manuell gesetzt werden um ein automatische IO-Zuweisung zu verhindern. Z.B. <code>attr <deviceName> IODev <m2client></code>.}}

;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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY</syntaxhighlight>

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:
<syntaxhighlight lang="perl">define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1</syntaxhighlight>

==Set-Befehle (SET)==

;<code id="set-customslot">customSlot</code>
:Erstellt einen neue - oder überschreibt einen alten - Slot in Rhasspy
:<code>slotname</code> und <code>slotdata</code> sind verpflichtend
:<code>overwrite</code> ist optional. Default ist <code>overwrite=true</code>. Das Setzen eines anderes Wertes verhindert das Überschreiben einen bereits bestehenden Slot mit gleichem Namen.
:<code>training</code> ist optional. Default ist <code>training=true</code>. Das Setzen eines anderen Wertes verhindert ein Training von Rhasspy nach dem Speichern des Slots.

:'''Beispiele:'''
:<code>set <rhasspyDevice> customSlot mySlot a,b,c overwrite training</code>
:<code>set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false</code>

;<code id="set-fetchsiteids">fetchSiteIds</code>
:Liest alle in Rhasspy vorhandenen siteIDs aus und speichert sie im Reading ''siteIds''. Wird z.B. verwendet, um festzustellen, auf welchem Satelliten der User über das Ende eines Timers benachrichtigt werden soll.
:Muss immer ausgeführt werden, wenn eine neue siteId in Rhasspy hinzugefügt wird (neuer Satellit z.B.).
:'''Beispiel:'''
:<code>set <rhasspyDevice> fetchSiteIds</code>

;<code id="set-play">play</code>
:Sendet eine WAV Datei an Rhasspy.
:<code>siteId</code> 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:'''
:<code>set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"</code>
:<code>set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20</code>

;<code id="set-speak">speak</code>
:Sendet einen Text an das TTS-Sytem, welches ihn dann als Sprache ausgibt.
:Beide Argumente <code>siteId</code> und <code>text</code> sind verpflichtend!
:'''Beispiel:'''
:<code>set <rhasspyDevice> speak siteId="wohnzimmer" text="This is a test"</code>

;<code id="set-textcommand">textCommand</code>
:Sendet ein Text-Kommando an Rhasspy.
:'''Example:'''
:<code>set <rhasspyDevice> textCommand schalte das licht ein</code>

;<code id="set-trainrhasspy">trainRhasspy</code>
:Startet das Training von Rhasspy.
:'''Beispiel:'''
:<code>set <rhasspyDevice> trainRhasspy</code>

;<code id="set-update">update</code>
:;<code id="set-update-devicemap">devicemap</code>
::Wenn an der Konfiguration von RHASSPY oder an den von ihm gesteuerten Geräten etwas geändert wurde, muss dieser Befehl ausgeführt werden, um die Datenstruktur von RHASSPY zu aktualisieren, Rhasspy von den Änderungen zu informieren (Slots z.B.), ein Training zu starten, etc.
::''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap</code>

:;<code id="set-update-devicemaponly">devicemap_only</code>
::Aktualisiert die Datenstruktur von RHASSPY. Es werden weder Slots in Rhasspy geändert, noch das Training gestartet.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update devicemap_only</code>

:;<code id="set-update-slots">slots</code>
::Aktualisiert (bzw. erstellt) alle Slots in Rhasspy mit den aktuellen Geräten, Räumen, usw.
::Erstellte/Aktualisierte Slots sind z.B.:
::*de.fhem.AllKeywords
::*de.fhem.Device
::*de.fhem.Device-''genericDeviceType''
::*de.fhem.Device-''Intent''
::*de.fhem.Group
::*de.fhem.Room
::*de.fhem.MediaChannels
::*de.fhem.Color
::*de.fhem.NumericType
::(Hinweis: Die ersten beiden Teile ''de'' und ''fhem'' hängen von der DEF des RHASSPY-Devices ab)
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots</code>

:;<code id="set-update-slotsnotraining">slots_no_training</code>
::Wie <code>slots</code>, aber ohne Training nach dem Update.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update slots_no_training</code>

:;<code id="set-update-language">language</code>
::Liest das das Sprach-File (''languageFile'') neu ein.
::Muss immer ausgeführt werden, wenn in diesem File oder dem Attribut ''languageFile'' etwas geändert wurde!
::'''Beispiel:'''
::<code>set <rhasspyDevice> update language</code>

:;<code id="set-udpate-intentfilter">intent_filter</code>
::Setzt die Intent Filter, die vom Rhasspy Dialogue Manger verwendet werden zurück. Details dazu bei [[#attr-rhasspytweaks-intentfilter|intentFilter]] im ''rhasspyTweaks''-Attribut.
::'''Beispiel:'''
::<code>set <rhasspyDevice> update intent_filter</code>

:;<code id="set-update-all">all</code>
::Aktualisiert die Devicemap und das languageFile
::'''Beispiel:'''
::<code>set <rhasspyDevice> update all</code>

;<code id="set-volume">volume</code>
::Stellt die Lautstärke der gewünschten siteId auf einen Wert zwischen 0 and 1 (float).
::Beide Argumente <code>siteId</code> <code>volume</code> sind verpflichtend.
::'''Beispiel:'''
::<code>set <rhasspyDevice> siteId="default" volume="0.5"</code>

{{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 [[#FHEM-Devices für die Verwendung mit Rhasspy konfigurieren|FHEM-Devices für die Verwendung mit Rhasspy konfigurieren]] behandelt.

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

===IODev===
Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
'''Beispiel:'''
<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

===forceNEXT===
Wenn dieses Attribut auf 1 gesetzt ist, leitet RHASSPY eingehende MQTT-Nachrichten an andere MQTT2-IO-Client Module wie MQTT2_DEVICE weiter, auch wenn das Topic zu einem von RHASSPY abonnierten passt.
Standardmäßig werden diese Nachrichten nicht weitergeleitet um eine bessere Kompatibilität mit dem ''autocreate''-Feature des MQTT2_DEVICE sicher zu stellen.
Siehe dazu das {{Link2CmdRef|Anker=MQTT2_CLIENT-attr-clientOrder|Lang=en|Label=clientOrder}}-Attribut in der CommandRef zum MQTT2_CLIENT Device.
Das Setzen dieses Attributs in einer RHASSPY-Instanz kann auch andere eventuell vorhandene RHASSPY-Instanzen beinflussen.
Default ist <code>0</code>

'''Beispiel:'''
<code>attr <rhasspyDevice> forceNext 1</code>

===languageFile===
{{Randnotiz|RNTyp=g|RNText=Bei Nutzung von configDB wird diese Datei aus der Datenbank gelesen.}}
Pfad zur Sprach-Datei
Ist dieses Argument nicht gesetzt, wird ein Standard-Set an englischen Sätzen für die Sprachantworten verwendet.
Die Datei selbst muss ein gültiges JSON-File sein, dass sich nach der Struktur aus den englischen Standardwerten richtet.
Eine deutsche Beispiel-Datei ist in [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/RHASSPY/rhasspy-de.cfg SVN] und [https://github.com/fhem/fhem-rhasspy/blob/dev/FHEM/rhasspy-de.cfg GitHub] vorhanden. Man kann aber einfach ein Dump der englischen Struktur machen (replace RHASSPY by your device's name: <code>{toJSON($defs{RHASSPY}->{helper}{lng})}</code>, das Ergebnis dann bearbeiten und es als eigenes languageFile verwenden.
Im Standard-Set sind auch einige Variablen enthalten. Auch die können im eigenen File verwendet werden.
''languageFile'' erlaubt auch eine Kombination aus vorhandenen und eigenen Sätzen. Dazu können die eigenen Sätzen einfach im Sub-Tree ''user'' abgelegt werden.

'''Beispiel:''' (vorausgesetzt, die Sprach-Datei ist im selben Verzeichnis wie fhem.pl):
<code>attr <rhasspyDevice> languageFile ./rhasspy-de.cfg</code>

====response====
{{Hinweis|Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.}}


===rhasspyHotwords===
Kann verwendet werden, um benutzerdefinierte Aktionen auszuführen, sobald ein bestimmtes Hotword erkannt wurde. Dazu sind keine speziellen Konfigurationsschritte in anderen FHEM Devices notwendig.
Wenn mittels Attribut oder DEF aktiviert, wird ein Reading ''hotword'' erstellt und mit dem erkannten Hotword und der siteId befüllt um ein Event-Handling zu ermöglichen.
{{Hinweis|Da bei den hotword messages für alle Teilnehmer dieselbe Topic-Structur verwendet wird, kann RHASSPY nicht unterscheiden, ob eine solche für diese Instanz relevant ist. Falls entsprechende Unterscheidungen gemacht werden sollen, muss dies vom User entsprechend konfiguriert werden, z.B. indem die subscriptions (am MQTT2_CLIENT) eingeschränkt werden oder indem nur jeweils andere hotword-Einträge für jede RHASSPY-Instanz genutzt werden.}}
Ein Hotword pro Zeile, Syntax entweder einfach oder erweitert

'''Beispiele:'''
:<code>bumblebee_linux = set amplifier2 mute on</code>
:<code>porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}</code>

Im ersten Beispiel wird der Befehl immer ausgeführt, wenn das Hotword ''bumblebee_linux'' erkannt wurde.
Im zweiten nur, wenn das Hotword ''porcupine_linux'' in der siteId ''livingroom'' erkannt wurde.
$DEVICE wird ausgewertet als der Name des RHASSPY Devices, $ROOM als siteId und $VALUE als das verwendete Hotword.

===rhasspyIntents===
Definiert einen benutzerdefinierten Intent.
Ein Intent pro Zeile.
'''Beispiel:'''
:<code>attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)</code>
in Kombination mit folgendem myUtils-Code
<syntaxhighlight lang="perl">
sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}</syntaxhighlight>
schreibt einen Log-Eintrag nach jedem Aufruf dieses Intents.

Die folgenden Argumente können dabei übergeben werden:
* NAME => Name des RHASSPY-Devices
* DATA => komplette JSON-$data (wie intern geparsed), in JSON kodiert
* siteId, Device etc. => jedes Element, das in JSON-$data existiert
Wird von der Funktion ein einfacher Text zurück geliefert, wird dieser als ''response'' angesehen. Wenn der Rückgabewert nicht definiert ist, wird die Standard-''response'' verwendet.

Es kann aber auch ein '''HASH''' oder '''ARRAY''' übergeben werden.
* Im Falle eines '''ARRAY'''s wird das erste Element als ''response'' interpretiert und kann ein reiner Text sein, womit der Dialog beendet wird.
* Ist das erste Element ein '''HASH'' wird die Dialog-Session fortgesetzt. Eine offene Dialog-Session wird per Default nach 20 Sekunden beendet. Diese Zeitspanne kann aber auch geändert werden, in dem im ARRAY als zweiter Wert eine Zahl übergeben wird. Das zweite Element kann aber auch eine komma-getrennte Liste an Geräten sein, die geändert (geschalten) wurden. Das dient dazu, damit die Geräte auch Events liefern, was ansonsten nicht der Fall wäre. Siehe dazu den "d"-Parameter beim Attribut [[#attr-rhasspyshortcuts|rhasspyShortcuts]].
Wird eine HASH-Datenstruktur (ggf. in $response innerhalb einer ARRAY-Struktur), um einen laufenden Dialog fortzusetzen, muss sichergestellt werden, dass alle erforderlichen Datenelemente enthalten sind, insbesondere ''intentFilter'', falls die für den weiteren Dialog relevanten Intents eingeschränkt (oder erweitert) werden sollen. Dabei sollte möglichst der Intent ''CancelAction'' aktiv gehalten werden, damit der User die Option hat, den Dialog jederzeit aktiv zu beenden.

Siehe dazu auch den Abschnitt [[#Eigene Intents erstellen]].

===rhasspyShortcuts===
Hiermit können benutzerdefinierte Sätze erstellt werden ohne die sentences.ini in Rhasspy bearbeiten zu müssen.
Diese Shortcuts werden zu Rhasspy hochgeladen, sobald das <code>updateSlots</code> [[#set-update|Set]]-Kommando ausgeführt wird.
Ein Shortcut pro Zeile, Syntax ist entweder einfach oder erweitert.
'''Beispiele:'''
:<code>mute on=set amplifier2 mute on</code>
:<code>lamp off={fhem("set lampe1 off")}</code>
:<code>i="du bist cool" f="set $NAME speak siteId='livingroom' text='danke dir! du bist noch viel cooler!'"</code>
:<code>i="schalte den ton aus" p={fhem ("set $NAME mute off")} n=amplifier2 c="soll ich den ton wirklich ausschalten?"</code>
:<code>i="ich hab hunger" f="set Herd on" d="Herd" c="möchtest du schweinsbraten?"</code>

Erklärung zu den Abkürzungen:
* <code>i</code> => intent
Zeilen, die mit <code>i</code> beginnen, werden als erweiterte Syntax interpretiert. Soll die erweiterte Syntax verwendet werden, ist das <code>i</code> also Pflicht!
* <code>f</code> => FHEM Befehl
Syntax wie von der FHEM Kommandozeile gewohnt
* <code>p</code> => Perl Befehl
Syntax wie von der FHEM Kommandozeile gewohnt, eingerahmt in geschwungenen Klammern (<code>{}</code>). <code>p</code> hat Vorrang vor <code>f</code>
* <code>d</code> => Device Name(en, Komma getrennt)
Device Name(n), die an fhem.pl als upgedated übergeben werden sollen. Das wird benötigt um weitere Aktionen in FHEM und das Longpolling zu triggern.

Hinweis: Wenn Perl-Funktionen aufgerufen werden, wird der Rückgabewert dieser Funktion verwendet, sofern kein explizites Device angegeben ist.
* <code>r</code> => Response
Sprachanwort, die ausgegeben wird. Ist <code>r</code> nicht gesetzt, wird der Rückgabewert der aufgerufenen Funktion verwendet.
In den Antwortsätze werden ''set magic''-ähnliche Ersetzungen verarbeitet. Es ist also auch eine Zeile wie <code>i="what's the time for sunrise" r="at [Astro:SunRise] o'clock"</code> gültig.

Mit den folgenden Abkürzungen kann auch nach einer Bestätigung für den Befehl gefragt werden:
* <code>c</code> => Entweder Zahl oder Text. Wenn Zahl, wird sie als Timeout für den Abbruch des Dialogs behandelt. Wenn Text wird dieser als Sprachausgabe zur Bestätigung verwendet.
* <code>ct</code> => Numerischer Wert für das Timeout des Dialogs in Sekunden. Default ist <code>15</code>.
Siehe [[#attr-rhasspytweaks-confirmintents|hier]] für weitere Informationen zu Bestätigungen.

===rhasspyTweaks===
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

====timerLimits====
Wird verwendet um den Timer anzuweisen mit z.B. "gestellt auf 30 Minuten" oder "gestellt auf 10:30" zu antworten
:<code>timerLimits=90,300,3000,2*HOURSECONDS,50</code>
Hierbei müssen fünf Werte gesetzt werden, die den Zeitgrenzen für Stufen in der Antwortstruktur ''timerSet'' entsprechen.
Obiges Beispiel also würde dazu führen, unter einer eingestellten Zeit von 90 Sekunden mit der Sekundenangabe geantwortet wird. In Minuten und Sekunden solange der Timer kürzer als 300 Sekunden ist. Usw. Der letzte Wert ist das Limit in Sekunden, wenn der Timer im "Uhrzeit"-Format gestellt ist.

====timerSounds====
Standardmäßig antwortet der Timer mit einer Sprachnachricht, wenn er abgelaufen ist. Soll lieber eine WAV-Datei verwendet werden, kann das hier eingestellt werden.
:<code>timerSounds= default=./yourfile1.wav eier=3:20:./yourfile2.wav kartoffeln=5:./yourfile3.wav</code>
Die Keys in dieser Code-Zeile sind Beispiele und deren Name - bis auf <code>default</code> frei wählbar. Der Name muss aber zu den ''Label''-Tags für die Timer in den Rhasspy-Sentences passen.
<code>default</code> ist optional. Wenn gesetzt, wird dieses WAV-File für alle benannten Timer verwendet, für die kein Keyword in der Konfiguration ist.
Die beiden Nummern sind optional. Die erste legt fest, wie oft die WAV-Datei wiederholt werden soll (Default: 5). Die zweite definiert die Pause in Sekunden zwischen den Wiederholungen (Default: 15). Ist nur eine Zahl gesetzt, wird diese als gewünschte Anzahl an Wiederholungen interpretiert.

====updateSlots====
Ändert diverse Aspekte des Erstellens und Updatens von Slots
* <code>noEmptySlots=1</code>
Per Default generiert RHASSPY einen zusätzlichen Slot für jeden ''genericDeviceType'', der erkannt wird. Unabhängig davon, ob er bei einem Gerät gesetzt ist. Das kann zu leeren Slots führen.
Ist der Wert <code>1</code>, werden keine leeren Slots erstellt.
* <code>overwrite_all=false</code>
RHASSPY überschreibt alle vorhandenen Slots wenn ein <code>updateSlots</code> ausgeführt wird. Ist das nicht gewünscht, muss dieser Wert auf <code>false</code> gesetzt werden.
* <code>timeouts</code>
Die Keywörter <code>confirm</code> und <code>default</code> können verwendet werden, um das Standard-Timeouts (15s/20s) für Dialoge zu ändern.
'''Beispiel:'''
<code>timeouts: confirm=25 default=30</code>

====confidenceMin====
Rhasspy ermittelt u.A. auch einen Indikator, anhand dem bestimmt werden kann, wie genau ein Satz erkannt wurde. Ist dieser ''confidence''-Wert sehr bzw. zu niedrig, kann es erwünscht sein, die (falsch erkannte) Absicht des Sprechers nicht umzusetzen. RHASSPY nutzt daher standardmäßig einen Mindestwert von 0.66, bei allen darunter liegenden Werten wird das betreffende Kommando nicht ausgeführt. Dies kann über diesen Tweak global (key: default) oder feiner pro Intent festgelegt werden.
Beispiel:
<code>confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8</code>

====confirmIntents====
Hiermit kann eingestellt werden, dass für bestimmte Intents immer ein Bestätigung erfragt wird. Unterstützt werden derzeit alle "set-"-Intents.
Dazu werden <code>Intent</code>=<code>regex</code>-Paare verwendet. <code>Intent</code> ist der Name des gewünschten Intents, <code>regex</code> ist eine Regex, die eine bestimmte Gruppe (für Gruppen-Intents) oder einen bestimmten Device-Namen beschreiben muss.
'''Beispiel:'''
<code>confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*</code>
Befehle werden nur nach einer positiven Bestätigung ausgeführt. Das bedeutet, es wird eine Rückfrage ausgegeben, auf diese muss dann (innerhalb des gesetzten Timeouts) unbedingt ein <code>Mode:OK</code>-Wert vom ''ConfirmAction''-Intent gesendet werden. Jede andere Wert für <code>Mode</code> wird als Abbruch gewertet. Es kann aber auch der eigene Intent ''CancelAction'' für den Abbruch verwendet werden.
'''Beispiel:'''

<syntaxhighlight lang="ini">
[de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}

[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
</syntaxhighlight>

====confirmIntentResponses====
Üblicherweise ist die Bestätigungs-Frage ein "Echo" des ursprünglich gesprochenen Befehls. Dies kann für jeden Intent geändert werden,
Dies kann für jeden Intent individuell angepaßt werden, wobei die Variablen $target, ($rawInput) und $Value verwendet werden können.
'''Beispiel:'''
<code>confirmIntentResponses=SetOnOffGroup="wirklich die Gruppe $target $Value schalten" SetOnOff="bestätige dass $target $Value geschaltet werden soll"</code>
<code>$Value</code> wird dabei mit den defaults aus dem ''words'' key in der languageFile übersetz (falls vorhanden). Weitere Optionen für Ersetzungen von <code>$Value</code> sind für einzelne Devices über den [[#attr-rhasspyspecials-confirmvaluemap|confirmValueMap]] key im Attribut ''rhasspySpecials'' verfügbar.

====intentFilter====
Rhasspy aktiviert bei jedem Neustart alle ihm bekannten Intents. Da manche der von FHEM genutzten Intents nur in bestimmten Situationen (v.a. innerhalb offener Dialoge) benötigt werden, deaktiviert RHASSPY diese (derzeit: ConfirmAction, CancelAction, Choice, ChoiceRoom und ChoiceDevice beim Start, sowie jedes Mal, wenn erkannt wird, dass das Standardfiltering nicht wie erwartet funktioniert (was v.a. bei einem zwischenzeitlichen Rhasspy-Neustart der Fall sein kann). Über diesen Tweak können weitere Intents mit in diese automatisierte (De-) Aktivierung mit einbezogen werden. Entweder ist dabei einfach der Name (ohne die Zusätze aus ''language'' und ''fhemId'' anzugeben, oder eine explizite Anweisung zum ein- und Ausschalten (in der Form <code>intentname=true</code>). Die 4 vorgenannten Standard-Intents können nicht über diesen Weg aktiviert werden. Details zur intern genutzten Rhasspy-Funktionalität sind in der [https://rhasspy.readthedocs.io/en/latest/reference/#dialogue-manager Rhasspy-Dokumentation] zu finden.

====ignoreKeywords====
Da in manchen der von RHASSPY automatisch ausgewerteten Attribute häufig auch eher technisch motivierte Angaben zu finden sind, kann über diesen Schlüssel verhindert werden, dass derartige Angaben bei der slot-Erstellung übergangen werden. Dies betrifft z.B. häufig anzutreffende ''room''-Werte wie ''MQTT'', ''alexa'', ''homebridge'' oder ''googleassistant''. Die hier angegebenen key-value-Paare werden als Negativ-Filter für die angegebenen Werte verwendet (derzeit nur für ''rooms'' und ''group''). ''value'' wird dabei als (case-insensitive) regex behandelt, verglichen wird auf exakten match (es müssen also ggf. vorne bzw. hinten ''.*'' angefügt werden).
Dieses '''Beispiel''' filtert daher die o.g. Räume aus und dazu noch die strukturierten Unterräume unterhalb ''Steuerung'':

<code>ignoreKeywords=rooms=mqtt.*|alexa|homebridge|googleassistant|steuerung-.</code>

====gdt2groups====
Dieser Eintrag ermöglicht es, alle Geräte eines generichDeviceType innerhalb der automatischen Erfassung automatisch einer oder mehreren Gruppen zuzuordnen. Die Vorgaben in diesem Eintrag werden nicht übernommen, wenn am jeweiligen Einzelgerät das Attribut ''rhasspyGroup'' gesetzt ist. Hier eine deutschsprachige Vorbelegung als '''Beispiel''': <code>gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten</code>

====mappingOverwrite====
Wird diese Option aktiviert, wird bei gesetztem ''rhasspyMapping''-Attribut an einem Device alles gelöscht, was die automatisierte mapping-Erkennung anhand des genericDeviceType erkannt hatte. Sonst ird jeweils nur überschrieben, was als Intent im ''rhasspyMapping'' dieses Geräts angegeben ist.

Syntax:
:mappingOverwrite=1

====extrarooms====
Komma-separierte Liste von weiteren Räumen, die die aus der Generierung der Device-Map bekannten Räume erweitert. Dies kann z.B. für CustomIntents benötigt werden.
Diese werden in die Slots für <code>rooms</code> und <code>mainrooms</code> integriert.
Beispiel:
:extrarooms= barn,music collection,cooking recipies

==Readings / Events==
;<code>IODev</code>
:Das eingestellte IO-Device
;<code>intents</code>
:Eine Liste der in Rhasspy vorhandenen Intents
;<code>lastIntentPayload</code>
:Inhalt des letzten Intents der von FHEM empfangen wurde
;<code>lastIntentTopic</code>
:Das MQTT-Topic des letzten Intents
;<code>listening_roomname</code>
:Ein Reading für jeden Raum bzw. jede siteId
:Wechselt auf 1 sobald ein Hotword erkannt wurde und zurück auf 0, sobald die Dialog-Session beendet ist.
:Kann z.B. verwendet werden, um den Ton eines TVs auszuschalten, während Rhasspy auf ein Kommando hört.
;<code>mute_roomname</code>
:Zeigt an, ob ein Raum / eine siteId vom Intent ''SetMute'' stumm geschalten wurde und somit keine Befehle ausführt.
:Jeweils ein Reading für jede siteId.
:Default ist 0.
;<code>responseType</code>
:Der Typ der letzten Antwort (text/voice).
:voiceResponse and textResponse
:Antwort auf das letzte Sprach-/Text-Kommando.
;<code>siteIds</code>
:Listet alle siteIds auf.
:Kann mit [[#set-fetchsiteids|fetchSiteIds]] aktualisiert werden.
;<code>state</code>
:Zeigt an ob RHASSPY mit Rhasspy verbunden ist
;<code>training</code>
:Letzte zurückgelieferte Antwort auf einen [[#set-trainrhasspy|trainRhasspy]]-Befehl.

;<code>updateSlots</code>
:Letzte zurückgelieferte Antwort nach einem [[#set-update-slots|updateSlots]]-Befehl.
;<code>hotword</code>
:Wenn aktiviert, beinhaltet dieses Reading das letzte verwendete Hotword und von welcher siteId es aufgerufen wurde.
;<code>voiceResponse</code>
:Letze Sprach-Antwort auf einen Sprach-Befehl

=== Benutzerdefinierte Readings ===

There are some readings you may find useful to tweak some aspects of RHASSPY's logics:
*<code>siteId2room_</code> Falls keine explizite Raum-Information in den an RHASSPY weitergegebenen Daten enthalten ist, ermittelt das Modul den Raum in der Regel aus dem Namen der ''siteId''. So werden z.B. alle raumlosen Anweisungen von einem Satelliten names ''schlafzimmer'', im Raum ''schlafzimmer'' ausgeführt werden (wenn möglich). Die Gruppenfunktion von Rhasspy wird unterstützt, so wird z.B. ''wohnzimmer.vorne'' ebenfalls automatisch dem Raum ''wohnzimmer'' zugeordnet. Über passende Angaben in ''siteId2room-Readings'' kann dieses Verhalten modifiziert werden: <code>setreading siteId2room_mobile_phone1 wohnzimmer</code> wird RHASSPY veranlassen, den Satelliten ''mobile_phone1'' dem Raum ''wohnzimmer'' zuzuweisen. Hierzu ist in ''contrib'' auch eine Hilfsfunktion zu finden, mit der mobilen Satelliten per Sprachbefehl einem neuen Raum zugewiesen werden können.
*<code>siteId2doubleSpeak_</code> RHASSPY antwortet immer über den Satelliten, von dem die jeweilige Sprachanweisung kam. Manchmal kann es erwünscht sein, zusätzliche Sprachrückmeldungen an einen weiteren Satelliten zu geben - z.B. weil der betreffende Lautsprecher (zeitweise) ausgeschaltet ist. Ist ein entsprechendes Reading gesetzt, erfolgen (zusätzliche!) Sprachausgaben an den dort als Readingwert angegebenen zweiten Satelliten; das Namensschema der Readings entspricht dem für site2room.

== FHEM-Devices für die Verwendung mit Rhasspy konfigurieren ==
Um ein Gerät mit Rhasspy steuern zu können, muss Rhasspy einige Details über das Gerät kennen. Diese werden bekannt gemacht, in dem bei den Geräten Attribute gesetzt werden, die anschließend vom RHASSPY-Modul ausgewertet und an Rhasspy gesendet werden.

Der einfachste - und empfohlene - Weg, dies zu erreichen, ist durch Setzen des Attributs '''''genericDeviceType'''''. Das Modul erkennt dann die möglichen Schalt - und Abfragemöglichkeiten des Gerätes automatisch.

Sollte ''genericDeviceType'' (gDT) nicht ausreichen, gibt es noch weitere Attribute, die stattdessen oder ergänzend dazu verwendet werden können (z.b. rhasspyName, rhasspyRoom, ...). Die Namen dieser Attribute beginnen alle mit dem ''prefix'', das in der DEF des RHASSPY-Moduls gesetzt wurde. Diese Dokumentation verwendet das Prefix <code>rhasspy</code>.

Sind sowohl ''genericDeviceType'' als auch Spezial-Attribute vorhanden, werden die von gDT gesammelten Möglichkeiten durch die der Spezial-Attribute überschrieben.

'''Wichtig:'''
*Nach JEDER Änderung an den folgenden Attributen muss ein <code>[[#set-update-devicemap|update devicemap]]</code> ausgeführt werden. Sonst erfahren weder RHASSPY, noch Rhasspy von der Änderung.
*RHASSPY sammelt alle Informationen aus diesen Attributen in seinem eigenen Device-HASH. Dieser wird durch das <code>update devicemap</code>-Kommando aktualisiert und kann mittels <code>[[List|list]]</code>-Befehl angezeigt werden. Für diesen HASH werden alle Namen und sonstige "Labels" in Kleinbuchstaben umgewandelt. Sollte man Slots händisch befüllen, muss also darauf geachtet werden, dass Rhasspy ebenfalls Werte in Kleinbuchstaben liefert.
*Die Mindestvoraussetzungen für ein FHEM Device um mit RHASSPY zusammenzuarbeiten sind:
**Das Device muss von der devspec im Define des RHASSPY-Devices abgedeckt werden
**Es muss mindestens eines der folgenden Attribute (im Normalfall ''genericDeviceType'') im Device gesetzt sein.
*Die Mapping-Logik (für Namen, mögliche Schaltzustände, etc.) ist wie folgt:
**Sind RHASSPY-spezifische Attribute gesetzt, werden ausschließlich diese verwendet. Natürlich nur für den Zweck des gesetzten Attributs. Ein gesetzter ''rhasspyName'' z.B. wird also nicht verhindern, dass die durch ''genericDeviceType'' ermittelten möglichen Schaltzustände ebenfalls gespeichert werden.
**Je spezifischer ein Attribut ist, desto eher wird überschreiben, was weniger speziell ist. Ein gesetzter ''alias'' wird also verhindern, dass der (technische) Device-Name verwendet wird. Aber ein gesetztes Attribut ''alexaName'', ''gassistantName'' oder ''siriName'' wird (auch) den ''alias'' überschreiben. Sind zwei "gleichwertige" Attribute vorhanden (z.B. ''siriName'' und ''alexaName''), werden beide verwendet.
*Attribut-Werte werden typischerweise "Zeile für Zeile" gelesen. Wobei gilt, eine Zeile pro Wert/Befehl/Funktionalität. Zeilenumbrüche '''müssen''' also an den richtigen Stellen gesetzt werden.

===<code>genericDeviceType</code>===

Ist dieses Attribut gesetzt '''und''' entspricht der Devicename der devspec, wird RHASSPY das Mapping (und andere eventuell schon vorhandene Werte) automatisch ermitteln.

Derzeit werden folgende Werte für das Attribut genericDeviceType unterstützt:
*switch
*light
*thermostat
*thermometer
*HumiditySensor
*blind/blinds/shutter
*media
*motion/contact/ContactSensor/lock/presence

Wird ''genericDeviceType'' verwendet, werden unter anderem folgende Informationen gesammelt:
* der Name (<code>NAME</code> oder <code>alias</code>) des Devices
* der (FHEM-)Raum, in dem sich das Device befindet.
* die Gruppe, zu der das Device gehört (ggf. unter Beachtung des Schlüssels <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> aus ''rhasspyTweaks'')
* wie Informationen vom Gerät abgefragt werden können
* wie Werte/Status am Gerät gesetzt werden können

Die Verwendung von ''genericDeviceType'' ist der einfachste Weg, wie man FHEM-Devices dazu bringen kann, mit RHASSPY zusammenzuarbeiten. Manchmal liefert genericDeviceType aber nicht ausreichende oder nicht passende Informationen. In so einem Fall können die folgenden Attribute (zusätzlich) verwendet werden.

===<code>rhasspyName</code>===
Mit diesem Attribut kann der Name des Geräts eingestellt werden, mit dem es in einem Sprachbefehl angesprochen werden soll. Es können auch mehrere Namen - getrennt durch ein Komma - angegeben werden.

'''Beispiel:''' <code>attr <device> rhasspyName Lampe,Stehlampe,Wunderlicht</code>

Es ist durchaus möglich, mehrere FHEM-Geräte mit dem selben Namen zu haben. Sie müssen dann nur in unterschiedlichen Räumen sein.

===<code>rhasspyRoom</code>===
Dieses Attribut kann verwendet werden, um Rhasspy mitzuteilen, in welchem physischem (oder logischen) Raum sich das Gerät befindet.

Ist es nicht vorhanden, wird <code>alexaRoom</code> oder das FHEM-Attribut <room> verwendet. Sind auch diese nicht vergeben, gehört das Gerät zum "Standard-Raum", der im Define des RHASSPY-Devices angegeben wurde.

Das Attribut ist nützlich, wenn man Sprachbefehle ohne explizite Raumangabe verwenden will. Gibt es z.B. ein Gerät mit dem Namen ''Lampe'' und dessen rhasspyRoom-Attribut ist gleich, wie die ''siteId'' von der aus der Sprachbefehl abgesetzt wird, reicht es zu sagen "Lampe ein". Der Raum muss also nicht extra dazu gesagt werden.

Es ist auch möglich, mehrere Raum-Namen zu vergeben sofern diese durch ein Komma voneinander getrennt werden.

'''Beispiel:''' <code>attr <device> rhasspyRoom livingroom</code>

Hinweis: Wenn die ''siteId'' den Konventionen von Rhasspy zur Gruppierung von siteIds folgt (''roomname.satellite''), wird nur <code>roomname</code> als Raum-Name angenommen. Beachte: Die automatisierte Zuweisung zu einem Raum kann durch ''siteId2room_.*''-Readings modifiziert werden (s.o.).
===<code>rhasspyGroup</code>===
Kommagetrennte Liste an Gruppen, zu denen das Gerät zugehörig ist

'''Beispiel:''' <code>attr <device> rhasspyGroup Lampen,Beleuchtung Arbeitsfläche,Küchen Beleuchtung</code>

===<code>rhasspyMapping</code>===
Wenn die automatische Erkennung des richtigen Intents für ein Gerät nicht funktioniert oder nicht das gewünschte Ergebnis liefert, kann mit diesem Attribut angegeben werden, mit welchem Intent das Gerät gesteuert werden kann.

Es ist möglich, mehrere verschiedene Intents pro Gerät zu verwenden. Es muss nur einfach eine neue Zeile für ein weiteres Mapping verwendet werden.

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="Alles klar"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
Status:response=Die Helligkeit in der Küche ist bei [<device>:pct]
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

====Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings====
Manche Intents können FHEM-Kommandos oder -Readings verwenden, um Werte auszulesen oder zu setzen.

Dabei gibt es drei Möglichkeiten, wie diese geschrieben werden können:
*Direktes Verwenden von SET-Kommando oder Reading des aktuellen Device:
:<code>cmd=on or currentReading=temperature</code>
*Umleiten eines Kommando auf ein anderes Device oder Verwenden eines Readings aus einem anderen Gerät:
:<code>cmd=Otherdevice:on or currentReading=Otherdevice:temperature</code>
*Perl-Code um einen Befehl auszuführen oder einen Wert zu setzen:
:Das ermöglicht sehr komplexe Anfragen.
:Der Code muss in geschwungenen Klammern sein.
:<code>{currentVal={ReadingsVal($DEVICE,"state",0)}</code>
:oder
:<code> cmd={fhem("set $DEVICE dim $VALUE")}</code>
:$DEVICE ist das aktuelle FHEM-device. Der SetNumeric-Intent kann $VALUE für den Wert verwenden, der gesetzt werden soll.

===<code>rhasspySpecials</code>===
Dieses Attribut wirkt ähnlich wie [[#rhasspyTweaks| rhasspyTweaks]], verändert allerdings nur jeweils das Verhalten des Geräts, bei dem es gesetzt ist. Auch dieses Attribut wird zeilenweise eingelesen, es können ein oder mehrere der folgenden Optionen gesetzt werden:

==== group ====
::Wird dieser Schlüssel gesetzt, wird das Gerät bei Gruppenaktionen nicht direkt adressiert, sondern die hier angegebene Gruppe. Details hierzu sind in [[RHASSPY/Vertiefung#Timing-Aspekte| Vertiefung - Timing-Aspekte]] zu finden.

::'''Beispiel:'''
::<code>attr lamp1 rhasspySpecials group:async_delay=100 prio=1 group=lights</code>

==== numericValueMap ====
::Ermöglicht es, statt der allgemeinen Methode zum Umgang mit numerischen Werten einzelnen Werten spezielle Kommandos zuzuweisen. Dies kann z.B. hilfreich sein, um spezielle Positionen für Rollladengeräte anzusteuern.
::'''Beispiel''':
::<code>attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'</code>
::führt dazu, dass ein numerischer Wert von 10 (im {Value}-key) das Kommando <code>set blind1 Event Slit</code> ausführt.

==== venetianBlind ====
Siehe [[RHASSPY/Vertiefung#Jalousien|Vertiefung - Jalousien]]

==== colorCommandMap ====
Sowie **colorTempMap** und **colorForceHue2rgb**
Siehe [[RHASSPY/Vertiefung#Farben|Vertiefung - Farben]]

==== priority ====
Ermöglicht es, Rückfragen zu vermeiden, wenn mehrere Geräte für bestimmte Aktionen in Frage kommen. Siehe [[RHASSPY/Vertiefung#Einer_statt_alle|Einer statt alle]]

==== confirm ====
Ist eine Möglichkeit, Geräte nur nach Rückfrage und Bestätigung zu schalten (ähnlich wie ''confirmIntents'' in ''rhasspyTweaks''). Es können entweder einfach nur Intent-Namen angegeben werden, oder Paare von **Intent** und zugehöriger **response**:
SetOnOff="Soll $target wirklich $Value geschaltet werden" SetScene

==== confirmValueMap ====
Kann spezielle Übersetzungen für $Value enthalten, z.B. für Rollladen-Geräte:

<syntaxhighlight lang="perl">confirm: SetOnOff="wirklich $Value $target"
confirmValueMap: on=öffnen off=schließen</syntaxhighlight>

==== scenes ====
Wird bei der automatisierten Erfassung erkannt, dass ein Gerät das Setzen von Szenen unterstützt, werden die erkannten Szenen-Namen an Rhasspy übergeben. Da diese häufig technischer Natur sind, eignen sie sich nicht für eine Spracherkennung. Über diesen Schlüssel können daher sprechbare Namen für jede Szene vergeben werden, und/oder einzelne bzw. alle Szenen von der Erkennung ausgenommen werden. Der Kenner ''none'' löscht die Szene von der Liste der übermittelten Szenen, wird die Kombination ''all=none'' angegeben, wird dieses Gerät insgesamt von der Vorbereitung für den Intent ''SetScene'' ausgeschlossen.
Beispiel:
<syntaxhighlight lang="perl">attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none</syntaxhighlight>
Siehe auch [[RHASSPY/Vertiefung#echte_Szenen|Vertiefung - echte Szenen]].

=== Veraltete Attribute ===
In der Regel sollte es ausreichen, die zu steuernden Devices über die oben genannten Attribute zu konfigurieren. Es gibt jedoch noch zwei ältere Methoden. Um diese zu verwenden, muss zuerst jeweils ein entsprechendes User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden.

====<code>rhasspyChannels</code>====
Das Attribut wird vom Intent ''MediaControls'' verwendet. Es informiert den Intent darüber, welche (Medien-)Kanäle vorhanden sind und welcher FHEM-Befehl oder Perl-Code auszuführen ist, wenn auf diesen Kanal geschaltet werden soll.

In diesem Attribut muss eine Zeile pro (Medien-)Kanal verwendet werden.

Um rhasspyChannels zu verwenden, muss zuerst ein neues User-Attribut im FHEM-Device, das damit gesteuert werden soll, angelegt werden. Dafür kann z.B. dieses Beispiel verwendet werden: <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr <device> rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203
netflix=launchApp Netflix
</syntaxhighlight>

====<code>rhasspyColors</code>====
Ältere Methode, die verwendet werden kann, um Lichtfarben zu wechseln. Es wird nachdrücklich empfohlen, die neueren Methoden über die (nummerisch zu übergebenden) allgemeinen Farbwerte und/oder ein ''colorCommandMap'' oder ''colorTempMap'' (siehe ''rhasspySpecials'') zu konfigurieren!

Um das Mapping zu verwenden, muss zuerst ein User-Attribut am zu steuernden Gerät angelegt werden. Z.B. <code>attr <deviceName> userattr rhasspyChannels:textField-long</code>

Eine Zeile pro Farbe

'''Beispiel:'''
<syntaxhighlight lang="perl">
attr lamp1 rhasspyColors rot=rgb FF0000
grün=rgb 008000
blau=rgb 0000FF
gelb=rgb FFFF00
</syntaxhighlight>

== Intents ==
Intents werden verwendet um FHEM zu sagen, was es nach einem erhaltenen Sprach-/Textkommand unternehmen soll. Dieses Modul stellt einige Intents bereit.

;Wichtig
:*Bei Tags (<code>Value</code>, <code>Room</code>, <code>Device</code>, etc.) ist die Schreibweise sehr wichtig! Die sind case-sensitive. Bitte daher genau so schreiben, wie sie in dieser Dokumentation vorkommen.
:*RHASSPY erstellt bei einem <code>update slots</code> auch Slots je nach Möglichkeiten der Geräte oder Gruppen. Unterstützt ein Gerät zum Beispiel den Intent ''GetNumeric'', wird auch ein Slot <code>de.fhem.Device-GetNumeric</code> erstellt. Ein Gerät, dass ein- und ausgeschalten werden kann, wird im Slot <code>de.fhem.Device-SetOnOff</code> untergebracht. Ein einzelnes Gerät kann sich auch in mehreren Slots befinden. Um eine möglichst genaue Spracherkennung zu gewährleisten, ist '''empfohlen''', diese '''spezifischen Slots''' - statt einfach nur <code>de.fhem.Device</code> oder <code>de.fhem.Group</code> - '''zu verwenden'''.

=== SetOnOff ===
Intent um Geräte zwischen zwei Zuständen (ein/aus, auf/zu, start/stop) zu schalten.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off
SetOnOff:cmdOn=on,cmdOff=off,response="Sir yes Sir"
SetOnOff:cmdOn=on,cmdOff=off,response="$DEVICE now [$DEVICE:state]"
</syntaxhighlight>

Argumente:
*<code>cmdOn</code> Befehl um das Gerät einzuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].
*<code>cmdOff</code> Befehl um das Gerät auszuschalten. Siehe [[#Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings|Formatierung von Befehlen und Readings innerhalb eines rhasspyMappings]].

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalten das licht ein
schließe den rollladen im schlafzimmer
starte die kaffeemaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOff]
(schalte|schalt|mache|mach|stelle|stell|starte) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] (an|ein){Value:on}
(schalte|schalt|mache|mach|stelle|stell) [den|die|das] $de.fhem.Device-SetOnOff{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] aus{Value:off}
(fahre|fahr) [den|die|das] $de.fhem.Device-blind{Device} [[(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room}] ((hoch|auf){Value:on}|(zu|runter){Value:off})

</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetOnOffGroup ===
Intent um Gruppen von Geräte zwischen zwei Zuständen zu schalten.

Dafür ist ein SetOnOff-Mapping benötigt und alle gewünschten Geräte müssen (ggf. u.A. auch) der gewählten Gruppe angehören (einzustellen über das Attribut <code>group</code> bzw. <code>rhasspyGroup</code>, oder allgemein kommend aus rhasspyTweaks - gdt2groups).

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte die lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte sämtliche lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] ein{Value:on}
\[(schalt|mach)] (die | alle | sämtliche ) $de.fhem.Group-SetOnOff{Group} [[in|im|in der|auf der] [( überall:global | $de.fhem.Room ){Room}] aus{Value:off}
(öffne{Value:on}|schließe{Value:off}) (alle | sämtliche ) $de.fhem.Group-blind{Group} [[in|im|in der|auf der] [( überall:global{Room:global} | $de.fhem.Room{Room} )]
(fahr|fahre|mach|mache) [den|die|das] $de.fhem.Group-blind{Group} [[(im|in dem|in der)] ( überall:global{Room:global} | $de.fhem.Room{Room} )] ( auf{Value:on} | hoch{Value:on} | zu{Value:off} | runter{Value:off} )
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value:on</code> und/oder <code>Value:off</code>
*<code>Group</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOff ===
Intent um Geräte für eine bestimmte Zeitspanne in einen bestimmten Zustand zu versetzten.

Device muss ein SetOnOff-Mapping haben und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte das licht für eine minute und dreißig sekunden aus
schalte die musik im bad bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOff]
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Device-SetOnOff{Device} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Device</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== SetTimedOnOffGroup ===
Intent um eine Gruppe von Geräten für eine bestimmte Zeit zu schalten.

Devices müssen ein SetOnOff-Mapping haben, in einer Gruppe sein und die {{Link2CmdRef|Anker=setExtensions|Lang=de|Label=SetExtentions}} unterstützen.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lichter in der küche für fünfzig sekunden ein
schalte alle licher bis zwei uhr ein
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetTimedOnOffGroup]
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] für ([(1..60){Hour!int} (stunde|stunden)] [und] [(1..60){Min!int} (minute|minuten)] [und] [(1..60){Sec!int} (sekunde|sekunden)]) (ein{Value:on}|aus{Value:off})
schalte $de.fhem.Group-SetOnOff{Group} [$de.fhem.Room{Room}] bis (0..24){Hourabs!int} [(1..60){Min!int}] (ein{Value:on}|aus{Value:off})
</syntaxhighlight>

Verpflichtende Tags:
*<code>Value</code>
*<code>Group</code>
*<code>Hour</code> oder <code>Min</code> oder <code>Sec</code> oder <code>Hourabs</code>

Optionale Tags:
*<code>Room</code>

=== GetOnOff ===
Intent um den aktuellen Zustand eines Gerätes zu erfragen.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetOnOff:currentVal=state,valueOff=closed
GetOnOff:currentVal=state,valueOn=on
GetOnOff:currentVal=pct,valueOff=0
</syntaxhighlight>

Argumente:
Hinweis: nur <code>valueOn</code> ODER <code>valueOff</code> müssen gesetzt werden. Der jeweils andere Wert bekommt den anderen Status.
*<code>currentVal</code> Reading aus dem der aktuelle Status hervorgeht
*<code>valueOff</code> Wert, der den Zustand ''aus'' beschreibt
*<code>valueOn</code> Wert, der den Zustand ''an'' beschreibt

Optionale Argumente:
*<code>response</code> Eine benutzerdefinierte Antwort auf den Befehl

Beispiel-Sätze:
<syntaxhighlight lang="perl">
ist das licht im bad ein
ist das fenster im wohnzimmer geöffnet
läuft die waschmaschine
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:GetOnOff]
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (ein|geöffnet){State:on}
ist $de.fhem.Device-GetOnOff{Device} [$de.fhem.Room{Room}] (aus|geschlossen){State:off}
</syntaxhighlight>

Die Zustände ''ein'' und ''aus'' sollten in unterschiedlichen Sentences sein und müssen <code>{State:on}</code> und <code>{State:off}</code> beinhalten.

Verpflichtende Tags:
*<code>State:on</code> und/oder <code>State:off</code>
*<code>Device</code>

Optionale Tags:
*<code>Room</code>

=== SetNumeric ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw..

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SetNumeric:currentVal=pct,cmd=dim,minVal=0,maxVal=99,step=25,type=brightness
SetNumeric:currentVal=volume,cmd=volume,minVal=0,maxVal=99,step=10,type=volume
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Reading, in dem der aktuelle Wert zu finden ist (wird zwingend benötigt).
*<code>part</code> Kann genutzt werden, um den Wert aus **currentVal** in mehrere Teile zu zerlegen (getrennt wird am Leerzeichen). Z.B. wenn currentVal 23 C ist, wird **part=0** **23** ergeben. Optionaler Parameter.
*<code>cmd</code> Das **Set**-Kommando des Geräts, das in Folge des Sprachkommandos ausgeführt werden soll. (Notwendiger Parameter).
*<code>minVal</code> Niedrigster zugelassener Wert, optional.
*<code>maxVal</code> Höchster zugelassener Wert, optional.
*<code>step</code> Schrittweite für relative Änderungen wie <code>mach lauter</code>. Optional. Default: 10.
*<code>map</code> Derzeit wird ausschließlich die Angabe **percent** ausgewertet. Optionaler Parameter, der bewirkt, dass alle Angaben als Prozentwert (zwischen minVal und maxVal) interpretiert werden und entsprechend gerechnet wird. So wird z.B. eine Leuchte mit **minVal=0** und **maxVal=255** beim Befehl "stelle das Licht auf 50" dies so verstehen, als wäre die Anweisung "stelle das Licht auf 50 Prozent" gewesen. Das Licht wird daher auf 127 gestellt, und nicht auf (absolut) 50.
*<code>type</code> Zur Unterscheidung, falls mehrere SetNumeric-Intents für das Gerät möglich sind. Empfohlener Parameter.

Gut zu wissen:
Um Kommandos wie **lauter** oder **leiser** ohne Angabe eines Gerätes ausführen zu können, muss RHASSPY zunächst ermitteln, welches Gerät gerade überhaupt etwas wiedergibt ist. Daher nutzt es die GetOnOff-Mappings, um festzustellen, welches Gerät vom **type=volume** überhaupt angeschaltet ist. Dabei wird wie üblich zunächst im aktuellen rhasspyRoom gesucht, bevor die Suche außerhalb fortgesetzt wird.
Setzt man also Mappings manuell, ist es ratsam, auch ein **GetOnOff**-Mapping zu setzen.

Zulässige Typen sind:
*<code>brightness</code>
*<code>setTarget</code>
*<code>temperature</code>
*<code>volume</code>

Beispiel-Sätze:
<syntaxhighlight lang="perl">
Stelle das Licht auf 30 Prozent
Mach das Radio leiser
Stell die Temperatur im Wohnzimmer 2 Grad wärmer
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
(Beachte: Wenn wie hier im Beispiel reele Zahlen (mit Komma) ermöglicht werden sollen ("acht Komma fünf"), wird ein [[#Custom Converter für reelle Zahlen| Custom Converter für reelle Zahlen]] benötigt)
<syntaxhighlight lang="perl">
[de.fhem:SetNumeric]
den=(den|die|das)
cmdmulti=(schalte|schalt|mache|mach|stelle|stell)
rooms=([(im|in dem|auf dem|in der|auf der)] $de.fhem.Room{Room})
<cmdmulti> [<den>] $de.fhem.Device-SetNumeric{Device} auf (0..100){Value!int} [Prozent{Unit:percent}]
\[<cmdmulti>] [die Lautstärke [an|am]] [dem|<den>] $de.fhem.Device-media{Device} [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [die Lautstärke [an|am]] [dem|<den>] [$de.fhem.Device-media{Device}] [<rooms>] [um] [(0..10){Value!float}] [dezibel{Unit:decibel}|Prozent{Unit:percent}] ( lauter:volUp | leiser:volDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-thermostat{Device} [<rooms>] [um] [(0..10){Value!int}] [Grad{Unit.degree}] ( wärmer:tempUp | kälter:tempDown ){Change}
<cmdmulti> [<den>] $de.fhem.Device-light{Device} [<rooms>] [um] [(0..30 [Komma:. 1..9]){Value!customFloat}] [Prozent{Unit:percent}] ( heller:lightUp | dunkler:lightDown){Change}
<cmdmulti> [<den>] ( $de.fhem.Device-light | $de.fhem.Device-media |$de.fhem.Device-blind){Device} [<rooms>] auf [(0..30 [Komma:. 1..9]){Value!customFloat}]
( mehr{Change:lightUp} | weniger{Change:lightDown} ) $de.fhem.Device-light{Device} [<de.fhem:SetOnOff.rooms>]
( halte | stoppe | stop ) [<den>] $de.fhem.Device-blind{Device} [<de.fhem:SetOnOff.rooms>] [an] {Change:cmdStop}
</syntaxhighlight>

Derzeit werden folgende Typen für das Feld <code>{Change}</code> ausgewertet:
*<code>tempUp</code> / <code>tempDown</code>
*<code>volUp</code> / <code>volDown</code>
*<code>lightUp</code> / <code>lightDown</code>
*<code>setUp</code> / <code>setDown</code>

Notwendig sind:
*<code>Change</code> oder <code>Type</code>
*<code>Value</code> oder <code>Change</code>

Optionale Tags:
*<code>Device</code>
*<code>Room</code>
*<code>Unit</code>

=== SetNumericGroup ===
Intent, um Lampen zu dimmen, Rollladengeräte zu positionieren, Lautstärken oder Solltemperaturen zu ändern, usw.. Die Funktionsweise entspricht dabei dem des Intents ''SetNumeric'', wobei eben statt eines einzelnen Devices eben ein oder mehrere Geräte über ihren Gruppennamen angesprochen werden. Statt des optionalen Tags <code>Device</code> ist daher der Tag <code>Group</code> zu übergeben.
Aus der Adressierung mehrerer Geräte ergeben sich einige Besonderheiten, die in der [[RHASSPY/Vertiefung]], dort speziell auch im Punkt [[RHASSPY/Vertiefung#Beispiel_SetOnOffGroup|Beispiel SetOnOffGroup]] näher erläutert sind. Wesentliche zu beachtende Aspekte sind:
* Vermeidung von Funk-Überschneidungen (''Specials'' ''partOf'' und ''async_delay'')
* Begrenzung der Gruppenzugehörigkeit durch die Raumzugehörigkeit (und die Aufhebung dieser Beschränkung durch die Übergabe des speziellen Raums ''global'')

=== GetNumeric ===
Intent, mit dem man Werte erfragen kann, wie z.B. die aktuelle Temperatur, Helligkeit, Lautstärke, ...

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetNumeric:currentVal=temperature,part=1,type=temperature
GetNumeric:currentVal=pct,map=percent,minVal=0,maxVal=100,type=brightness
GetNumeric:currentVal=volume,type=volume
GetNumeric:currentVal=humidity,part=0,type=humidity
GetNumeric:currentVal=batteryPercent,type=battery
</syntaxhighlight>

Argumente:
*<code>currentVal</code> Das Reading, das den abzufragenden Wert enthält
*<code>part</code> Teile aus currentVal ableiten, indem am Leerzeichen getrennt wird. Ist ''currentVal'' beispielsweise ''23 C'', entspricht ''part=1'' dem Wert ''23''
*<code>map</code> Die Funktionswiese entspricht dem ''SetNumeric'' Intent. Wandelt den vorhandenen Wert in eine Prozent-Angabe um.
*<code>minVal</code> Niedrigster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>maxVal</code> Höchster zulässiger Wert (nur benötigt, wenn ''map'' angegeben ist).
*<code>type</code> Dient der Unterscheidung zwischen mehreren GetNumeric-Anfragemöglichkeiten für dasselbe Gerät (auch relevant für SetNumeric-Anweisungen).

Mögliche Abfragetypen:
*<code>humidity</code>
*<code>battery</code>
*<code>brightness</code>
*<code>desired-temp</code>
*<code>setTarget</code>
*<code>soilMoisture</code>
*<code>temperature</code>
*<code>volume</code>
*<code>waterLevel</code>
Aus dem Abfragetypen ergibt sich die von RHASSPY ausgewählte Antwort.

Beispiel Sätze:
<syntaxhighlight lang="perl">
what is the temperature in the living room
how bright is the floor lamp
what is the volume of the tv
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[en.fhem:GetNumeric]
#actual temperature
(what is|how high is) the temperature{Type:temperature} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#desired-temperature
\[what is the|how high is the] (desired temperature){Type:desired-temp} [$de.fhem.Device-GetNumeric{Device}] [$de.fhem.Room{Room}]

#volume
(what is the|how high is the) volume{Type:volume} $de.fhem.Device-GetNumeric{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>
*<code>Type</code>

Optional tags
*<code>Room</code>

=== GetState ===
Intent to get specific information of a device. The respone can be defined.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
GetState:response="Temperature is [$DEVICE:temp] degree at [Thermo:hum] percent humidity"
GetState:response={my $value=ReadingsVal("$DEVICE","brightness",""); return "Brightness is $value";}
</syntaxhighlight>

Options:
*<code>response</code> Text for the response Rhassyp will give.
:To use values from FHEM use format [Device:Reading].
:A comma within the response has to be escaped (\, instead of ,).
:Or you can use Perl-code enclosed in curley brackets to define the response.
:Mixing text and Perl-code is not supported.

Example-Sentences:
<syntaxhighlight lang="perl">
How is the state of the thermostat in the kitchen
state light in livingroom
state washer
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="perl">
[de.fhem:GetState]
\[how is the] (state) $de.fhem.Device{Device} [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Device</code>

Optional tags:
*<code>Room</code>

=== MediaControls ===
Intent to control media devices

Beispiel-Mapping:
<syntaxhighlight lang="perl">
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next
</syntaxhighlight>

Options:
*<code>cmdPlay</code> Play command of the device. See chapter Formatting Commands and Readings inside a rhasspyMapping.
*<code>cmdPause</code> Command to pause the device.
*<code>cmdStop</code> Command to stop the device.
*<code>cmdFwd</code> Command to skip to the next track/channel/etc.
*<code>cmdBack</code> Command to skip to the previous track/channel/etc.

Note on issuing a voice-command without a room-name:
As described in the SetNumeric-Intent, it is recommended to define a GetOnOff-Mapping to use the MediaControls-Intent without a room name.

Example-Sentences:
<syntaxhighlight lang="perl">
skip to next track on the radio
pause
skip video on the dvd player
stop playback
next
previous
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:MediaControls]
(start){Command:cmdPlay} the playback [$de.fhem.Device-MediaControls{Device}]
(stop){Command:cmdStop} the playback [$de.fhem.Device-MediaControls{Device}]
(pause){Command:cmdPause} the playback [$de.fhem.Device-MediaControls{Device}]
(next){Command:Fwd} (song|title) [$de.fhem.Device-MediaControls{Device}]
(previous){Command:Back} (song|title) [$de.fhem.Device-MediaControls{Device}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags:
*<code>Command</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== MediaChannels ===
Intent to change radio-/tv channels, favorites, playlists, lightscenes, ...

Instead of using the attribute rhasspyMapping, this intent is configured with an own attribute [[#rhasspyChannels]] in the respective device. Reason is the multiple-line-configuration.

Beispiel-Mappings:
<syntaxhighlight lang="perl">
SWR3=favorite s_w_r_3
SWR1=favorite s_w_r_1
ARD=channel 204
Netflix=launchApp Netflix
Leselicht=set lightSceneWz scene Leselicht
</syntaxhighlight>

Notice on using the commands without a device name:
To start playback on a device without specifying the device name in the voice command, the module needs to know, which device should be used. Therefor it searches the attribute rhasspyChannels for suitable one. Devices in the actual or spoken room are preferred.

Example-Sentences:
<syntaxhighlight lang="perl">
play CNN on the radio in my office
switch to HBO
change channel on radio to BBC news
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:MediaChannels]
\[(play|switch to|change to)] ($de.fhem.MediaChannels){Channel} [($de.fhem.Device){Device}] [($de.fhem.Room){Room}]
</syntaxhighlight>

Required tags:
*<code>Channel</code>

Optional tags:
*<code>Device</code>
*<code>Room</code>

=== SetColor ===
Intent to change light colors

Because of the multi-line settings, instead of configuring this intent with the attribute rhasspyMapping, a separate user-attribute [[#rhasspyColors]] is used.

The content of the rhasspyColors uses the following format:
<code>Colorname=cmd</code>

Settings:
*<code>Colorname</code> The name of the color you want to use in a voice-command
*<code>cmd</code> The FHEM-command

Example-Mappings:
<syntaxhighlight lang="perl">
red=rgb FF0000
green=rgb 00FF00
blue=rgb 0000FF
white=ct 3000
warm white=ct 2700
</syntaxhighlight>

Example-Sentences:
<syntaxhighlight lang="perl">
change light to green
lightstrip blue
color the light in the sleeping room white
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[en.fhem:SetColor]
\[change|color] $de.fhem.Device{Device} [$de.fhem.Room{Room}] $de.fhem.Color{Color}
</syntaxhighlight>

Required tags:
*<code>Color</code>
*<code>Device</code>

Optional tags
*<code>Room</code>

=== SetColorGroup ===

=== SetScene ===

=== GetTime ===
Intent um die Uhrzeit zu erfragen.

Es werden keine Konfigurationen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
wie spät ist es?
sag mir die uhrzeit
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetTime]
wie spät [ist es]
sag mir die uhrzeit
</syntaxhighlight>

=== GetDate ===
Intent um das aktuelle Datum zu erfragen.

Keine FHEM Einstellungen nötig.

Beispiel-Satz:
<syntaxhighlight lang="perl">
welcher tag ist heute
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:GetDate]
welcher tag ist heute
</syntaxhighlight>

=== SetTimer ===
Intent to create a timer/countdown/alarm

This intent creates an AT-command in FHEM with the given time and - currently - speaks the sentences "timer expired" when it has expired.

No FHEM-settings needed

Beispiel Sätze:
<syntaxhighlight lang="perl">
Set timer in bedroom to five minutes
Set countdown in the kitchen to two hours
set timer to five and a half hours
set alarm to 5 o' clock
set timer to 3 hours and 20 minutes
set timer to 1 hour, 30 minutes and 15 seconds
stop the timer in bedroom
</syntaxhighlight>

Example-Rhasspy-Sentence:
<syntaxhighlight lang="ini">
[de.fhem:SetTimer]
labels=(alarm|teetimer|countdown|timer)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) [((1..60){Hour!int} (hour|hours))] [and] [((1..60){Min!int} (minute|minutes))] [and] [((1..60){Sec!int} (second|seconds))]
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Hour!int} and (a quarter{Min:15}|a half{Min:30}|three quarters{Min:45}) (hour|hours)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) (1..60){Min!int} and (a quarter{Sec:15}|a half{Sec:30}|three quarters{Sec:45}) (minute|minutes)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (hour)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in) ((the fourth){Min:15}|(half a){Min:30}|(three fourth){Min:45}) (minute)
\[<labels>{Label}] [$de.fhem.Room{Room}] (to|in|at) (1..24){Hourabs!int} [(1..60){Min!int}] o clock

(cancel|remove|stop|delete){CancelTimer} [<labels>{Label}] [$de.fhem.Room{Room}]
</syntaxhighlight>

Required tags to set a timer:
*<code>Label</code>
*<code>Hour</code>, <code>Hourabs</code>, <code>Min</code> oder <code>Sec</code>

Required tags to cancel a timer:
*<code>Label</code>

rhasspyTweaks for Timer:
*<code>[[#attr-rhasspytweaks-timerlimits|timerLimits]]</code>
*<code>[[#attr-rhasspytweaks-timersounds|timerSounds]]</code>

=== SetMute ===
Intent to disable/enable the processing of intents on a specific siteId. Rhasspy will still listen to the wakeword but will not process any intents.

This intents creates a Reading <code>mute_siteId</code> for every siteId it get's a voice-command from.

No FHEM-settings needed

Beispiel-Sätze:
<syntaxhighlight lang="perl">
good night
be quiet
good morning
make noise
start listening
stop listening
</syntaxhighlight>

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetMute]
(good night|be quiet){Value:on}
(good morning|make noise){Value:off}
</syntaxhighlight>

Hinweis: Die Felder <code>{Value:on}</code> bzw. <code>{Value:off}</code> sind verpflichtend und ''case sensitive'', der Wert ''on'' bzw. ''off'' ist in Englisch anzugeben!

=== ConfirmAction ===
Dies ist - wie die folgenden Intents ''CancelAction'' und ''Choice'' (bzw. die überholten Varianten ''ChoiceRoom'' und ''ChoiceDevice'') auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Um eine Aktion tatsächlich auszuführen, ist als Rückgabe zwingend <code>{Mode}</code> mit dem Wert ''OK'' erforderlich, alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden, was zur Beendigung des Dialogs ohne Aktion führt.

=== CancelAction ===
Siehe ''ConfirmAction''. Dieser Intent muss nicht zwingend existieren, es kann auch ein unpassender Rückgabewert in ''ConfirmAction'' angegeben werden, um die Abbruch-Routinen für Dialoge zu starten.

=== Choice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl von einem oder mehreren der folgenden Elemente:
<code>{Device}</code>, <code>{Room}</code> und/oder <code>{Scene}</code>.

Beispiel für Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:Choice]
den=(den|die|das)
choose= ( nimm [bitte] | [bitte] nimm | ich hätte gerne | [ich] (wähle|nehme) )

<choose> [ <den> [( Gerät | $de.fhem.Aliases{Device} )] ] ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room}
<choose> [ <den> ] $de.fhem.Aliases{Device} [ ( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ]
<choose> [ ( die Szene | den Modus ) ] $de.fhem.Scenes [Modus] [ [( am | vom )] $de.fhem.Aliases{Device} ] [( aus ( dem | der ) | im | den | die ) $de.fhem.MainRooms{Room} ] [bitte]
</syntaxhighlight>.

==== ChoiceRoom ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Raums, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

==== ChoiceDevice ====
Veralteter Intent. Diente im Rahmen von Dialogen der Auswahl eines Gerätes, wird heute pauschal nach ''Choice'' umgeleitet und sollte nicht mehr verwendet werden!

=== ReSpeak ===
Wiederholt den letzten Satz, den Rhasspy gesprochen hat. Um genauer zu sein: Spricht den Inhalt des FHEM Readings <code>voiceResponse</code>.

Keine Einstellungen in FHEM benötigt.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
was hast du gesagt
kannst du das wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

Example-Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:ReSpeak]
was hast du gesagt
kannst du das [bitte] wiederholen
ich habe dich nicht verstanden
</syntaxhighlight>

== Eigene Intents erstellen ==
Es ist auch möglich, eigene Intents zu erstellen, sollten die hier vorgestellten nicht reichen. Dafür gibt es zwei Wege: Für kleinere Intents können die Möglichkeiten von FHEMs [[99_myUtils_anlegen|99_myUtils.pm]] genutzt werden. Aufwendigere Intents können in jeweils eigenen Dateien abgelegt werden, die dann von RHASSPY ausgelesen werden.
=== Intents in 99_myUtils.pm ===

Hier ein (veraltetes, siehe oben) Beispiel, mit dem die letzte ''voice response'' wiederholt werden kann.

Ergänze deine 99_myUtils.pm mit folgender Funktion:

<syntaxhighlight lang="perl">
sub Respeak(){
#Credits to JensS
my $name = "Rhasspy"; #Replace "Rhasspy" with the name of your RHASSPY-Device
my $response = ReadingsVal($name,"voiceResponse","Ich kann mich leider nicht erinnern");
return $response;
}
</syntaxhighlight>

Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
Respeak=Respeak()
</syntaxhighlight>

Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:

<syntaxhighlight lang="ini">
[de.fhem:Respeak]
was hast du gesagt
</syntaxhighlight>

=== Intents in eigenen Dateien ===
Beispiele: https://github.com/fhem/fhem-rhasspy/blob/main/FHEM/99_RHASSPY_Utils_Demo.pm

==== Beispiel: Raumwechsel ====
Erforderlichen Code in das Modulverzeichnis holen und laden:
<syntaxhighlight lang="perl">{ Svn_GetFile('contrib/RHASSPY/99_RHASSPY_Utils_siteId2room.pm', 'FHEM/99_RHASSPY_Utils_siteId2room.pm',sub(){ RHASSPY_Utils_siteId2room_Initialize() }) }</syntaxhighlight>Ergänze im Attribut ''rhasspyIntents'' folgende Zeile (je Intent muss eine eigene Zeile verwendet werden):
<syntaxhighlight lang="perl">
siteId2room=RHASSPY::siteId2room::siteId2room(NAME,DATA)
</syntaxhighlight>Ergänze einen neuen Intent in deinen ''sentence.ini'' an der Rhasspy base:
<syntaxhighlight lang="ini">
[de.fhem:siteId2room]
( Ortswechsel | begib dich ) ( ins | in den ) $de.fhem.Room{Room}
</syntaxhighlight>

== Tipps & Tricks ==
===Custom Converter für reelle Zahlen===
{{Randnotiz|RNTyp=g|RNText=RHASSPY enthält für <code>{Value}</code> nunmehr auch einen Konverter, der Leerzeichen aus Zahlenwerten entfernt. Enthält dieses Datenfeld bei der Übergabe aus Rhasspy z.B. <code>- 10 .5</code>, wird dies automatisch in <code>-10.5</code> umgewandelt.}}
Rhasspy kann (derzeit) keine gesprochenen reellen Nummern (z.B. 22,5) als Nummer erkennen. Stattdessen interpretiert es die Zahl als zwei Nummern und einen Punkt.

Um reelle Nummern richtig zu verwenden, muss ein [https://rhasspy.readthedocs.io/en/latest/training/#converters Custom Converter] erstellt und in der sentences.ini verwendet werden.

So ein Konverter kann erstellt werden, in dem unter <code><profile>/converters</code> ein neues File mit beliebigem Namen angelegt wird. Der Name muss aber dann auch genau so als Converter in der sentences.ini verwendet werden. Anschließend muss die Datei noch ausführbar gemacht werden.

Z.B.:
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Folgender Beispiel-Code kann danach in die Datei geschrieben werden:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# von Rhasspy als JSON übergebene/n Wert/e einlesen
args = json.load(sys.stdin)

# wenn im deserialisierten JSON nur ein Wert ist, wird der als Ergebnis genommen
# sind mehrere Werte vorhanden (z.B. 22,.,5), werden die zu einem einzelnen String zusammen gesetzt
if type(args) == int:
num = args
else:
num = "".join(str(s).strip() for s in args)

# Ergebnis wird an Rhasspy übergeben
print(num)
</syntaxhighlight>

Nach einem Neustart von Rhasspy kann dieser Converter dann verwendet werden.

<syntaxhighlight lang="ini">
[de.fhem.SetNumeric]
stelle die heizung auf (0..30 [komma:. 0..99]){Value!customFloat}
</syntaxhighlight>

=== Rhasspy speaks actual state of device after switching it===
JensS wrote a short script to let Rhasspy speak the actual state of a FHEM-device after switching it with a voice-command.
Add the following to your 99_myUtils.pm
<syntaxhighlight lang="perl">
sub ResponseOnOff($){
my ($dev) = @_;
my $room;
my $state = lc(ReadingsVal($dev,"state","in unknown state"));
my $name = (split(/,/,AttrVal($dev,"rhasspyName","error")))[0];
if (AttrVal($dev,"rhasspyRoom","")){$room = " in ".(split(/,/,AttrVal($dev,"rhasspyRoom","")))[0]};
$state=~s/.*on/turned on/;
$state=~s/.*off/turned off/;
return "Ok - ".$name.$room." is now ".$state
}
</syntaxhighlight>
and add a response to the SetOnOff-Mapping of a device
<syntaxhighlight lang="perl">
SetOnOff:cmdOn=on,cmdOff=off,response={ResponseOnOff($DEVICE)}
</syntaxhighlight>

== Links ==
* [https://github.com/rhasspy/rhasspy Rhasspy auf Github]
* [https://rhasspy.readthedocs.io/en/latest/ offizielle Rhasspy Doku-Seite]
* [https://community.rhasspy.org/ Offizielles Rhasspy Forum]
* [https://github.com/fhem/fhem-rhasspy fhem-rhasspy Modul auf GitHub]
* [https://github.com/Romkabouter/ESP32-Rhasspy-Satellite ESP32-basierte Hardware als Satelliten]
* [https://github.com/razzo04/rhasspy-mobile-app App für Android-Satelliten]
* [https://www.youtube.com/watch?v=sWVl0ZoXZEo Video zu sentences.ini]
[[Kategorie:Sprachsteuerung]]