FHEMWiki - Benutzerbeiträge [de]

Signalbot

2025-12-14T16:06:57Z

Drhirn: /* Troubleshooting / FAQ */

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messenger Signal
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=118370
|ModTechName=50_Signalbot.pm
|ModOwner=Adimarantis ({{Link2FU|39402|Forum}}/[[Benutzer Diskussion:Adimarantis‎|Wiki]])}}
Das Modul [[Signalbot]] ermöglicht den Versand von Nachrichten über den Instant-Messaging-Dienst [https://signal.org Signal] aus FHEM heraus.

== Beschreibung ==
Beschreibung in Kurzform:

Signalbot stellt eine Schnittstelle von FHEM zum Signal Messenger unter Linux zur Verfügung. Dazu wird das Tool [https://github.com/AsamK/signal-cli signal-cli] im DBus-Daemon Modus verwendet, welches dann letztendlich mit Signal kommuniziert.

Aktuell unterstützte Funktionen aus FHEM:
* Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
* Versenden von einem oder mehreren Attachments (Bilder) sowie Plots von SVG und DOIF
* Einlesen, Speichern und Übersetzen von Gruppennamen (statt base64 Strings)
* Setzen, Empfangen und Übersetzen von Kontaktnamen (statt Telefonnummern)
* Einschränken von Gruppen oder Kontakten, auf die FHEM reagieren soll
* Direkte Verknüpfung mit dem [[Modul Babble|Babble]] Modul zur Interpretation von Befehlen
* Authentifizierte Befehle an FHEM senden ({{Link2CmdRef|Anker=GoogleAuth}}) mit Favoriten
* Blockieren von Kontakten und Gruppen
* Verwalten und Betreten/Verlassen von Gruppen

* Registrierung von neuen Nummern inklusive Hilfestellung für Captchas
* Linken von bestehenden Accounts zu FHEM
Die Installation von signal-cli ist aktuell je nach Linux Kenntnissen durchaus anspruchsvoll. Daher gibt es ein Installationsscript welches für aktuelle Ubuntu und Raspian Distributionen getestet ist (höchstwahrscheinlich aber auch für andere Debian basierte Distributionen funktioniert).

Signalbot ist weitgehend kompatibel mit SiSi, verfolgt aber technisch ein paar andere Ansätze und stellt zusätzliche Funktionalitäten zur Verfügung:
* Signalbot erzeugt keinen eigenen Prozess sondern integriert sich voll in die laufende FHEM Instanz (ist dadurch hoffentlich stabiler und verbraucht auch weniger Speicher)
* Gruppen werden grundsätzlich mit ihren Klarnamen verwendet und können auch nur mit einem vorangestellten "#" (statt "@#") gekennzeichnet werden.
* Kontakte werden soweit möglich auch mit Klarnamen (statt +49....) unterstützt. Diese kommen aus dem internen Adressbuch und können über "setContact" definiert werden, bzw. kommen bei verlinkten Accounts aus dem Adressbuch des Hauptgeräts.
* Die Möglichkeit von SVG oder DOIF Plots zu versenden (mit & wie bei anderen Anhängen, Details in den Beispielen)
* Wurde mit und für die aktuelle Version von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version vom Perl Modul Protocol::DBus (aktuell 0.22) benötigt
* Wird aktiv (Januar 2024) gewartet (letztes Update für SiSi auf github ist von August 2018)

=== "set" Funktionen im Detail ===

==== send [@<Recipient1> ... @<RecipientN>] [#<Group1> ... #<GroupN>] [&<Attachment1>; ... &<AttachmentN>] [<Text>] ====
* '''Recipient:''' Nummer mit Ländervorwahl (+49....) oder Kontaktname aus dem internen Adressbuch
* '''Group:''' Gruppenname, wie in Signal definiert im Klartext
* '''Attachment''': Dateiname (Pfad für muss für fhem lesbar und absolut oder relativ zum fhem home sein) oder Stream einer Bilddatei (z.B.)SVG
* '''Text:''' Die eigentlich Textnachricht, kann Leerzeichen und Umbrüche (mit "\n" oder \0x0a) enthalten
* Sofern ein Recipient, Group oder Attachment Leerzeichen enthält, den ganzen Teilstring in Anführungszeichen setzen: z.B. "@Max Mustermann"
* Wenn ein FHEM Befehl ausgeführt werden soll, dann diesen in runde Klammern setzen z.B. &({plotAsPng('SVG_Aussentemperatur')})

Ein paar Beispiele
send @+498514711 Hallo Signal
send #FHEM &/tmp/foto.jpg Ein Bild schicken
send "@Mein Freund" Leerzeichen durch Anführungszeichen um den ganzen Teilbefehl
send @Joerg #FHEM #Familie Jeder Empfänger, jede Gruppe und Attachments können mehrfach vorkommen
send "@({my $var=\"Joerg\";; return $var;;})" Perl Code mit Leerzeichen ausführen
send @(define dummy1 dummy) FHEM Befehl ausführen, wird aber nicht gesendet, da kein gültiger Empfänger zurück geliefert wird
send @Joerg &({plotAsPng(\'SVG_Aussentemperatur\')}) Einen FHEM SVG Plot verschicken oder
send @Joerg "&({plotAsPng('SVG_Aussentemperatur')})" so - oder
send @Joerg &SVG_Aussentemperatur so - oder
send @Joerg "&SVG_Aussentemperatur,day,-1" SVG Plot vom voherigen Tag
send @Joerg &DI_uitable Sende erstes Widget aus einem DOIF mit definiertem uiTable
send @Joerg "&DI_uitable,dev=outtemp,state" Sende erstes Widget dass Werte aus der Device "outtemp" verwendet aus definiertem uiState
send @Joerg Mehrzeilige Ausgabe:\nNeue Zeile
send @Joerg Umlaute öäü und Emojis 🙃😆🤗🤑🤪 sowie 𝐅𝐨𝐫𝐦𝐚𝐭𝐢𝐞𝐫𝐮𝐧𝐠𝐞𝐧 direkt senden oder
send @Joerg <nowiki><b>Fetter</b></nowiki> Text und Emojis :) :smile: - siehe get helpUnicode für Details
send @Joerg Die Aussentemperatur ist [out_temp:temperature] Grad
'''Tipp zu den Formatierungen''': Auf z.B. https://yaytext.com/ kann man sich seine UTF8 Kodierungen erstellen und nach FHEM per copy&paste einfügen. Vorrausetzung dürfte sein, dass die "locale" des Systems auf UTF8 eingestellt ist

'''Hinweis:''' Signalbot bietet in den Device Details eine "send message" Zeile um bequem Nachrichten zu versenden. Hier gibt es jedoch durch das Webinterface einige Einschränkungen, z.B. in der Verwendung von Anführungszeichen. Für komplexere Nachrichten, daher möglichst "set send" verwenden.

===== Details zum Versenden von Plots =====
Seit Signalbot V3.5 wird eine vereinfachte Form der Versendung von SVG Plots und sogar von DOIF uiTable Widgets unterstützt (siehe [[DOIF/uiTable Schnelleinstieg]]). Entspricht der mit "&" übergebene Anhang einem FHEM Device, und ist dies vom Typ SVG oder DOIF, wird dies besonders behandelt.

Für SVG wird die Funktion "plotAsPng" dann intern aufgerufen. Es können dabei mit Komma getrennt noch der "Zoom" und das "Offset" angegeben werden, als ''"&SVG_Device,Zoom,Offset"''. Es wird empfohlen den Term in Anführungszeichen zu setzen, das z.B. DOIF die Kommas sonst als FHEM Befehlstrenner interpretiert. Zoom ändert nicht die Größe! Diese bitte ggf. im SVG Device anpassen.

Erlaubte Werte für Zoom: hour, qday, day, week, month, year, 10years, 20years

Offset dürfte üblicherweise eine negative Zahl sein, und gibt an wie oft man zurückblättert (Zoom gibt dabei die Einheit an).

Die Unterstützung der DOIF Widgets verwendet einige Internas von DOIF und daher kann die Kompatibilität mit zukünftigen DOIF Versionen leider nicht garantiert werden. Falls es nach einem DOIF update nicht mehr funktioniert, bitte in Forum posten. Widgets werden primär aus dem Attribut uiTable genommen, ist dies nicht vorhanden, oder wird der Parameter "state" angeben, schaut Signalbot auch in uiState nach. Eine spezielle Fehlerbehandlung gibt es derzeit nicht, sondern es kommt nur die Meldung, dass die Datei nicht gefunden wurde.

'''Syntax''': ''"&DI_device,param1=wert1,param2=wert2" -'' die Verwendung von Anführungszeichen ist bei der Verwendung innerhalb eines DOIF nötig, das die Kommas sonst als Befehlstrenner interpretiert werden.

Mögliche Parameter:
* id : Sequentielle Nummer des Widgets welches angezeigt werden soll. Dabei zählen auch seperate Beschriftungen. "id=" kann auch weggelassen werden und nur die Zahl angegeben werden. "id" hat Vorrang vor "dev" oder "val"
* dev : Identifiziert das Widget über das FHEM Device aus welchem das Widget seine Daten holt. Ist dies nicht eindeutig, wird das Erste in der Liste verwendet - kann mit "val" kombiniert werden
* val : dentifiziert das Widget über das FHEM Reading aus welchem das Widget seine Daten holt. Ist dies nicht eindeutig, wird das Erste in der Liste verwendet - kann mit "dev" kombiniert werden
* zoom: Zoomfaktor bei der SVG->PNG Umwandlung. Dies ändert nicht die Größe des Bildes so dass ggf. Teile abgeschnitten werden.
* sizex / sizey: Ändert die Größe des Bildes, aber nicht des Widgets. Es sollten also üblicherweise zoom, sizex und sizey kombiniert werden bis das Ergebnis passt oder die Größe gleich im DOIF Widget angepasst werden.
* state : (ohne =) Hole die Widget Definition nicht aus uiTable sondern aus uiState
'''Achtung''': Es gibt einen bekannten Fehler, dass die SVG library die '''Halbring'''-Darstellung in der uiTable card nicht verdaut und diese daher nicht verwendet werden kann

==== setContact <Number> <Contactname> ====
Definiert einen Kontakteintrag im internen Adressbuch. Es kann beim '''send''' Befehl dann der ''ContactName'' statt der Nummer verwendet werden.

==== reinit ====
Verbindung zum DBus wiederherstellen. Dies sollte nicht nötig sein, außer der signal-cli Service funktionierte nicht richtig und wurde korrigiert. Ich rate hier aber eher zu einem FHEM Neustart.

==== createGroup <Groupname> [&<path to picture>] ====
Erzeugt eine neue Signalgruppe und versieht diese (optional) mit einem Gruppenbild.

==== updateGroup <Groupname> [<new Groupname>] [&<path to picture>] ====
Aktualisiert den Namen und/oder das Gruppenbild einer Gruppe.

==== invite <Groupname> <Contact1> [<Contact2>...] ====
Lädt einen oder mehrere Kontakte (per Namen oder Nummer) in eine bestehende Gruppe ein.

==== joinGroup <group link> ====
Einer bestehenden Gruppe beitreten. Dazu ist eine Einladung über einen "group link" nötig, der das Format <nowiki>https://signal.group/ https://signal.group/....</nowiki> hat. Der einfachste Weg hierzu ist es, wenn aus der Signal App die Funktion "group link" verwendet wird und der Link dann per Signal an den FHEM User gesendet wird. Sofern das ''autoJoin'' Attribut gesetzt ist, wird dieser erkannt und FHEM tritt der Gruppe automatisch bei.

==== reply <message> ====
Wie "send", nur kann der Empfänger weggelassen werden - stattdessen wird die Nachricht an den Absender der zuletzt empfangenen Nachricht gesendet

==== trust <Contact|"all"> ====
Setzt den entsprechenden Kontakt - oder mit "all" alle bekannten Kontakte auf "TRUSTED_UNVERIFIED". Dies ist manchmal nötig um von diesem Kontakt problemlos Nachrichten zu empfangen. Der Kontakt ist damit nicht vollständig verifiziert - dazu gibt es "trustVerified". Details über den Status eines Kontakts gibt es per "get identityDetails"

Die Liste ist mit Kontakten vorbefüllt, die noch "UNTRUSTED" sind - steht dort nur "all" sind also alle bekannten Kontakte mindestens "TRUSTED_UNVERIFIED". Sofern die Liste der Kontakte länger als 20 ist, ist die Nummer allerdings in ein Textfeld einzugeben, da das Dropdown sonst zu lang werden würde.

==== trustVerified <Contact> <SafetyNumber> ====
Validiert einen Kontakt als "TRUSTED_VERIFIED". Die SafetyNumber sollte üblicherweise auf einem sicheren Weg vom jeweiligen Kontakt übermittelt werden (z.B. vom persönlich vom Display abtippen oder über einen verifizierten Kommunikationskanal senden). Die Nummer ist aber symmetrisch (also für jedes Sender und Empfänger Paar gleich) und wird mit "get identityDetails" angezeigt und kann dort verglichen und dann einfach mit copy&paste übernommen werden. Kontakte denen voll vertraut wird, können via Signal Kommandos an FHEM senden, sofern ''authTrusted=yes'' gesetzt ist.

==== quitGroup <Groupname> ====
Aus einer Gruppe austreten. Die Gruppe wird dabei lediglich auf "inaktiv" gesetzt und ist mit ''get groups'' weiterhin als solche sichtbar. Eine Möglichkeit die Gruppe komplett aus dem Profil zu löschen besteht aktuell nicht.

==== block #<Groupname>|<Contact> ====
Blockiert eine Gruppe oder einen Kontakt (per Namen oder Nummer) serverseitig. Signalbot bekommt dann keine Nachrichten dieser Absender mehr (im Gegensatz zu ''allowedPeer'' bei der FHEM die Nachrichten noch bekommt, diese aber ignoriert.)

==== unblock #<Groupname>|<Contact> ====
Hebt die Blockierung wieder auf.

==== updateProfile <name> [&<Avatar picture>] ====
Setzt den Namen des Anwenders und optional ein Avatar Bild.

=== "set" Sonderfunktionen zur Registrierung ===

==== signalAccount <Telefonnummer> ====
Setzt eine bereits registrierte oder gelinkte Telefonnummer aktiv. Die bekannten Nummern werden als Pulldown zur Verfügung gestellt. Falls eine Nummer fehlen sollte, kann diese mit "set reinit" aktualisiert werden.

Ist nur eine Telefonnummer registriert, wird diese automatisch verwendet.

Wenn mehrere Nummern gleichzeitig verwendet werden sollen, braucht jede Nummer eine eigenen Instanz des Moduls.

==== register <Telefonnummer> ====
Eine neue Nummer für Signal registrieren. Die Telefonnummer muss in Internationaler Schreibweise (+49.....) angegeben werden.

Signalbot führt den Anwender in einer Art Wizard (Detailtexte auf der Modulseite) durch den Registrierungsprozess. Der erste Schritt ist, eine Nummer festzulegen. Üblicherweise ist das eine Festnetznummer, was die normale Verwendung der Nummer nicht beinträchtigt.

'''Achtung:''' Hier nicht die Handynummer eines Smartphones verwenden auf dem Signal schon installiert ist. Das Handy würde dadurch von Signal abgemeldet. Dazu kann "link" verwendet werden.

'''Wichtig:''' Im Laufe der Registrierung wird eine Verifikationsnummer übermittelt, normalerweise per SMS. Für Festnetznummern sollte man das aber üblicherweise auf Sprachanruf umstellen. Dazu das Attribut "registerMethod" auf "Voice" umstellen.

Die Registrierung wird meistens durch ein Captcha geschützt. Details dazu weiter unten.

'''captcha <signalcaptcha://.......>'''

Setzen des Captcha String im Rahmen der Registrierung. Details dazu, wie man den bekommt und wie der Prozess teilweise automatisiert werden kann weiter unten

==== verify <Verifizierungscode> ====
Setzen des Codes, den man im Rahmen der Registrierung per SMS oder Sprachanruf übermittelt bekommen hat.

Dies ist der letzte Schritt der Registrierung. Danach ist Signalbot einsatzbereit.

==== link <Name> ====
Zeigt einen QR Code an, den man mit der Signal App auf dem Smartphone scannen kann um FHEM als "Mitbenutzer" zu registrieren. FHEM erhält dann alle Nachrichten und gesendete Nachrichten haben den Absender des Telefons. Dies ist ein einfacher und schneller Weg um Signalbot auszuprobieren, sollte aber nicht für die produktive Benutzung verwendet werden, um unerwünschte Nebeneffekte zu vermeiden. Da FHEM nicht benachrichtigt wird, wenn der "link" zustande gekomme ist, muss danach manuell ein "set reinit" durchgeführt werden.

Der optionale Name (wenn leer wird "FHEM" verwendet) dient zur Identifizierung.

Die angezeigte URI kann mittels "addDevice" auch dafür verwendet werden zwei FHEM Instanzen miteinander zu verküpfen, welches auf der Hauptinstanz ausgeführt wird.

==== addDevice <device URI> ====
Fügt eine andere Instanz als "Mitbenutzer" hinzu. Die URI wird mit "set link" auf der anderen (nicht registrierten) FHEM Instanz erzeugt.

Dabei ist zu beachten, dass alle Nachrichten/Befehle an beide Instanzen gehen, was bei entsprechenden Triggern zu beachten ist. Ansätze dazu sind mit "allowedPeer" auf unterschiedliche Sender zu reagieren, unterschiedliche cmdKeyWord's zu setzen etc.

==== removeDevice <deviceID> ====
Entfernt einen Mitbenutzer anhand seiner deviceID. Diese kann mit "get devices" abgefragt werden. Wenn nur Mitbenutzer verlinkt ist, ist da üblicherweise "2" da "1" dem Hauptbenutzer zugeordnet wird.

=== "get" Funktionen im Detail ===

==== contacts all|nonblocked ====
Öffnet ein Fenster mit allen bekannten Kontakten mit Telefonnummer und Kontaktname sowie deren "blocked" Status. Mit dem Parameter "nonblocked" werden geblockte Kontakte ausgeblendet. Als Name wird primär der selbstdefinierte Kontaktname angezeigt. Sofern keiner definiert ist, wird der durch den Kontakt selbst definierte Profilname angezeigt.

==== chat <Contact|Group> ====
Signalbot speichert eine kurze Chat Historie per Kontakt oder Gruppe die hiermit abgerufen wird. Die Gruppen sind aktuell mit "+" statt "#" gekennzeichnet, da es mit dem "#" Zeichen Probleme in der Implementierung gab.

Die Historie wird nicht abgespeichert, ist also nach einem Neustart wieder weg und beschränkt sich auf 20 Zeilen.

==== groups all|active|nonblocked ====
Öffnet ein Fenster mit allen bekannten Gruppen. Es wird der Gruppenname, der "Active" Status (ist FHEM Mitglied der Gruppe), der "Blocked" Status sowie die Liste der anderen Gruppenmitglieder angezeigt. Mit dem Parameter "active" wird die Liste auf Gruppen beschränkt, in denen FHEM Mitglied ist, mit "nonblocked" werden zusätzlich noch geblockte Gruppen ausgeblendet.

==== accounts ====
Zeigt alle aktuell in signal-cli registierten Telefonnummern an, die mit "set signalAccount" verwendet werden können.

==== devices ====
Zeigt alle verlinkten Mitbenutzer an. Üblicherweise hat dies nur einen Eintrag (den Hauptbenutzer = aktuelle Instanz). Die ID Nummer können mit "removeDevice" verwendet werden um Mitbenutzer zu entfernen.

==== favorites ====
Listet die definierten Favoriten im Attribut "favorites" (siehe unten) in tabellarischer Form auf. Nützlich um zu prüfen ob das Attribut korrekt befüllt ist.

==== helpUnicode ====
Zeigt alle unterstützten Tags zur Formattierung von Nachrichten mittels HTML oder Markdown Tags.

'''Achtung''': Die Funktion muss über dass Attribut ''formatting'' aktiviert werden.

==== identityDetails <Contact> ====
Zeigt Systemdetails zu einem Kontakt an. Neben dem vollen Namen, dem Trust Level (UNTRUSTED,TRUSTED_UNVERIFIED oder TRUSTED_VERIFIED), die SafetyNumer die mit "set trustVerified" verwendet werden kann um den TRUSTED_VERIFIED Status zu setzen, wann der Kontakt zu signal-cli hinzugefügt wurde sowie einen QR-Code der mit der Signal App gescannt werden kann um umgekehrt TRUSTED_VERIFIED für FHEM auf dem Telefon zu setzen.

=== Attribute im Detail ===
==== authTimeout ====
Gibt bei Verwendung des {{Link2CmdRef|Anker=GoogleAuth|Label=GoogleAuth}} device die Dauer in Sekunden an, die ein Nutzer authentifiziert bleibt. Siehe ''commandKeyword'' für mehr Infos.

==== authDev ====
Name des genutzten GoogleAuth device. Dies wird üblicherweise automatisch gesetzt, sofern bereits ein GoogleAuth device im System definiert ist, sobald das ''authTimeout'' gesetzt wird.

==== authTrusted ====
Falls auf "yes" gesetzt, dürfen Kontakte die den Vertrauensstatus "TRUSTED_VERIFIED" haben auch ohne GoogleAuth Kommandos an FHEM senden. Da Signal z.B. mit diesem Mechanismus vor Accountübernahme, Handywechsel etc. schützt, ist die Identität des Kontakts zweifelsfrei sichergestellt und die umständliche Eingabe eines Codes von GoogleAuth kann entfallen.

==== autoJoin 0|1 ====
Falls auf 1 gesetzt, reagiert FHEM automatisch auf Einladungslinks (siehe ''joinGroup'') und tritt der Gruppe bei

==== cmdKeyword ====
Eine Zeichenkette aus einem oder mehreren Zeichen, die am Anfang einer Nachricht stehen kann, damit FHEM die restliche Nachricht ungefiltert als Kommando ausführt. Die Funktion ist über GoogleAuth geschützt, d.h. ein Benutzer muss sich erst mit einem gültigen GoogleAuth Token legitimieren und bleibt entsprechend des ''authTimeout'' Attributs für gewisse Zeit authorisiert.

''Beispiel:''

Man setzt ''cmdKeyword'' auf "=" , dann kann man ''"=123456 set lamp off"'' senden. Im weiteren Verlauf reicht ''"=set lamp on"'' solange bis der Timeout abgelaufen ist.

Zur Authorisierung muss nicht zwingend gleich ein Befehl mitgesendet werden. Sofern ''allowedPeer'' gesetzt ist, muss der Absender zusätzlich in dieser Liste stehen.

==== defaultPeer ====
Gruppe, Kontaktname oder Nummer an die '''send''' eine Nachricht schicken soll, wenn kein Empfänger mit @ oder # definiert wurde.

==== allowedPeer ====
Komma getrennte Liste von Gruppen, Kontaktnamen oder Nummern auf die Signalbot reagieren soll (also bei empfangenen Nachrichten Readings aktualisiert). Ist dieses Attribut nicht gesetzt, reagiert Signalbot auf alle Nachrichten.

==== babblePeer ====
Komma getrennte Liste von Gruppen, Kontaktnamen oder Nummern auf die Signalbot reagieren soll indem es die Nachricht an das über '''babbleDev''' (nicht zu verwechseln mit ''babbleDevice'') definierte [[Modul Babble|Babble]] Modul schickt. Die Nachrichten werden zuerst (beschränkt auf allowedPeer) normal verarbeitet (also Readings aktualisiert) und nur nach Babble gesendet wenn diese Attribut gesetzt ist.

Der Absender der Nachricht (Gruppe hat Prio über individuellem Absender) wird Babble als ''$PARM0'' übergeben. Dazu in Babble noch das Attribut helpFunc wie folgt setzen
{fhem("set SignalBot send \@$PARM0 $HELP")}
Sollen die rivescript Spracherweiterungen genutzt werden muss außerdem "noChatbot" auf 0 stehen.

Nach dem selben Prinzip können in der Babble Definition auch Antworten spezfisch für Devices angelegt werden, z.B. als Aktion für out-temp -> Temperatur -> draußen -> sagen -> Status:
set SignalBot send @$PARM0 Die Temperatur draußen ist [out_temp:temperature] Grad
Womit die Frage (ohne Fragezeichen!) "Wie ist die Temperatur draußen" entsprechend quittiert wird.

==== babbleDev ====
Name des definierten Babble Device.Wird beim Setzen vom babblePeer automatisch mit der ersten "Babble" Device gefüllt sofern vorhanden.

==== babbleExclude ====
Regulärer Ausdruck auf den Nachrichtentext um bestimmte Nachrichten von der Weiterleitung zu Babble auszuschließen (ein Event wird trotzdem generiert und kann mit Notify, DOIF etc. verarbeitet werden).

==== registerMethod <SMS|Voice> ====
Stellt die Registrierungsmethode (Rückmeldung des Verifizierungscodes) auf SMS oder Sprachanruf um.

==== cmdFavorites ====
Definiert eine Zeichensequenz die bei remote Befehlen (siehe ''cmdKeyword'') als Favorit interpretiert wird. Details siehe unter ''favorites''. Da Favoriten vor FHEM Befehlen ausgewertet werden, sollte z.B. "set" nicht verwendet werden.

==== formatting <none|html|markdown|both> ====
Aktiviert die Ersetzung von html-ähnlichen Formatierungen (z.B. <nowiki><b>bold text</b></nowiki>) und/oder Markdown (z.B. __italic text__) um diese direkt in ASCII angeben zu können, anstatt nur per copy&paste.

Die komplette Liste von Tags/Ersetzungen kann über die ''get helpUnicode'' Funktion direkt im Model angezeigt werden.

==== favorites <[alias1]><-><command1>;<[alias2]><-><command2>;.... ====
Definiert Favoriten um remote Befehle (siehe ''cmdKeyword'') abzukürzen.

Einträge werden durch Semikolon getrennt und automatisch durchnummeriert.

Optional kann in eckigen Klammern "[]" ein alias angebenben werden, sowie ebenfalls optional dem Befehle ein Minuszeichen "-" vorangestellt werden, womit für diesen Befehl keine vorherige GoogleAuth Authentifizierung zu erfolgen hat.

'''Wichtig:''' Favoriten funktionieren nur wenn ''cmdKeyword, cmdFavorites, authTimeout, authDev'' und ''favorites'' gesetzt sind.

'''Beispiele''' (angenommen cmdKeyword="/" , cmdFavorites="fav", favorites="set lamp on;[off]set lamp off;[hi]-set talk say Jemand zuhause"):
{| class="wikitable"
|+
!Befehl
!Effekt
|-
|/fav 1
|Fehler weil nicht authentifiziert
|-
|/fav 3
|"set talk" Befehl wird ausgeführt, da "-" Befehle ohne Authentifizierung funktionieren
|-
|/fav hi
|"set talk" Befehl wird ausgeführt
|-
|/123456
|GoogleAuth Token setzen um remote Befehle freizuschalten
|-
|/fav 1
|"set lamp on" wird ausgeführt
|-
|/fav off
|"set lamp off" wird ausgeführt
|-
|/fav
|Liste all Favoriten mit IDs wird ausgegeben
|}

=== Readings im Detail ===
{| class="wikitable"
|account
|Aktuell verwendete Telefonnummer (nur verfügbar wenn signal-cli 0.9.0 ohne -u Parameter gestartet wurde)
|-
|joinedGroups
|Liste der beigetretenen Gruppen getrennt mit Leerzeichen
|-
|lastError
|Text der letzten Fehlermeldung. Bitte unbedingt den Timestamp beachten. Das Reading wird bei erfolgreichen Aktionen nicht zurückgesetzt und enthält ggf. sehr alte Fehlermeldungen.
|-
|msgAttachment
|Attachments (Dateinamen im signal-cli repository) der zuletzt empfangenen Attachments
|-
|msgGroupName
|Gruppenname aus der zuletzt eine Nachricht empfangen wurde - leer wenn es eine persönlich Nachricht war
|-
|msgSender
|Absender der letzten Nachricht als Nummer oder wenn bekannt als Name
|-
|msgText
|Empfangenen Nachricht
|-
|msgTimestamp
|Zeitstempel der Nachricht
|-
|msgAuth
|Ist auf 1 gesetzt wenn der Absender der aktuellen Nachricht (also zum Zeitpunkt zu dem z.B. ein Notify/DOIF die Nachricht auswertet) per GoogleAuth authentifiziert war.
|-
|prevMsgAttachment
| rowspan="5" |Wie oben, nur enthalten diese Readings die Daten der zuvor empfangenen Nachricht (n-1)
|-
|prevMsgGroupName
|-
|prevMsgSender
|-
|prevMsgText
|-
|prevMsgTimestamp
|-
|sentMsg
|Zuletzt gesendete Nachricht
|-
|sentMsgRecipient
|Empfänger der zuletzt gesendeten Nachricht. Enthält zumeist den Namen aus der Empfangsbestätigung und somit bei vielen Empfängern den zuletzt bestätigten Empfang.

Dies muss nicht zwingend auf die zuletzt gesendete Nachricht (sendMsg) passen, wenn mehrere Nachrichten versendet wurden.
|-
|sentMsgTimestamp
|Zeitstempel des Empfangs oder "pending" wenn noch keine Bestätigung vorliegt
|-
|VERSION
|Internal Reading die die aktuelle Version von Signalbot, signal-cli und Dbus angibt - vor Support Anfragen bitte erst im Forum prüfen ob die aktuellste Version verwendet wird und ggf. updaten.
|}

== Installation ==
Zur Installation steht das Script "signal_install.sh" zur Verfügung, welches aber nicht zwangsweise in jeder Umgebung funktioniert. Daher erst einmal ein paar Referenzen zur manuellen Installation von signal-cli:
* Quickstart (englisch) für [https://github.com/AsamK/signal-cli/wiki/Quickstart signal-cli]
* Anleitung zum [https://github.com/AsamK/signal-cli/wiki/Provide-native-lib-for-libsignal#libsignal-client Übersetzen und Installieren der Libraries] für armv7 (Raspberry) da die Distribution nur x86 libraries enthält
* CPAN Seite des Perl Moduls zur [https://metacpan.org/pod/Protocol::DBus DBus Kommunikation]
Vorbereitung:

Das Script "signal_install.sh" aus der Detailseite des Moduls oder vom [https://svn.fhem.de/fhem/trunk/fhem/contrib/signal/ FHEM SVN] runterladen und ins Verzeichnis eines beliebigen "sudo"-fähigen Users kopieren.

Das Script hat mehrere Optionen um Teilfunktionen direkt auszuführen, diese sind:
{| class="wikitable"
|+
!Argument
!Bedeutung
|-
|system
|System für die signal-cli Installation vorbereiten. Es werden per "apt install" fehlende Pakete installiert und Verzeichnisse erstellt.
Muss mindestens einmal erfolgreich gelaufen sein, damit die restliche Installation funktioniert
|-
|install
|Installiert signal-cli als System Service. Automatischer Download, Installation und Konfiguration (dbus, systemd)
|-
|test
|Versendet eine Testnachricht auf zwei Arten - direkt mit dem Client (klappt das, ist die Grundregistrierung schon mal erfolgreich) und über Dbus (dann ist auch der System Service korrekt eingerichtet)
|-
|remove
|Löscht alle durch "install" installierten Verzeichnisse und Dateien (aber nicht die Pakete die durch "system" installiert wurden)
|-
|start
|Starten des singal service über systemd bzw. im Container des Dbus daemon and signal-cli Daemon
|-
|backup
|Erstellt ein Archiv aller relevanten Scripts und Einstellungen (z.B. für einen System Umzug) in der Datei signal-backup.tar.gz
|-
|restore
|Schreibt die Archive Datei signal-backup.tar.gz ins System zurück
|}
Im Normalfall kann das script einfach unter root Rechten, also mit
sudo -E ./signal_install.sh
aufgerufen werden (wenn das Script per Download geholt wurde, muss es vorher noch mit "chmod a+x signal_install.sh" ausführbar gemacht werden). Wenn kein Argument übergeben wird, dann wird automatisch der Ablauf ''system -> install -> test'' durchlaufen.

Wenn Betriebssystem oder CPU Architektur nicht unterstützt werden, gibt es eine Warnung bzw. das Script bricht ab.

'''Hinweis:''' Es prüft außerdem ab, ob es im Container läuft. Dieser Modus ist nur dafür gedacht, wenn mein FHEM/Signal Container Script verwendet wurde. In anderen Container Umgebungen wird es üblicherweise nicht funktionieren. Details dazu weiter unten.

Dann Modul per '''"define <name> Signalbot"''' definieren.

=== Registrierung ===
Die Registrierung wird ab Version 3.0 nicht mehr im Script sondern in FHEM selbst geführt durchgeführt.

'''Hinweis:''' Eine Nummer kann immer nur '''einmal''' registriert sein. Eine bereits bestehende Registrierung (Smartphone) wird dabei '''aufgehoben'''. Daher entweder eine Festnetznummer verwenden mit der Option "link" FHEM als Zweitbenutzer zu einer bestehenden Nummer hinzugefügen. Dies ist zum Testen ok, aber produktiv ist davon abzuraten, da FHEM dann alle Mitteilungen bekommt die man am Handy auch kriegt, was zu unerwarteten Nebeneffekten führen kann.

Die Registrierung erfolgt mit "set register <nummer>" (Telefonnummer in internationaler Schreibweise mit +49....).

Nach erfolgter Registrierung bekommt man je nach Wert des Attributs "registerMethod" eine SMS oder einen Sprachanruf mit einer Verifikationsnummer.

Signal versucht sich gegen unberechtigte Nutzung des Service (man könnte ja damit quasi SMS/Telefonterror betreiben) zu schützen. Nach gewissen Kriterien (soweit bekannt z.B. Registrierung aus einer VM oder über VPN) wird daher ein Captcha verlangt.

FHEM führt hierbei durch den Prozess mit Hilfestellungen

Ablauf:
# [https://signalcaptchas.org/registration/generate.html Captcha Seite] von Signal aufrufen. Link ist auch direkt in FHEM verfügbar
# Nach erfolgreichem Lösen des Captchas erscheint ein Link "Signal öffnen" bzw. unter Windows besteht eine Automatisierungsoption (siehe unten)
# Üblicherweiser (Browserspezifisch) kann hier mit Rechtsklick und "Adresse des Links kopieren" das "signalcaptcha" kopiert werden
# Diesen String dann im "set captcha" Befehl eintragen und dann sollte die Registrierung weitergehen (SMS/Anruf)
#* SMS: Hier sollte relativ zeitnah eine SMS mit einem 6-stelligen Code übermittelt werden
#* Voice: Die Registrierung per Sprachanruf ist mit einigen Hürden versehen. Man muss erst mit SMS registrieren, 1 Minute warten, dann mit Voice. Ab Signalbot V3.19 wird dieser Vorgang automatisiert. Dauert aber durch die zwingende Wartezeit von 1 Minute ein wenig.

'''Captcha "Automatisierung":'''

Am einfachsten ist die Registrierung wenn sich von Windows aus mit FHEM verbindet. Hier stellt Signalbot ein Windows Registry File (signalcaptcha.reg) zum Download zur Verfügung. Dieses einfach runterladen und per Doppelklick in die Registry eintragen.

Wenn jetzt die Signal Captcha Seite besucht wird, wird nach Bestätigung ein Powershell Script welches einfach wieder FHEM mit der entsprechenden "set captcha" Befehl automatisch ausführt.

Für Linux habe ich aktuell nur eine Lösung für Firefox. Hier die signalcaptcha.desktop runterladen und nach ''~/.local/share/applications/signalcaptcha.desktop'' kopieren und mit ''xdg-mime default signalcaptcha.desktop x-scheme-handler/signalcaptcha'' (alles mit dem Desktop User) aktivieren. Dann sollte ebenfalls automatisch FHEM aufgerufen werden.

'''Wichtig:''' Wenn csrf-Tokens nicht abgeschaltet sind, werden diese bei jedem FHEM Neustart neu erzeugt, womit man auch neue .reg/.desktop Dateien benötigt (set reinit, neuer Download)

==== Verifizierung ====
Zuletzt wird mit "set verify" der Verifizierungscode eingetragen und die Registrierung ist damit abgeschlossen.

=== Bestehende Nummer verlinken ===
Alternativ kann man auch eine bestehende Nummer verlinken. Dazu "set link" aufrufen. Es wird jetzt ein QR-Code auf dem Bildschirm angezeigt. In der Signal App dann auf Settings->Linked Devices gehen und mit "+" den QR-Code abfotografieren.

Bitte beachten, dass bei verlinkten Devices immer alle Devices (also auch das Smartphone) Nachrichten bekommen. Bei reinem Sendebetrieb dürfte das weniger stören, soll aber auch auf Befehle reagiert werden, dann ist das eventuell verwirrend.

== Einrichtung des Moduls ==
Siehe Forenthema {{Link2Forum|Topic=118370|LinkText=Neues Modul: Signalbot}}.

Nachdem alles sauber eingerichtet ist und das Modul im FHEM Directory abgelegt wurde, entweder ein "reload 50_Signalbot" oder besser ein "shutdown restart" von FHEM machen.

Das Modul dann einfach mit
define <name> Signalbot
definiert.

== Umstieg von SiSi ==
Da SiSi eine inzwischen sehr alte '''signal-cli''' Version verwendet, die sehr wahrscheinlich nicht mehr voll abwärtskompatibel ist, wird von einer einfachen Migration abgeraten.

Die Installation und Neuregistrierung der Nummer ist inzwischen soweit vereinfacht worden, dass diese Vorgehensweise weniger aufwändig ist.

Ohne Garantie, dass dies mit der aktuellen signal-cli/Signalbot Version noch funktioniert hier trotzdem die potentielle Migration:

Signalbot allerdings eine andere Dbus Implementierung (Protocol::DBus), diese muss erst installiert werden:
:<syntaxhighlight lang="bash">cpan install -f Protocol::DBus</syntaxhighlight>
Sofern nach dem SiSi Wiki vorgegangen wurde, dann sind folgende Anpassungen im Script notwendig:
SIGNALPATH=/opt/fhem
SIGNALUSER=fhem
SIGNALVAR=/opt/fhem/.local/share
Das Verzeichnis /opt/fhem/signal-cli kann gelöscht werden.

Wenn mein Installationsschema übernommen werden soll, dann
sudo mv /opt/fhem/.local/share/signal-cli /var/lib

Jetzt kann das Script einfach wie oben beschrieben gestartet werden.

=== Umzug auf ein neues System ===
Dazu einfach das Script mit dem Argument "backup" starten. Die alte Konfiguration wird dabei im Home Verzeichnis des aktuellen Benutzers als ''~/signal-backup.tar.gz'' gesichert.

auf dem neuen System dann diese Datei wieder ins Home und entsprechend das Script mit "restore" laufen lassen.
== Eigene native Library übersetzen ==
Signal-cli ist zwar überwiegend in Java geschrieben, hat aber leider eine binäre Library die zwingend benötigt wird. Ohne diese startet der Service nicht.

Der Installler lädt automatisch die korrekte Library für unterstützte Architekturen und ersetzt die am64/glibc-2.31 die von signal-cli standardmäßig mitgeliefert wird. Unterstützt werden aktuell:
* Raspberry (armv7l) für Buster (glibc2.28) und Bullseye (glibc2.31)
* Raspberry 64-bit (aarch64) für glibc2.28 (ungetestet, sollte für Buster und Bullseye funktionieren)
* AMD/Intel 64-bit (amd64) für glibc2.28 und glibc2.31 (Ubuntu 18,20,22, Debian 10,11 u.a.)
Es gibt mehrere github Projekte um signal-cli die auch fertig übersetzte libsignal_jni.so im Angebot haben (einfach mal suchen). Man kann sich die Library aber auch selbst übersetzen.

Ich gehe dabei davon aus, dass eine (wenn auch inkompatible) Installation von signal-cli bereits erfolgt ist und z.B. alle Java libraries an Ort und Stelle sind.

Es werden eine Reihe von Programmen benötigt. Diese Liste ist möglicherweise nicht vollständig, je nachdem wie eurer System konfiguriert ist:<syntaxhighlight lang="shell">
sudo apt-install git build-essential clang cmake openjdk-17-jdk-headless
sudo curl https://sh.rustup.rs -sSf | sh
</syntaxhighlight>Es ist hier wichtig, dass die libsignal-client in der Version passt, daher in der signal-cli Installation checken<syntaxhighlight lang="shell">
ls /opt/signal/lib/libsignal-client*
</syntaxhighlight>Und die Versionsnummer notieren (für signal-cli 0.11.3 ist das 0.20.0)

Jetzt entsprechend auschecken<syntaxhighlight lang="shell">
git clone git@github.com:signalapp/libsignal-client.git
cd libsignal-client
git checkout v0.20.0
cd java
./build_jni.sh desktop

</syntaxhighlight>''libsignal_jni.so'' aus ''target/release/'' nach ''/opt/signal/lib'' kopieren

Libraries in den Java .jar Files durch die selbst compilierten ersetzen:<syntaxhighlight lang="shell">
cd /opt/signal/lib
sudo -u signal-cli zip -u signal-client-java-*.jar libsignal_jni.so
</syntaxhighlight>Dann Service neu starten

<code>sudo service signal start</code>

Wenn alles richtig funktioniert hat, sollte der Service jetzt laufen (syslog prüfen, oder ''ps -ef | grep signal-cli )''

== Installation im Docker Container ==
Um signal-cli in einem Docker Container zu installieren stellt sich die Schwierigkeit, dass man dort nicht so einfach Dienste per systemd starten kann und die Kommunikation zum System Dbus schwierig ist. Dies wird in durch die spezielle Docker Installation umgangen, indem der dbus-daemon dort eigens gestartet wird und signal-cli per script in den Hintergrund gestartet wird.

Unter Verwendung [https://svn.fhem.de/fhem/trunk/fhem/contrib/signal/fhem_signal_docker_install.sh dieses Scripts] wird eine komplette FHEM Basisinstallation per Docker erstellt und dort signal-cli eingerichtet.

==== Funktionsweise: ====
Das Script erstellt alle notwendigen Dateien in einem User Verzeichnis (default: $HOME/fhem) und installiert dort auch in "fhem-<version>" die aktuelle FHEM Version sowie ein Verzeichnis "signal" für die Registrierungsdaten. Diese sind somit persistent außerhalb des Containers und können auch von außen überschrieben werden.

Wer bereits eine Signal Registrierung einer normalen Installation hat, kann diese von /var/lib/signal-cli in dieses "signal" Verzeichnis kopieren, so das sie verwendet wird.

Das Script muss mit "sudo" ausgeführt werden und hat noch die Option "remove" alle Dockerdateien die es erzeugt auch wieder zu entfernen. FHEM bleibt dabei unangetastet.

Bei einer erneuten Erstellung des Containers (z.B. um package updates oder eine neue signal-cli Version einzuspielen) kann man wählen FHEM nicht neu zu installieren womit es danach genauso konfiguriert wieder gestartet wird.

Der Container wird basierend auf einem aktuellen Ubuntu Image erzeugt (aktuelle Ubuntu 20.04). Falls in FHEM Module verwendet werden, müssen oft weiteren Pakete (über apt, cpan oder npm) installiert werden. Im Installscript finden sich hier auskommentiert ein paar Hinweise wie für einige gängige Module (bzw. eben welche die ich verwende) die entsprechenden Abhängigkeiten mit eingebunden werden können.

'''Achtung:''' Das Ganze ist experimentell und für eine einmalige Installation/Start gebaut. Wenn fhem, signal-cli oder der dbus-daemon im Docker beendet werden, dann muss man diese evtl. selbst wieder nachstarten. Das kann man sicher noch einiges verbessern. Sinnvollerweise nimmt man die erzeugten Config Dateien und Scripte eher als Anregung für eine eigene Konfiguration. Verbesserungsvorschläge gerne auch im Forum.

== Versenden von Nachrichten ohne FHEM ==
Falls jemand auch aus Shell Scripten heraus Signal Nachrichten versenden möchte, kann die FHEM signal-cli Installation am einfachsten über den "dbus-send" Befehl mitverwendet werden:

<code>dbus-send --system --type=method_call --print-reply --dest=org.asamk.Signal /org/asamk/Signal/_xxxxxx org.asamk.Signal.sendMessage string:Hallo array:string: string:+49yyyy</code>

''/org/asamk/Signal/_xxxxxx'' entspricht hier der registrierten Nummer und steht in FHEM Signalbot im Status ("connected to ..."). Dabei wird das "+" in der Nummer durch "_" ersetzt.

Wichtig ist bei Dbus Nachrichten nicht nur der Name der Methode (sendMessage) sondern auch Typ und Reihenfolge der Parameter. Für ''sendMessage'' heisst das:
# Die eigentliche Nachricht als String
# Ein Array von Strings die Attachments enthalten (da man dies von der Kommandozeile eher nicht machen wird, erzeugt ''array:string'' hier einen leeren Parameter)
# Die Telefonnummer der Empfängers als String
Grundsätzlich kann man so alle Dbus Methoden von signal-cli ansteuern, welche unter https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-dbus.5.adoc dokumentiert sind.

Einige Dinge sind aber nicht so komfortabel, z.B. kann man Gruppen nicht per Namen, sondern nur über einen langen base64-kodierten String ansteuern - hier übernimmst SignalBot eine benutzerfreundliche Übersetzung.

Eine weitere Alternative ist dann einfach einen FHEM Befehl abzusetzen - z.B. per ''telnet'' Kommando.

Alternativ geht es auch direkt über den signal-cli client. Dafür muss aber vorher der service beendet sein (Konflikt):
sudo service signal stop
sudo -E -u signal-cli /opt/signal/bin/signal-cli -c /var/lib/signal-cli -u +49<registrierte Nummer> send -m "testmessage" +49<Empfänger>

== Fernsteuerung und Authentifizierung ==
Signalbot ermöglicht es FHEM über Signal fernzusteuern und dies auch abzusichern.

Um die Fernsteuerung zu aktivieren muss zuerst über das Attribut "cmdKeyword" festgelegt werden, woran Signalbot erkennen soll, dass es sich um einen Befehl handelt. In dieser Dokumentation gehe ich jetzt davon aus das "/" als Keyword gesetzt ist. Das Keyword kann auch mehrere Zeichen lang sein.

Sendet man jetzt "/set lamp on" an Signalbot, so führt dieser das entsprechende set Kommando direkt aus.

Dies ist natürlich sicherheitstechnisch ein offenes Scheunentor und es gibt mehrere Methoden der Absicherung

==== Attribut allowedPeer ====
Dieses Attribut enthält eine Komma-getrennte Liste von Nummer, Kontakt- oder Gruppennamen welche als gültige Absender akzeptiert werden. Ist es nicht gesetzt kann jeder mit Signalbot kommunizieren und Kommandos senden oder Events triggern

==== GoogleAuth ====
Vorrausetzung ist, dass man in FHEM ein GoogleAuth Device angelegt hat und entsprechend auch die App auf dem Telefon. Näheres in der Commandref.

Über das Attribut "authDev" kann die GoogleAuth Device zugewiesen werden. Üblicherweise ist dies nicht erforderlich, da SignalBot dieses in System sucht und das Attribut automatisch setzt.

Um die Prüfung per GoogleAuth zu aktivieren wird das Attribut "authTimeout" (in Sekunden) gesetzt, welches definiert wie lange eine erfolgreiche Authentifierung gültig bleibt.

Wenn jetzt Befehle an FHEM gesendet werden, quittiert Signalbot diese mit "You are not authorized to execute commands". Zur Authentifizierung wird einfach die 6-stellige Nummer aus dem Google Authenticator mit vorangestelltem Keyword an FHEM gesendet, also z.B. "/123456"

Man erhält die Meldung, dass man nur für gewisse Zeit (authTimeout) authentifiziert ist und kann Kommandos senden.

==== Trust ====
Signal hat eine eigene Funktionalität um Kommunikationspartner zu überprüfen und Ihnen das Vertrauen auszusprechend. Siehe dazu "set trust" und "set trustVerified". Da die Authentifizierung per GoogleAuth auf Dauer lästig sein kann, besteht die Möglichkeit diese für verifizierte vertraute Nutzer zu umgehen. Dazu wird das Attribut "authTrusted" auf "yes" gesetzt. Nutzer denen nicht voll vertraut wird, müssen sich weiter authentifzieren.

====== Favoriten ======
Der Vollständigkeit halber sei hier noch erwähnt, dass man Befehlskürzel per Favoriten definieren kann. Details dazu in der Beschreibung der set Befehle und Attribute.

Per Attribut "cmdFavorite" wird festgelegt welches Keyword die Favoritenauswahl triggert. Das könnte z.B. auch "/" sein, so dass "// 1" den ersten Favoriten triggert. Dass Attribute "favorites" enhält dann die eigentliche Definition der Favoritenliste.

== Troubleshooting / FAQ ==
Anmerkung: Ich gehe hier davon aus, dass die Installation mit den im Script voreingestellten Pfaden/Users durchgeführt wurde. Änderungen auf eigene Gefahr.

Bevor ich hier ein paar typische Probleme und Lösungen aus dem Foren Thread aufliste, bitte folgende Punkte sicherstellen:
# Ich verwende eine unterstütztes Betriebssystem (Raspbian oder Ubuntu) und CPU Architektur (armv7l oder x86)
# Ich habe das neuste Install Script aus https://svn.fhem.de/fhem/trunk/fhem/contrib/signal/ verwendet
# Ich habe vor der Installation nach besten Wissen und Gewissen Reste einer vorherigen Installation (z.B. auch für SiSi) entfernt (das Repository kann weggesichert werden um eine erneute Registrierung zu vermeiden und dann statt dem Registrierungsschritt in /var/lib/signal-cli kopiert werden
# Ich habe das Install Script gemäß Anleitung vollständig durchlaufen lassen und auf Fehlermeldungen geachtet

==== Wo finde ich Fehlermeldungen/Logfiles? ====
* Beim Install Script direkt in der Console - achte auf die Bildschirmausgabe
* Beim Install Script auch in ''/tmp/signal_install.log'' - ggf. wegsichern da es bei jedem Durchlauf wieder überschrieben wird.
* Fehler beim Starten und Betrieb des signal-cli service (normale Installation) in /var/log/syslog
* Fehler beim Betrieb in FHEM im normalen FHEM log (ggf. Signalbot mit verbose=5 definieren)
* Im Container, sofern die Daemons mit dem Install Script gestartet wurden, schreiben ihr log in /var/log/dbus.log bzw. signal.log und die Fehlerausgabe in /var/log/dbus.err bzw. signal.err

==== Probleme bei normaler Installation ====
{| class="wikitable"
|+
!Fehler
!Lösungsansatz
|-
|'''In FHEM:'''
Error sending message:org.asamk.Signal.Error.Failure: org.whispersystems.signalservice.api.push.exceptions.NotFoundException: Not found
|signal-cli läuft nicht.
Prüfe ggf. '''/var/log/syslog''' für weitere Fehlermeldungen.

Führe '''sudo service signal start''' aus.
|-
|signal-cli läuft nach reboot oder restart nicht, aber ein manueller Start ist erfolgreich.
<code>sudo systemctl status dbus-org.asamk.Signal.service</code>

meldet einen timeout
|Möglicherweise dauert das Starten von signal-cli länger als der standard 90sec Timeout des systemd (langsames System, langsame SD-Karte bei Raspberry, viele gleichzeitiger Startprozesse bei Reboot).

Hier kann man in ''/etc/systemd/system/signal.service'' den Timeout erhöhen indem in der Sektion ''[Service]'' die Zeile

<code>TimeoutSec=200</code>

eingefügt wird.
|-
|'''Bei Starten von signal-cli:'''
OpenJDK Server VM warning: You have loaded library /tmp/resource17792002454964883349.so which might have disabled stack guard. The VM will try to fix the stack guard now.

It's highly recommended that you fix the library with 'execstack -c <libfile>', or link it with '-z noexecstack'.

oder

ERROR App - Missing required native library dependency: libsignal-client
|Passiert üblicherweise auf dem '''Raspberry pi.''' Die Standard Distribution von signal-cli enthält eine x86 library libsignal_jni.so, die mit armv7l nicht kompatibel ist, welche im jar libsignal-client-*.jar enthalten sind. Das Install Script entfernt diese und ersetzt sie durch armv7l libraries die vom Signalbot Maintainer auf svn.fhem.de zur Verfügung gestellt werden.
Irgendwo auf dem System vorhandene alte Versionen können aber versehentlich erwischt werden und diese Fehler produzieren. Als ersten Schritt mit

''sudo rm -rf /opt/signal''

die alte Installation komplett löschen (enthält keine Konfigurationen) und vom Install Script neu erstellen lassen (einfach wie oben beschrieben starten).

Weitere Tests wenn der Fehler nicht behoben ist:
# Welche Library wird vom System verwendet: ''sudo ldconfig -v | grep libsignal_jni.so'' . Da die libraries in .jar files eingebettet sind, darf hier keine gefunden werden.
# Check gibt es noch irgendwo ein anderes jar <code>sudo find / -name libsignal-client-*.jar 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
|-
|Beim Start von signal-cli:
Fehler: Beim Laden der Klasse org.asamk.signal.Main ist ein LinkageError aufgetreten

java.lang.UnsupportedClassVersionError: org/asamk/signal/Main has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to xx.0
|Signal-cli benötigt seit der Version 0.13+ eine vorhandene Java 21 Installation. Ältere Systeme haben von Haus aus aber nur Java 11 oder 17.
Das Install Script kann hier helfen und eine Binärdistribution von OpenJDK 21 installieren und setzt JAVA_HOME im Startup des Service üblicherweise auch entsprechend.

Wenn signal-cli allerdings in der Kommandozeile ausgeführt wird, ist darauf zu achten das JAVA_HOME=/opt/java gesetzt ist (bzw. auch die von euch gewählte Java 21 Distribution).

Ein häufiger Fehler ist auch beim sudo das "-E" zu vergessen, denn nur so wird JAVA_HOME beim sudo "durchgereicht".
|-
|Fehler beim Setzen des Captcha: "Incorrect captcha - e.g. needs to start with signalcaptcha://"
|
# Sicherstellen, dass das Captcha tatsächlich korrekt ist - am Besten die Automatisierung über die Windows Registry verwenden
# Alternativ kann die Registrierung auch in der Kommandozeile vorgenommen werden
<syntaxhighlight lang="bash">
sudo service signal stop

cd /opt/signal/bin/

sudo -E -u signal-cli ./signal-cli --config /var/lib/signal-cli -u +4912456 register --voice --captcha signalcaptcha://03AG....

sudo -E -u signal-cli ./signal-cli --config /var/lib/signal-cli -u +4912456 verify 12345

sudo service signal start
</syntaxhighlight>
|-
|Fehler: ''Untrusted Identity for "+49xxxxxxx"'' beim Versenden von Nachrichten.

Dieses Fehlerbild ist zu erwarten, wenn ein bereits bestehender Kontakt sich erneut bei Signal angemeldet hat (z.B. Handywechsel) und sich der Sicherheitscode dadurch geändert hat.
|Mit "set trust <Nummer>" das Vertrauen (unverified) zum Kontakt wieder herstellen.
Sollte das nicht reichen (Nachrichten kommen nicht an / werden nicht empfangen) siehe weiter unten "Ich kann Nachrichten ohne Fehler senden....."
|-
|Senden von Nachrichten schlägt fehl oder Nachrichten werden nicht versendet
|Zur Prüfung ob der Fehler in FHEM, der DBUS Konfiguration oder bei signal-cli liegt, sind im Kapitel "Versenden von Nachrichten ohne FHEM" Methoden beschrieben direkt mit Dbus oder von der Kommandozeile Nachrichten zu senden.
Sicherstellen, dass mit "updateProfile" ein Name für das aktuelle Profil angelegt ist, sonst werden Nachrichten möglicherweise nicht verschickt.
|-
|Signal-cli started nach "apt update/upgrade" unter Raspberry Bullseye oder Buster nicht mehr.
Fehlermeldungen z.B. wrong ELF class: ELFCLASS64 (Possible cause: can't load AARCH64 .so on a ARM platform)

oder

Fehler wenn signal-cli als service läuft im syslog:

Caused by: org.sqlite.NativeLibraryNotFoundException: No native library found for os.name=Linux, os.arch=aarch64, paths=[/org/sqlite/native/Linux/aarch64:/usr/java/packages/lib:/lib:/usr/lib]
|Seit März 2023 stellt Raspian anscheinend den Kernel auf 64bit um, sofern es sich um einen neueren 64-bit fähigen Raspberry handelt. Mit dem Befehl "arch" wird dann "aarch64" statt "armv7l" ausgegeben.
Aktuell hilft hier nur wieder auf den 32-bit Kernel umzustellen.

Dazu am Ende der /boot/config.txt die Zeile
:<code>arm_64bit=0</code>
einfügen. Das Mischmasch aus 64Bit Kernel und 32Bit libraries bringt den Java loader für native libraries durcheinander. Aktuell ist dazu keine andere Lösung bekannt.
|-
|Die Registrierung schlägt fehl , z.B. mit der Fehlermeldung "Rate limit exceeded"
|
# Ein paar Stunden warten und es dann nochmal probieren (bei Rate limit exceeded)
# Anderen Browser probieren - es gibt Berichte, dass Firefox nicht funktioniert - Chrome scheint hier die bessere Wahl zu sein
|-
|Ich kann Nachrichten ohne Fehler senden, diese kommen aber beim Empfänger nicht an.
Ich empfange keine Nachrichten, obwohl diese vom Sender korrekt abgeschickt wurden.
|'''Möglicherweise liegt es daran, dass dem Kontakt nicht vertraut wird.'''
Am Handy in die Details des FHEM Kontakts gehen, Sicherheitsnummer anzeigen und als verifiziert markieren.
In FHEM "set trustVerified" mit der Telefonnummer des Kontakts und dessen Sicherheitsnummer ausführen.
Damit man die Sicherheitsnummer nicht abtippen muss, kann man diese auch mit "get identityDetails" anzeigen lassen, grob vergleichen und per copy&paste in den set Befehl übernehmen.
Anschliessend (möglicherweise mit etwas Verzögerung) sollte der Kontakt bei "get identityDetails" als "TRUSTED_VERIFIED" angezeigt werden.
|-
|Signal findet "Protocol::DBus" nicht mehr. "sudo cpan install Protocol::DBus" bricht mit einer Fehlermeldung ab.
|Passiert z.B. nach einem Upgrade des Betriebssystemes auf Debian Trixie.<br>Die Lösung ist, Protocol::DBus mit cpanminus zu installieren:
<syntaxhighlight lang="text">
sudo apt install cpanminus
sudo cpanm --notest Protocol::DBus
</syntaxhighlight>
|}

==== Links ====
* Thread {{Link2Forum|Topic=118370|LinkText=Neues Modul: Signalbot}}

[[Kategorie:Signal]]

Ble2mqtt

2024-03-24T09:11:16Z

Drhirn: Infobox auf Contrib geändert und Download-Link hinzugefügt

{{SEITENTITEL:ble2mqtt}}
{{Infobox Modul
|ModPurpose=Anwesenheitserkennung von Bluetooth-Geräten
|ModType=contrib
|ModFTopic=127173
|ModForumArea=Unterstützende Dienste
|ModTechName=ble2mqtt
|ModOwner=PatrickR
}}
[[ble2mqtt]] ist ein Script, das den Anwesenheitsstatus eines oder mehrerer Bluetooth Low Energy Geräte überprüfen und das Ergebnis an einen MQTT Broker schicken kann.

Es verwendet dazu die Linux Tools ''bluetoothctl'' und ''gatttool''.

ble2mqtt ist in Perl geschrieben und wurde von {{Link2FU|5068|PatrickR}} erstellt. Weitere Informationen finden sich in diesem {{Link2Forum|Topic=127173|LinkText=Forums-Thema}}. Fragen dazu bitte in den Bereich {{Link2Forum|Area=Unterstützende Dienste}}.

==Voraussetzungen==
* Debian od. Raspberry Pi OS
* Bluetooth Empfänger

==Parameter==
Beim Start von ble2mqtt können folgende Parameter angegeben werden:

{| class="wikitable"
!Parameter!!Beschreibung!!Standardwert!!Beispiel!!Optional
|-
| --mqttserver
|Die Adresse des MQTT Brokers inklusive Port
|
| --mqttserver mqtt.example.org:1883
|nein
|-
| --mqttfingerprint
|Der Fingerprint des für die TLS-verschlüsselte Kommunikation mit dem MQTT Broker verwendeten Zertifikates
|
| --mqttfingerprint bfe5d244a821194230f1479fe2f8f7bbcd2a8cb8
|ja
|-
| --mqtttopic
| An welches MQTT-Topic das Tool die Informationen schicken soll.
|ble2mqtt
| --mqtttopic ble2mqtt/Wohnzimmer
|ja
|-
| --mqttuser
|Der Benutzernamen, unter dem die Verbindung zum Broker hergestellt werden soll
|
| --mqttuser ble2mqtt
|ja bzw. abhängig vom Broker
|-
| --mqttpass
|Das zum Benutzernamen gehörende Passwort
|
| --mqttpass verysecret3
|ja bzw. abhängig vom Broker
|-
| --retain
|Versendet die Nachrichten present und lastseen als retained.
|0
| --retain
|ja
|-
| --daemonize
|Wenn ble2mqtt im Hintergrund (als Daemon) ausgeführt werden soll
|0
| --daemonize
|ja
|-
| --loglevel
|Wie und was genau protokolliert werden soll. Mögliche Loglevel sind LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
|LOG_INFO
| --loglevel LOG_ERR
|ja
|-
| --logtarget
|Wohin gelogged werden soll. Mögliche Optionen sind ''syslog'' und ''stdout''.
|syslog
| --logtarget stdout
|ja
|-
| --absentinterval
|Anzahl an Sekunden, nach denen das Gerät als abwesend bezeichnet werden soll. Mindestwert ist 30.
|60
| --absentinterval 120
|ja
|-
| --rssithreshold
|Ab welcher Abweichung des RSSI Wertes ein Update getriggert werden soll. Mindestwert ist 5.
|10
| --rssithreshold 8
|ja
|-
| --watchdogthreshold
|Ab welchem Zeitraum in Sekunden nach Empfangen des letzten BT-Signals ble2mqtt neu gestartet werden soll. Mindestwert ist 30. Der Wert 0 bedeutet deaktiviert, also nie.
|0
| --watchdogthreshold 30
|ja
|-
| --debug
|Kann nur gemeinsam mit --daemonize verwendet werden, um Logeinträge auf stdout auszugeben. Je höher die Nummer, desto mehr Output.
|0
| --daemonize --debug 4
|ja
|-
| --mac
|Filtert mittels Regex nach MAC-Adressen der von ble2mqtt zu beachtenden BLE-Geräte. Alle anderen Geräte werden ignoriert.
|
| --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'
|ja
|-
| --batterymaxage
|Zeit in Stunden, nach denen ein Batterie-Wert als veraltet angesehen und aktualisiert wird. Der Wert 0 deaktiviert den Batterie-Check.
|48
| --batterymaxage 6
|ja
|-
| --forcebattery
|Nur in Kombination mit --mac. Erzwingt einen Batterie-Check, auch wenn das battery-service am Gerät nicht erkannt wird.
|0
| --forcebattery
|ja
|}
===Beispiele===
* Broker verlangt Username/Passwort; es sollen keine Batterie-Werte ausgelesen werden
ble2mqtt --mqttserver mqtt.example.org:1883 --mqttuser ble2mqtt --mqttpass verysecret3 --batterymaxage 0

* Broker verlangt keine Authentifizierung; es soll nach zwei G-Tags gesucht werden; definiertes MQTT-Topic; Batteriewerte benötigt
ble2mqtt --mqttserver mqtt.example.org:1883 --mqtttopic ble2mqtt/Wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'

* Broker verlangt keine Authentifizierung; Geräte sollen nach 45s ohne Kontakt als abwesend angezeigt werden; MQTT Nachrichten sollen gespeichert bleiben
ble2mqtt --mqttserver mqtt.example.org:1883 --absentinterval 45 --retain

==Installation==
Zur Installation muss das ble2mqtt-Script auf den Server kopiert werden und es müssen diverse Linux- und Perl-Pakete installiert werden. Das Script findet ihr im [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/ble2mqttd Contrib-Verzeichnis] von FHEM.

Zuerst das Script nach /usr/local/bin kopieren, um beim Aufruf in der Bash nicht immer den ganzen Pfad voranstellen zu müssen.
:<code>sudo cp -a ble2mqttd /usr/local/bin/</code>
Danach das Script noch als ausführbar markieren
:<code>sudo chmod +x /usr/local/bin/ble2mqttd</code>

===Benötigte Linux Pakete===
Die benötigten Pakete können ganz einfach mit ''apt'' installiert werden. Dabei werden auch mögliche Abhängigkeiten automatisch installiert.
<syntaxhighlight lang="bash">
sudo apt install -y libssl-dev libio-socket-ssl-perl libreadonly-perl libtest-expect-perl libnet-ssleay-perl libnet-server-perl
</syntaxhighlight>

===Benötigte Perl-Module===
Es wird das Modul ''Net::MQTT::Simple'' (''libnet-mqtt-simple-perl'') benötigt. Das ist - Stand 08.11.2023 - noch nicht in den Stable-Repositories von Debian verfügbar und muss daher mittels ''cpan'' installiert werden. Voraussetzung dafür ist das Modul ''CPAN::DistnameInfo'', welches zuerst installiert werden muss.
<syntaxhighlight lang="Bash">
sudo cpan CPAN::DistnameInfo
sudo cpan Net::MQTT::Simple
</syntaxhighlight>
Sobald ''libnet-mqtt-simple-perl'' verfügbar ist, kann dieses statt der Perl-Module wie ein normales Linux-Paket installiert werden.

===Erster Test===
Mit einem einfachen Aufruf von '''ble2mqtt''' kann getestet werden, ob alle benötigten Module und Pakete vorhanden sind.
<syntaxhighlight lang="Bash">
sudo /usr/local/bin/ble2mqttd
</syntaxhighlight>

===Erstellen einens Systemd-Daemons===
Damit '''ble2mqtt''' bei jedem Systemstart automatisch gestartet wird, muss ein Systemd-Daemon erstellt werden. Das wird gemacht, in dem eine neue Textdatei mit folgendem Inhalt angelegt und der Daemon dann aktiviert wird.

{{Hinweis|'''Wichtig:''' Das Kommando, mit welchen Parametern ble2mqtt gestartet wird, muss natürlich individuell angepasst werden!}}
<syntaxhighlight lang="bash">
sudo nano /etc/systemd/system/ble2mqttd.service
</syntaxhighlight>

<syntaxhighlight lang="ini">
[Unit]
Description=ble2mqttd
After=bluetooth.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/ble2mqttd --mqttserver mqtt.example.com:1883 --mqtttopic ble2mqtt/wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)' --absentinterval 30 --mqttuser <username> --mqttpass <password>

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

sudo systemctl daemon-reload
sudo systemctl enable ble2mqttd.service
sudo systemctl start ble2mqttd.service

==Einbindung in FHEM==
Da ble2mqtt alle Informationen an einen [[MQTT]]-Broker sendet, können diese Informationen ganz einfach als [[MQTT2_DEVICE]] in FHEM eingebunden werden. Wie dabei vorgegangen werden kann, unterscheidet sich je nach Anwendungsbereich und den eigenen Vorlieben.

Als Beispiel sie hier die Anwesenheitserkennung mittels BT-Tags angeführt.

===Anwesenheitserkennung mittels BT-Tags===
[[File:ble2mqtt.png|thumb|Readings eines Devices, dass mit diesem Code erstellt wurde]]
Der folgende Code geht davon aus, dass es mehrere ble2mqtt-Instanzen gibt und ein BT-Tag mit der MAC-Adresse AA:BB:CC:DD:EE:FF erkannt werden soll.

Die verschiedenen ble2mqtt-Instanzen schicken ihre Nachrichten in unterschiedliche Topics.
Für jede Instanz ein eigenes Topic:
*ble2mqtt/wohnzimmer
*ble2mqtt/schlafzimmer
*ble2mqtt/kueche
Im Attribut ''devicetopic'' werden diese Topics dann gemeinsam ausgewertet. Das funktioniert, in dem der Name des Subtopics einfach durch den Regex-Ausdruck ''.*'' ersetzt wird.

Bedeutet aber auch, dass die Informationen - wenn gewünscht - wieder in unterschiedliche Readings zerlegt werden müssen. Um z.B. schnell zu erkennen, in welchem Raum der BT-Tag gerade liegt. Das passiert hier z.B. bei den Nachrichten für ''rssi'' und ''presence''. Daraus resultieren dann eigene Readings für jedes MQTT-Subtopic.

Das "raumübergreifende" Reading ''presence'' wird anhand der des Alters in Sekunden der letzten lastseen-Nachricht gesteuert. Die lastseen-Nachricht wird immer gesendet, wenn der Scanvorgang von ble2mqtt das gewünschte Gerät findet.

<syntaxhighlight lang="perl">
define ble2mqttGTag MQTT2_DEVICE FHEM
attr ble2mqttGTag devicetopic ble2mqtt/.*/AA_BB_CC_DD_EE_FF
attr ble2mqttGTag event-on-change-reading .*
attr ble2mqttGTag readingList ble2mqtt/.*/heartbeat:.* heartbeat
$DEVICETOPIC/rssi:.* {my $room=(split m{[/]}x,$TOPIC)[1]; my $roomMax=$room; my $rssiMax=$EVENT; my @readings = grep { $_ =~ m{\Arssi_(?!$room).*}x } keys %{$defs{"$NAME"}->{READINGS}}; for (@readings) {my $rssiTmp=ReadingsVal($NAME,$_,'-100'); my $roomTmp=(split m{[_]}x,$_)[1]; if(($rssiMax gt $rssiTmp)&&(ReadingsVal($NAME,"presence_".$roomTmp,'absent') eq 'present')) {$rssiMax=$rssiTmp; $roomMax=$roomTmp}}; {rssi=>$rssiMax,room=>$roomMax,"rssi_$room"=>$EVENT}}
$DEVICETOPIC/lastseen:.* {lastseen=>strftime "%Y-%m-%d %H:%M:%S", localtime($EVENT)}
$DEVICETOPIC/present:.* {my $roomAct=(split m{[/]}x,$TOPIC)[1]; my $rssi=ReadingsVal($NAME,"rssi_".$roomAct,'-100'); my $presenceAct=$EVENT?'present':'absent'; my $room=$EVENT ? $roomAct:''; my @readings = grep { $_ =~ m{\Apresence_(?!$roomAct).*}x } keys %{$defs{$NAME}->{READINGS}}; for (@readings) {if(ReadingsVal($NAME,$_,'absent') eq 'present') {my $roomTmp=(split m{[_]}x,$_)[1]; my $rssiTmp=ReadingsVal($NAME,"rssi_".$roomTmp,'-100'); if($rssi gt $rssiTmp){$room=$roomTmp; $rssi=$rssiTmp}}}; {"presence_$roomAct"=>$presenceAct, room=>$room}}
ble2mqtt/.*/state:.* state
$DEVICETOPIC/battery:.* batteryLevel
attr ble2mqttGTag userReadings presence {if (ReadingsAge($NAME,"lastseen",0)>60) {return "absent";}else{return "present";}}
</syntaxhighlight>

Das Ergebnis ist unter anderem ein Reading ''presence'' mit den Zuständen ''absent'' und ''present''. Es kann somit ganz einfach als "presenceDevice" in einem [[ROOMMATE]]-Device verwendet werden:
attr rr_Franz rr_presenceDevices ble2mqttGTag

[[Category:MQTT]][[Category:Anwesenheitserkennung]][[Category:FHEM Utilities]]

Ble2mqtt

2024-03-21T12:42:00Z

Drhirn: Link zum Script-Download hinzugefügt

{{Infobox Modul
|ModPurpose=Anwesenheitserkennung von Bluetooth-Geräten
|ModType=u
|ModFTopic=127173
|ModForumArea=Unterstützende Dienste
|ModTechName=ble2mqtt
|ModOwner=PatrickR
}}
'''ble2mqtt''' ist ein Script, dass den Anwesenheitsstatus eines oder mehrerer Bluetooth Low Energy Geräte überprüfen und das Ergebnis an einen MQTT Broker schicken kann.

Es verwendet dazu die Linux Tools ''bluetoothctl'' und ''gatttool''.

ble2mqtt ist in Perl geschrieben und wurde von {{Link2FU|5068|PatrickR}} erstellt. Weitere Informationen finden sich in diesem {{Link2Forum|Topic=127173|LinkText=Forums-Topic }}. Fragen dazu bitte in den Bereich [https://forum.fhem.de/index.php?board=44.0 Unterstützende Dienste].


==Voraussetzungen==
* Debian od. Raspberry Pi OS
* Bluetooth Empfänger

==Parameter==
Beim Start von ble2mqtt können folgende Parameter angegeben werden:

{| class="wikitable"
!Parameter!!Beschreibung!!Standardwert!!Beispiel!!Optional
|-
| --mqttserver
|Die Adresse des MQTT Brokers inklusive Port
|
| --mqttserver mqtt.example.org:1883
|nein
|-
| --mqttfingerprint
|Der Fingerprint des für die TLS-verschlüsselte Kommunikation mit dem MQTT Broker verwendeten Zertifikates
|
| --mqttfingerprint bfe5d244a821194230f1479fe2f8f7bbcd2a8cb8
|ja
|-
| --mqtttopic
| An welches MQTT-Topic das Tool die Informationen schicken soll.
|ble2mqtt
| --mqtttopic ble2mqtt/Wohnzimmer
|ja
|-
| --mqttuser
|Der Benutzernamen, unter dem die Verbindung zum Broker hergestellt werden soll
|
| --mqttuser ble2mqtt
|ja bzw. abhängig vom Broker
|-
| --mqttpass
|Das zum Benutzernamen gehörende Passwort
|
| --mqttpass verysecret3
|ja bzw. abhängig vom Broker
|-
| --retain
|Versendet die Nachrichten present und lastseen als retained.
|0
| --retain
|ja
|-
| --daemonize
|Wenn ble2mqtt im Hintergrund (als Daemon) ausgeführt werden soll
|0
| --daemonize
|ja
|-
| --loglevel
|Wie und was genau protokolliert werden soll. Mögliche Loglevel sind LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
|LOG_INFO
| --loglevel LOG_ERR
|ja
|-
| --logtarget
|Wohin gelogged werden soll. Mögliche Optionen sind ''syslog'' und ''stdout''.
|syslog
| --logtarget stdout
|ja
|-
| --absentinterval
|Anzahl an Sekunden, nach denen das Gerät als abwesend bezeichnet werden soll. Mindestwert ist 30.
|60
| --absentinterval 120
|ja
|-
| --rssithreshold
|Ab welcher Abweichung des RSSI Wertes ein Update getriggert werden soll. Mindestwert ist 5.
|10
| --rssithreshold 8
|ja
|-
| --watchdogthreshold
|Ab welchem Zeitraum in Sekunden nach Empfangen des letzten BT-Signals ble2mqtt neu gestartet werden soll. Mindestwert ist 30. Der Wert 0 bedeutet deaktiviert, also nie.
|0
| --watchdogthreshold 30
|ja
|-
| --debug
|Kann nur gemeinsam mit --daemonize verwendet werden, um Logeinträge auf stdout auszugeben. Je höher die Nummer, desto mehr Output.
|0
| --daemonize --debug 4
|ja
|-
| --mac
|Filtert mittels Regex nach MAC-Adressen der von ble2mqtt zu beachtenden BLE-Geräte. Alle anderen Geräte werden ignoriert.
|
| --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'
|ja
|-
| --batterymaxage
|Zeit in Stunden, nach denen ein Batterie-Wert als veraltet angesehen und aktualisiert wird. Der Wert 0 deaktiviert den Batterie-Check.
|48
| --batterymaxage 6
|ja
|-
| --forcebattery
|Nur in Kombination mit --mac. Erzwingt einen Batterie-Check, auch wenn das battery-service am Gerät nicht erkannt wird.
|0
| --forcebattery
|ja
|}
===Beispiele===
* Broker verlangt Username/Passwort; es sollen keine Batterie-Werte ausgelesen werden
ble2mqtt --mqttserver mqtt.example.org:1883 --mqttuser ble2mqtt --mqttpass verysecret3 --batterymaxage 0

* Broker verlangt keine Authentifizierung; es soll nach zwei G-Tags gesucht werden; definiertes MQTT-Topic; Batteriewerte benötigt
ble2mqtt --mqttserver mqtt.example.org:1883 --mqtttopic ble2mqtt/Wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'

* Broker verlangt keine Authentifizierung; Geräte sollen nach 45s ohne Kontakt als abwesend angezeigt werden; MQTT Nachrichten sollen gespeichert bleiben
ble2mqtt --mqttserver mqtt.example.org:1883 --absentinterval 45 --retain

==Installation==
Zur Installation muss das ble2mqtt-Script auf den Server kopiert werden und es müssen diverse Linux- und Perl-Pakete installiert werden. Das Script findet ihr in {{Link2Forum|Topic=127173|Message=1286068|LinkText=diesem Forumsbeitrag}} zum Download.

Zuerst das Script nach /usr/local/bin kopieren, um beim Aufruf in der Bash nicht immer den ganzen Pfad voranstellen zu müssen.
sudo cp -a ble2mqttd /usr/local/bin/
Danach das Script noch als ausführbar markieren
sudo chmod +x /usr/local/bin/ble2mqttd

===Benötigte Linux Pakete===
Die benötigten Pakete können ganz einfach mit ''apt'' installiert werden. Dabei werden auch mögliche Abhängigkeiten automatisch installiert.

sudo apt install -y libssl-dev libio-socket-ssl-perl libreadonly-perl libtest-expect-perl libnet-ssleay-perl libnet-server-perl

===Benötigte Perl-Module===
Es wird das Modul ''Net::MQTT::Simple'' (''libnet-mqtt-simple-perl'') benötigt. Das ist - Stand 08.11.2023 - noch nicht in den Stable-Repositories von Debian verfügbar und muss daher mittels ''cpan'' installiert werden. Voraussetzung dafür ist das Modul ''CPAN::DistnameInfo'', welches zuerst installiert werden muss.

sudo cpan CPAN::DistnameInfo
sudo cpan Net::MQTT::Simple

Sobald ''libnet-mqtt-simple-perl'' verfügbar ist, kann dieses statt der Perl-Module wie ein normales Linux-Paket installiert werden.

===Erster Test===
Mit einem einfachen Aufruf von '''ble2mqtt''' kann getestet werden, ob alle benötigten Module und Pakete vorhanden sind.

sudo /usr/local/bin/ble2mqttd

===Erstellen einens Systemd-Daemons===
Damit '''ble2mqtt''' bei jedem Systemstart automatisch gestartet wird, muss ein Systemd-Daemon erstellt werden. Das wird gemacht, in dem eine neue Textdatei mit folgendem Inhalt angelegt und der Daemon dann aktiviert wird.

{{Hinweis|'''Wichtig:''' Das Kommando, mit welchen Parametern ble2mqtt gestartet wird, muss natürlich individuell angepasst werden!}}

sudo nano /etc/systemd/system/ble2mqttd.service

<syntaxhighlight lang="ini">
[Unit]
Description=ble2mqttd
After=bluetooth.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/ble2mqttd --mqttserver mqtt.example.com:1883 --mqtttopic ble2mqtt/wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)' --absentinterval 30 --mqttuser <username> --mqttpass <password>

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

sudo systemctl daemon-reload
sudo systemctl enable ble2mqttd.service
sudo systemctl start ble2mqttd.service

==Einbindung in FHEM==
Da ble2mqtt alle Informationen an einen [[MQTT]]-Broker sendet, können diese Informationen ganz einfach als [[MQTT2_DEVICE]] in FHEM eingebunden werden. Wie dabei vorgegangen werden kann, unterscheidet sich je nach Anwendungsbereich und den eigenen Vorlieben.

Als Beispiel sie hier die Anwesenheitserkennung mittels BT-Tags angeführt.

===Anwesenheitserkennung mittels BT-Tags===
[[File:ble2mqtt.png|thumb|Readings eines Devices, dass mit diesem Code erstellt wurde]]
Der folgende Code geht davon aus, dass es mehrere ble2mqtt-Instanzen gibt und ein BT-Tag mit der MAC-Adresse AA:BB:CC:DD:EE:FF erkannt werden soll.

Die verschiedenen ble2mqtt-Instanzen schicken ihre Nachrichten in unterschiedliche Topics.
Für jede Instanz ein eigenes Topic:
*ble2mqtt/wohnzimmer
*ble2mqtt/schlafzimmer
*ble2mqtt/kueche
Im Attribut ''devicetopic'' werden diese Topics dann gemeinsam ausgewertet. Das funktioniert, in dem der Name des Subtopics einfach durch den Regex-Ausdruck ''.*'' ersetzt wird.

Bedeutet aber auch, dass die Informationen - wenn gewünscht - wieder in unterschiedliche Readings zerlegt werden müssen. Um z.B. schnell zu erkennen, in welchem Raum der BT-Tag gerade liegt. Das passiert hier z.B. bei den Nachrichten für ''rssi'' und ''presence''. Daraus resultieren dann eigene Readings für jedes MQTT-Subtopic.

Das "raumübergreifende" Reading ''presence'' wird anhand der des Alters in Sekunden der letzten lastseen-Nachricht gesteuert. Die lastseen-Nachricht wird immer gesendet, wenn der Scanvorgang von ble2mqtt das gewünschte Gerät findet.

<syntaxhighlight lang="perl">
define ble2mqttGTag MQTT2_DEVICE FHEM
attr ble2mqttGTag devicetopic ble2mqtt/.*/AA_BB_CC_DD_EE_FF
attr ble2mqttGTag event-on-change-reading .*
attr ble2mqttGTag readingList ble2mqtt/.*/heartbeat:.* heartbeat
$DEVICETOPIC/rssi:.* {my $room=(split m{[/]}x,$TOPIC)[1]; my $roomMax=$room; my $rssiMax=$EVENT; my @readings = grep { $_ =~ m{\Arssi_(?!$room).*}x } keys %{$defs{"$NAME"}->{READINGS}}; for (@readings) {my $rssiTmp=ReadingsVal($NAME,$_,'-100'); my $roomTmp=(split m{[_]}x,$_)[1]; if(($rssiMax gt $rssiTmp)&&(ReadingsVal($NAME,"presence_".$roomTmp,'absent') eq 'present')) {$rssiMax=$rssiTmp; $roomMax=$roomTmp}}; {rssi=>$rssiMax,room=>$roomMax,"rssi_$room"=>$EVENT}}
$DEVICETOPIC/lastseen:.* {lastseen=>strftime "%Y-%m-%d %H:%M:%S", localtime($EVENT)}
$DEVICETOPIC/present:.* {my $roomAct=(split m{[/]}x,$TOPIC)[1]; my $rssi=ReadingsVal($NAME,"rssi_".$roomAct,'-100'); my $presenceAct=$EVENT?'present':'absent'; my $room=$EVENT ? $roomAct:''; my @readings = grep { $_ =~ m{\Apresence_(?!$roomAct).*}x } keys %{$defs{$NAME}->{READINGS}}; for (@readings) {if(ReadingsVal($NAME,$_,'absent') eq 'present') {my $roomTmp=(split m{[_]}x,$_)[1]; my $rssiTmp=ReadingsVal($NAME,"rssi_".$roomTmp,'-100'); if($rssi gt $rssiTmp){$room=$roomTmp; $rssi=$rssiTmp}}}; {"presence_$roomAct"=>$presenceAct, room=>$room}}
ble2mqtt/.*/state:.* state
$DEVICETOPIC/battery:.* batteryLevel
attr ble2mqttGTag userReadings presence {if (ReadingsAge($NAME,"lastseen",0)>60) {return "absent";}else{return "present";}}
</syntaxhighlight>

Das Ergebnis ist unter anderem ein Reading ''presence'' mit den Zuständen ''absent'' und ''present''. Es kann somit ganz einfach als "presenceDevice" in einem [[ROOMMATE]]-Device verwendet werden:
attr rr_Franz rr_presenceDevices ble2mqttGTag

[[Category:MQTT]][[Category:Anwesenheitserkennung]][[Category:FHEM Utilities]]

FHEMWEB mit Let's Encrypt Zertifikaten

2024-01-15T13:18:56Z

Drhirn: Beispiel mit mehreren Domains ergänzt

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der [https://www.eff.org/ Electronic Frontier Foundation (EFF)] mit dem automatisiert Zertifikate der [https://letsencrypt.org/ Let's Encrypt CA] erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um mittels HTTPS auf [[FHEMWEB]] zuzugreifen.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com -d example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com -d www.example.org -d example.org

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/www.example.com/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/www.example.com/privkey1.pem

Sind alle Berechtigungen vergeben (die sich beim Erneuern der Zertifikate nicht ändern), müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

[[Kategorie:HOWTOS]][[Kategorie:Sicherheit]][[Kategorie:Systemadministration]][[Kategorie:FHEM Frontends]]

FHEM Tablet UI

2023-11-09T11:31:39Z

Drhirn: ToDo entfernt. Wird nicht mehr weiter entwickelt.

Diese Version der Tablet UI wird nicht weiterentwickelt!<ref>https://forum.fhem.de/index.php/topic,115259.msg1095261.html#msg1095261</ref>

Siehe https://forum.fhem.de/index.php/topic,115259.msg1095261.html#msg1095261

Es gibt eine neue Version 3 hier: [[FHEM Tablet UI v3]]

Achtung: Version 3 ist nicht mit Version 2 kompatibel. <ref>Ein Umstieg auf FTUI3 hat eine Neu-Programmierung der Oberfläche zur Folge.</ref>

{{Infobox Modul
|ModPurpose=Oberfläche für FHEM
|ModType=x
|ModFTopic=34233
|ModForumArea=TabletUI
|ModTechName=n.a.
|ModOwner=setstate ({{Link2FU|7023|Forum}})
}}
[[FHEM Tablet UI v2]] (FTUI2) ist ein leichtgewichtiges aber funktionsreiches Frontend-Framework zum Steuern und Überwachen von in FHEM integrierten Geräten. Es basiert auf HTML/CSS/JavaScript und stellt somit keine zusätzlichen Anforderungen an den FHEM-Server.

Mit Hilfe zahlreicher Widgets, die sehr leicht mit HTML Code konfiguriert werden können, ist es möglich, innerhalb kurzer Zeit ein den eigenen Wünschen entsprechendes User-Interface aufzubauen.

Für den Betrieb ist nur eine FHEM-Installation mit [[HTTPSRV|HTTPSRV-Modul]] sowie ein gängiger Webbrowser notwendig.

Mit wenigen Anpassungen ist es auch möglich, das UI auf anderen Webservern (Apache, u.a.) zu betreiben. Somit können FHEM und FHEM Tablet UI auch auf getrennten Systemen ausgeführt werden.

[[File:tablet_ui.png|thumb|500px|center|Beispiel für ein mit [[FHEM Tablet UI]] erstelltes User-Interface]]

== Installation ==
Die Installation von FHEM Tablet UI v2 erzeugt keinen großen Aufwand und besteht im Großen und Ganzen aus drei Schritten:
*Dateien aus dem GitHub-Repository herunterladen
*FHEM konfigurieren ([[HTTPSRV]]-Device erstellen, [[FHEMWEB]]-Attribut longpoll einstellen)
*Eine Beispieldatei anlegen

{{Hinweis|Diese Anleitung geht davon aus, dass FHEM unter Debian nach der Anleitung [https://debian.fhem.de Stable build using apt] installiert wurde.
Ist dies nicht der Fall, muss der Pfad '''/opt/fhem''' dementsprechend angepasst werden.}}

'''1.''' Zuerst müssen alle Dateien von FHEM Tablet UI in das FHEM-Verzeichnis '''/opt/fhem/www''' kopiert werden. Das geht mit folgendem '''update'''-Befehl über die FHEM-Befehlszeile.
:<code>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</code>

:[[Datei:FTUI_Installation_01.png|thumb|none|Schritt 1: Dateien kopieren]]

'''2.''' Anschließend ist ein neues [[HTTPSRV]]-Device in FHEM anzulegen, welches auf den Ordner mit den gerade heruntergeladenen Dateien verweist.
:<code>define TABLETUI HTTPSRV ftui/ ./www/tablet/ Tablet-UI</code>

:[[Datei:FTUI_Installation_02.png|thumb|none|Schritt 2: HTTPSRV-Device anlegen]]

{{Hinweis|Dieser Schritt kann ausgelassen werden, wenn die Funktionalitäten von [[FHEMWEB]] ausreichend sind. Dann muss FTUI aber in weiterer Folge unter der URL '''<nowiki>http(s)://<fhem-server>:8083/fhem/tablet/index.html</nowiki>''' aufgerufen werden und es wird kein Link auf FTUI in der FHEM GUI erstellt. Vorteil ist aber, dass das FHEMWEB-Caching verwendet werden kann. Siehe dieser {{Link2Forum|Topic=86362|Message=788258}}.}}

'''3.''' Damit FHEM Tablet UI mit FHEM kommunizieren kann, ist noch die '''longpoll'''-Einstellung im [[FHEMWEB]] Device festzulegen.

:<code>attr WEB longpoll websocket</code>
:bzw. bei Problemen mit ''websocket''
:<code>attr WEB longpoll 1</code>

:[[Datei:FTUI_Installation_03.png|thumb|none|Schritt 3: longpoll einstellen]]

'''4.''' Weil FTUI noch nichts anzuzeigen hat, wird die Datei '''/opt/fhem/www/tablet/index-example.html''' nach '''/opt/fhem/www/tablet/index.html''' kopiert.
:<code>sudo cp -a /opt/fhem/www/tablet/index-example.html /opt/fhem/www/tablet/index.html</code>

:[[Datei:FTUI_Installation_04.png|thumb|none|Schritt 4: index.html erstellen]]

'''5.''' Abschließend muss FHEM noch '''neu gestartet''' werden (''shutdown restart'') da das Attribut '''longpoll''' geändert wurde.

Somit ist FHEM Tablet UI bereit zur Verwendung und kann durch Aufruf der URL '''<nowiki>http://<fhem-server>:8083/fhem/ftui/</nowiki>''' oder den Link im FHEM-Menü geöffnet werden

== Update ==
Ein Update von FTUI kann ebenfalls über die FHEM-Kommandozeile erfolgen.

'''1.''' Prüfen der Änderungen seit dem letzten Download/Update durch Eingabe von:
:<code><nowiki>update check https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

'''2.''' Update der geänderten Dateien durch Eingabe von:
:<code><nowiki>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

Eine weitere Option ist das Hinzufügen des FTUI-Git-Repositories zum allgemeinem Update-Vorgang von FHEM. Dabei wird dann bei einem FHEM-Update auch gleich FHEM Tablet UI aktualisiert, bzw. die Änderungen angezeigt.
:<code><nowiki>update add https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

Beachte: Das Ergebnis des o.g. Befehls wird in FHEM/controls.txt eingetragen, siehe auch [[Update#update_add]]

== Konfiguration ==
===DOCTYPE===
In allen HTML-Dateien, die im Browser geladen werden und das typische HTML-Gerüst besitzen (also alle Hauptseiten, jedoch keine Template-Dateien), sollte eine ''Document Type Declaration'' (DTDT) eingefügt werden. Mit ihr wird festgelegt, welche ''Document Type Definition'' hier verwendet wird (das kommt aus der Metasprache XML), konkret also, in welcher Version der nachfolgende HTML-Code vom Browser interpretiert werden soll. Lässt man die DTDT weg, oder definiert sie auf verschiedenen Seiten unterschiedlich, kann ein und der selbe HTML-Code zu unterschiedlichen Darstellungen führen. Die DTDT erfolgt immer auf der ersten Zeile, noch vor dem <code><html></code>-Tag. Nachfolgend wird HTML5 verwendet.

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<head>...</head>
<body>...</body>
</html>
</syntaxhighlight>

===META-Parameter===
Das Tablet UI lässt sich über die META-Parameter konfigurieren. Diese Parameter sind in jeder '''.html''' Datei (z.B. index.html) im Abschnitt '''<head>''' einzutragen. Ausgenommen davon sind Dateien, die als Template, Pagebutton-Zielseiten oder ähnliches eingebunden werden.

Die Parameter sind immer nach diesem Schema aufgebaut:
<meta name="[Parameter-Name]" content="[Parameter-Wert]">

===Verbindung zu FHEM===
{| class="wikitable"
|-
!Parameter-Name!!Standard-Wert!!Mögliche Werte!!Beschreibung
|-
|web_device||WEB||String||FHEM-Device, welches für das Polling verwendet wird
|-
|longpoll||1||0, 1||
'''0''': Longpoll deaktiviert; alle 30s ein Shortpoll (Neuladen der gesamten Statusänderungen)

'''1''': Longpoll aktiv; geänderte Stati werden sofort aktualisiert, zusätzlich werden alle 15min die gesamten Statusänderungen geladen.
|-
|longpoll_type||websocket||websocket, ajax, 0||
'''websocket''': Für die Aktualisierung der Daten wird das Websocket-Protokoll verwendet. Werden vom Browser keine Websockets unterstützt, gibt es einen automatischen Fallback auf Ajax.

'''ajax''': Ajax wird für die Aktualisierung verwendet.

'''0''': Longpoll deaktiviert, Shortpoll wird verwendet.
|-
|longpoll_filter||.*||RegEx||Event-Filter. Kann verwendet werden, wenn z.B. Devices, die in FTUI angezeigt werden, in einem eigenen FHEM-Room sind.
|-
|longpoll_maxage||240||Integer||Kommen in diesem Zeitraum (Sekunden) keine Longpoll-Events bei FTUI an, wird die Verbindung als "disconnected" angesehen und ein neuer Verbindungsversuch wird gestartet.
|-
|shortpoll_interval||900||Integer||Zeitraum in Sekunden, nach dem ein vollständiger Refresh stattfindet
|-
|shortpoll_only_interval||30||Integer||Zeitraum in Sekunden, nach dem ein vollständiger Refresh stattfindet, sollte Longpoll deaktiviert sein
|-
|fhemweb_url||/fhem/||Integer||URL zu FHEM. Wird benötigt wenn FTUI auf einem anderen als dem FHEM Server läuft oder nicht im Standard-Pfad installiert ist.
Hinweis: Wenn FHEM auf einem anderem Server/Domain läuft muss man das "CORS" Attribut im FHEMWEB Modul (s.o.) auf 1 setzen, sonst bekommt man Cross Origin Fehler.
|}

===Funktionalität===
{| class="wikitable"
|-
!Parameter-Name!!Standard-Wert!!Mögliche Werte!!Beschreibung
|-
|debug||0||0 - 5||Log-Level
|-
|toast||5||Integer||Anzahl an gleichzeitig angezeigten Toast-Nachrichten. Um keine anzuzeigen, ist der Wert auf 0 zu setzen.
|-
|toast_position||bottom-left||||Position im Browserfenster, wo die Toast-Nachrichten angezeigt werden.
|-
|lang||de||de||Sprache der Oberfläche (für z.B. Datums-/Zeitfunktionen)
|-
|username||||String||Benutzername für eine Basic-Authentifierung *
|-
|password||||String||Passwort für eine Basic-Authentifizierung *
|}
'''*''' Derzeit wird die Basic-Authentifizierung in Kombination mit WebSockets nicht unterstützt. Die Verwendung von '''longpoll=1''' (ajax) ist daher notwendig.

===Toast-Nachrichten===
[[Datei:Ftui_toast.png|thumb|Toast-Nachrichten]]
Tablet-UI liefert Informationen darüber, was im Moment gerade passiert. Das geschieht über Toast-Nachrichten, die in der Standardeinstellung unten links im Browser auftauchen.

Wird beispielsweise ein Gerät eingeschaltet, so erscheint eine kleine Nachricht mit dem abgesetzten Befehl. Auch Fehlermeldungen und Statusinformationen werden angezeigt. Ob überhaupt und was konkret angezeigt wird, richtet sich nach dem eingestellten Debug-Level (siehe oben). Beim Debug-Level 5 werden alle Nachrichten angezeigt, bei 0 keine.

Die Position der Toast-Nachrichten kann über den Meta-Tag <code>meta name='toast_position'</code> festgelegt werden. Für oben-mittig müsste folgender Code eingefügt werden:
<pre><meta name='toast_position' content='top-center'></pre>

Möglich sind folgende Positionen:
* <code>top-left</code>
* <code>top-right</code>
* <code>bottom-left</code>
* <code>bottom-right</code>
* <code>top-center</code>
* <code>bottom-center</code>
* <code>mid-center</code>

Die maximale Anzahl an Nachrichten, die gleichzeitig angezeigt werden können, lässt sich mit <code>meta name='toast'</code> Sind maximal 2 Nachrichten gewünscht, muss folgender Meta-Tag gesetzt werden:
<pre><meta name='toast' content='2'></pre>

==Navigationsmethoden==
{{Todo|Dieser Abschnitt dient derzeit lediglich als Sammlung von Stichpunkten und muss vollständig überarbeitet werden.}}

'''Unterschied zwischen Pagetab und Pagebutton:'''

'''Pagetab:''' Ganze Seite austauschen -> Menü muss auf jede Seite
[[FTUI_Widget_Pagetab]]

'''Pagebutton:''' Teil der Seite austauschen -> Menü nur in erster Seite
[[FTUI_Widget_Pagebutton]]

'''Pagelink:''' damit kann man beliebige Widgets kapseln und vorhandene Pagebutton-Seiten ansteuern
[[FTUI Widget Link]]

==Gestaltung==
===Layout-Optionen===
* [[FTUI Layout Gridster|Gridster]]
* [[FTUI Layout Flex|Flex]]
* [[FTUI Layout Sheet|Tabelle]]
* [[FTUI Layout Row|Reihen]]

=== Farben ===
Es besteht die Möglichkeit, die Farbwerte in hexadezimaler Form, als RGB-Wert oder mit dem Farbnamen anzugeben. Zum Beispiel:

*HEX: #ADD8E6
*RBG: rgb(173, 216, 230)
*Namen: lightblue

Knallige Farben wie '''<span style="color: #ff0000;">#ff0000</span>''' für Rot oder '''<span style="color: #00ff00;">#00ff00</span>''' für Grün sollten vermieden werden.
Es ist besser unterhalb von #D0 (208) für die Grundfarben zu bleiben.

Empfohlene Farben sind z.B.:

*Orange: <span style="color: #aa6900;">#aa6900</span>
*Rot: <span style="color: #ad3333;">#ad3333</span>
*Grün: <span style="color: #32a054;">#32a054</span>
*Blau: <span style="color: #6699FF;">#6699FF</span>
*Grau: <span style="color: #8C8C8C;">#8C8C8C</span>

Hilfreich bei der Suche nach den Farbwerten ist zum Beispiel der Color-Picker auf dieser Seite: http://www.colorpicker.com. Für die Suche nach Farben, die einen guten Kontrast bilden, diese Webseite: http://vanisoft.pl/~lopuszanski/public/colors/

Im Ordner ''css'' der FTUI Installation finden sich einige vorbereitete Farbschemata. Diese können mit einem zusätzlichen Eintrag im <nowiki><head></nowiki>-Bereich der FTUI-Seite(n) aktiviert werden.

Hier am Beispiel eines blauen Farbschemas:
<syntaxhighlight lang="html">
<html>
<head>
[...]
<link rel="stylesheet" href="/fhem/tablet/css/fhem-blue-ui.css" />
[...]
</head>
</syntaxhighlight>

Diese Schema-Dateien ändern alle Widgets.
<gallery>
File:Theme_default.png|default
File:Theme_blue.png|fhem-blue-ui.css
File:Theme_green.png|fhem-green-ui.css
File:Theme_mobile.png|fhem-mobile-ui.css
File:Theme_darkblue.png|fhem-darkblue-ui.css
File:Theme_darkgreen.png|fhem-darkgreen-ui.css
</gallery>

Einzelne Widgets können durch Hinzufügen der jeweiligen [[#CSS-Klassen|CSS-Klasse]] geändert werden.

===CSS-Styles===
Das Layout und das Aussehen des UI kann durch diverse vorgegebene CSS-Klassen beeinflusst werden. Die verfügbaren Klassen sind im Abschnitt [[#CSS-Klassen|CSS-Klassen]] aufgeführt.

Soll das Aussehen des UI durch eigene CSS-Klassen oder durch Überschreiben der vorhandenen verändert werden, kann eine eigene CSS-Datei erstellt werden, die dann bei einem eventuellen Update von FTUI nicht überschrieben wird. Diese Datei muss den Dateinamen '''fhem-tablet-ui-user.css''' haben und im Ordner '''/fhem/tablet/css''' abgelegt werden. Sie wird dann beim Aufruf von FTUI automatisch mitgeladen.

=== CSS-Klassen ===
Nicht alle Widgets unterstützen alle hier angegebenen Klassen. Welche genau unterstützt werden, kann auf der jeweiligen Widget-Seite nachgelesen werden.

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |sheet/row/cell-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|sheet}}{{FTUI Klasse|row}}{{FTUI Klasse|cell}}{{FTUI Klasse|cell-1-x}}{{FTUI Klasse|cell-x}}{{FTUI Klasse|left-align}}{{FTUI Klasse|right-align}}{{FTUI Klasse|bottom-align}}{{FTUI Klasse|top-align}}{{FTUI Klasse|center-align}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |row/col-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|col}}{{FTUI Klasse|col-1-x}}{{FTUI Klasse|col-x}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |hbox/vbox-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|vbox}}{{FTUI Klasse|hbox}}{{FTUI Klasse|card}}{{FTUI Klasse|phone-width}}{{FTUI Klasse|full-height}}{{FTUI Klasse|full-width}}{{FTUI Klasse|grow-0}}{{FTUI Klasse|grow-1}}{{FTUI Klasse|grow-2}}{{FTUI Klasse|grow-x}}{{FTUI Klasse|items-top}}{{FTUI Klasse|items-center}}{{FTUI Klasse|items-bottom}}{{FTUI Klasse|items-space-between}}{{FTUI Klasse|items-space-around}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |Generelle Klassen für die Positionierung
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|inline}}{{FTUI Klasse|newline}}{{FTUI Klasse|top-space}}{{FTUI Klasse|top-space-2x}}{{FTUI Klasse|top-space-3x}}{{FTUI Klasse|left-space}}{{FTUI Klasse|left-space-2x}}{{FTUI Klasse|left-space-3x}}{{FTUI Klasse|right-space}}{{FTUI Klasse|right-space-2x}}{{FTUI Klasse|right-space-3x}}{{FTUI Klasse|top-narrow}}{{FTUI Klasse|top-narrow-2x}}{{FTUI Klasse|top-narrow-10}}{{FTUI Klasse|left-narrow}}{{FTUI Klasse|left-narrow-2x}}{{FTUI Klasse|left-narrow-3x}}{{FTUI Klasse|right-narrow}}{{FTUI Klasse|right-narrow-2x}}{{FTUI Klasse|right-narrow-3x}}{{FTUI Klasse|centered}}{{FTUI Klasse|wider}}{{FTUI Klasse|narrow}}{{FTUI Klasse|fullsize}}{{FTUI Klasse|compressed}}{{FTUI Klasse|height-narrow}}{{FTUI Klasse|w1x}}{{FTUI Klasse|w2x}}{{FTUI Klasse|w3x}}{{FTUI Klasse|maxw40}}{{FTUI Klasse|doublebox-v}}{{FTUI Klasse|doublebox-h}}{{FTUI Klasse|triplebox-v}}{{FTUI Klasse|right}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |Vordergrundfarben
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|red}}{{FTUI Klasse|green}}{{FTUI Klasse|blue}}{{FTUI Klasse|lightblue}}{{FTUI Klasse|orange}}{{FTUI Klasse|gray}}{{FTUI Klasse|lightgray}}{{FTUI Klasse|white}}{{FTUI Klasse|black}}{{FTUI Klasse|mint}}{{FTUI Klasse|yellow}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |Hintergrundfarben
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|bg-red}}{{FTUI Klasse|bg-green}}{{FTUI Klasse|bg-blue}}{{FTUI Klasse|bg-lightblue}}{{FTUI Klasse|bg-orange}}{{FTUI Klasse|bg-gray}}{{FTUI Klasse|bg-lightgray}}{{FTUI Klasse|bg-white}}{{FTUI Klasse|bg-black}}{{FTUI Klasse|bg-mint}}{{FTUI Klasse|bg-yellow}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |Rahmen
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|verticalLine}}{{FTUI Klasse|border-black}}{{FTUI Klasse|border-white}}{{FTUI Klasse|border-orange}}{{FTUI Klasse|border-red}}{{FTUI Klasse|border-green}}{{FTUI Klasse|border-mint}}{{FTUI Klasse|border-lightblue}}{{FTUI Klasse|border-blue}}{{FTUI Klasse|border-gray}}{{FTUI Klasse|border-yellow}}{{FTUI Klasse|border-lightgray}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |Größen
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|mini}}{{FTUI Klasse|tiny}}{{FTUI Klasse|small}}{{FTUI Klasse|normal}}{{FTUI Klasse|large}}{{FTUI Klasse|big}}{{FTUI Klasse|bigger}}{{FTUI Klasse|tall}}{{FTUI Klasse|great}}{{FTUI Klasse|grande}}{{FTUI Klasse|gigantic}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |Schriftstil
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|thin}}{{FTUI Klasse|bold}}{{FTUI Klasse|darker}}{{FTUI Klasse|truncate}}
|}

{| class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
! colspan="2" style="text-align: left;" |Sonstiges
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|blank}}{{FTUI Klasse|transparent}}{{FTUI Klasse|half-transparent}}{{FTUI Klasse|blurry}}{{FTUI Klasse|shake}}{{FTUI Klasse|fail-shake}}{{FTUI Klasse|marquee}}{{FTUI Klasse|icon round}}{{FTUI Klasse|icon square}}{{FTUI Klasse|readonly}}{{FTUI Klasse|blink}}{{FTUI Klasse|rotate-90}}{{FTUI Klasse|horizontal}}{{FTUI Klasse|circleborder}}{{FTUI Klasse|autohide}}{{FTUI Klasse|notransmit}}{{FTUI Klasse|tap}}{{FTUI Klasse|FS20}}{{FTUI Klasse|value}}{{FTUI Klasse|novalue}}{{FTUI Klasse|timestamp}}{{FTUI Klasse|percent}}{{FTUI Klasse|nocache}}{{FTUI Klasse|fade}}{{FTUI Klasse|rotate}}{{FTUI Klasse|nolabels}}{{FTUI Klasse|default}}{{FTUI Klasse|prefetch}}{{FTUI Klasse|circulate}}{{FTUI Klasse|valueonly}}{{FTUI Klasse|positiononly}}{{FTUI Klasse|lineIndicator}}{{FTUI Klasse|barIndicator}}{{FTUI Klasse|roundIndicator}}{{FTUI Klasse|dim-tick}}{{FTUI Klasse|dim-front}}{{FTUI Klasse|dim-back}}{{FTUI Klasse|hue-tick}}{{FTUI Klasse|hue-front}}{{FTUI Klasse|hue-back}}{{FTUI Klasse|warn}}{{FTUI Klasse|activate}}{{FTUI Klasse|labelright}}{{FTUI Klasse|interlock}}{{FTUI Klasse|keepopen}}{{FTUI Klasse|noshade}}
|}

=== Überlagerung von Text und Bild ===
[[Datei:FTUI_Text_auf_Bild.png||thumb|right]]
Texte können auf Bildern positioniert werden:
<syntaxhighlight lang="html5">
<li data-row="1" data-col="4" data-sizey="4" data-sizex="6">
<div class="display">
<div data-type="image" data-url="https://picsum.photos/200/125/?random" data-size="100%"></div>
<div class="display-center bigger" data-type="label">Text1</div>
<div class="display-topright bigger right-space top-space" data-type="label">Text2</div>
<div class="ontop bigger" style="left: 120px; top: 50px">Text3</div>
</div>
</li>
</syntaxhighlight>

Zur Verfügung stehen folgende Grundpositionen:
* <code>display-topleft</code>
* <code>display-topcenter</code>
* <code>display-topright</code>
* <code>display-centerleft</code>
* <code>display-left</code>
* <code>display-centerright</code>
* <code>display-right</code>
* <code>display-bottomleft</code>
* <code>display-bottomcenter</code>
* <code>display-bottomright</code>

Feinjustage ist möglich über

* <code>right-space</code>
* <code>top-space</code>
* <code>left-space</code>
* <code>bottom-space</code>
* <code>right-space-2</code>
* <code>top-space-2</code>
* <code>left-space-2</code>
* <code>bottom-space-2</code>
* <code>right-space-3</code>
* <code>top-space-3</code>
* <code>left-space-3</code>
* <code>bottom-space-3</code>

[[Datei:FTUI_Beispiel_Positionierung.png|200px|thumb|right]]
Verallgemeinert lassen sich auf diese Weise '''Objekte frei im Elternelement positionieren''':
<syntaxhighlight lang="html5">
<div class="display" data-type="html">
<div class="display-topcenter top-space big">Fenster</div>
<div class="display-center fa fa-4x ftui-window"></div>
<div class="display-bottomleft bottom-space left-space" data-type="label">Text</div>
</div>
</syntaxhighlight>
=== Icons ===
FTUI bringt einige Icons-"Schriftarten" mit, die für die Darstellung genützt werden können. Diese werden automatisch beim Start des UI eingebunden, sobald ein entsprechendes Icon-Präfix im Code der Seite vorkommt.

Verfügbare Icon-Schriftarten sind:
* Eingebaute Icons ''ftui-window'' und ''ftui-door''. Präfix '''ftui-'''. Beispiel: <code>data-icon="ftui-door"</code>
* [http://fontawesome.io/icons/ Font-Awesome]: Mehr als 500 Icons zur Auswahl. Präfix '''fa-'''. Beispiel: <code>data-icon="fa-volume-up"</code>
* [https://material.io/icons/ Material Icons]: Mehr als 900 Icons zur Auswahl. Präfix '''mi-'''. Beispiel: <code>data-icon="mi-local_gas_station"</code>
* FHEM und OpenAutomation Icons: Präfix '''fs-''' und '''oa-'''. Beispiel: <code>data-icon="oa-secur_locked"</code>
* [https://erikflowers.github.io/weather-icons/ Weather-Icons]: Präfix '''wi '''. Beispiel: <code>data-icon="wi wi-day-rain-mix"</code>

Alternativ können auch Bilder Icons (bspw. png) über CSS verwendet werden. Bspw:
<syntaxhighlight lang="html5">
<head>
<style type="text/css">
.logo-fhem {
background: url(https://wiki.fhem.de/fhemlogo.png) no-repeat;
width: 120px;
height: 132px;
background-size: contain;
}
</style>
</head>
<body>
<div data-type="symbol" data-icon="logo-fhem"></div>
</body>
</syntaxhighlight>

== Widgets ==
===Allgemeine Attribute===
Jedes Widget kann über verschiedene Attribute konfiguriert werden. Folgende Attribute gelten für alle Widgets:

{| class="wikitable"
|+allgemeine Attribute
|-
! align="right" |data-type
|Widget-Typ
|-
! align="right" |data-device
|FHEM-Name des Gerätes (mit dem Befehl 'list' bekommt man im FHEM die kpl. Liste)
|-
! align="right" |class
|CSS-Klassen für Aussehen und Formatierung des Widgets
|-
|}

{| class="wikitable"
|+Daten Empfangen
|-
! align="right" |data-get
|Reading Name
|-
! align="right" |data-get-on
|Wert für den Status on
|-
! align="right" |data-get-off
|Wert für den Status off
|-
|}

{| class="wikitable"
|+Daten Senden
|-
! align="right" |data-set
|Reading Name
|-
! align="right" |data-set-on
|Wert für den Status on
|-
! align="right" |data-set-off
|Wert für den Status off
|-
|}

Widget-spezifische Attribute können auf der jeweiligen Widget-Seite nachgelesen werden.

=== Integrierte Widgets ===
Folgende Widgets sind direkt in FHEM Tablet UI integriert und können "out of the box" verwendet werden.

* [[FTUI Widget Button|button]]: Variante der push und switch Widgets, die entweder einen URL ansteuern oder einen FHEM-Befehl absetzen kann
* [[FTUI Widget Checkbox|checkbox]]: Umschalter zwischen zwei definierten Zuständen
* [[FTUI Widget Circlemenu|circlemenu]]: Mehrere Widgets hinter einem Widget verborgen, trotz des 'circle' im Namen kann das Menue jetzt auch horizontal oder vertikal ausgeklappt werden
* [[FTUI Widget Clock|clock]]: Stellt eine einfache Uhr zur Verfügung
* [[FTUI Widget Colorwheel|colorwheel]]: Farbpalette zur Auswahl von Farben
* [[FTUI Widget Controlbutton|controlbutton]]: iOS-ähnlicher Button zum Schalten zwischen zwei Zuständen (z.B. on / off)
* [[FTUI Widget Controller|controller]]: iOS-ähnlicher vertikaler Schieberegler zum Einstellen eines Wertes
* [[FTUI Widget Datetimepicker|datetimepicker]]: Erstellt eine Auswahl für Datum/Uhrzeit
* [[FTUI Widget Departure|departure]]: Abfahrtszeiten öffentlicher Verkehrsmittel
* [[FTUI Widget Dimmer|dimmer]]: Ein-/Aus-Button mit integriertem Schieberegler für z.B. einen Dim-Wert
* [[FTUI Widget Eventmonitor|eventmonitor]]:
* [[FTUI Widget Homestatus|homestatus]]: Auswahl für vier oder fünf definierte Zustände eines Objects (z.B.: FHEM Residents)
* [[FTUI Widget Html|html]]:
* [[FTUI Widget Iframe|iframe]]: Widget zum Einbinden externer Inhalte in einem Iframe
* [[FTUI Widget Image|image]]: Zeigt ein Bild, dessen URL fest vorgegeben oder aus einem Device-Reading gelesen werden kann
* [[FTUI Widget Input|input]]: Erstellen eines Texteingabefeldes
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/joinedlabel joinedlabel]: verbindet mehrere Readings zu einem Feld
* [[FTUI Widget Klimatrend|klimatrend]]: wandelt Daten aus dem statistics-Modul in einen Pfeil um, der den aktuellen Trend anzeigt
* [[FTUI Widget Knob|knob]]: Erstellt einen Statusbalken auf einer Kreisbahn
* [[FTUI Widget Label|label]]: Reading als Text anzeigen
* [[FTUI Widget Level|level]]: Vertikale oder horizontale Leiste zur Anzeige von Werten zwischen einem Minimal- und einem Maximalwert
* [[FTUI Widget Link|link]]: Erstellt einen Link oder Button zum Aufrufen von URLs oder Senden von Befehlen an FHEM
* [[FTUI Widget Medialist|medialist]]:
* [[FTUI Widget Multistatebutton|multistatebutton]]: Variante des push-Widgets, welches den set-Befehl abhängig vom gelesenen Status ändert
* [[FTUI Widget Notify|notify]]: Blendet ein Hinweisfenster im Browser ein
* [[FTUI Widget Pagebutton|pagebutton]]: Button, mit dem auf andere Seiten gesprungen werden kann. Eignet sich gut für eine Navigation
* [[FTUI Widget Pagetab|pagetab]]: Tauscht den Inhalt einer Seite durch den einer anderen. Eignet sich gut für ein Navigationsmenü
* [[FTUI Widget Playstream|playstream]]: Abspielen eines Webradio-Streams per Button
* [[FTUI Widget Popup|popup]]: Öffnet ein Popup nach einem Klick auf ein Widget oder HTML-Element
* [[FTUI Widget Progress|progress]]: Zeigt einen Prozentwert in Form einer runden Fortschrittsleiste
* [[FTUI_Widget_Push|push]]: Button, mit dem ein Befehl an FHEM gesendet werden kann
* [[FTUI Widget Range|range]]: Erstellt vertikale Balken, die einen Wertebereich in unterschiedlichen Farben darstellen
* [[FTUI Widget Readingsgroup|readingsgroup]]: Zeigt eine Readingsgroup an, wie sie in FHEM definiert wurde
* [[FTUI Widget Rotor|rotor]]: Animiertes Umschalten von zwei oder mehr Widgets an einer Position
* [[FTUI Widget Scale|scale]]: Vertikale oder horizontale Leiste zur Anzeige von Werten zwischen einem Minimal- und einem Maximalwert
* [[FTUI_Widget_Select|select]]: Combobox, die eine Liste an Werten zur Auswahl anzeigt
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/settimer settimer]: Zum Anzeigen und Einstellen einer Uhrzeit
* [[FTUI Widget Simplechart|simplechart]]: Einfaches XY-Diagramm zur Anzeige eines Wertes, der direkt aus einem FHEM-Logfile gelesen wird
* [[FTUI Widget Slideout|slideout]]:
* [[FTUI Widget Slider|slider]]: Vertikaler Schieberegler zum Einstellen eines Wertes
* [[FTUI Widget Spinner|spinner]]: Element, um Werte durch Drücken auf Plus-/Minus- oder Höher-/Tiefer-Icons zu ändern
* [[FTUI Widget Swiper|swiper]]: Bietet die Möglichkeit, durch Wischen zwischen verschiedenen Seiten zu wechseln
* [[FTUI Widget Switch|switch]]: Button, um zwischen zwei Zuständen zu schalten (z.B. on / off)
* [[FTUI Widget Symbol|symbol]]: Status eines Devices als Symbol darstellen (z.B. Fenster offen)
* [[FTUI Widget Theme|theme]]: Kontextspezifisches Design
* [[FTUI Widget Thermostat|thermostat]]: Anzeige für Heizungsthermostate, mit der die gewünschte Temperatur eingestellt werden kann
* [[FTUI Widget Volume|volume]]: Einstellscheibe zur Änderung eines einzelnen Wertes
* [[FTUI Widget Weather|weather]]: Wettersymbol anzeigen
* [[FTUI Widget WindDirection|wind_direction]]: Anzeige der Windrichtung auf einer Windrose

===3rd Party Widgets===
Für diese Widgets kann nicht sichergestellt werden, dass sie mit der jeweils aktuellen Version von FTUI funktionieren.
* [[FTUI Widget Agenda|agenda]]: Zeigt Kalendereinträge in einer Listenform an
* [[FTUI_Widget_Analogclock|analogclock]]: Analoguhr
* [[AutomowerConnect#Tablet-UI%2FFTUI_Version_2|automowerconnect]]: Für das Modul AutomowerConnect
* [[FTUI Widget Calview|calview]]: Zeigt Einträge aus einem [[CALVIEW]]-Device an
* [[FTUI Widget Chart|chart]]: Diagramm mit ähnlichen Möglichkeiten wie die FHEM-Plots
* [[FTUI Widget Classchanger|classchanger]]: Ändert seine CSS-Klassen je nach Status eines Devices
* [[FTUI Widget Clicksound|clicksound]]: Mit dem Widget "clicksound" können Sounds an Click-Events von Elementen gebunden werden.
* [[FTUI Widget Dwdweblink|dwdweblink]]: Grafische Anzeige DWD-Wetter-Weblink
* [[FTUI Widget Filelog|filelog]]: Teile aus einem FHEM Logfile anzeigen
* [[FTUI Widget Fullcalview|fullcalview]]:
* [[FTUI Widget Gds|gds]]:
* [[FTUI Widget Maps|maps]]: Kartendarstellung mit Google Maps API
* [[FTUI Widget Highchart|highchart]]:
* [[FTUI Widget Highchart3d|highchart3d]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/itunes_artwork itunes_artwork]: itunes_artwork durchsucht die iTunes-Datenbank anhand eines Arrays von beliebigen Suchworten nach einem Cover-Artwork und zeigt dieses an.
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/javascript javascript]: Ermöglicht die Ausführung beliebigen Javascript-Codes aus einem Reading.
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/kodinowplaying kodinowplaying]: zeigt Informationen zu grade in KODI gespielten Medien in Form eines Labels an.
* [[FTUI Widget Loading|loading]]:
* [[FTUI Widget Meteogram|meteogram]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/mpdnowplaying mpdnowplaying]: Zeigt Titelinformationen eines per MPD-Modul angebundenen Music Player Daemon an.
* [https://forum.fhem.de/index.php/topic,79283.msg712855.html#msg712855 pinpad]: Pinpad für z.B. eine Alarmanlage
* [https://forum.fhem.de/index.php/topic,76643.msg685472.html#msg685472 postme]: Liste des PostMe-Devices anzeigen
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/reload reload]: auslösen eine Pagereloads
* [[FTUI Widget Screensaver|screensaver]]:
* [[FTUI Widget SMAPortalSPG|smaportalspg]]: Anzeige von SMAPortal-Daten im FHEM Tablet UI
* [[FTUI Widget für SSCam Streaming Devices (SSCamSTRM)|sscamstrm]]: Integration von SSCam Streaming-Devices (Synology Surveillance Station Kameras) im FHEM Tablet UI
* [https://forum.fhem.de/index.php/topic,73497.0.html scrolllabel]: Texte in Laufschrift darstellen
* [[FTUI Widget Svgplot|svgplot]]: Unveränderte Übernahme eine bestehenden SVG-Plots
* [https://forum.fhem.de/index.php?topic=82883.msg750237#msg750237 todoist]: einfaches widget für todoist
* [[FTUI Widget Tts|tts]]: Sprachausgabe eines Textes aus einem Reading auf dem Endgerät.
* [[FTUI Widget UWZ|uwz]]: Anzeige der Warnungen der Unwetterzentrale
* [[FTUI Widget Wakeup|wakeup]]:
* [https://github.com/svenson08/ftui-weekdaytimer-widget wdtimer]: Visualisierung des [[WeekdayTimer]] Modul
* [[FTUI Widget Weekprofile|weekprofile]]: Visualisierung des [[weekprofile]] Moduls
* [[FTUI Widget Weatherdetail|weatherdetail]]: Detaillierte Wettervorhersage über 4 Tage (Nutzt das Proplanta Modul)
* [[FTUI Widget Video|videodetail]]: Video Widget für die FTUI

===Anwendungsbeispiele===
Durch die Verbindung von Widgets mit dem FHEM-Umfeld entstehen Lösungen für typische Anwendungen.
* [[FTUI_Beispiel_Datetimepicker_für_Timer|Datetimepicker für Timer]]: Oberfläche für Timereinstellungen
* [[FTUI_Beispiel_Mondphase|Mondphase]]: Visuelle Darstellung der Mondphase
* [[FTUI_Beispiel_Webradio|Webradio]]
* [[FTUI Beispiel Zeitschaltung|Verschiedene Zeitschaltungen]]

==Templates==
Kommt ein bestimmtes "Code-Fragment" auf mehreren Seiten oder öfter pro Seite vor, bietet FTUI die Option, Templates zu erstellen. Diese werden einmal gebaut und können dann mit dem Attribut '''data-template''' nach Belieben in eine Seite eingefügt werden. Dabei besteht auch die Möglichkeit, Variablen zu verwenden.

Die Variablennamen sollten möglichst eindeutig und unverwechselbar gewählt werden, da bei der Verwendung von Templates im Prinzip Suchen & Ersetzen angewendet wird. Verwendet man beispielsweise die Variablen '''dev:Thermostat_Kueche''' und '''dev_temp:temperatue''', so kann es passieren, dass die Ergebnisse im erzeugten Code dann '''Thermostat_Kueche''' und '''Thermostat_Kueche_temp''' lauten, statt wie gewünscht '''Thermostat_Kueche''' und '''temperature'''. Um dies zu vermeiden, sollten die Variablen besser '''device:Thermostat_Kueche''' und '''temp:temperature''' lauten.

Im Folgenden ein paar Beispiele, wie Templates verwendet werden können.

===Einzelnes Widget===
Soll ein Widget an mehreren Stellen in exakt der selben Ausführung eingebunden werden, kann diese Widget in einer eigenen Datei erstellt und diese dann auf den Zielseiten automatisch mitgeladen werden.

;Template-Seite
Die Template-Seite soll in diesem Beispiel ''template_symbol.html'' genannt werden. Diese wird daher zuerst im FTUI-Verzeichnis erstellt.
<syntaxhighlight lang="html">
<div data-type="symbol"
data-device="dummy1">
</syntaxhighlight>

;Haupt-Seite
Die oben erstellte Template-Seite kann nun in jeder gewünschten Seite eingebunden werden.
<syntaxhighlight lang="html" highlight="6">
[...]
<body>
<div class="gridster">
<ul>
<li data-row="1" data-col="1" data-sizey="1" data-sizex="1">
<div data-template="template_symbol.html"></div>
</li>
</ul>
</div>
</body>
[...]
</syntaxhighlight>

===Gridster-Element===
Natürlich kann auch ein ganzes Gridster-Element - in diesem Fall ein Menü - als Template eingebunden werden.
<syntaxhighlight lang="html">
<li data-row="1" data-col="1" data-sizex="1" data-sizey="4" data-template="menu.html"></li>
</syntaxhighlight>

=== Widget-Gruppen ===
Die Template-Datei des [[#Einzelnes Widget|ersten Beispiels]] kann natürlich auch mehrere Widgets auf einmal enthalten.

=== Verwendung von Variablen ===
==== Einfaches Beispiel ====
Oft wird ein und dasselbe Widget für verschiedenen Devices verwendet. Um nicht für jedes Device das Widget neu kopieren zu müssen (bzw. bei Änderungen alle Seiten ausbessern zu müssen), kann ein Template verwendet werden, dem einfach per Parameter mitgeteilt wird, von welchem Device es gerade die Daten empfangen soll.

In diesem Beispiel wird ein Template erzeugt, dass nur die Temperatur verschiedenen Thermostate mittels eines [[FTUI Widget Label|Label-Widgets]] anzeigt.

;Template-Seite
Die Template-Seite enthält nur ein einfaches Label-Widget und wird in diesem Beispiel ''template_label.html'' genannt. Um sie für mehrere Devices verwenden zu können, wird im Attribut '''data-device''' der Name des eigentlichen Devices durch den Parameter '''par01''' ersetzt.
<syntaxhighlight lang="html" highlight="2">
<div data-type="label"
data-device="par01"
data-get="measured-temp"></div>
</syntaxhighlight>

;Haupt-Seite
Auf der Haupt-Seite wird die Template-Seite mit dem Attribut '''data-template''' eingebunden und ihr via Attribut '''data-parameter''' das jeweils gewünschte Device übergeben.
<syntaxhighlight lang="html">
[...]
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat1"}'></div>
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat2"}'></div>
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat3"}'></div>
[...]
</syntaxhighlight>

==== Wetter-Slider mit Template ====
In diesem Beispiel wird ein [[FTUI Widget Slider|Slider-Widget]] erstellt, welches die verschiedenen Tage eines Wetterberichtes anzeigt. Dabei wird für den Wetterbericht des jeweiligen Tages immer dasselbe Template verwendet um nicht für jeden Tag ein eigenes Widget schreiben zu müssen.

;Template-Seite
<syntaxhighlight lang="html">
<div class="left">
<div data-type="label" data-device="AgroWeather" data-get="par01" data-unit="°C"></div>
<div class="inline">
<div data-type="label" data-device="AgroWeather" data-get="par02"></div>
<div data-type="weather" data-device="AgroWeather" data-get="par02"></div>
min: <div data-type="label" data-device="AgroWeather" data-get="par03" data-unit="°C"></div>
</div>
</div>
<div class="left">
<div data-type="label" data-device="AgroWeather" data-get="par04" data-substitution="toDate().eeee()+','"></div>
<div data-type="label" data-device="AgroWeather" data-get="par04" data-substitution="toDate().ddmm()"></div>
</div>
</syntaxhighlight>

;Haupt-Seite
In der Haupt-Seite wird das Template dann für jede Slider-Seite eingebunden und das Reading für den jeweiligen Tag via Parameter übergeben.
<syntaxhighlight lang="html">
[...]
<div data-type="swiper">
<ul>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc0_tempMax","par02":"fc0_weatherDay","par03":"fc0_tempMin","par04":"fc0_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc1_tempMax","par02":"fc1_weatherDay","par03":"fc1_tempMin","par04":"fc1_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc2_tempMax","par02":"fc2_weatherDay","par03":"fc2_tempMin","par04":"fc2_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc3_tempMax","par02":"fc3_weatherDay","par03":"fc3_tempMin","par04":"fc3_date"}'></li>
</ul>
</div>
[...]
</syntaxhighlight>

== JavaScript-Funktionen ==
Neben den Widgets können auch einige JavaScript-Funktionen verwendet werden, um Befehle an FHEM zu senden.

Folgende Zeile setzt einen direkten Befehl an FHEM ab (<code>set dummy1 off</code>):
<syntaxhighlight lang="html"><div onclick="ftui.setFhemStatus('set dummy1 off')">Dummy1 aus</div></syntaxhighlight>

Diese Zeile veranlasst FHEM dazu, eine Funktion aus der 99_myUtils.pm auszuführen (<code>myUtils_HeizungUpDown("WZ.Thermostat_Climate","up")</code>):
<syntaxhighlight lang="html"><div onclick="ftui.setFhemStatus('{myUtils_HeizungUpDown("WZ.Thermostat_Climate","up")}')">+</div></syntaxhighlight>

Ein Beispiel, wie ein Kommando an FHEM gesendet wird und gleichzeitig der Wert eines bereits in FTUI angezeigten Readings verwendet werden kann:
<syntaxhighlight lang="html">
<div data-type="label" data-device="dummy1" data-get="temperature"></div>
<div onClick="ftui.setFhemStatus('set dummy2 '+ftui.getDeviceParameter('dummy1','temperature').val);">Senden</div>
</syntaxhighlight>

== Eigene Widgets erstellen ==
Wie eigenen Widgets für FTUI erstellt werden können, ist auf der Seite [[FTUI eigene Widgets]] beschrieben.

Eine Schritt für Schritt Anleitung für das erste eigene Widget gibts hier [[FTUI eigene Widgets - Beispiel]]

== FAQ ==
Häufig gestellte Fragen zum FHEM Tablet UI sind in der [[FHEM Tablet UI FAQ]] zusammengestellt.

== Links ==
* [https://github.com/knowthelist/fhem-tablet-ui Projekt auf Github]
* {{Link2Forum|Topic=34233|LinkText=Forums-Beitrag}}
* [[FTUI_Snippets|Snippets]]
* [http://knowthelist.github.io/fhem/tablet/demo_widgets.html Live-Demos]
* [https://waschto.eu/fhem-und-tabletui-livedemo/ FHEM und TabletUI Live-Demo]
* {{Link2Forum|Topic=37378|LinkText=User-Demos}}
* [https://github.com/ovibox/fhem-ftui-user-demos Download der User-Demo-Dateien]

[[Kategorie:FHEM Tablet UI|!]]

Kategorie:Vorlage:

2023-11-09T11:03:23Z

Drhirn: Weiterleitung auf Kategorie:Vorlage entfernt

{{Löschkandidat|Da ist wohl mal was bei der Erstellung einer Seite schief gelaufen. Der Doppelpunkt in dieser Kategorie ist zu viel.}}
#WEITERLEITUNG [[:Kategorie:Vorlage]]

FHEMWiki:Sandbox

2023-11-09T10:58:06Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

<syntaxhighlight lang="perl">
#!/usr/bin/perl
use strict;
use warnings;

use Path::Class;
use autodie; # die if problem reading or writing a file

my $dir = dir("/tmp"); # /tmp

my $file = $dir->file("file.txt"); # /tmp/file.txt

# Get a file_handle (IO::File object) you can write to
my $file_handle = $file->openw();

my @list = ('a', 'list', 'of', 'lines');

foreach my $line ( @list ) {
# Add the line to the file
$file_handle->print($line . "\n");
}
</syntaxhighlight>

Test Tracking categories:
[[Datei:Brokenfile.pdf]]
<syntaxhighlight lang="html">
<Seiten mit dem veralteten source-Tag>
</syntaxhighlight>
<syntaxhighlight>
<syntaxhighlight ohne lang=>
</syntaxhighlight>

DWD OpenData

2023-11-09T10:57:25Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Hinweis|Versionsänderung: Die Vorhersagedaten wurden Mitte September 2018 von CSV auf KML umgestellt. Diese Umstellung ist inkompatibel: das DWD_OpenData-Modul muss aktualisiert werden, einige Reading-Namen haben sich geändert und der Weblink muss deinstalliert und neu installiert werden (siehe diesen {{Link2Forum|Topic=83097|Message=840270|Linktext=Beitrag im Forum}}).}}

{{Infobox Modul
|ModPurpose=Daten vom DWD OpenData Server abrufen
|ModType=d
|ModCmdRef=DWD_OpenData
|ModForumArea=Unterstützende Dienste/Wettermodule
|ModTechName=55_DWD_OpenData.pm
|ModOwner=JensB ({{Link2FU|14024|Forum}}/[[Benutzer Diskussion:JensB|Wiki]])
}}

Der Deutsche Wetterdienst (DWD) stellt Wetterdaten über den [https://www.dwd.de/DE/leistungen/opendata/opendata.html Open Data Server] zur Verfügung. Die Verwendung dieses Dienstes und der vom DWD zur Verfügung gestellten Daten unterliegt den auf der OpenData Webseite beschriebenen Bedingungen. Einen Überblick über die verfügbaren Daten findet man in der Tabelle [https://www.dwd.de/DE/leistungen/opendata/help/inhalt_allgemein/opendata_content_de_en_xls.xls OpenData_weather_content.xls] oder hier: https://opendata.dwd.de/weather/lib/MetElementDefinition.xml.

== Anwendung ==
Aufgrund der unterschiedlichen vom DWD bereitgestellten Datenformate benötigt das Modul zur Dekodierung je nach gewünschtem Funktionsumfang zusätzliche Perl-Module, die nicht standardmäßig vorinstalliert sind und je nach Systemkonfiguration nachinstalliert werden müssen. Außerdem unterstützt das Modul Zeitzonen, um z.B. die Wettervorhersage internationaler Stationen in Ortszeit darstellen zu können. Hierfür sind je nach Systemkonfiguration weitere Einstellungen erforderlich. Auch die Sprache der Wochentage für die Wettervorhersage ist frei wählbar. Je nach Systemkonfiguration ist aber die Standardsprache u.U. auf Englisch eingestellt, was weitere Anpassungen der Systemkonfiguration erforderlich macht.

=== Vorbereitung ===
Im folgenden wird z.T. von einem System mit Rasbian oder Debian mit System-V Startsystem ausgegangen. Auf anderen Betriebssystemen und auf Systemen mit System-D müssen die Installationsschritte ggf. angepasst werden.

1. Für die Wettervorhersage und die Wetterwarnungen:
Installation des Perl-Moduls ''XML::LibXML'' über die System-Kommandozeile mit
<syntaxhighlight lang="bash">
sudo apt-get install libxml-libxml-perl
</syntaxhighlight>
oder mit CPAN.

2. Weiterhin ist das Perl-Modul '' DateTime'' erforderlich. Dieses lässt sich mit <syntaxhighlight lang="bash">sudo apt-get install libdatetime-perl</syntaxhighlight> installieren.

3. Falls man einen eigenen Internet-Proxy nutzt:
Die Konfiguration des Proxies für FHEM erfolgt z.B. durch Eintrag von
<pre>
attr global proxy <myProxyHost>:<myProxyPort>
</pre>
in die [[Konfiguration]], wobei ''myProxyHost'' durch den Namen oder die IP-Adresse des Proxy-Servers ersetzt werden muss und für ''myProxyPort'' der Port des Proxy-Servers eingetragen werden muss (oft 3128).

3. FHEM Uhrzeit und Zeitzone:
Durch Eingabe von
<pre>
{localtime()}
</pre>
in die FHEM-Kommandozeile überprüfen, ob die FHEM-Uhrzeit plausibel ist. Ist dies nicht der Fall sollten die Uhrzeit auf Systemebene überprüft werden und ggf. die Systemeinstellungen angepasst werden.
Ermitteln der Bezeichnung der eigenen Zeitzone über die System-Kommandozeile mit
<pre>
tzselect
</pre>
und diese Bezeichnung in die Datei ''/etc/timezone'' eintragen und
<pre>
export TZ=`cat /etc/timezone`
</pre>
der Datei ''/etc/profile'' hinzufügen und dann das System neu starten. Nun muss die Zeitanzeige in FHEM korrekt sein.

4. FHEM Sprache:
Durch Eingabe von
<pre>
{$ENV{LANG}}
</pre> in die FHEM-Kommandozeile überprüfen, in welcher Sprache der Wochentag angezeigt wird. Stimmt die Sprache nicht, dann auf der System-Kommandozeile
<pre>
dpkg-reconfigure locales
</pre> eingeben und aus der Liste z.B. ''de_DE.UTF-8'' zusätzlich auswählen. Dieser Befehl gilt für Debian-basierte Betriebssysteme - für andere Betriebssysteme ist eine analoge Funktion zu verwenden. Mit Eingabe von
<pre>
locale -a
</pre> auf der System-Kommandozeile überprüfen, ob die ausgewählte Sprache nun zur Verfügung steht. Sollte FHEM nach einem Neustart noch immer nicht die gewünschte Sprache verwenden, kann man auf einem System V Linux durch Hinzufügen von z.B.
<pre>
export LANG=de_DE.UTF-8
</pre> in die Datei ''/etc/init.d/fhem'' (irgendwo zwischen ''start'' und ''perl'') und erneutem Neustart von FHEM die Sprache für FHEM erzwingen. Bei einem Systemd Linux kann man die Einstellungen mit ''systemctl edit --full fhem.service'' bearbeiten. Spätestes jetzt muss die Wochentagsanzeige in FHEM korrekt sein.

5. Nur für den Weblink erforderlich:
Installation des Perl-Moduls ''DateTime'' über die System-Kommandozeile mit
<pre>
sudo apt-get install libdatetime-perl
</pre>
oder mit CPAN.

=== Define ===
Siehe {{Link2CmdRef|Anker=DWD_OpenDatadefine|Label=Commandref}}.

=== Attributes ===
Siehe {{Link2CmdRef|Anker=DWD_OpenDataattr|Label=Commandref}}.

== Anwendungsbeispiele ==
=== Beispiel zur Modul-Einrichtung ===

* Wettervorhersage
Für die Wettervorhersage muss der Stationscode ermittelt werden. Dazu den [https://www.dwd.de/DE/leistungen/met_verfahren_mosmix/mosmix_stationskatalog.pdf MOSMIX Stationskatalog] herunterladen, öffnen und die gewünschte Station heraussuchen (Spalte ''id''). Einen Teil der deutschen Stationen kann man auch der [https://www.dwd.de/DE/derdwd/messnetz/bodenbeobachtung/messnetzkarte_boden.pdf Bodenmessnetzkarte] entnehmen. Den ermittelten Stationscode kann man dann entweder für eine Einzelabfrage als Parameter für das Kommando ''get forecast'' verwenden oder für die automatische Aktualisierung als Attribut ''forecastStation'' hinterlegen. Insgesamt werden vom DWD mehr als 70 Merkmale zur Verfügung gestellt. Eine Auflistung findet sich im Dokument [https://opendata.dwd.de/weather/lib/MetElementDefinition.xml MetElementDefinition]. Nur ein kleiner Teil der Merkmale wird in der Standardeinstellung des Moduls als Reading zur Verfügung gestellt. Wer andere Merkmale benötigt muss sie mit Komma getrennt dem Attribut ''forecastProperties'' zuweisen. Es empfiehlt sich zur Performance-Optimierung sowohl das Attribut ''forecastDays'' als auch das Attribut ''forecastProperties'' auf den tatsächlichen Bedarf einzustellen.

* Wetterwarnungen
Für die Wetterwarnungen muss die Warnzelle ermittelt werden. Dazu [https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv Warnzellen-ID Katalog] herunterladen, öffnen und die gewünschte Warnzelle heraussuchen. Unterstützt werden Gemeinden (beginnen mit 8), Landkreise (beginnen mit 1 oder 9) oder Küste (beginnen mit 5). Die Warnzellen-ID kann man dann entweder für eine Einzelabfrage als Parameter für das Kommando ''get alerts'' verwenden oder für die automatische Aktualisierung als Attribut ''alertArea'' hinterlegen. Die Warnzellen-ID ist ab der 2. Stelle identisch mit den ersten Ziffern des amtlichen Gemeindeschlüssels. Man kann z.B. den Namen von Gemeinde oder Landkreis bei den [https://www.statistik-bw.de/Statistik-Portal/gemeindeverz.asp Statistischen Ämtern des Bundes und der Länder] eingeben, den amtlichen Gemeindeschlüssel ermitteln und dann mit vorangestellter 1, 8 oder 9 im Warnzellen-ID Katalog des DWD nach einem Eintrag mit exakter oder weitgehender Übereinstimmung suchen. Wem das zu kompliziert vorkommt, der kann bei mehrdeutigen Gemeinde- bzw. Landkreisbezeichnungen auch versuchen auszuprobieren, welche die richtige Warnzellen-ID ist.

Um das Modul mit automatisch Aktualisierung von Vorhersage und Wetterwarnungen zu nutzen, kann z.B. folgendes in die [[Konfiguration]] eingetragen werden:

<pre>
define DWD DWD_OpenData
attr DWD alertArea 111000000
attr DWD forecastStation 99810
attr DWD forecastDays 3
attr DWD forecastWW2Text 1
</pre>

* Performance
Das DWD_OpenData-Modul ist ein Datenmodul mit relativ vielen Readings. In der Standardkonfiguration wird, wie bei jedem anderen FHEM Modul, bei jeder Änderung jedes Readings ein FHEM internes Ereignis erzeugt, damit andere FHEM Devices auf diese Änderungen reagieren können. Diese Ereignisse sorgen auch dafür, dass man Änderungen in der Weboberfläche sofort angezeigt bekommt, ohne die Webseite neu aufzurufen. Interessiert sich aber kein FHEM Device für die Änderungsbenachrichtigung bestimmter Readings, entsteht unnötiger Verarbeitungs-Overhead, der je nach FHEM Konfiguration und verfügbarer CPU-Leistung auch mehrere Sekunden benötigen kann und in dieser Zeit andere Abläufe blockiert. Um die Performance zu optimieren, empfiehlt es sich, mit [[event-on-update-reading]] für eine angepasste und dadurch effizientere Verarbeitung zu sorgen, indem man nur für jene Readings Ereignisse zulässt, welche man für die Weiterverarbeitung braucht. Der DWD_OpenData_Weblink braucht z.B. gar keine Ereignisse, um zu funktionieren. Hier eine minimalistische Beispielkonfiguration:

<pre>
attr DWD event-on-update-reading state,fc_state,a_state
</pre>

Weitere Details zur Installation und Konfiguration des Moduls finden sich in der
{{Link2CmdRef|Anker=DWD_OpenData|Label=Commandref}}.

=== Beispiel für die Einrichtung eines Meteogramms ===
Um den vorhergesagten Wetterverlauf als Meteogramm in Kurvenform mit [[SVG]] darzustellen, kann man wie folgt vorgehen:

1. 99_myUtils.pm

Für die Bestimmung der Werte für den SVG-Plot wird eine Perl-Funktion benötigt, die in die Datei 99_myUtils.pm vor dem Ende eingefügt wird. Wer diese FHEM-Datei noch nicht nutzt, legt sie einfach an (siehe [[99_myUtils_anlegen]]).
<syntaxhighlight lang="perl">
package main;

use strict;
use warnings;

...

#
# (c) mumpitzstuff 19.12.2018
#
# see https://forum.fhem.de/index.php/topic,83097.msg874150.html#msg874150
#
sub logProxy_dwd2Plot($$$$;$$$)
{
my ($device, $fcValue, $from, $to, $fcHour, $expMode, $shiftTime) = @_;
my $regex;
my @rl;

return undef if(!$device);

if ($fcValue =~ s/_$//)
{
$regex = "^fc[\\d]+_[\\d]+_".$fcValue."\$";
}
else
{
$regex = "^fc[\\d]+_".$fcValue."\$";
}

$fcHour = 12 if(!defined($fcHour));
$expMode = "point" if(!defined($expMode));
#Log3 undef,2, "Regex: ".$regex;

# ermitteln aller relevanten Readings
if ( defined($defs{$device}) )
{
if ( $defs{$device}{TYPE} eq "DWD_OpenData" )
{
@rl = sort
{
my ($an) = ($a =~ m/fc(\d+)_.*/);
my ($bn) = ($b =~ m/fc(\d+)_.*/);
my ($ao) = ($a =~ m/fc\d+_(\d+).*/);
my ($bo) = ($b =~ m/fc\d+_(\d+).*/);
$an <=> $bn or $ao <=> $bo or $a cmp $b;
} ( grep /${regex}/,keys %{$defs{$device}{READINGS}} );
return undef if ( !@rl );
}
else
{
Log3 undef, 2, "logProxy_dwd2Plot: $device is not a DWD_OpenData device";
return undef;
}
}

my $fromsec = SVG_time_to_sec($from);
my $tosec = SVG_time_to_sec($to);
my $sec = $fromsec;
my ($h, $hp, $fcDay, $mday, $mon, $year);
my $timestamp;

my $reading;
my $value;
my $prev_value;
my $min = 999999;
my $max = -999999;
my $ret = "";

# while not end of plot range reached
while (($sec < $tosec) && @rl)
{
#remember previous value for start of plot range
$prev_value = $value;

$reading = shift @rl;
($fcDay) = $reading =~ m/^fc(\d+).*/;
($hp) = $reading =~ m/^fc\d+_(\d+).*/;
#Log 1, "hp: ".$hp;

if ($hp)
{
$h = ReadingsVal($device, "fc".$fcDay."_".$hp."_time", $fcHour);
if ($h =~ m/^(\d+):\d+/)
{
$h = $1;
}
}
else
{
$h = $fcHour;
}

$value = ReadingsVal($device, $reading, undef);

# calculate minutes of sunshine per hour
if ($fcValue =~ /^SunD(\d+)/)
{
if (defined($1))
{
$value = $value / ($1 * 36);
}
else
{
$value = $value / (12 * 36);
}
}

# calculate amount of rain per hour
if ($fcValue =~ /^RR(\d+)c$/)
{
if (defined($1))
{
$value /= $1;
}
}

($year, $mon, $mday) = split('\-',ReadingsVal($device, "fc".$fcDay."_date",undef));
$timestamp = sprintf("%04d-%02d-%02d_%02d:%02d:%02d", $year, $mon, $mday, $h, 0, 0);
$sec = SVG_time_to_sec($timestamp);
if (defined($shiftTime))
{
$sec += $shiftTime;
$timestamp = logProxy_shiftTime($timestamp, $shiftTime);
}

# skip all values before start of plot range
next if ( $sec < $fromsec );

# add first value at start of plot range
if ( !$ret && $prev_value )
{
$min = $prev_value if ( $prev_value < $min );
$max = $prev_value if ( $prev_value > $max );
$ret .= "$from $prev_value\n";
}

# done if after end of plot range
last if ($sec > $tosec);

$min = $value if ( $value < $min );
$max = $value if ( $value > $max );

# add actual control point
$ret .= "$timestamp $value\n";
}

if (($sec < $tosec) && !@rl && ($expMode eq "day"))
{
$timestamp = sprintf("%04d-%02d-%02d_%02d:%02d:%02d", $year, $mon, $mday, 23, 59, 59);
$_ = SVG_time_to_sec($timestamp);
if (defined($shiftTime))
{
$_ += $shiftTime;
$timestamp = logProxy_shiftTime($timestamp, $shiftTime);
}

if ($_ < $tosec)
{
$ret .= "$timestamp $value\n";
}
else
{
$ret .= "$to $value\n";
}
}
elsif (($sec > $tosec) && ($expMode eq "day"))
{
$value = $prev_value + ($value - $prev_value) * (86400 + ($tosec - $sec)) / 86400;
$ret .= "$to $value\n";
}

return ($ret, $min, $max, $prev_value);
}

1;
</syntaxhighlight>

2. LogProxy

Wer bereits ein [[logProxy]]-Device hat, muss den Namen seines logProxy-Devices in die weiter unter aufgeführte GPlot-Konfiguration eintragen. Ansonsten wird es wie folgt neu erstellt:
<pre>
define LogProxy logProxy
</pre>

3. FileLog

Das Meteogramm kennt anders als andere FHEM-Plots keine Vergangenheit außer heute. Trotzdem wird aus formalen Gründen ein [[FileLog]]-Device benötigt. Dazu kann ein beliebiges vorhandenes FileLog-Device verwendet werden. Wer will, kann hierfür aber auch ein neues FileLog Device für das DWD_OpenData-Device anlegen (Achtung: wird schnell umfangreich):
<pre>
define FileLog_DWD FileLog ./log/DWD-%Y-%m.log DWD
</pre>

Im folgenden wird für das FileLog-Device der Platzhalter ''FileLog_Dummy'' verwendet, der mit dem Namen des gewählten FileLog-Devices zu ersetzen ist.

4. SVG Plot

Das eigentliche Meteogramm ist ein SVG-Device. Will man mehrere Tage darstellen bietet sich die folgende Definition an:
<pre>
define SVG_DWD SVG FileLog_Dummy:SVG_DWD:CURRENT
attr SVG_DWD fixedoffset 6
attr SVG_DWD fixedrange 7days
attr SVG_DWD nrAxis 1,2
</pre>

Dabei muss das SVG-Attribut ''fixedoffset'' entweder gleich oder kleiner als die Einstellung des DWD_OpenData-Attributs ''forecastDays'' (Standardwert: 6 Tage) gewählt werden und das SVG-Attribut ''fixedrange'' um eins größer als ''fixedoffset'' eingestellt werden.

Will man stattdessen nur die nächsten 24 Stunden anzeigen, nimmt man folgende Einstellungen:
<pre>
define SVG_DWD SVG FileLog_Dummy:SVG_DWD:CURRENT
attr SVG_DWD endPlotNow 1
attr SVG_DWD fixedoffset 1
attr SVG_FileLog_WETTER_DWD_3 label "Tmin: $data{max1} °C, Tmax: $data{min1} °C"
attr SVG_DWD nrAxis 1,2
</pre>

Um die DWD_OpenData-Readings mit dem Plot zu verknüpfen, muss man nun die GPlot-Konfigurationsdatei des SVG-Plots manuell bearbeiten. Dazu auf den Link klicken, der im SVG_DWD-Device am Internal ''GPLOTFILE'' steht. Die y-Wertebereiche für die Regenmenge und die Temperaturen sind im Beispiel auskommentiert (Autorange). Das kann man so lassen oder man stellt sie nach den eigenen Wetter-Gegebenheiten ein. Je nach Konfiguration des DWD_OpenData-Attributs ''forecastResolution'' sind aber noch einige weitere Einstellungen anzupassen. Das folgende Beispiel ist für die 3h-Auflösung:
<pre>
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title 'Wettervorhersage'
set ytics
set y2tics
set grid ytics
set ylabel "Regen [mm]"
#set yrange [0:4]
set y2label "Temperatur [°C]"
#set y2range [-5:35]
set y3label "Wolken/Regen/Sonne [%]"
set y3range [0:100]

#LogProxy Func:logProxy_dwd2Plot("DWD","TTT_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","Tx",$from,$to,18,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","Tn",$from,$to,6,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","SunD3_",$from,$to,0,"day",(-3*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","RR3c_",$from,$to,0,"day",(-3*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","FX1_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","R600_",$from,$to,0,"day",(-3*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","Neff_",$from,$to,0,"day")
#LogProxy ConstX:TimeNow(),0,100
#LogProxy ConstY:0

plot "<IN>" using 1:2 axes x1y2 title 'T' ls l0 lw 2 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y2 title 'Tmax' ls l0dot lw 2 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y2 title 'Tmin' ls l0dot lw 2 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Sonne' ls l4fill lw 1 with lines,\
"<IN>" using 1:2 axes x1y1 title 'Regenmenge' ls l2fill lw 1 with steps,\
"<IN>" using 1:2 axes x1y3 title 'Wind' ls l1 lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Regen' ls l5fill lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Wolken' ls l6fill lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 notitle ls l5 lw 4 with lines,\
"<IN>" using 1:2 axes x1y2 notitle ls l5 lw 1 with lines
</pre>

Verwendet man dagegen eine Auflösung von 1 Stunde, sind folgende LogProxy-Einträge erforderlich:
<pre>
#LogProxy Func:logProxy_dwd2Plot("DWD","TTT_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","Tx",$from,$to,18,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","Tn",$from,$to,6,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","SunD1_",$from,$to,0,"day",(-1*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","RR1c_",$from,$to,0,"day",(-1*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","FX1_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","R101_",$from,$to,0,"day",(-0.5*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","Neff_",$from,$to,0,"day")
#LogProxy ConstX:TimeNow(),0,100
#LogProxy ConstY:0
</pre>

Für die Darstellung der nächsten 24 Stunden mit einer Auflösung von 1 Stunde nimmt man folgende GPlot-Konfiguration:
<pre>
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'
set ytics
set y2tics
set y3tics
set grid xtics y2tics
set ylabel "Regen [mm]"
set y2label "Temperatur [°C]"
set y3label "Wolken/Regen/Sonne [%]"
set y3range [0:100]

#LogProxy Func:logProxy_dwd2Plot("DWD","TTT_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","SunD1_",$from,$to,0,"day",(-1*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","RR1c_",$from,$to,0,"day",(-1*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","FX1_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","R101_",$from,$to,0,"day",(-0.5*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","Neff_",$from,$to,0,"day")
#LogProxy ConstY:0

plot "<IN>" using 1:2 axes x1y2 title 'T' ls l0 lw 2 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Sonne' ls l4fill lw 1 with lines,\
"<IN>" using 1:2 axes x1y1 title 'Regenmenge' ls l2fill lw 1 with steps,\
"<IN>" using 1:2 axes x1y3 title 'Wind' ls l1 lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Regen' ls l5fill lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Wolken' ls l6fill lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y2 notitle ls l2 lw 2 with lines
</pre>

Je nachdem, welche Auflösung man verwendet, werden unterschiedliche Readings des DWD_OpenData-Devices benötigt. Diese sind in den LogProxy-Zeilen in der GPlot-Konfigurationsdatei zu finden und müssen auf jeden Fall dem Attribut ''forecastProperties'' des DWD_OpenData-Device hinzugefügt werden.

Viele Detaileinstellungen des Meteogramms lassen sich individualisieren. Man kann z.B. mehr oder weniger Daten anzeigen und zumindest für ''heute'' auch aktuelle Messwerte hinzufügen.

Hier ein Beispiel für ein Meteogramm über 4 Tage mit 3 Stunden Auflösung:

[[File:DWDODmeteogram4d3h.png|500px]]

=== Beispiel für die Einrichtung eines Weblinks ===
Zur graphischen Darstellung der Vorhersage und der Wetterwarnungen mit [[FHEMWEB]] steht das Modul [https://raw.githubusercontent.com/jnsbyr/fhem/master/FHEM/99_DWD_OpenData_Weblink.pm 99_DWD_OpenData_Weblink.pm] zur Verfügung.

Zunächst die Moduldatei herunterladen und in das Modulverzeichnis ''fhem/FHEM'' kopieren. Entweder die Datei direkt auf den FHEM-Server herunterladen (z.B. mit ''wget'') oder beim indirekten Herunterladen darauf achten, dass dabei das Encoding nicht verändert wird (also z.B. bei WinSCP den Binär-Modus und nicht den Text-Modus verwenden). Ansonsten werden später z.B. Sonderzeichen wie ''°C'' falsch angezeigt.

Anschließend kann in die [[Konfiguration]] z.B. folgendes eingetragen werden:

<pre>
define DWD_Weblink_Generator DWD_OpenData_Weblink
attr DWD_Weblink_Generator IODev DWD
attr DWD_Weblink_Generator forecastDays 4
# refreshRate nur dann setzten, wenn der Browser Java-Script beherrscht:
attr DWD_Weblink_Generator refreshRate 900

define DWD_Weblink weblink htmlCode { DWD_OpenData_Weblink::AsHtmlH("DWD_Weblink_Generator") }
</pre>

Damit legt man das Weblink-Generator-Device an und verknüpft es mit dem DWD_OpenData-Device. Außerdem wird der [[weblink ]] selbst angelegt, der seinerseits mit dem Weblink-Generator-Device verknüpft wird. Der Weblink benötigt für seine Funktion eine bestimmte Auswahl der Vorhersage-Merkmale. Wer das Attribut ''forecastProperties'' des DWD_OpenData-Moduls anpassen will, muss diese Merkmale auf jeden Fall mit berücksichtigen.

Wenn vom Weblink nichts im Browser zu sehen ist, kann das daran liegen, dass der Browser kein aktuelles JavaScript verwendet oder JavaScript deaktiviert ist. Dann sollte das Attribut ''refreshRate'' auf 0 Sekunden eingestellt oder gelöscht werden. Mit aktiviertem Refresh werden die Daten auch ohne Seitenneuaufbau regelmäßig und bei Tab-Wechsel aktualisiert.

Die Liste der erforderlichen Vorhersage-Merkmale finden sich zusammen mit allen weiteren Details zur Installation und Konfiguration in der Modulhilfe von ''99_DWD_OpenData_Weblink.pm'', die man z.B. nach dem Anlegen des Weblink-Generator-Devices über die Weboberfläche abrufen kann.

Hier ein Ausschnitt aus der Darstellung des Weblinks mit [[FHEMWEB]]:

[[File:DWDODweblink.png|500px]]

Vbus

2023-11-09T10:56:56Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

<div style="float:right">{{Infobox Modul
|ModPurpose=VBUS LAN Adapter Device
|ModType=x
|ModCmdRef=VBUSIF
|ModForumArea=Sonstige Systeme
|ModFTopic=10303
|ModTechName=19_VBUSIF.pm
|ModOwner={{Link2FU|1754|Jörg (pejonp}})
}}
{{Infobox Modul
|ModPurpose=VBUS Client Device
|ModType=x
|ModCmdRef=VBUSDEV
|ModForumArea=Sonstige Systeme
|ModFTopic=10303
|ModTechName=21_VBUSDEV.pm
|ModOwner={{Link2FU|1754|Jörg (pejonp}})
}}
</div>

== Kurzbeschreibung ==
Das Vbus-Modul verbindet einen Vbus LAN-Adapter mit FHEM.

== Voraussetzung ==
Voraussetzung zur Anbindung eines VBus Device an FHEM ist eine bestehende Netzwerkverbindung und die Verwendung der zur Verfügung stehenden Module:
* 19_VBUSIF.pm
* 21_VBUSDEV.pm

Diese Module werden aktuell extern gehostet (es findet sich aber auch noch eine veraltete Version im FHEM repository). Um diese in die FHEM Installtion einzubinden muss folgender Befehl abgesetzt werden
:<syntaxhighlight lang="bash">update all https://raw.githubusercontent.com/pejonp/vbus/master/controls_vbus.txt</syntaxhighlight>

Damit werden auch bei einer FHEM Aktualisierung ([[update]]) diese Module berücksichtigt

== Installation RESOL VBUS LAN Gateway ==
# Vorerst keine Einstellungen am VBUS/Lan Gateway (Passwort/Port etc.) vornehmen
# Die IP Adresse herausfinden (z.B. am Router) und prüfen, ob man per Browser darauf zugreifen kann
# Optional: Testen, ob Daten ankommen mit der ServiceCenter Software von Resol
# dann nur das VBUSIF als ''define'' eintragen

== Definition ==
:<code>define <name> VBUSIF <IP des VBus-Lan> <Port muss 7053 bleiben></code>

<pre>
define vbus VBUSIF 192.168.1.25:7053
attr vbus event-min-interval .*:120
attr vbus verbose 5
</pre>

== Features / Funktionen ==
Es wurden die Module
*DL 2 0050
*DL 3 0053
*Vitosolic200_SD4 1060
*DeltaSol_SL 2251
*WMZ 4010
*SKSC1/2 4211
*DeltaSolC 4212
*Sonnenkraft_SKSC2HE 4214
*DeltaSol_BS4 4278
*DeltaSol_BS_2009 427b
*DeltaTherm_FK 5611
*MSR65_1 6521
*MSR65_2 6522
*SKS3HE 7160
*SKSC3HE_[HK1] 7161
*SKSC3HE_[HK2] 7162
*DeltaSol_M 7311
*DeltaSol_M_HKM 7312
*DeltaSol_M_Volumen 7315
*DeltaSol_M_WMZ1 7316
*DeltaSol_M_WMZ2 7317
*Vitosolic200 7321
*Vitosolic200_WMZ1 7326
*Vitosolic200_WMZ2 7327
*SLR 7331
*CitrinSLR_XT 7341
*DeltaSol_ES 7411
*DeltaSol_BX 7421
*DeltaSolE_Regler 7721
*DeltaSolE_WMZ 7722
*DiemasolC 7751
*Cosmo_Multi_Regler 7821
*Cosmo_Multi_WMZ 7822
*DeltaSol_MX_Regler 7E11
*DeltaSol_MX_Module 7E12
*DeltaSol_MX_HK 7E21
*DeltaSol_MX_WMZ 7E31

== Bekannte Probleme ==
Aktuell ist es nicht möglich, die Konfiguration der Steuerungen zu ändern; es ist nur ein Abfragen der Werte implementiert.

== Weblinks ==
* Resol Protokollbeschreibung [https://danielwippermann.github.io/resol-vbus/vbus-packets.html]
* VBus GitHub [https://github.com/pejonp/vbus]

[[Kategorie:Heizungssteuerung]]

Unifi

2023-11-09T10:56:30Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Infobox Modul
|ModPurpose=Steuerung des Unifi-Controllers über FHEM
|ModType=d
|ModForumArea=Automatisierung
|ModTechName=74_Unifi.pm
|ModOwner=Wuehler ({{Link2FU|18141|Forum}} / [[Benutzer Diskussion:Wuehler|Wiki]])}}
Das Modul [[Unifi]] ermöglicht die Steuerung eines Unifi-Controllers durch FHEM. Wenn durch den Unifi-Controller auch ein [[UnifiSwitch]] verwaltet wird, so legt das Modul bei aktiviertem [[autocreate]] UnifiSwitch-Devices an.
Ausserdem gibt es das Unterstützungsmodul [[UnifiClient]], welches alle vorhandenen Informationen zu Clients als Reading bereitstellt und clientspezifische Funktionen zur Verfügung stellt.

== Voraussetzungen ==
=== Unifi-Controller ===
Es wird eine dauerhaft laufende Unifi-Controller-Software benötigt. Diese kann z.B. auf dem Unifi-Cloud-Key oder selbst installiert z.B. auf einem RaspberryPi laufen.

=== Definition ===
Die Definition erfolgt mittels <code>define <name> Unifi <ip> <port> <username> <password> [<interval> [<siteID>]] </code>.
Dabei ist folgendes zu beachten:
* ip: Der Unifi-Controller muss eine feste IP-Adresse haben
* port: Port der Adminkonsole des Unifi-Controllers. In der Regel 8443 oder 443.
* username/password: Username und Passwort eines Unifi-Controller-Users (siehe [[Unifi#Unifi-User|Unifi-User]])
* interval: Gibt die Zeit in Sekunden an, nach der das Modul erneut die Daten beim Unifi-Controller abfragt. Default: 30 Sekunden. Es ist darauf zu achten, dass das Intervall groß genug ist, so dass auch unter Last nicht vor Ende eines Update-Zyklus ein neuer Update-Zyklus gestartet wird. Dies kann zum Beispiel passieren, wenn FHEM und der Unifi-Controller auf demselben RaspberryPi laufen (interval dann zB auf 90 setzen).
* siteID: Üblicherweise und als Default <code>default</code>

Damit ist die Installation abgeschlossen. Nach kurzer Zeit sollten die ersten Readings angezeigt werden.

=== Unifi-User ===
Bei der Definition des Moduls werden username und passwort mit angegeben. Entweder wird der standardmäßig angelegte Admin des Unifi-Controllers, oder besser ein im Unifi-Controller angelegter eigener User (unter <code>settings-> admins -> add new admin</code>) genutzt. Wenn ein neuer User angelegt wird kann dieser z.B. auch ausschließlich read-only-Berechtigungen bekommen. Dies reicht für die Grundfunktion des Unifi-Moduls )Informationen auslesen und in Readings darstellen) aus. Alle set-Funktionen (Ausnahmen: clear, update und updateClient) sowie das Attribut voucherCache benötigen schreibende Rechte im Unifi-Controller .

== Anwendung ==
=== Readings ===
Details siehe Siehe {{Link2CmdRef|Lang=en|Anker=Unifi}}

==== Attribut customClientReadings ====
Mit dem Attribut <code>customClientReadings</code> können die Readings für Clients individualisiert werden. Eine Liste der möglichen Readings erhält man mittels <code>get <unifi> clientData all</code>.
* Der state eines clients kann nicht entfernt werden. D.h. für jeden client wird es ein Reading <clientName> geben, das entweder den Wert <code>connected</code> oder <code>disconnected</code> hat.
* Es werden die Daten, die der Unifi-Controller zu den Clients vorhält 1:1 als Readings zur Verfügung gestellt.
* Zusätzlich stehen mit dem Präfix _f_ versehen formatierte Werte als Reading zur Verfügung.
* Wenn der Unifi-Controller einen Wert nicht liefert, so wird auch kein Reading angelegt, selbst wenn dies im Attribut customClientReadings explizit angegeben wird.

Bei der Verwendung des Attributes gibt es teilweise Abweichungen vom Standardverhalten, die bei einer nachträglichen Verwendung des Attributes ggf. berücksichtigt werden müssen:
* Das Reading <clientName>_last_seen wird nicht als Datum formatiert dargestellt, sondern wie vom Unifi-Controller zurückgegeben als Unix-Timestamp.
* Das Reading <clientName>_hostname kann ggf. auch fehlen. Ohne das Attribut customClientReadings wird bei fehlendem hostname die ip oder "unknown" angezeigt.
* Das Reading <clientName>_snr entfällt und lautet <clientName>_rssi.

Beispiele:
* <code>.:^mac$</code> : Stellt für alle Clients zusätzlich ein Reading mit der mac-Adresse zur Verfügung
* <code>.:^mac$|^uptime$</code> : Stellt für alle Clients zusätzlich ein Reading mit der mac-Adresse und ein Reading mit der uptime (Unix-Timestamp) zur Verfügung
* <code>^meinTelefon$:^mac$</code> : Stellt nur für den Client mit dem Namen "meinTelefon" ein zusätzliches Reading mit der mac-Adresse zur Verfügung
* <code>^meinTelefon$:^mac$ ^seinTelefon$:^mac$</code> : Stellt nur für die Clients mit dem Namen "meinTelefon" oder "seinTelefon" ein zusätzliches Reading mit der mac-Adresse zur Verfügung
* <code>einTelefon$:^mac$</code> : Stellt für alle Clients, die auf "einTelefon" enden im Client-Namen haben die mac-Adresse zusätzlich zur Verfügung
* <code>.:uptime</code> : Stellt für alle Clients zusätzlich einige Readings zur Verfügung, die "uptime" im Namen enthalten. Darunter sind auch formatierte uptimes.

=== Anwesenheitserkennung ===
Üblicherweise: siehe [[PRESENCE#Beispiel_Anwesenheitserkennung_mittels_UniFi_Controller|PRESENCE]]

Oder falls man einen [[UnifiClient]] definiert hat:
<code>define <NAME> PRESENCE event <UnifiClientName>:fhem_state:.disconnected <UnifiClientName>:fhem_state:.connected</code>

=== Voucher ===
Das Modul kann automatisiert immer eine ausreichende Anzahl an Voucher-Nummern für den Zugang in ein per GuestPortal mit Voucherzugang konfiguriertes WLAN bereithalten.
Dazu wird das Attribut <code>voucherCache</code> genutzt. Mit Komma separiert können mehrere Vouchercaches angegeben werden. Je Vouchercache werden vier Attribute mit Leerzeichen getrennt mitgegeben:
* expire: Ablaufzeit des Vouchers in Minuten
* quota: Anzahl der Voucher, die mindestens vorgehalten werden (sinnvoller Wert ist >=2)
* n: Gibt an, wie oft ein einzelner Voucher genutzt werden kann (sinnvoll ist in der Regel der Wert 1)
* note: der Name des Vouchers. Er darf keine Leerzeichen enthalten und kann z.B. bei einer Auswahl in ftui angezeigt werden.
Je Vouchercache wird ein Reading -VC_<note> mit dem nächsten noch nicht bzw. am längsten nicht angeforderten Voucher zur Verfügung gestellt. Wenn weniger als "quota"-Voucher zur Verfügung stehen werden "quota" neue Voucher erstellt. Die Maximalanzahl an vorgehaltenen Vouchern beträgt als 2*quota-1.

==== Voucherverwendung aufzeichnen ====
Dies geschieht außerhalb des Moduls mit einem dummy und wird in den weiteren Beispielen mit verwendet:
<pre>defmod voucherComment dummy
attr voucherComment event-on-change-reading comment
attr voucherComment readingList comment
attr voucherComment setList comment</pre>

Über eine ReadingsHistory kann dies festgehalten werden:
<pre>defmod voucherCacheRH readingsHistory voucherComment:comment
attr voucherCacheRH nolinks 1
attr voucherCacheRH rows 10
attr voucherCacheRH timestampFormat %Y.%m.%d_%H:%M:%S</pre>

Und/oder in einem Log speichern:
<pre>defmod voucherCommentLog FileLog ./log/voucher.log voucherComment:.*</pre>

==== Voucher bereitstellen ====
Die Beispiele gehen davon aus, dass auch die Verwendung aufgezeichnet werden soll.

===== über Telegram =====
Voraussetzung in diesem Beispiel ist, dass das Modul msgDialog eingerichtet ist und ein VoucherCache mit der note "2h" konfiguriert wurde:
<pre>defmod voucher_Dialog msgDialog {\
"Voucher": {\
"commands": [\
"{fhem('set voucherComment comment '.ReadingsVal('Unifi','-VC_2h','').' (2h): $recipient')}"\
],\
"message": "{return('Code: '.fhem('get Unifi voucher 2h'))}"\
}\
}</pre>

===== in FTUI =====
Im head der Seite wird folgender code benötigt:
<syntaxhighlight lang="html">
<script>
var oldcode=0;
function setComment(){
var code =document.getElementById('voucherCode').children[0].value;
if(oldcode!=code){
oldcode=code;
ftui.sendFhemCommand('get Unifi voucher ' + document.getElementById('voucherCacheNote').children[0].children[0].options.item(document.getElementById('voucherCacheNote').children[0].children[0].selectedIndex).text);
ftui.sendFhemCommand('set voucherComment comment ' + code +' ('+document.getElementById('voucherCacheNote').children[0].children[0].options.item(document.getElementById('voucherCacheNote').children[0].children[0].selectedIndex).text+'): '+document.getElementById('comment').children[0].value);
}
}
</script>
</syntaxhighlight>

Im body der Seite kann der folgende code verwendet werden. Es wird vorausgesetzt, dass es Vouchercaches mit der note 2h und 3h gibt.

[[Datei:ftui_vouchercache.png|thumb|FTUI-Darstellung]]
<syntaxhighlight lang="html">
<li data-row="18" data-col="1" data-sizex="2" data-sizey="3" class="semitransparent">
<header>Voucher</header>
Typ:
<div data-type="select" data-items='["-VC_2h","-VC_3h"]' data-alias='["2h","3h"]' id="voucherCacheNote" class="notransmit w3x"></div>
Kommentar:
<div data-type="input"
id="comment"
class="notransmit"></div>
Code:
<div data-type="input"
data-device="Unifi"
data-get="#voucherCacheNote"
id="voucherCode"
class="notransmit w3x"></div>
<div data-type="link"
class="round notransmit"
onclick="setComment()">
Save</div>
</li>
</syntaxhighlight>

=== Erkennung neuer clients ===
Kleines DOIF mit [[TelegramBot|Telegram]]-Benachrichtigung:
<pre>defmod di_newClients DOIF ([Unifi:-UC_newClients] ne "" ) (set Telegram message unbekannter WLAN Zugriff:[Unifi:-UC_newClients])</pre>Mit zusätzlichen Infos zu SSID und AP:
<pre>
defmod UniFi_new_Client DOIF ([UniFi:-UC_newClients] ne "" )\
{my $host = ReadingsVal("UniFi","-UC_newClients","--");; ## einlesen Hostname neuer WLAN Client\
my $readingSSID = ReadingsVal("UniFi",$host."_essid","--");; ## bauen Reading SSID\
my $readingAP = ReadingsVal("UniFi",$host."_accesspoint","--");; ## bauen Reading AP\
my $text = "Neuer WLAN Zugriff von ".$host." über ".$readingAP." an ".$readingSSID;; ## vorbereiten Text\
fhem("set TelegramBot msg $text")} ## Telegram senden
</pre>

=== Funkscan mit startRFScan ===
Die Accesspoints von Unifi erlauben eine automatische Kanalwahl.

Besonders dann, wenn der Funkraum mit vielen verschiedenen WLAN-Geräten belegt ist, ist die Auswahl des richtigen Kanals für einen stabilen Funkempfang wichtig. Um den richtigen Kanal zu wählen, sollte aber der vorhandene Funkraum vorher analysiert werden. Unifi erlaubt dies durch den so genannten RFScan, der für jeden einzelnen Accesspoint aufgerufen werden kann (und der dann für die Zeit des Scan von ca 5 Minuten offline ist).

Im Modul wird der Funkscann durch den Befehl
:<code>set <UnifiModulname> setRFScan <APName></code>
sofort ausgelöst. Wenn beispielsweise bei zwei Accesspoints mit den Namen Arbeitszimmer und Keller jeweils Montag Nacht ein Scan ausgelöst werden soll, kann dies mit folgendem DOIF geschehen:

<code>defmod MeinScan DOIF ([02:55|Mo]) (set Unifi startRFScan Keller) DOELSEIF ([03:10|Mo]) (set Unifi startRFScan Arbeitszimmer) </code>

== FAQ ==
=== Warum enthält die DropDown-Liste einiger set-/get-Funktionen nicht alle Clients? ===
Vom UnifiController werden nur die Geräte mitgesendet, die connected sind / die im UnifiController auf der Seite Clients angezeigt werden. Clients, die connected waren, es aber nicht mehr sind - im UnifiController auf der Seite Insights - werden vom Modul aktuell nicht ausgelesen.

Seit März 2019 wird versucht, auch disconnected clients nach einem Neustart aus den Readings wiederherzustellen. Damit sollten die clients in den DropDowns vollständig sein.

[[Kategorie:IP Components]]
[[Kategorie:Code Snippets]]

Summe aller Einschaltzeiten eines Gerätes

2023-11-09T10:56:03Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

Dieses Beispiel ermittelt aus der Datenbank die Einschaltdauer eines Kühlschrankes (über einen Zwischenstecker HM-ES-PMSw1-Pl) innerhalb der letzten 24 Stunden. Wie üblich kann der Auswertungszeitraum über die Time-spezifischen Attribute abgeändert werden.

Es wird angenommen, dass "Aus" = 0 ist und "Ein" ein von 0 abweichender Wert (1 oder eine andere Zahl).

Es sind zwei Komponenten notwendig, ein DbRep-Device und eine Subroutine "switchontime" in der 99_myUtils.
Diese Auswertungsroutine kann abweichend davon auch in einer eigenen 99_xxxUtils.pm, z.B. 99_myOntimeUtils.pm, eingebaut werden. Diese Datei ist in das FHEM-Verzeichnis zu kopieren (üblicherweise /opt/fhem/FHEM).

== DbRep-Device ==

Das DbRep-Device wird entsprechend dieser '''Raw-Definition''' angelegt:

<pre>
define Rep.powerOnTime DbRep LogDB
attr Rep.powerOnTime aggregation no
attr Rep.powerOnTime comment Ermittlung der Anschaltdauer (Switch-on Time) eines Gerätes (z.B. Kühlschrank) \
innerhalb der letzten 24 Stunden.\
Es wird die Auswertungsroutine "switchontime" im Attribut "userExitFn" benötigt \
(in 99_myOntimeUtils.pm enthalten).\
\
Start erfolgt mit: "set <;Name>; fetchrows history"
attr Rep.powerOnTime devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.powerOnTime device eg.az.fridge_Pwr
attr Rep.powerOnTime event-on-update-reading state,switch_on_time_sec
attr Rep.powerOnTime reading power
attr Rep.powerOnTime room DbLog
attr Rep.powerOnTime timeDiffToNow 86400
attr Rep.powerOnTime userExitFn switchontime
attr Rep.powerOnTime verbose 2
</pre>

Natürlich ist das angegeben DbLog-Device (LogDB) in der Definition, sowie die Attribute device und reading den eigenen Gegebenheiten anzupassen.
Wichtig ist die Angabe:

<pre>
attr Rep.powerOnTime userExitFn switchontime
</pre>

was die Aktivierung der userExit-Funktion bzw. den Aufruf der Auswertungsroutine "switchontime" bewirkt.

Die Daten in der Datenbank befinden sich im Device "eg.az.fridge_Pwr" und dem Reading "power". Daraus resultiert dass nach einem

<pre>
set <Name> fetchrows history
</pre>

Readings mit folgenden Muster generiert werden. [[Datei:po_readings.PNG|right|thumb|300px|set <Name> fetchrows history]]

<pre>
2017-11-22_16-26-50__eg.az.fridge_Pwr__power 0 2017-11-22 18:33:50
2017-11-22_16-29-54__eg.az.fridge_Pwr__power 0 2017-11-22 18:33:50
2017-11-22_16-32-43__eg.az.fridge_Pwr__power 57.83 2017-11-22 18:33:50
2017-11-22_16-35-18__eg.az.fridge_Pwr__power 51.09 2017-11-22 18:33:50
2017-11-22_16-37-39__eg.az.fridge_Pwr__power 50.13 2017-11-22 18:33:50
2017-11-22_16-39-45__eg.az.fridge_Pwr__power 50.17 2017-11-22 18:33:50
2017-11-22_16-42-40__eg.az.fridge_Pwr__power 49.59 2017-11-22 18:33:50
2017-11-22_16-45-22__eg.az.fridge_Pwr__power 48.57 2017-11-22 18:33:50
2017-11-22_16-47-48__eg.az.fridge_Pwr__power 47.48 2017-11-22 18:33:50
2017-11-22_16-50-01__eg.az.fridge_Pwr__power 46.97 2017-11-22 18:33:50
2017-11-22_16-53-03__eg.az.fridge_Pwr__power 46.02 2017-11-22 18:33:50
2017-11-22_16-53-05__eg.az.fridge_Pwr__power 11.09 2017-11-22 18:33:50
2017-11-22_16-53-13__eg.az.fridge_Pwr__power 0 2017-11-22 18:33:50
2017-11-22_18-14-05__eg.az.fridge_Pwr__power 0 2017-11-22 18:33:50
2017-11-22_18-16-39__eg.az.fridge_Pwr__power 0 2017-11-22 18:33:50
2017-11-22_18-18-58__eg.az.fridge_Pwr__power 0 2017-11-22 18:33:50
2017-11-22_18-21-03__eg.az.fridge_Pwr__power 0 2017-11-22 18:33:50
2017-11-22_18-23-58__eg.az.fridge_Pwr__power 0 2017-11-22 18:33:50
2017-11-22_18-26-08__eg.az.fridge_Pwr__power 56.37 2017-11-22 18:33:50
2017-11-22_18-26-38__eg.az.fridge_Pwr__power 43.22 2017-11-22 18:33:50
2017-11-22_18-29-04__eg.az.fridge_Pwr__power 50.92 2017-11-22 18:33:50
2017-11-22_18-31-16__eg.az.fridge_Pwr__power 50.12 2017-11-22 18:33:50
</pre>

== Auswertungsroutine "switchontime" ==

Die nachfolgende Auswertungsroutine wird z.B. in der Datei 99_myOntimeUtils.pm gespeichert. Der Code ist mit Kommentaren angereichert um den Ablauf der Auswertung verständlich darzustellen und dadurch eine abgewndelte Nutzung in eigenen Projekten zu erleichtern.

Den Code in die Datei kopieren:

<syntaxhighlight lang="perl">
############################################################################
# $Id: myUtilsTemplate.pm 7570 2015-01-14 18:31:44Z rudolfkoenig $
# Beispiel aus https://wiki.fhem.de/wiki/Summe_aller_Einschaltzeiten_eines_Ger%C3%A4tes

package main;

use strict;
use warnings;
use Time::Local;

sub
myOntimeUtils_Initialize($$)
{
my ($hash) = @_;
}

############################################################################################################
## Ermitteln der Einschaltzeiten eines Gerätes
############################################################################################################
# Im DbRep-Device ist das Attribut "userExitFn = switchontime" zu setzen.
# Auswertung wird im DbRep gestartet mit:
#
# set <DbRep-Device> fetchrows history
#
# Die resultierende Switch-on Zeit wird im aufrufenden DbRep-Device in Readings dargestellt:
# switch_on_time -> on-Zeit als formatierte Angabe hhh:mm:ss
# switch_on_time_sec -> on-Zeit als Sekundenwert
#
# Die Routine ist für alle Readings geeignet die Zahlenwerte als Switch-on/off Zustand beinhalten.
# Switch-off = 0
# Swich-off != 0
#
# Nach der Erstellung jedes einzelnen Readings wird die im Attribut "userExitFn" hinterlegte Funktion
# aufgerufen. Es wird der Devicename des aufrufenden Device, Reading und Wert des Readings übergeben.
# Der Aufrufablauf ist:
# 1. Start: state = running
# 2. Übermittlung jedes generierten Readings
# 3. Stop: state = done (bzw. nicht running)
#
###########################################################################################################
my $t = 0; # Variable für resultierende Sekunden
my $sekunden = 0; # Variable für sekunden des Readings
my $startzeit = 0; # Variable für Beginn des Zeitraums
my $endzeit = 0; # Variable für Ende des Zeitraums
my $letztervalue = 0; # Variable für Value des vorherigen Readings
my $letztersekunden = 0; # Variable für Sekunde des vorherigen Readings
my $initvalue = 0;
my $pattern = "Ttim__state"; # verwendbarer Teilstring des Switch-on/Switch-off Werte
# enthaltenden Readings (entsprechend anpassen !)
my $runde;

sub switchontime($$$)
{
my ($name,$reading,$value) = @_;
my $hash = $defs{$name};
# $value = int $value; #schöner für Anzeigen

if($reading eq "state" && $value eq "running") # der Select wurde gestartet
{
$letztervalue = -1;
$runde = 0;
my ($devn,$devread) = split("__",$pattern); # den aktuellen Zustand des Devices ermitteln
$devread = uc ($devread);
$initvalue = InternalVal("$devn","$devread",99);
if ($initvalue == 99)
{
Log3 $name, 1, "$name - der Patternname scheint falsch zu sein";
}

my $jetzt = TimeNow(); # aktuelle Zeit = Ende des Abfragezeitraums ermitteln

my $lstr = (split("__",$jetzt))[0];
my ($year, $month, $day, $hour, $min, $sec) = ($lstr =~ /(\d+)-(\d+)-(\d+) (\d+):(\d+):(\d+)/);
# Umwandeln in Epochesekunden

$endzeit = timelocal($sec, $min, $hour, $day, $month-1, $year-1900);
$startzeit = $endzeit - AttrVal("Rep.powerOnTime","timeDiffToNow",98); # Beginn des Abfragezeitraums ermitteln

Log3 $name, 3, "$name - UserExitFn \"ontime\" has been called.";
($sec,$min,$hour) = localtime($startzeit);
Log3 $name, 3, "Start der Abfrage $startzeit $hour:$min:$sec";
($sec,$min,$hour) = localtime($endzeit);
Log3 $name, 3, "Ende der Abfrage $endzeit $hour:$min:$sec";

$t = 0;
return;
}
$runde = $runde +1;
if($reading =~ /$pattern/) # den Timestamp unabhängig vom Status festhalten
{
my $lstr = (split("__",$reading))[0];
my ($year, $month, $day, $hour, $min, $sec) = ($lstr =~ /(\d+)-(\d+)-(\d+)_(\d+)-(\d+)-(\d+)/);
# Umwandeln in Epochesekunden
$sekunden = timelocal($sec, $min, $hour, $day, $month-1, $year-1900);
Log3 $name, 4, "t:$t s:$sekunden value:$value $hour:$min:$sec ";

if($letztervalue == -1) # wenn jüngster Wert (erstes reading)
{
if($value != 0) # an
{
$t = $endzeit;
}
}
if ($value == $letztervalue)
{
Log3 $name, 2, "$name - Ein value ist doppelt";
}
if( $value != 0 && $value != $letztervalue) # Gerät wurde eingeschaltet
{
$t = $t - $sekunden;
}
if($value == 0 && $value != $letztervalue) # Gerät wurde ausgeschaltet
{
$t = $t + $sekunden;
}

# Value sichern für endberechnung und doppelte Werte
$letztervalue = $value;
$letztersekunden = $sekunden;
}
if($reading eq "state" && $value ne "running") # die Selektion ist beendet, Summensekunden in Format hhh:mm:ss umwamdeln
{
if ($letztervalue == 0) # am Ende der Auswertung ist Status immer noch switch-on
{
$t = $t - $startzeit;

}
if ($letztervalue == -1) #wenn keine Werte kamen
{
if( $initvalue != 0 ) # Gerät ganze Zeit an
{
$t = AttrVal("Rep.powerOnTime","timeDiffToNow",98);
Log3 $name, 5, "Gerät ganze Zeit an";
}
if($initvalue == 0 ) # Gerät ganze Zeit aus
{
$t = 0;
Log3 $name, 5, "Gerät ganze Zeit an";
}
}

my $ut = $hash->{".updateTime"};
$hash->{".updateTime"} = 0;
fhem("setreading $name switch_on_time_sec $t");

my $m = int $t/60;
my $s = $t - ($m*60);
my $h = int $m/60;
$m = $m - ($h*60);
my $timestring = sprintf("%03d:%02d:%02d",$h,$m,$s);

fhem("setreading $name switch_on_time $timestring (hhh:mm:ss)");

Log3 $name, 3, "$name - switch-on time was $timestring (hhh:mm:ss)";
$hash->{".updateTime"} = $ut;
}

return;
}

1;
</syntaxhighlight>

Es werden zwei zusätzliche Readings im Device Rep.powerOnTime generiert, '''switch_on_time''' und '''switch_on_time_sec'''.
Das Reading '''switch_on_time_sec''' ist die summarische "EIN"-Zeit in Sekunden der letzten 24 Stunden und kann gut zur weiteren Auswertung genutzt werden.
'''switch_on_time''' ist eine in hhh:mm:ss formatierte Angabe des Readingswertes von '''switch_on_time_sec''' zur leichteren Lesbarkeit.

Natürlich kann man '''switch_on_time_sec''' wiederum loggen um z.B. daraus eine grafische Anzeige zu erstellen, die die Entwicklung der täglichen "EIN"-Zeiten über einen längeren Zeitraum darstellen könnte (z.B. Heizzeiten).

Mit kleinen Abwandlungen könnten zum Beispiel auch die täglichen Raumlüftungszeiten (Fenter "open", "closed") ausgewertet und überwacht werden.
Wird die vorgegeben "open"-Zeit unterschritten, könnte ein Alarm ausgelöst werden.

Wie üblich können die Auswertungszeitgrenzen durch die Zeit-spezifischen Attribute timestamp_begin, timestamp_end usw. den Anforderungen entsprechend abgeändert werden.

[[Kategorie:Code Snippets]]

SSCal - Integration des Synology Calendar Servers

2023-11-09T10:55:33Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Infobox Modul
|ModPurpose=Integration des Synology Calendar Servers
|ModType=d
|ModCmdRef=SSCal
|ModForumArea=Unterstützende Dienste
|ModTechName=57_SSCal.pm
|ModOwner=DS_Starter}}

= Zweckbeschreibung und Voraussetzungen =

Mit diesem Modul erfolgt die Integration des Synology Calendar Servers in FHEM. Die Verbindung zum Kalenderserver erfolgt über eine Session ID nach erfolgreichem Login. Anforderungen/Abfragen des Servers werden intern in einer Queue gespeichert und sequentiell abgearbeitet. Dadurch gehen Kalenderabfragen auch dann nicht verloren, wenn der Synology Kalender zeitweise nicht zur Verfügung stehen sollte.
Die Kalendereinträge werden im Klartext als Blockeinträge in den Readings aufgelistet.
Der Synology Calendar Server ist für den Synology Server Besitzer ein Teil einer private Cloud Lösung.

Es können sowohl Terminkalender (Events) als auch Aufgabenlisten (ToDo's) abgefragt und verarbeitet werden. Für diese verschiedenen Kalenderarten kann das Modul unterschiedliche Device-Models definieren, Model '''Diary''' für Terminkalender und Model '''Tasks''' für Aufgabenlisten.

Voraussetzung ist ein installiertes Calendar Package und ein Nutzerkonto mit der Zugehörigkeit zur Gruppe Administratoren auf der Synology DS.

Das Modul benötigt einige FHEM und Perl Standardmodule die installiert sein müssen. Die Commandref zum Modul enthält diese Angaben aktuell. Mit dem [https://fhem.de/commandref.html#Installer Installer-Modul] ist es ebenfalls möglich eventuell fehlende Perl-Module zu ermitteln und ggf. zu installieren.

<br>

= Definition eines Synology Kalenderdevices =

[[Datei:sscal1.PNG|right|thumb|200px|initiale Definition]]
Die Definition erfolgt mit:

define <Name> SSCal <Adresse Synology Server> [<Port>] [<Protokoll>] [Tasks]

* Port: Port der Synology Diskstation (default 5000)
* Protokoll: Protokoll zur Kommunikation mit dem Kalender-Server, http oder https (default http)
* Zusatz Tasks: definiert eine Aufgabenliste anstatt eines Terminkalenders

Die Angaben Port, Protokoll und Tasks sind optional. Der Zusatz '''Tasks''' definiert ein Aufgabenlisten-Device mit MODEL=Tasks. Per default wird ein Terminkalender-Device mit MODEL=Diary, Port=5000 und Protokoll=http erstellt.

'''Beispieldefinitionen:'''

define Appointments SSCal 192.168.2.10 # Terminkalender mit Standardport
define Calendar SSCal 192.168.2.10 5001 https # Terminkalender mit HTTPS-Protokoll
define Tasklist SSCAL ds.myds.org 5001 https Tasks # Aufgabenliste mit HTTPS-Protokoll

Nach der Definition des Devices gibt es zunächst nur den Set-Befehl '''credentials'''.
[[Datei:sscal2.PNG|right|thumb|300px|Kalenderabruf durchgeführt]]
Mit dem Befehl:

set <name> credentials <User> <Passwort>

ist im Kalender-Device der für den Kalenderzugriff verwendete Nutzer und dessen Paßwort zu speichern.

'''Hinweis:''' <br>
Der Nutzer '''muß''' Mitglied der Administrator-Group auf der Synology Diskstation sein und muß zusätzlich auch die entsprechend benötigte Berechtigung zum Lesen und/oder Schreiben des/der relevanten Kalender haben. Die Kalenderberechtigungen können direkt in der [https://www.synology.com/de-de/knowledgebase/DSM/help/Calendar/calendar_desc Synology Kalenderapplikation] eingestellt werden.

Sind die Credentials korrekt, werden die auf der Synology verfügbaren (und für den Nutzer freigegeben) Kalender automatisch abgerufen.
Dieser Vorgang ist durch den state '''running''' und dem OPMODE '''listcal''' in den Internals gekennzeichnet. Nach einem erfolgreichen Abruf, der am Anfang etwas länger dauern kann, springt der Status des Devices auf '''done'''. Damit ist das Kalenderdevice grundsätzlich einsatzbereit.

<br>

= Terminkalender und Aufgabenlisten auswählen und Einträge abrufen =

[[Datei:sscal3.PNG|right|thumb|300px|Popup von getCalendars]]
Nach der initialen Definition des Kalenderdevices müssen ein oder mehrere Kalender ausgewählt werden, deren Termine (Events) abgerufen werden sollen.
Welche Kalender vom Modul erkannt wurden, kann mit dem Befehl

get <name> getCalendars

ermittelt werden. Die angezeigte Liste enthält sowohl Terminkalender (Type Event) als auch Aufgabenkalender (Type ToDo).

Mit dem Attribut '''usedCalendars''' wählt man den/die relevanten Kalender über ein Popup aus. Alternativ kann dem nachfolgend ausgeführten '''calUpdate''' Befehl die abzurufende Kalenderliste direkt mitgegeben werden.

Ohne Änderung der Zeitabgrenzung werden die Termine 5 Tage vor und 5 Tage nach dem aktuellen Datum abgerufen. Um diese Zeitgrenzen zu verändern, werden die Attribute '''cutOlderDays''' bzw. '''cutLaterDays''' verwendet.

Mit dem Befehl:

set <name> calUpdate [Kalenderliste]

[[Datei:sscal4.PNG|right|thumb|300px|Kalendereinträge abgerufen]]
werden Terminkalendereinträge manuell abgerufen. Die optional anzugebende Kalenderliste ist eine durch Komma getrennte Liste von abzurufenden Kalendernamen. Die Kalendernamen können Leerzeichen enthalten, z.B.:

set <name> calUpdate Heikos Kalender,Abfall

Im Standard werden sowohl einmalige, als auch wiederkehrende Events abgerufen und dargestellt. Möchte man die wiederkehrenden Events vom Abruf ausschließen, muss das Attribut '''showRepeatEvent''' explizit auf '''false''' gestellt werden.

Mit dem Befehl '''calUpdate''' werden nur Kalender verarbeitet, die dem definierten Model, "Diary" oder "Tasks", entsprechen. Kalender abweichenden Typs werden ignoriert.

Aufgaben können Fälligkeitstermine enthalten. Sind diese enthalten, werden Aufgaben deren Fälligkeitstermine sich außerhalb der durch die Attribute '''cutOlderDays''' bzw. '''cutLaterDays''' festgelegten Zeitgrenzen befinden, gefiltert und nicht dargestellt.
[[Datei:sscal8.PNG|right|thumb|300px|Kalenderübersicht in Detailanzeige]]

[[Datei:sscal9.PNG|right|thumb|300px|Spalte "Map" mit GPS-Koordinaten Icon]]

Wurden Termin- bzw. Aufgabenlisten erfolgreich abgerufen, wird per default sowohl in der Raumansicht als auch in der Detailansicht eine Kalenderübersicht angezeigt. Mit den Attributen '''tableInRoom''' bzw. '''tableInDetail''' können diese Übersichten ausgeschaltet werden (setzen auf "0").

Ist in den Terminen ein GPS-Wert gespeichert, wird in der tabellarischen Terminübersicht per default ein Weltkugel-Icon angezeigt, vorausgesetzt man hat auch das Feld '''Map''' im Attribut '''tableFields''' mit ausgewählt. Ein "Klick" auf dieses Icon öffnet eine neue Browserseite mit den im Termin gespeicherten Koordinaten in Google Maps.

Alle Abrufaufgaben werden zunächst in eine Queue eingestellt, die sequentiell abgearbeitet wird. Sollte der Synology Kalender zum Beispiel während einer Wartung temporär nicht verfügbar sein, erfolgt eine Wiederholung der anstehenden Aufgaben nach einer gewissen Wartezeit. Diese Wartezeit vergrößert sich mit zunehmenden Fehlversuchen.

Wurde für eine Abrufaufgabe ein dauerhafter Fehler diagnostiziert, wird diese Aufgabe von der weiteren Abarbeitung ausgeschlossen und verbleibt zur Dokumentation in der Queue (siehe auch '''set <name> listSendqueue''').

Das Reading '''QueueLenth''' zeigt die aktuelle Queue-Länge an. Sollten die Einträge nicht auf "0" abgebaut werden, sollte mit

set <name> listSendqueue

die Queue aufgelistet und analysiert werden, durch welche Fehlerzustände die verbliebenen Einträge nicht abgearbeitet werden konnten.

<br>
== non-blocking Verarbeitung ==

Das Kalendermodul ist non-blocking implementiert. In der Definition des Devices sollte die IP-Adresse der Synology Diskstation angegeben werden. Wird statt dessen ein DNS-Name verwendet, ist darauf zu achten im global Device einen validen DNS-Server im Attribut '''dnsServer''' zu hinterlegen.

In Abhängigkeit der Menge abgerufener Kalender und Termine kann allerdings die Aufbereitung der Daten sehr aufwändig sein und FHEM dennoch blockieren.
Um das zu verhindern, kann das Parsing der Kalenderdaten in einen Hintergrundprozess verlagert werden. Dazu ist das Attribut '''asyncMode=1''' zu setzen.

<br>
== regelmäßiger automatischer Datenabruf ==

Über das Attribut '''interval''' wird ein regelmäßigen Abruf der Kalendereinträge ermöglicht.
Es sind die Sekunden zwischen den Abrufen anzugeben. Mit '''0''' wird der automatische Datenabruf ausgeschaltet. Gleiches gilt wenn das Attribut wieder gelöscht wird.

Im Reading '''nextUpdate''' wird der Modus "Automatic" und die Zeit des nächsten Abrufes dargestellt, z.B.:

nextUpdate Automatic - next polltime: 09:49:59

<br>

== FHEM Eventgenerierung und Empfehlung zu Attributen ==

Je nach Umfang der abgerufenen Daten können sehr viele Readings erstellt werden. Um eine zu umfangreiche Eventgenerierung in FHEM zu verhindern, ist nach der Definition des Kalenderdevices das Attribut '''event-on-update-reading''' voreingestellt auf:

attr <SSCal-Device> event-on-update-reading .*Summary.*,state

Es werden demzufolge nur Events für die Terminzusammenfassung und für state erzeugt. Der User kann die Einstellung natürlich seinen Erfordernissen entsprechend anpassen.
Sollen Events für alle Readings erstellt werden, muss '''event-on-update-reading''' auf '''.*''' eingestellt werden.

Nach dem Abruf von Terminen oder Aufgaben wird per default eine tabellarische Übersicht sowohl in der Raumsicht als auch in der Datailansicht erstellt. Will man diese Übersichten abschalten, sind dazu die Attribute '''tableInRoom''' bzw. '''tableInDetail''' explizit auf "0" zu setzen.

Empfehlung für das Setzen des Attributs '''stateFormat''':
<pre>
attr <SSCal-Device> stateFormat <b>Status:</b> done - <b>Last Update</b>: 2020-02-02 19:57:47 - <b>Next Update</b>: Automatic - next polltime: 20:57:46
</pre>

Für die Funktionen des Moduls ist die UID eines Events nicht notwendig. Somit wird das Reading x_x_IcalUID nicht benötigt.

<pre>
attr <SSCal-Device> suppressReading .*_95_IcalUID
</pre>

<br>

= Schema der erzeugten Readings =

Die Termine der abgerufenen Kalender werden in Blöcken erzeugt.
Jeder Block steht für einen Termin, dessen einzelne Eigenschaften mit einer laufenden Nummer vor dem Readingnamen gekennzeichnet sind.

Diese laufende Nummer ist für den jeweiligen Readingnamen immer gleich. Da es für einen Termin eine oder auch mehrere Erinnerungstermine geben kann, wird das Reading '''notifyDateTime''' zusätzlich von einem laufenden Index angeführt.
[[Datei:sscal5.PNG|right|thumb|500px|Schema der Readings]]

Das allgemeine Schema der erzeugten Readings ist:

<Blocknummer>_<Readingnummer>_<Readingname>

Zum Beispiel für die Anfangszeit und Endezeit eines Termins:

0_02_Begin 2020-01-15 09:30:00
0_03_End 2020-01-15 10:30:00

Das Reading '''notifyDateTime''' wird noch um einen Index ergänzt:

<Blocknummer>_<Readingnummer>_<Index>_<notifyDateTime>

Zum Beispiel:

0_14_0_notifyDateTime 2020-01-15 09:25:00
0_14_1_notifyDateTime 2020-01-15 03:30:00
0_14_2_notifyDateTime 2020-01-14 09:30:00
0_14_3_notifyDateTime 2020-01-12 09:30:00
0_14_4_notifyDateTime 2020-01-11 09:30:00

<br>

= Set-Befehle =

; calUpdate: Die Einträge der ausgewählten Kalender werden abgerufen. Die relevanten Kalender werden im Attribut usedCalendars angegeben. Alternativ können ein oder mehrere Kalender als eine durch Komma getrennte Liste dem Befehl direkt übergeben werden, z.B.:

::: set <name> calUpdate Heikos Kalender,Abfall

: Die Kalendernamen können Leerzeichen enthalten. Welche Kalender erkannt wurden, kann mit dem Befehl

::: get <name> getCalendars

: ermittelt werden. Es werden nur die Kalender abgerufen, deren Typ zum Model des SSCal-Devices passen. D.h. ist das Model '''Diary''', werden Kalender vom Typ '''Event''' verarbeitet und das Model '''Tasks''' verarbeitet Kalender des Typs '''ToDo'''.

; cleanCompleteTasks (nur Model "Tasks"): In den selektierten Aufgabenlisten (siehe Attribut usedCalendars) werden alle abgeschlossenen Aufgaben gelöscht.

; deleteEventId: die angegebene Event Id (siehe Reading x_x_EventId) wird aus dem Kalender bzw. der Aufgabenliste gelöscht. Die aktuell ermittelten Event Id's werden über eine Drop-Down Liste zur Auswahl bereitgestellt.

; credentials: Speicherung der Zugangsdaten.
::: set <name> credentials User Passwort

; eraseReadings: Löscht alle Kalenderreadings

; listSendqueue: Zeigt alle Einträge in der Sendqueue. Die Queue ist normalerweise nur kurzfristig gefüllt, kann aber im Problemfall dauerhaft Einträge enthalten. Dadurch kann der bei der jeweiligen Abrufaufgabe aufgetretene Fehler ermittelt werden.

; logout: Der User wird ausgeloggt und die Session beendet

; purgeSendqueue: löscht Einträge in der Sendequeue. Es stehen verschiedene Optionen ja nach Situation zur Verfügung:
::: -all- = löscht alle in der Sendequeue vorhandenen Einträge
::: -permError- = löscht alle Einträge, die durch einen permanenten Error von der weiteren Verarbeitung ausgeschlossen sind
::: -<Index>- = löscht einen eindeutigen Eintrag der Sendequeue

; restartSendqueue: Die Abarbeitung der Einträge in der Sendequeue wird manuell neu angestoßen. Dies ist normalerweise nicht notwendig. Die Sendequeue wird bei der Initialisierung jeder neuen Aufgabe implizit neu gestartet.

<br>

= Get-Befehle =

[[Datei:sscal7.PNG|right|thumb|300px|get calAsHtml Popup]]
;apiInfo: Ruft die API Informationen des Synology Calendars ab und öffnet ein Popup mit diesen Informationen.

;calAsHtml: Zeigt ein Popup mit einer Übersicht der Termine/Aufgaben. In eigenen Perl-Routinen (z.B. bei Einbindung in weblink) kann die Übersicht abgerufen mit:
::: { SSCal_calAsHtml ("<SSCal-Device>") }

;getCalendars: Ruft die auf der Synology vorhandenen Kalender ab und öffnet ein Popup mit Informationen über die jeweiligen Kalender.

;storedCredentials: zeigt die gespeicherten User/Passwort Kombination

;versionNotes: Zeigt Informationen und Hilfen zum Modul

<br>

= Attribute =

;asyncMode: wenn "1" wird das Datenparsing in einen Hintergrundprozess ausgelagert und vermeidet Blockierungssituationen

;createATDevs: wenn "1" werden bei der Erkennung von FHEM-Kommandos bzw. auszuführenden Perl-Routinen im Kalendereintrag durch SSCal automatisiert at-Devices zur termingerechten Ausführung dieser Kommandos erstellt, geändert und gelöscht. Lesen sie bitte dazu die detailliierte Beschreibung im Abschnitt [[SSCal - Integration des Synology Calendar Servers#at-Devices für Steuerungen automatisch erstellen und verwalten lassen | at-Devices für Steuerungen automatisch erstellen und verwalten lassen]]

;cutOlderDays: Terminkalendereinträge und Aufgabenkalendereinträge mit Fälligkeitstermin älter als die angegeben Tage werden von der Verarbeitung ausgeschlossen (default: 5)
::: attr <name> cutOlderDays 30

;cutLaterDays: Terminkalendereinträge und Aufgabenkalendereinträge mit Fälligkeitstermin später als die angegeben Tage werden von der Verarbeitung ausgeschlossen (default: 5)
::: attr <name> cutLaterDays 90

;filterCompleteTask (nur Model "Tasks"): Es werden Einträge in Aufgabenkalendern entsprechend der Fertigstellung gefiltert:
::: 1 = nur fertig gestellte Aufgaben werden angezeigt
::: 2 = nur nicht fertige Aufgaben werden angezeigt
::: 3 = es werden fertige und nicht fertige Aufgaben angezeigt (default)

;filterDueTask (nur Model "Tasks"): Es werden Einträge in Aufgabenkalendern mit/ohne Fälligkeit gefiltert:
::: 1 = nur Einträge mit Fälligkeitstermin werden angezeigt
::: 2 = nur Einträge ohne Fälligkeitstermin werden angezeigt
::: 3 = es werden Einträge mit und ohne Fälligkeitstermin angezeigt (default)

;interval: Automatischer Abrufintervall der Kalendereintträge in Sekunden. Ist "0" agegeben, wird kein automatischer Datenabruf ausgeführt. Soll jede Stunde die Einträge der gewählten Kalender abgerufen werden, wird das Attribut wie folgt gesetzt:
::: attr <name> interval 3600

;loginRetries: Anzahl der Versuche für das inititiale User login (default: 3)

;showRepeatEvent (nur Model "Diary"): Wenn "true", werden neben einmaligen Terminen ebenfalls wiederkehrende Termine ausgewertet. (default: true)

;showPassInLog: Wenn "1", wird das Passwort bzw. die SID im Log mit angezeigt. (default: 0)

;tableColumnMap: Legt fest, wie der Link zur Karte in der Tabellspalte "Map" bzw. "Karte" gestaltet wird.
::: icon - es wird ein durch den User anpassbares Symbol angezeigt (default)
::: data - es werden die GPS-Daten angezeigt
::: text - es wird ein durch den Nutzer einstellbarer Text verwendet

Der Nutzer kann weitere Anpassungen des verwendeten Icons oder Textes in den Eigenschaften des Attributs "tableSpecs" vornehmen. Siehe dazu Kapitel [[SSCal_-_Integration_des_Synology_Calendar_Servers#Darstellung_der_.C3.9Cbersichtstabelle_in_Raum-_und_Detailansicht_beeinflussen | Darstellung der Übersichtstabelle in Raum- und Detailsicht beeinflussen]]

;tableInDetail: Eine Termin/Aufgabenübersicht wird in der Detailansicht erstellt (default: 1) bzw. ausgeschaltet (0).

;tableInRoom: Eine Termin/Aufgabenübersicht wird in der Raumansicht erstellt (default: 1) bzw. ausgeschaltet (0).

;tableFields: Auswahl der in der Termin/Aufgabenübersicht (Raum- bzw. Detailansicht) anzuzeigenden Felder über eine Drop-Down Liste

;tableSpecs: Über verschiedene Schlüssel-Wertpaar Kombinationen kann die Darstellung der Informationen in der Übersichtstabelle angepasst werden. Das Kapitel [[SSCal_-_Integration_des_Synology_Calendar_Servers#Darstellung_der_.C3.9Cbersichtstabelle_in_Raum-_und_Detailansicht_beeinflussen | Darstellung der Übersichtstabelle in Raum- und Detailsicht beeinflussen]] liefert detailiierte Informationen dazu.

;timeout: Timeout für den Datenabruf in Sekunden. (default: 20)

;usedCalendars: Auswahl der abzurufenden Kalender über ein Popup. Die Liste der Kalender wird beim Start des Moduls initial gefüllt, kann danach aber ebenfalls durch den Befehl "get <name> getCalendars" manuell ausgeführt werden. Wurde noch kein erfolgreicher Kalenderabruf ausgeführt, enthält dieses Attribut lediglich den Eintrag
::: --wait for Calendar list--

<br>

= Darstellung der Übersichtstabelle in Raum- und Detailansicht beeinflussen =

Im Standard wwird sowohl in der Raum- als auch Detailansicht eine Tabelle mit den aktuell abgerufenen Terminen bzw. Aufgaben angezeigt. Die verwendeten Spalten der Tabelle sind vorbelegt, können aber durch das Attribut:

attr <Device> tableFields

verändert werden. Es wird eine Drop-Down-Liste mit einer Auswahl der möglichen Tabellenfelder bereitgestellt.

Das Attribut '''tableSpecs''' besteht aus Schlüssel-Wert Paaren, die in '''{ }''' eingeschlossen werden müssen und miteinander kombiniert sein können.
Weiterhin können Schlüssel auch Subschlüssel enthalten, die ebenfalls in '''{ }''' eingeschlossen werden. In den nachfolgenden Beispielen wird die Verwendung vorgestellt.

== Allgemeine Gestaltung des Tabellenheaders und der Spalten ==

<br>
Mit den Subschlüsseln '''noHeader''' => 1 kann die Headerzeile der Tabelle ausgeschaltet werden. Der Subschlüssel '''headerAlign''' dient der Ausrichtung der Headerspalten und '''columnAlign''' der Ausrichtung der Inhaltsspalten.

{| class="wikitable"
! Inhalt Attribut tableSpecs: <br> Allgemeine Gestaltung des Tabellenheaders und der Spalten !! Erläuterungen !! Aussehen
|-
| style="width:55%" |
<pre>
{
"cellStyle" => {
"noHeader" => "1",
"headerAlign" => "center",
"columnAlign" => "left",
},
}
</pre>
| '''noHeader 1''' verbirgt die Headerzeile, '''noHeader 0''' zeigt sie an (Standard). Die Subschlüssel '''headerAlign''' und '''columnAlign''' können die Werte left, center und right annehmen und dienen der Ausrichtung der Spalten im Header bzw. Body der Tabelle.

Der Subschlüssel '''columnAlign''' legt zunächst die Ausrichtung für alle Spalten des Tabellbodys fest. Die Spaltenausrichtung kann aber zusätzlich für jede Spalte spezifisch eingestellt werden, wie im nachfolgenden Beispiel gezeigt.
| [[Datei:sscal25.PNG|200px]]
|-
|
<pre>
{
"cellStyle" => {
"noHeader" => "0",
"headerAlign" => "center",
"columnAlign" => "left",
"columnSymbolAlign" => "center",
"columnDaysLeftAlign" => "center",
},
}
</pre>
| Die '''Ausrichtung''' jeder Spalte kann '''separat''' erfolgen. Die Subschlüssel dafür heißen '''column<Spaltenname>Align'''. Demzufolge betreffen die im Beispiel dargestellten Subschlüssel '''columnSymbolAlign''' und '''columnDaysLeftAlign''' die Spalten '''Symbol''' sowie '''DaysLeft''' und werden abweichend von Standard zentriert dargestellt. Die Werte können '''left''', '''center''' oder '''right''' sein.

Die weiteren Subschlüssel zur Ausrichtung der Spalten heißen dementsprechend:

{| class="wikitable"
|-
| columnBeginAlign
| columnEndAlign
|-
| columnDaysLeftLongAlign
| columnWeekdayAlign
|-
| columnTimezoneAlign
| columnSummaryAlign
|-
| columnDescriptionAlign
| columnStatusAlign
|-
| columnCompletionAlign
| columnLocationAlign
|-
| columnMapAlign
| columnCalendarAlign
|-
| columnEventIdAlign
|
|}

| [[Datei:sscal26.PNG|200px]]
|}

<br>
== Gestaltung der Spalte "Map" bzw. "Karte" ==

In der Spalte '''Map''' bzw. '''Karte''' wird bei Vorhandensein von GPS-Daten ein Link zur Karte von '''Google Maps''' (default) oder '''OpenStreetMap''' angeboten.
Die Auswahl, welcher Kartenprovider verwendet werden soll, erfolgt über den Schlüssel '''columnMapProvider''' im Attribut '''tableSpecs'''.
Der Wert in der Spalte Map kann als Icon (default), Text oder der GPS-Daten selbst dargestellt werden. Das Attribut '''tableColumnMap''' legt fest, wie der Wert dargestellt wird:

attr <Device> tableColumnMap <icon | data | text>

Über folgende Schüssel wird das verwendete Icon bzw. ein eigener Link-Text festgelegt und der Kartenprovider ausgewählt:

{| class="wikitable"
! Inhalt Attribut tableSpecs: <br> Gestaltung Spalte "Map" !! Erläuterungen !! Aussehen
|-
| style="width:45%" |
<pre>
{
"columnMapIcon" => "rc_WEB",
"columnMapText" => "Hier gehts zur Karte",
"columnMapProvider" => "GoogleMaps",
}
</pre>
| Der Icon-Dateiname im Schlüssel '''columnMapIcon''' wird ohne Endung angegeben. Im Schlüssel '''columnMapProvider''' kann "OpenStreetMap" oder "GoogleMaps" enthalten sein.
| [[Datei:sscal10.PNG|200px]]
|-
| style="width:45%" |
<pre>
{
"columnMapIcon" => "rc_WEB@red",
"columnMapText" => "Hier gehts zur Karte",
"columnMapProvider" => "GoogleMaps",
}
</pre>
| Das Icon kann eingefärbt werden. Entweder mit der Farbangabe hinter '''@''' oder dem Farbcode wie '''@#DF0101'''
| [[Datei:sscal11.PNG|200px]]
|-
|
<pre>
{
"columnMapIcon" => {
"Status" => "eq 'ended' ",
"icon" => "rc_WEB@grey",
},
"columnMapProvider" => "GoogleMaps",
}
</pre>
| Das Icon wird in "rc_WEB geändert und grau eingefärbt, wenn eine zweite Bedingung wahr ist. Der Schlüssel der zweiten Bedingung ist ein Readingname ohne Block- und Readingnummer gefolgt von einer Bedingung ("eq") und einem Wert ("ended") auf den geprüft wird.
Ist die Bedingung unwahr, wird das Standardicon eingefügt.
| [[Datei:sscal12.PNG|200px]]
|-
|
<pre>
{
"columnMapIcon" => [
{
"Status" => "eq 'ended' ",
"icon" => "rc_WEB@grey",
},
{
"Status" => "eq 'upcoming' ",
"icon" => "rc_WEB@red",
}
],
"columnMapText" => "Hier gehts zur Karte",
}
</pre>
| Es können mehrere Bedingungen angegeben werden. Diese werden in Gruppen angegeben. Die Gruppen werden von oben nach unten abgearbeitet. Ist eine Gruppe wahr, wird der Wert im Schlüssel "icon" zurück gegeben.

'''Hinweis:''' Eine Gruppe ist in '''[ ]''' einzufügen.

Es können je Gruppe weitere Bedingungen hinzugefügt werden, die alle "wahr" sein müssen um das in dieser Gruppe eingetragene Icon zurück zu geben. Der Schlüssel der Bedingung ist immer ein Readingname ohne Block- und Readingnummer gefolgt von einer Bedingung und dem Wert zum Vergleich. Zum Beispiel "daysLeft" wenn das Reading "x_x_daysLeft" ausgewertet werden soll. Das Modul übernimmt selbstständig die korrekte Zuweisung des Readings im aktuellen Block.

| [[Datei:sscal13.PNG|200px]]
|}

Mit dem Schlüssel '''columnMapText''' wird ein eigener Text für den Karten-Link in Spalte Map hinterlegt. Damit der Text anstatt eines Icon dargestellt wird, schaltet man diese Option mit dem Attribut

attr <Device> tableColumnMap text

ein. Im Schlüssel columnMapText können verschiedene vordefinierte Variablen verwendet werden:

$NAME - der Name des SSCal-Devices
$BNR - Blocknummer eines Readings
$we - siehe holiday2we
$hms - Zeit im sprintf-Format "hh:mm:ss"

$sec, $min, $hour, $mday, $month, $year, $wday, $yday, $isdst - siehe Perl localtime

Der Schlüssel wird dann wie folgt definiert:

{| class="wikitable"
! Inhalt Attribut tableSpecs: <br> Gestaltung Spalte "Map" als Text !! Erläuterungen !! Aussehen
|-
| style="width:50%" |
<pre>
{
"columnMapText" => "Hier gehts zur Karte",
"columnMapProvider" => "OpenStreetMap",
}
</pre>
| Der Text im Schlüssel "columnMapText" wird als Linktext in der Spalte "Map" verwendet.
| [[Datei:sscal14.PNG|200px]]
|-
|
<pre>
{
"columnMapText" => "{ ReadingsVal('$NAME', '$BNR_35_Location','') }",
"columnMapProvider" => "OpenStreetMap",
}
</pre>
| Im Schlüssel "columnMapText" kann eine Perl-Routine (eingeschlossen in '''{ }''') hinterlegt werden, die einen Text zurückliefert. In diesem Beispiel wird als Linktext der Inhalt des Readings '''Location''' benutzt und wird als anklickbaren Text in der Spalte "Map" angezeigt. Die "35" vor dem Readingnamen "Location" ist die Readingnummer (siehe Kapitel [[SSCal - Integration des Synology Calendar Servers#Schema der erzeugten Readings | Schema der erzeugten Readings]]).
| [[Datei:sscal15.PNG|200px]]
|}

<br>

== Gestaltung der Spalte "Days left" bzw. "Resttage" ==

<br>
Die Spalte "Resttage" zeigt die verbleibende Zeit bis zum Eintritt des Termins. Ist der Termin beendet bzw. in der Vergangenheit, bleibt diese Spalte leer.

Um diese Spalte als Icon darzustellen, wird der Schlüssel '''columnDaysLeftIcon''' verwendet. Es können mehrere Subschlüssel angewendet werden die logisch durch '''und''' verknüpft sind. D.h. alle Bedingungen der Subschlüssel müssen wahr werden damit die Gruppe wahr wird.

Dabei können mehrere Gruppen von Subschlüsseln verwendet werden um abhängig von unterschiedlichen Readingwerten das resultierende Icon zu wählen oder einzufärben.

{| class="wikitable"
! Inhalt Attribut tableSpecs: <br> Gestaltung Spalte "Resttage" als Icon !! Erläuterungen !! Aussehen
|-
| style="width:55%" |
<pre>
{
"columnDaysLeftIcon" => {
"Summary" => "=~ /[Tt]onne|Restabfall/",
"Status" => "ne 'ended' ",
"icon" => "Tonne_green",
},
}
</pre>
| Der Text im Reading "x_x_Summary" wird ausgewertet und ergibt '''wahr''' wenn er "Tonne" oder "tonne" oder "Reastabfall" im String trägt.
Der Inhalt des Readings "x_x_Status" muß ungleich "ended" sein damit diese Auswertung '''wahr''' wird.

Beide Bedingen müssen '''wahr''' sein, damit das angegeben "Icon" in der Spalte angezeigt wird. Deswegen wird in den ersten zwei Zeilen der Tabelle kein Tonnen-Icon eingefügt.
| [[Datei:sscal16.PNG|200px]]
|-
|
<pre>
{
"columnDaysLeftIcon" => [
{
"Summary" => "=~ /Gelbe Tonne/",
"icon" => "dustbin@#DF7401",
},
{
"Summary" => "=~ /Biotonne/",
"icon" => "dustbin@brown",
},
{
"Summary" => "=~ /Restabfall/",
"icon" => "dustbin@black",
},
{
"Summary" => "=~ /Papier/",
"icon" => "dustbin@blue",
},
{
"Status" => "=~ /ended/",
"icon" => "dustbin@grey",
},
],
}
</pre>
| Der Schlüssel '''columnDaysLeftIcon''' kann einen oder mehrere Subschlüssel enthalten.
Mehrere Subschlüssel werden wie hier dargestellt als Gruppe zusammengefasst und in [ ] eingeschlossen. Im Beispiel wird der Text im Reading "x_x_Summary" ausgewertet und wenn die Bedingung zutrifft das Icon und dessen Farbe entsprechend gesetzt.

Die Gruppen werden von oben nach unten abgearbeitet. Die letzte "wahre" Gruppe siegt.
| [[Datei:sscal17.PNG|200px]]
|-
|
<pre>
{
"columnDaysLeftIcon" => [
{
"Status" => "!~ /ended/ ",
"daysLeft" => ">= 2",
"icon" => "10px-kreis-gruen",
},
{
"Status" => "!~ /ended/ ",
"daysLeft" => ">= 16",
"icon" => "10px-kreis-gelb",
},
{
"Status" => "!~ /ended/ ",
"daysLeft" => ">= 30",
"icon" => "10px-kreis-rot",
},
]
}
</pre>
| Der Schlüssel '''columnDaysLeftIcon''' kann einen oder mehrere Subschlüssel enthalten.
Mehrere Subschlüssel werden wie hier dargestellt als Gruppe zusammengefasst und in [ ] eingeschlossen. Im Beispiel werden die Inhalte der Readings "x_x_Status" und "x_x_dayLeft" ausgewertet.

Wenn alle zwei Bedingungen '''wahr''' sind, wird die jeweilige Gruppe '''wahr''' und das angegebene Icon in der Spalte angezeigt.

Die Gruppen werden von oben nach unten abgearbeitet. Die letzte "wahre" Gruppe siegt.
| [[Datei:sscal18.PNG|200px]]
|}

<br>

== Gestaltung der Spalte "State" bzw. "Status" ==

<br>
Die Spalte "Status" zeigt den aktuellen Status eines Termins an. Abhängig davon sowie den Inhalten weiterer Readings kann in dieser Spalte ein Icon anstatt des Statustextes angezeigt werden.

Um diese Spalte als Icon darzustellen, wird der Schlüssel '''columnStateIcon''' verwendet. Es können mehrere Subschlüssel angewendet werden die logisch durch '''und''' verknüpft sind. D.h. alle Bedingungen der Subschlüssel müssen wahr sein damit die Gruppe wahr wird.

Dabei können mehrere Gruppen von Subschlüsseln verwendet werden, um abhängig von unterschiedlichen Readingwerten das resultierende Icon zu wählen oder einzufärben.

{| class="wikitable"
! Inhalt Attribut tableSpecs: <br> Gestaltung Spalte "Status" als Icon !! Erläuterungen !! Aussehen
|-
| style="width:55%" |
<pre>
{
"columnStateIcon" => [
{
"Status" => "eq 'ended' ",
"icon" => "ios-off",
},
{
"Status" => "eq 'upcoming' ",
"icon" => "ios-on-for-timer-green",
},
{
"Status" => "eq 'upcoming' ",
"daysLeft" => ">= 4",
"icon" => "ios-on-for-timer-blue",
},
],
}
</pre>
| Der Inhalt des Readings "x_x_Status" wird ausgewertet und abhängig von dessen Inhalt das Icon bestimmt.

In der untersten Gruppe muß außerdem der Inhalt von "x_x_daysLeft" größer/gleich "4" sein damit diese Gruppe '''wahr''' wird.

Alle Bedingungen in einer Gruppe müssen '''wahr''' sein, damit das angegebene "Icon" in der Spalte angezeigt wird. Die Gruppen werden der Reihe nach von oben nach unten ausgewertet. Die letzte '''wahre''' Gruppe gewinnt und deren Icon wird dargestellt.

'''Hinweis:''' Gruppen werden immer in '''[ ]''' eingeschlossen.
| [[Datei:sscal19.PNG|200px]]
|}

<br>
== Gestaltung der Spalte "Symbol" ==

<br>
Sofern man mit dem Attribut '''tableFields''' die Spalte '''Symbol''' mit auswählt, wird in der tabellarischen Übersicht jede Tabellenzeile von einem Standardicon angeführt. Das Standardicon ist abhängig vom Internal MODEL des Kalenders, d.h. ob es sich um einen Terminkalender oder eine Aufgabenliste handelt.

Dieses Standardicon kann mit dem Schlüssel '''columnSymbolIcon''' den persönlichen Bedürfnissen entsprechend angepasst werden.

{| class="wikitable"
! Inhalt Attribut tableSpecs: <br> Gestaltung der Spalte "Symbol" !! Erläuterungen !! Aussehen
|-
| style="width:55%" |
<pre>
{
"columnSymbolIcon" => "time_manual_mode",
}
</pre>
| Mit einer einfachen Schlüssel - Wert Zuweisung kann das Ico geändert werden.
| [[Datei:sscal22.PNG|200px]]
|-
|
<pre>
{
"columnSymbolIcon" => [
{
"Weekday" => "eq 'Montag' ",
"icon" => "edit_numeric_1",
},
{
"Weekday" => "eq 'Dienstag' ",
"icon" => "edit_numeric_2",
},
{
"Weekday" => "eq 'Mittwoch' ",
"icon" => "edit_numeric_3",
},
{
"Weekday" => "eq 'Donnerstag' ",
"icon" => "edit_numeric_4",
},
{
"Weekday" => "eq 'Freitag' ",
"icon" => "edit_numeric_5",
},
{
"Weekday" => "eq 'Samstag' ",
"icon" => "edit_numeric_6",
},
{
"Weekday" => "eq 'Sontag' ",
"icon" => "edit_numeric_7",
},
],
}
</pre>
| Durch die Auswertung des Readings "x_x_Weekday" wird in diesem Beispiel die Zeile des Kalendereintrags in der Spalte '''Symbol''' nummeriert.
Die Bedingung in einer Gruppe muß '''wahr''' sein, damit das angegebene "Icon" in der Spalte angezeigt wird. Die Gruppen werden der Reihe nach von oben nach unten ausgewertet.

'''Hinweis:''' Gruppen werden immer in '''[ ]''' eingeschlossen.
| [[Datei:sscal23.PNG|200px]]
|}

<br>

== Optimierung der Tabelle für smallscreen Styles ==

<br>
Für bestimmte Styles ist es sinnvoll die Tabellengestaltung flexibel zu gestalten, sodass z.B. Spalten umgebrochen werden können um Platz zu sparen. In dem Schlüssel '''smallScreenStyles''' wird hinterlegt, für welche Styles die optimierte Anpassung gelten soll.

{| class="wikitable"
! Inhalt Attribut tableSpecs: <br> Optimierung der Tabelle für Smallscreen Styles !! Erläuterungen !! Aussehen
|-
| style="width:55%" |
<pre>
{
"smallScreenStyles" => "darksmallscreen,smallscreen,default",
}
</pre>
| Es wird als Schlüsselwert eine durch Komma getrennte Liste der Styles eingetragen, für eine optimierte Anpassung der Tabelle vorgenommen werden soll.
| [[Datei:sscal20.PNG|200px]]
|}

<br>
== Beispiele mit Kombinationen von Schlüsseln ==

<br>
Alle oben genannten Schlüssel und Varianten können miteinander kombiniert werden. Im Ergebnis werden die jeweiligen Spalten der Übersichtstabelle entsprechend der Auswertungergebnisse ihrer Definitionen dargestellt.

{| class="wikitable"
! Inhalt Attribut tableSpecs: <br> Schlüsselkombinationen !! Erläuterungen !! Aussehen
|-
| style="width:55%" |
<pre>
{
"columnMapIcon" => [{
"Status" => "eq 'ended' ",
"icon" => "rc_WEB@grey",
},
{
"daysLeft" => ">= 1 ",
"icon" => "rc_WEB",
}],
"columnMapProvider" => "GoogleMaps",
"columnMapText" => "{ ReadingsVal('$NAME', '$BNR_35_Location','') }",
"smallScreenStyles" => "darksmallscreen,smallscreen",
"columnStateIcon" => [
{
"Status" => "eq 'ended' ",
"icon" => "ios-off",
},
{
"Status" => "eq 'upcoming' ",
"icon" => "ios-on-for-timer-green",
},
{
"Status" => "eq 'upcoming' ",
"daysLeft" => ">= 4",
"icon" => "ios-on-for-timer-blue",
},
],
"columnDaysLeftIcon" => [
{
"Summary" => "=~ /Gelbe Tonne/",
"icon" => "dustbin@#DF7401",
},
{
"Summary" => "=~ /Biotonne/",
"icon" => "dustbin@brown",
},
{
"Summary" => "=~ /Restabfall/",
"icon" => "dustbin@black",
},
{
"Summary" => "=~ /Papier/",
"icon" => "dustbin@blue",
},
{
"Status" => "=~ /ended/",
"icon" => "dustbin@grey",
},
],
}
</pre>
| Zusätzlich zu der aufgezeigten Definition ist das Attribut '''tableColumnMap''' auf '''icon''' gestellt um in der Spalte '''Map''' nicht den im Schüssel '''columnMapText''' definierten Text (Auswertung von ReadingsVal) zu zeigen, sondern das im Schlüssel '''columnMapIcon''' angegebene Icon.
| [[Datei:sscal21.PNG|200px]]
|-
|
<pre>
{
"smallScreenStyles" => "dark,default",
"columnSymbolIcon" => [
{
"Summary" => "eq 'Biotonne' ",
"icon" => "message_garbage@brown",
},
{
"Summary" => "eq 'Gelbe Tonne' ",
"icon" => "message_garbage@orange",
},
{
"Summary" => "eq 'Papiertonne' ",
"icon" => "message_garbage@blue",
},
{
"Summary" => "=~ /Restabfall/ ",
"icon" => "message_garbage@Wheat",
},
],
"columnDaysLeftIcon" => [
{
"Summary" => "=~ /[Tt]onne|Restabfall/",
"Status" => "ne 'ended' ",
"daysLeft" => "<= 4",
"icon" => "message_garbage_collection@orange",
},
{
"Summary" => "=~ /[Tt]onne|Restabfall/",
"Status" => "ne 'ended' ",
"daysLeft" => "<= 2",
"icon" => "message_garbage_collection@green",
},
{
"Summary" => "=~ /[Tt]onne|Restabfall/",
"Status" => "ne 'ended' ",
"daysLeft" => "> 4",
"icon" => "bag@grey",
},
],
"columnStateIcon" => [
{
"Status" => "eq 'ended' ",
"icon" => "1px-spacer",
},
{
"Status" => "eq 'started' ",
"icon" => "10px-kreis-gruen",
},
{
"Status" => "eq 'upcoming' ",
"icon" => "10px-kreis-gelb",
},
{
"Status" => "eq 'alarmed' ",
"icon" => "10px-kreis-rot",
},
],
}
</pre>
| Dieses Beispiel zeigt eine Konfiguration zur Anzeige eines Abfallkalenders. Es werden nur die minimal notwendigen Informationsspalten angezeigt.
| [[Datei:sscal24.PNG|200px]]
|}

<br>

= Termintabelle als Weblink einfügen =

Zur Einbindung in ein Weblink-Device oder zur Verwendung in eigenen Perl-Routinen stellt SSCal die Subroutine '''SSCal_calAsHtml''' zur Verfügung. Sie liefert ein HTML-Output zurück, welches dem eingestellten Tabellenaufbau in der Detail- bzw. Raumübersicht entspricht.
[[Datei:sscal27.PNG|right|thumb|300px|Spaltensteuerung Tabelle bei weblink Einbindung ]]

Die Definition des Weblink-Devices erfolgt:

define SynCal.Abfall.WBL weblink htmlCode { FHEM::SSCal::calAsHtml ("SynCal1") }

'''SynCal1''' ist der Name des SSCal-Devices dessen Ausgabetabelle eingebunden werden soll.

Möglicherweise sollen die Spalten Start/Ende jeweils nur als eine und nicht zwei (Datum/Zeit) Spalten dargestellt werden.
Im Attribut '''tableSpecs''' steuert der Schlüssel '''smallScreenStyles''' den Aufbau dieser Spalten in Abhängigkleit vom verwendeten Style des aufrufenden FHEMWEB Devices. Bei einer programmtechnischen Verwendung muss diese Information explizit mitgegeben werden.

Verwendet z.B. das FHEMWEB Device "WEB.BLACK" das Style "dark" und dieses ist im Schlüssel hinterlegt ("smallScreenStyles" => "dark"), erfolgt die Definition des Weblink-Devices in dieser Form:

define SynCal.Abfall.WBL weblink htmlCode { FHEM::SSCal::calAsHtml ("SynCal1","WEB.BLACK") }

Dadurch simuliert man gegenüber der FHEM::SSCal::calAsHtml Routine den Aufruf über das FHEMWEB-Device "WEB.BLACK" und die Routine wertet für dieses Device den eventuell vorhandenen Schlüssel "smallScreenStyles" => "dark" aus, was zur Darstellung der optimierten Ansicht führt.

<br>

= Reagieren auf Events und eine FHEM-Aktivität erstellen =

<br>
Das SSCal-Modul bietet für den Anwender zusätzliche Hilfsmittel an, um aus einem Kalendereintrag Steuerungen für Geräte oder Mitteilungen aufzubauen. Die wesentlichen sind nachfolgend beschrieben.

== at-Devices für Steuerungen automatisch erstellen und verwalten lassen ==

Um aus FHEM-Befehlen (z.B. "set lampe on") oder Perl-Routine Aufrufen (z.B. checkit()) automatisch eine zeitgesteuerte FHEM-Aktion zu erstellen, kann diese Funktionalität mit dem Attribut:

attr <SSCal> createATDevs 1

eingeschaltet werden.

Es wird der Eintrag im Reading '''Description''' ausgewertet, was dem Feld '''Beschreibung''' im Synology Kalender WebUI entspricht.
Um als FHEM-Befehl erkannt zu werden, muss der Text in der Beschreibung in '''{ }''' eingefasst sein bzw. in doppelte '''{{ }}''' zur Kennzeichnung einer Perl-Routine.
Der Kalendereintrag muss ebenfalls eine defininierte Anfangszeit in der Zukunft enthalten. Für beendete oder bereits gestartete Ereignisse wird kein at-Device erstellt.

Sind die Voraussetzungen erfüllt, wird für jedes erkannte Befehls-Ereignis ein at-Device erstellt und die Werte aus dem Kalendereintrag übernommen:

{| class="wikitable"
|-
| '''Begin'''
| Starttermin im at-Device
|-
| '''Description'''
| der FHEM-Befehl bzw. die auszuführende Perl-Routine
|-
| '''Summary'''
| wird in das alias-Attribut des at übernommen
|-
| '''Location'''
| wird als room-Attribut im at verwendet falls gesetzt. Sonst wird das room-Attribut des SSCal-Devices übernommen
|}

Der Name der erstellten at-Devices folgenden dem Schema:

SSCal.<SSCal-Device>.<Event-ID>.<ISO-Startzeit>

Bei jedem erneuten Einlesen des Kalenders werden eventuell bereits vorhandene at-Devices gelöscht, die durch das '''<SSCal-Device>''' erstellt wurden. Dadurch werden im Kalender vorgenommene Änderungen bestehender Termine und deren Inhalte übernommen. Im Kalender gelöschte Termine werden ebenfalls erkannt und die referenzierten at-Devices in FHEM gelöscht.

'''Beipiel:'''

Ein Kalendereintrag mit den Readings:
<pre>
2_01_Summary bald beginnend
2_03_Description {{ Perl-Routine }}
2_05_Begin 2020-02-17 20:45:00
2_10_End 2020-02-17 21:45:00
2_15_Timezone Europe/Berlin
2_17_Status alarmed
2_20_daysLeft 0
2_25_daysLeftLong in 0 Tagen
2_30_Weekday Montag
2_50_isAllday 0
2_55_isRepeatEvt 0
2_80_0_notifyDateTime 2020-02-16 20:45:00
2_90_calName Testkalender
2_98_EventId 2000
</pre>

führt zur Erstellung des at-Devices '''SSCal.SynCal3.2000.20200217T204500''' mit der Definition:

<pre>
defmod SSCal.SynCal3.2000.20200217T204500 at 2020-02-17T20:45:00 { Perl-Routine }
attr SSCal.SynCal3.2000.20200217T204500 comment created automatic by SSCal "SynCal3"
attr SSCal.SynCal3.2000.20200217T204500 alias bald beginnend"
attr SSCal.SynCal3.2000.20200217T204500 room SSCal

setstate SSCal.SynCal3.2000.20200217T204500 Next: 2020-02-17 20:45:00
setstate SSCal.SynCal3.2000.20200217T204500 2020-02-17 19:44:09 state Next: 2020-02-17 20:45:00
</pre>

== zusätzliches composite-Event für eigene Logiken ==

<br>
Für jedes Ereignis, welches einen Begin-Zeitpunkt enthält, werden zuätzliche composite-Events bei jedem erneuten Einlesen eines Kalenders erstellt. Der Event '''composite''' enthält die Informationsfelder:

* Blocknummer des Termins
* Event-ID des Termins
* Kennzeichen für ein Serientermin (0=kein Serientermin oder 1=Serientermin)
* Startzeitpunkt im ISO 8601 Format
* Status des Events
* den Text in '''Description''' (entspricht dem Feld Beschreibung im Synology Kalender WebUI) bzw. den Text in '''Summary''' falls '''Description''' nicht gesetzt ist

Der Event '''compositeBlockNumbers''' enthält die Blocknummern aller Termine des Kalenders. Sind keine Termine vorhanden, enthält dieser Event nur den Wert '''none'''.

Ausschnitt aus dem Eventmonitor:

2020-02-14 13:19:11 SSCal SynCal2 compositeBlockNumbers: 00 01 02 03 04 05 06 07 08 09 10 # alle Block-Nr
2020-02-14 13:19:11 SSCal SynCal2 composite: 00 1983 0 2020-02-14T13:15:00 started {set lampe on} # FHEM-Befehl
2020-02-14 13:19:11 SSCal SynCal2 composite: 01 1984 0 2020-02-14T15:15:00 alarmed {set lampe off} # FHEM-Befehl
2020-02-14 13:35:31 SSCal SynCal2 composite: 02 1985 1 2020-02-14T18:00:00 upcoming {{ <Perl-Routine> }} # Perl-Routine

Das ISO Format des Zeitstempels kann unmittelbar zur Erstellung eines '''at''' verwendet werden. Um die Verwendung des Kalenderinhaltes als FHEM-Befehl zu deklarieren, kann bei der Erstellung des Kalendereintrages das Ereignis in '''{ }''' eingefasst werden um z.B. in einem '''notify''' darauf zu filtern.

Die nachfolgende Definition eines notify-Devices zeigt eine mögliche Verfahrensweise um bei Erkennung eines FHEM-Befehls automatisch ein at-Device mit einem entsprechenden Startzeitpunkt für die Ausführung des angegebenen Befehls zu definieren:

<pre>
SynCal.*:.*composite.*
{
my ($PART0, $PART1) = split(": ", $EVENT,2);;
my ($bnr,$id,$repeat,$isot,$tate,$cmd) = split(" ", $PART1,6);;
if ($tate =~ /upcoming|alarmed/ && $cmd =~ /^\s*\{(.*)\}\s*$/) {
$cmd = $1;
if(!$repeat) {
Log3($NAME, 3, "$NAME - Command received. Create/modify \"SSCal.$id\" - Timestamp: $isot, Command: $cmd");;
fhem("defmod SSCal.$id at $isot $cmd");;
} else {
my $ao = $isot;
$ao =~ s/[-:]//g;
Log3($NAME, 3, "$NAME - Command received. Create/modify \"SSCal.$id.$ao\" - Timestamp: $isot, Command: $cmd");;
fhem("defmod SSCal.$id.$ao at $isot $cmd");;
}
}
}
</pre>

'''Funktionsweise:''' <br>

Wird ein composite-Event eines SSCal-Devices mit dem Betreff eingeschlossen in '''{ }''' erkannt und ist der Status dieses Termins "upcoming" oder "alarmed", wird ein at-Device mit dem Startzeitpunkt und dem Befehl (ohne die einschließenden { }) aus dem Event erstellt. Ist das Device bereits vorhanden, wird das Device aktualisiert. '''Durch eine eindeutige Zuordung des Kalendereintrags zu dem at-Device über die Event-ID im Namen wird in dem Fall, dass es kein Serientermin ist, der Start des FHEM-Befehl automatisch angepasst wenn man den Zeitpunkt im Kalender verändert.'''

Zusätzlich wird ein Logeintrag mit verbose 3 zur Protokollierung erstellt.
Soll statt FHEM-Befehl eine Perl-Routine ausgeführt werden, schließt man den Betreff des Kalendereintrags in doppelte '''{{ }}''' ein.

<br>
== Urlaub/Abwesenheiten automatisiert in holiday Device Steuerdatei übernehmen ==

Mit Hilfe des Events '''compositeBlockNumbers''' können Urlaubs- oder allgemeine Abwesenheitstermine aus einem Kalender automatisch in ein holiday Device bzw. die Steuerdatei des holiday Devices übertragen werden.

Zu diesem Zweck werden zwei Subroutinen in der 99_myUtils.pm erstellt und ein Notify um auf den Event zu reagieren und die Subroutine '''SSCalToHoliday''' auszuführen.

In dem Beispiel wird davon ausgegangen:

* das holiday Device verwendet die Datei (HOLIDAYFILE) ./FHEM/central.holiday
* die Abwesenheiten werden durch die Signalwörter '''Urlaub''' bzw. '''Abwesend''' gekennzeichnet
* das Kalenderdevice, welches die Urlaubsdaten enthält, heißt '''SynCal2'''

Es werden die Routinen '''SSCalToHoliday''' und '''SSCalWriteHoliday''' in die Datei 99_myUtils.pm eingefügt.

<syntaxhighlight lang="Perl">
###################################################################################################
### Urlaubstermine auswerten mit 57_SSCal.pm
### Aufruf der Funktion aus Notify
###
### $event = compositeBlockNumbers-$EVENT und enthält alle Blocknummern des Kalenders, z.B.
### compositeBlockNumbers: 00 01 02 03 04 05 06 07 08 09 10 11 12 13
###
####################################################################################################
sub SSCalToHoliday($$$) {
my ($name,$fName,$event) = @_;
my $hash = $defs{$name};
my ($reading,$evt) = split(": ",$event,2);
my (@bnr) = split(" ",$evt);

my @SigList = qw/Urlaub Abwesend/; # Signalwörter im Kalender für "Abwesenheit"
my @ul;

foreach my $bnr (@bnr) {
last if($bnr eq "none");
my $status = ReadingsVal($name, $bnr."_17_Status", ""); # Status
my $summary = ReadingsVal($name, $bnr."_01_Summary", ""); # Summary
my $begin = ReadingsVal($name, $bnr."_05_Begin", ""); # Starttermin
my $end = ReadingsVal($name, $bnr."_10_End", ""); # Endtermin

if($status =~ /upcoming|alarmed|started/) { # Termine beginnen in Zukunft, Signalwort aus
# Liste enthalten ?
if (grep {$summary =~ /$_/} @SigList) {
my ($sy,$sm,$sd,$sh,$smin,$ss) = ($begin =~ /(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})/);
my ($ey,$em,$ed,$eh,$emin,$es) = ($end =~ /(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})/);

if($sy != $ey) { # wenn Jahreswechsel vorliegt zwei Sätze erzeugen
push(@ul, "4 $sm-$sd 12-31 $summary"); # 4 12-09 12-31 Urlaub Teil1
push(@ul, "4 01-01 $em-$ed $summary"); # 4 01-01 01-05 Urlaub Teil2

} else {
my $ue = "4 $sm-$sd $em-$ed $summary";
push(@ul, $ue);
}
}
}
}

if (@ul) {
Log3 ($name, 4, "$name - Argument list for SSCalWriteHoliday:");
foreach my $i (@ul) {
Log3 ($name, 4, "$name - $i");
}
} else {
Log3 ($name, 4, "$name - No absence time detected. All absence will be deleted.");
}

SSCalWriteHoliday($name,$fName,@ul);

return;
}

############################################################################
### Schreibroutine Urlaub in File (central.holiday)
############################################################################
sub SSCalWriteHoliday(@) {
my ($name,$fName,@ul) = @_;
$fName = $attr{global}{modpath}."/FHEM/".$fName;

my $param = {
FileName => $fName,
ForceType => "file",
};

my ($err, @old) = FileRead($param);
if($err) {
Log3 ($name, 2, "$name - Couldn't read file: $err");
return;
}

my @new; # neue Liste zum Schreiben
my $del = 0;

foreach my $l (@old) {
if($l =~ m/^# Time of absence from Calendar $name/i) {
$del = 1;
}

if($l =~ m/^# End Time of absence from Calendar $name/i) {
$del = 0;
next;
}

if ($del) {
next;
} else {
push (@new, $l);
Log3 ($name, 4, "$name - add line: $l");
}
}

unshift (@ul, "# Time of absence from Calendar $name, updated: ".TimeNow());
push (@ul, "# End Time of absence from Calendar $name");
push (@new, @ul);

Log3 ($name, 4, "$name - -> Start new list write into $fName <-");
foreach my $i (@new) {
Log3 ($name, 4, "$name - $i");
}
Log3 ($name, 4, "$name - -> End new list <-");

$err = FileWrite($param, @new);
if($err) {
Log3 ($name, 2, "$name - Couldn't write holiday data into $fName: $err");
}

return;
}
</syntaxhighlight>

Das folgende '''Notify''' (Raw-Definition) wird verwendet:

<pre>
define N.SSCalWriteHolidays notify SynCal2:compositeBlockNumbers:.* { SSCalToHoliday($NAME,"central.holiday",$EVENT) }
attr N.SSCalWriteHolidays devStateIcon active:remotecontrol/black_btn_GREEN:inactive inactive:remotecontrol/black_btn_RED:active
</pre>

'''Funktionsweise:''' <br>
Wird der Event '''compositeBlockNumbers''' durch das Device '''SSCal2''' ausgelöst, wird die Subroutine '''SSCalToHoliday''' ausgeführt. Dieser Routine werden der auslösende Devicename ($NAME = SSCal2 in dem Beispiel), das HOLIDAYFILE und der komplette Event übergeben.

Das Event compositeBlockNumbers enthält die Blocknummern aller Termine im Kalenderdevice. Im Array '''@SigList''' werden alle Signalwörter hinterlegt, die bei Vorhandensein im Reading x_x_Summary eine Abwesenheit kennzeichnen.
Wird eines dieser Signalwörter erkannt und ist der dazu gehörige Termin nicht vergangen, erfolgt die Übersetzung in das durch holiday verarbeitbare Format und der Termineintrag in die Datei '''central.holiday'''.

Beispiel für einen Eintrag:

<pre>
# Time of absence from Calendar SynCal2, updated: 2020-03-05 21:20:47
4 03-28 04-04 Urlaub - Nordsee
# End Time of absence from Calendar SynCal2
</pre>

Änderungen oder Löschen des Termins im Synology-Kalender führen ebenfalls zu einer automatischen Anpassung oder Löschen des Eintrags in der holiday-Steuerdatei.

Damit können Zeiten der Abwesenheiten über Kalendereinträge an FHEM übermittelt und durch holiday ausgewertet werden (Stichwort holiday2we bzw. $we).

<br>

= Anwendungsbeispiele =

== Backup des FHEM Filesystems über Synology Kalendereinplanung ==

In diesem [[SSFile_-_Integration_der_Synology_File_Station#Backup_des_FHEM_Filesystems_.C3.BCber_Synology_Kalendereinplanung|Beitrag]] ist beschrieben, wie mit dem Synology Modulen SSCal und SSFile eine übersichtliche und einfach konfigurierbare Sicherungslösung für die Verzeichnisse des FHEM-Servers aufgebaut werden kann.

<br>
= Beschränkungen und Known Bugs =

<br>

= Weiterentwicklungen und Testversionen =

Weiterentwicklungen und Testversionen stelle ich in meinem contrib-Verzeichnis bereit.

Eine Entwicklungsversion kann aus dem diesem Verzeichnis einfach per Download mit diesem Befehl in der FHEM Kommandozeile bezogen werden. Bitte so komplett mit den Ausführungszeichen am Anfang und Ende eingeben:

<pre>
"wget -qO ./FHEM/57_SSCal.pm https://svn.fhem.de/fhem/trunk/fhem/contrib/DS_Starter/57_SSCal.pm"
</pre>

Danach FHEM restarten.

Durch Weiterentwicklung können sich jederzeit Änderungen ergeben. Im Zweifel das [https://forum.fhem.de/index.php/topic,106963.0.html Forum] konsultieren.

<br>

= Links =

Forumthread zu diesem Modul: https://forum.fhem.de/index.php/topic,106963.0.html <br>
Synology KnowledgeBase: https://www.synology.com/de-de/knowledgebase/DSM/help/Calendar/calendar_desc

SiSi

2023-11-09T10:54:46Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messenger Signal
|ModType=x
|ModForumArea=Codeschnipsel
|ModFTopic=84996
|ModTechName=32_SiSi.pm
|ModOwner=Quantum ({{Link2FU|35410|Forum}})}}
Das Modul [[SiSi]] ermöglicht den Versand von Nachrichten über den Instant-Messaging-Dienst [https://signal.org Signal] aus FHEM heraus.

{{Randnotiz|RNTyp=r|RNText=Dieses Modul wird derzeit (letzte Änderung: August 2018) nicht mehr aktiv gepflegt. Es entsteht jedoch (ab Januar 2021) mit [[Signalbot]] ein weiteres Modul zur Unterstützung des Signal Messenger Protokolls.}}

Um dies zu ermöglichen, sind mehrere Schritte notwendig:
#Installation des [https://github.com/AsamK/signal-cli Signal Messenger Command Line Interface (signal-cli)].
#Registrierung einer Rufnummer bei Signal
#Einrichtung der [https://de.wikipedia.org/wiki/D-Bus D-Bus]-Schnittstelle
#Inbetriebnahme des FHEM-Moduls

Diese Anleitung geht davon aus, dass
*als Betriebssystem Debian oder Raspbian verwendet wird
*FHEM im Verzeichnis ''/opt/fhem'' installiert wurde (ansonsten müssen die Pfade in der Anleitung angepasst werden)

Alle in dieser Anleitung vorkommenden Textstellen in spitzen Klammern (z.B. <ErsetzMich>) sind durch eigene Werte zu ersetzen, sofern es sich nicht um Auszüge aus Konfigurationsdateien handelt.

==Voraussetzungen==
Um sowohl das ''signal-cli'' als auch das Modul verwenden zu können, müssen bestimmmte Linux-Pakete installiert sein. Im Folgenden eine Liste der Pakete für Debian/Raspbian:
*'''''libunixsocket-java'''''
*'''''dbus'''''
*'''''libnet-dbus-perl'''''
*'''''haveged''''' (Dient dazu, genügend Entropie für den Zufallszahlengenerator zu erzeugen.)
*'''''openjdk-11-jre-headless''''' (Es sollte eine Version >= 11 installiert werden. Welche genau, hängt von Betriebssystem und dem Installationszeitpunkt ab. Diese ist als Default JRE mit Debian Stretch verfügbar. Installationen, die auf einer früheren Debian Version aufsetzen, müssen gegebenfalls auf Stretch geupgraded werden). Die aktuellsten Informationen über das benötigte JRE findest du [https://github.com/AsamK/signal-cli#installation hier].

Optional kann noch das Paket '''''shared-mime-info''''' installiert werden wenn ein gesendeter Anhang nicht direkt im Chatverlauf angezeigt werden soll, sondern erst durch einen Klick auf das Datei-Icon.

Installation der Pakete in einem Rutsch:
sudo apt-get update
sudo apt-get install libunixsocket-java dbus libnet-dbus-perl shared-mime-info haveged openjdk-11-jre-headless

==Installation des signal-cli==
[https://github.com/AsamK/signal-cli signal-cli] ist ein Kommandozeilen-Interface für [https://github.com/signalapp/libsignal-service-java libsignal-service-java]<ref>libsignal-service-java ist eine Java/Android Bibliothek zur Kommunikation mit dem Signal Messaging Service</ref>. Es unterstützt das Registrieren und Verifizieren einer Rufnummer sowie das Senden und Empfangen von Nachrichten.

Der erste Schritt zur Installation von ''signal-cli'' ist, die aktuellste Versionsnummer auf der GitHub-Seite des Projektes unter "[https://github.com/AsamK/signal-cli/releases Releases]" zu finden. Zum Zeitpunkt der Erstfassung dieser Anleitung war das die Version 0.6.0.

Anschließend wird die Release heruntergeladen und als Benutzer '''''fhem''''' in den Wurzelordner von FHEM (z.B. ''/opt/fhem'') entpackt.
<syntaxhighlight lang="text">
export VERSION=0.6.0
wget https://github.com/AsamK/signal-cli/releases/download/v"${VERSION}"/signal-cli-"${VERSION}".tar.gz
sudo -u fhem tar xf signal-cli-"${VERSION}".tar.gz -C /opt/fhem
</syntaxhighlight>

Zur einfacheren Handhabung kann der neu erstellte Ordner umbenannt und ein symbolischer Link in ''/usr/local/bin/'' erstellt werden.
<syntaxhighlight lang="text">
sudo mv /opt/fhem/signal-cli-"${VERSION}" /opt/fhem/signal-cli
sudo ln -sf /opt/fhem/signal-cli/bin/signal-cli /usr/local/bin/
</syntaxhighlight>

==Registrierung einer Rufnummer==
Um Signal nutzen zu können, ist eine Rufnummer zwingend erforderlich. Für diesen Fall empfiehlt es sich, eine Nummer zu verwenden, die nicht schon für die Kommunikation mit Signal verwendet wird. Zum Beispiel eine Festnetznummer.

'''Alternativ''' kannst du den Signal Bot auch mit deiner eigenen Rufnummer verknüpfen, analog zum Verknüpfen deiner Rufnummer mit z.B. der Desktop Installation von Signal. Siehe dazu den Abschnitt "Verknüpfen mehrerer Accounts" weiter unten.

=== Registrierung mit neuer Nummer ===

Die Registrierung einer Nummer läuft wie folgt ab:
#Registrierung der Nummer mittels ''signal-cli''
#Erhalt einer Textnachricht mit dem Verifizierungscode an angegebene Nummer. Wenn an der Rufnummer keine Textnachrichten empfangen werden können, kann - wie in diesem Beispiel - mit dem Parameter ''--voice'' ein Sprachanruf erzwungen werden. In beiden Fällen kann es durchaus etwas länger dauern, bis man den Verifizierungscode erhält.
#Verifizierung der Nummer mittels ''signal-cli''

{{Hinweis|Alle der folgenden Befehle werden als Benutzer '''''fhem''''' ausgeführt, damit die Konfigurationsdateien im Home-Verzeichnis des Benutzers (z.B. ''~/.local/share/signal-cli'') landen.}}

Im ersten Schritt registriert man eine Nummer mittels ''signal-cli''.
<syntaxhighlight lang="text">sudo -u fhem signal-cli -u <Telefonnummer> register --voice</syntaxhighlight>
Wenn alles in Ordnung ist, erhält man keine Rückmeldung. Wenn es lange dauert, hat man nicht genug Entropie.
Kurz darauf erhält man einen Sprachanruf auf Englisch, mit dem einem der sechsstellige Verifizierungscode yyyyyy mitgeteilt wird.

Im zweiten Schritt wird diese Nummer mit Hilfe des erhaltenen Codes verifiziert.
<syntaxhighlight lang="text">sudo -u fhem signal-cli -u <Telefonnummer> verify <VerificationCode></syntaxhighlight>
Auch hier gibt es keine Rückmeldung, solange alles funktioniert hat.

War die Registrierung erfolgreich, können nun Nachrichten via ''signal-cli'' versendet werden:
<syntaxhighlight lang="text">sudo -u fhem signal-cli -u <RegistrierteNummer> send -m "Greetings from FHEM!" <Empfängernummer></syntaxhighlight>

=== Verknüpfen mehrerer Accounts ===
Das Verknüpfen mehrerer Devices / Installationen / Bots unter der selben Rufnummer nennt sich Provisioning und ist [https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning) hier] beschrieben. Es ist ähnlich dem Vorgehen der Registrierung einer neuen Telefonnummer, nur dass du hier deine eigene Nummer wiederverwenden kannst. ACHTUNG: Das bedeutet allerdings, dass alle Nachrichten, die über den Bot verschickt werden, unter deiner Nummer und somit unter deinem Account und Namen verschickt werden. Empfänger deiner Nachrichten sehen diese also als Teil deines Chats mit jenen Empfängern. Für den Empfänger ist daher nicht ersichtlich, dass die Nachrichten automatisiert von einem Bot verschickt wurden. Schickst du eine Nachricht an dich selbst, taucht diese in deinem Signal Messenger im Chat "Notiz an mich" auf.

Um den Signal Bot mit deinem Account zu verknüpfen gehst du wie [https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning) hier] beschrieben vor. Installiere am besten noch das Paket [https://fukuchi.org/works/qrencode/ qrencode].<syntaxhighlight lang="bash">
sudo apt-get install qrencode
</syntaxhighlight>Danach führst du diesen Befehl aus:<syntaxhighlight lang="bash">
sudo signal-cli link -n "optional device name" | tee >(xargs -L 1 qrencode -t utf8)
</syntaxhighlight>Dieser Befehl generiert einen QR Code im Terminal, den du mit deinem Hauptgerät (vermutlich dein Handy) scannst und somit das neue "Gerät" hinzufügst. Navigate in Signal dazu in die Einstellungen > Gekoppelte Geräte und wähle "Neues Gerät koppeln". Danach ist das Gerät erfolgreich verknüpft und du kannst wie unten beschrieben mit der Einrichtung fortfahren.

== Einrichten der Kommunikation über D-Bus ==
Damit das FHEM-Modul über die D-Bus Schnittstelle mit ''signal-cli'' kommunizieren kann, ist die Einrichtung von D-Bus sowie die Erstellung eines [https://de.wikipedia.org/wiki/Systemd systemd]-Scripts notwendig.

{{Hinweis|Alle der folgenden drei Dateien müssen als Benutzer '''''root''''' angelegt und editiert werden.}}

;/etc/dbus-1/system.d/org.asamk.Signal.conf
Die Datei in einem Editor öffnen
sudo nano /etc/dbus-1/system.d/org.asamk.Signal.conf
und mit folgendem Inhalt befüllen
<syntaxhighlight lang="xml">
<?xml version="1.0"?> 
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">

<busconfig>
<policy user="fhem">
<allow own="org.asamk.Signal"/>
<allow send_destination="org.asamk.Signal"/>
<allow receive_sender="org.asamk.Signal"/>
</policy>

<policy context="default">
<allow send_destination="org.asamk.Signal"/>
<allow receive_sender="org.asamk.Signal"/>
</policy>
</busconfig>
</syntaxhighlight>

;/usr/share/dbus-1/system-services/org.asamk.Signal.service
Die Datei in einem Editor öffnen
sudo nano /usr/share/dbus-1/system-services/org.asamk.Signal.service
und mit folgendem Inhalt befüllen
<syntaxhighlight lang="ini">
[D-BUS Service]
Name=org.asamk.Signal
Exec=/bin/false
SystemdService=dbus-org.asamk.Signal.service
</syntaxhighlight>

;/etc/systemd/system/signal.service
Die Datei in einem Editor öffnen
sudo nano /etc/systemd/system/signal.service
und mit folgendem Inhalt befüllen.

<syntaxhighlight lang="ini">
[Unit]
Description=Send secure messages to Signal clients
Requires=dbus.socket
After=dbus.socket
Wants=network-online.target
After=network-online.target

[Service]
Type=dbus
Environment="SIGNAL_CLI_OPTS=-Xms2m"
ExecStart=/opt/fhem/signal-cli/bin/signal-cli -u +49xxxxxxxxxxx --config /opt/fhem/.local/share/signal-cli daemon --system
User=fhem
BusName=org.asamk.Signal

[Install]
Alias=dbus-org.asamk.Signal.service
</syntaxhighlight>

'''Achtung!'''
* Die Rufnummer im Script muss durch die in den vorigen Schritten registrierte ersetzt werden.
* Außerdem muss unter Umständen der Pfad des FHEM-Wurzelverzeichnisses angepasst werden.
* Der Pfad zur Konfigurationsdatei ist je nach signal-cli Version anders:

;<0.6.1:
$HOME/.config/signal/data/
oder
$HOME/.config/textsecure/data/

;>=0.6.1
$HOME/.local/share/signal-cli/data/

Sind alle Dateien angelegt, können die Services mit diesen Befehlen aktiviert und gestartet werden.
<syntaxhighlight lang="text">
sudo systemctl daemon-reload
sudo systemctl reload dbus.service
sudo systemctl enable signal.service
sudo systemctl start signal.service
</syntaxhighlight>

Ob alles funktioniert, kann wie folgt getestet werden:
*D-Bus:
sudo -u fhem dbus-send --system --type=method_call --print-reply --dest="org.asamk.Signal" /org/asamk/Signal org.asamk.Signal.sendMessage string:<Nachricht> array:string: string:<EmpfängerNummer>
*signal-cli über D-Bus:
sudo -u fhem signal-cli --dbus-system send -m "<Nachricht>" <EmpfängerNummer>

== Einbindung des FHEM-Moduls ==
Solange das Modul '''32_SiSi.pm''' noch nicht via FHEM-Update verteilt wird, ist eine manuelle Installation notwendig. Das geschieht, in dem es von der [https://github.com/Quantum1337/32_SiSi.pm GitHub-Seite] des Modul-Autors heruntergeladen und in den FHEM-Ordner kopiert wird.

Der Befehl
wget https://raw.githubusercontent.com/Quantum1337/32_SiSi.pm/master/FHEM/32_SiSi.pm
speichert das Modul im aktuellen Verzeichnis.

Mit den folgenden Befehlen wird das Modul ins das FHEM-Verzeichnis verschoben und anschließend die Datei-Rechte angepasst.
sudo mv 32_SiSi.pm /opt/fhem/FHEM/
sudo chown fhem:dialout /opt/fhem/FHEM/32_SiSi.pm

Anschließend wird noch die lokale CommandRef aktualisiert:
cd /opt/fhem
sudo /usr/bin/perl contrib/commandref_join.pl

Zum Abschluss wird das Modul noch FHEM bekannt gemacht. Dazu in der FHEM-Kommandozeile folgenden Befehl eingeben:
reload 32_SiSi.pm

==Verwendung des FHEM-Moduls==
Die genaue Verwendung des Moduls 32_SiSi.pm ist in der CommandRef beschrieben. Hier deshalb nur ein kleines Beispiel.

SiSi-Device definieren:
define Signal SiSi

Dem Device mitteilen, dass es eine Verbindung zum signal-cli D-Bus Service herstellen soll:
attr Signal enable yes

Eine Standard-Empfängernummer definieren, falls im Befehlsaufruf keine angegeben ist:
attr Signal defaultPeer +49170zzzzzzzz

Anschließend kann aus FHEM heraus eine Nachricht gesendet werden:
set Signal msg Hurra, es funktioniert!

===Zusammenspiel mit den Modulen Msg und Roommate===
Um mithilfe des Moduls [[Msg]] Signal-Nachrichten versenden zu können, ist im Device ''globalMsg'' das Attribut '''msgCmdPush''' zu setzen.
attr globalMsg msgCmdPush set %DEVICE% msg @%RECIPIENT% %MSG%

Optional kann ein Standard-Empfänger gesetzt werden der die Nachricht erhält, wenn beim Aufruf von ''Msg'' kein Empfänger angegeben wurde:
attr globalMsg msgContactPush <Signal-Device>:<Empfängernummer>
Danach kann mit <code>msg Testnachricht</code> eine Signal-Nachricht versendet werden.

Werden {{Link2CmdRef|Anker=ROOMMATE|Lang=de|Label=ROOMMATE-Devices}} verwendet, kann jedem eine Kontaktadresse hinterlegt werden, damit beim Aufruf von ''Msg'' einfach der Device-Name anstatt der Nummer angegeben werden kann. (Funktioniert natürlich bei jedem anderen Device auch. Aber ein ROOMMATE-Device macht das ganze anschaulicher.)
<syntaxhighlight lang="text">
attr <ROOMMATE-Device> msgContactPush <Signal-Device>:<Empfängernummer>

z.B.:
attr rr_Max msgContactPush Signal:+49...
</syntaxhighlight>
Anschließend kann mit <code>msg @rr_Max Testnachricht</code> eine Nachricht an Max gesendet werden.

==Hinweise==
Derzeit ist es aufgrund von Einschränkungen in der D-Bus-API noch nicht möglich, mit dem SiSi-Modul neue Fingerprints von Kontakten hinzuzufügen oder aus Gruppen auszutreten. Daher muss beides noch manuell auf der Linux-Kommandozeile erfolgen.

;Neuer Fingerprint
:Mit folgendem Befehl wird dieser Nummer wieder vertraut und ''signal-cli'' fügt den geänderten Fingerprint dann automatisch zu seiner Liste hinzu.
:<syntaxhighlight lang="text">sudo -u fhem signal-cli -u <FHEM-NUMMER> trust -a <Nummer mit geänderten Fingerprint></syntaxhighlight>

;Aus einer Gruppe austreten
:Soll die "FHEM-Signal-Rufnummer" aus einer bestehende Gruppe entfernt werden, kann dieser Aufruf von ''signal-cli'' verwendet werden.
:<syntaxhighlight lang="text">sudo -u fhem signal-cli -u <FHEM-NUMMER> quitGroup -g <GroupID></syntaxhighlight>

==Querverweise==
<references />

[[Kategorie:Signal]]

SIGNALduino Compilieren

2023-11-09T10:51:46Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

__TOC__
== SIGNALduino in die Arduino Entwicklungsumgebung einbinden ==
Zur Inbetriebnahme von [[SIGNALduino]] auf der Arduino IDE (getestet mit auf Arduino V1.6.7) müssen die Quelltexte von [https://github.com/RFD-FHEM/SIGNALDuino/ GitHub] (Stand Feb. 2017) geladen werden.

Dort <code>Clone or download</code> und danach <code>Download ZIP</code> klicken und das ZIP-Archiv auspacken oder auf der Kommandozeile <code>git clone https://github.com/RFD-FHEM/SIGNALDuino.git</code> ausführen.

Es werden folgende Dateien benötigt:
* Die Datei <code>RF_Receiver.ino</code> in einen Ordner <code>RF_Receiver</code>, am besten direkt ins <code>Arduino</code> Verzeichnis der IDE kopieren.
* Im <code>libraries</code> Ordner der Arduino IDE am besten einen Ordner mit Namen <code>SIGNALduino</code> anlegen, dort müssen dann die Dateien <code>bitstore</code>, <code>output</code>, <code>signalDecoder</code>, <code>SimpleFIFO</code> und <code>TimerOne</code> (jeweils <code>.cpp</code> und <code>.h</code> Datei) abgelegt werden.
* In diesem <code>SIGNALduino</code> Verzeichnis ist dann noch ein Unterverzeichnis <code>config</code> anzulegen, dort muss die Datei <code>known_16bit_timers.h</code> abgelegt werden.

Struktur der SIGNALduino libraries:[[Datei:SIGNALduino-ViaArduinoEnvironment.jpg]]

In der Arduino Entwicklungsumgebung unter <code>Werkzeuge</code> → <code>Board</code> <tt>'''"Arduino Nano"'''</tt> und unter <code>Werkzeuge</code> → <code>Prozessor</code> <tt>'''"ATmega328"'''</tt> angeben. Nach Einstecken des SIGNALduinos in die USB Buchse noch den entsprechenden <code>COM-Port</code> unter <code>Werkzeuge</code> → <code>Port</code> angeben, danach sollte sich der Scetch <code>RF_Receiver.ino</code> übersetzen und auf den SIGNALduino laden lassen.

== SIGNALduino mit Makefile unter Linux ==
Wer lieber auf der Kommandozeile arbeitet kann SIGNALduino auch mit einem Makefile übersetzen und laden.
Benötigt werden dazu:
* Der Cross-Compiler und alle Werkzeuge für Arduino bzw. AVR. Bei Ubuntu und Debian Systemen:
<syntaxhighlight lang=bash>
# Arduino Pakete installieren:
sudo apt-get install arduino arduino-core arduino-mighty-1284p arduino-mk
# AVR
sudo apt-get install flashrom gcc-avr avrdude avr-libc binutils-avr
# Die Unterstützung der Braillezeile kann zu Konflikten um den seriellen Port führen
sudo apt-get remove brltty brltty-x11
# Arduino-Makefile verwendet YAML und serialport in Perl
sudo apt-get libdevice-serialport-perl libyaml-perl
</syntaxhighlight>
In den Paketen sind die Arduino Quellen und Arduino-Makefile enthalten.
Bei wem das aber nicht klappt, der sollte wie hier beschrieben die neuesten Versionen verwenden.

* [https://github.com/RFD-FHEM/SIGNALDuino.git SIGNALDuino Quelltexte]
<syntaxhighlight lang=bash>
# Hier kann man natürlich jedes beliebige Verzeichnis nehmen.
mkdir -p ~/src/arduino; cd ~/src/arduino
# SIGNALDuino von github clonen
git clone https://github.com/RFD-FHEM/SIGNALDuino.git
</syntaxhighlight>

* Die [https://www.arduino.cc/en/Main/Software Arduino Quellen] (optional)
<syntaxhighlight lang=bash>
# siehe https://www.arduino.cc/en/Main/Software für neueste Version
wget https://downloads.arduino.cc/arduino-1.8.5-linux64.tar.xz
tar xvJf arduino-1.8.5-linux64.tar.xz
</syntaxhighlight>

* Die neueste Version Arduino-Makefile (optional)
<syntaxhighlight lang=bash>
# Neueste Version von github clonen
git clone https://github.com/sudar/Arduino-Makefile.git
</syntaxhighlight>

Jetzt muss in <code>SIGNALDuino/RF_Receiver</code> noch ein <code>Makefile</code> erstellt werden:
<syntaxhighlight lang=make>
# Verzeichnis in dem die Arduino-Quellen liegen
ARDUINO_DIR=$(HOME)/src/arduino/arduino-1.8.5
# Verzeichnis mit dem Arduino-Makefile
ARDMK_DIR=$(HOME)/src/arduino/Arduino-Makefile
# Basisverzeichnis unter dem die AVR-Werkzeuge liegen
AVR_TOOLS_DIR=/usr
AVRDUDE_OPTS = -v
# Ab Arduino 1.5 sollte man die Architektur angeben.
ARCHITECTURE = avr
BOARD_TAG = nano
BOARD_SUB = atmega328
USER_LIB_PATH += $(realpath ../src/_micro-api/libraries)
ARDUINO_LIBS += bitstore output signalDecoder SimpleFIFO TimerOne EEPROM
# Device des Arduino nano
MONITOR_PORT = /dev/ttyUSB0
# AVRDUDE = /usr/bin/avrdude
AVRDUDE_CONF = /etc/avrdude.conf
include $(ARDMK_DIR)/Arduino.mk
</syntaxhighlight>
Wer die Arduino Quellen und Arduino-Makefile aus der Paketverwaltung verwenden möchte, kann folgendes ändern:
<syntaxhighlight lang=make>
ARDUINO_DIR=/usr/share/arduino
ARDMK_DIR=$(ARDUINO_DIR)
</syntaxhighlight>

Mit Stand vom 17.02.2018 müssen jetzt noch ein paar kleine Fehler beseitigt werden:
Präprozessor-Direktiven werden nicht mit Semikolon abgeschlossen
* in <code>RF_Receiver/RF_Receiver.ino</code>
:* <code>#define CMP_NEWSD</code> statt <code>#define CMP_NEWSD;</code>
Linux unterscheidet Groß- und Kleinschreibung bei Dateien:
* in <code>src/_micro-api/libraries/output/src/output.h</code>
* und in <code>src/_micro-api/libraries/signalDecoder/src/signalDecoder.h</code>
:* <code> #include "Arduino.h"</code> statt <code> #include "arduino.h"</code>
Das Makefile ignoriert Bibliotheken ohne <code>library.properties</code>
* in <code>src/_micro-api/libraries/signalDecoder</code> fehlt <code>library.properties</code>.
<syntaxhighlight lang=bash>
cd src/_micro-api/libraries/signalDecoder
cp ../bitstore/library.properties .
sed -i 's/bitstore/signalDecoder/g' library.properties
</syntaxhighlight>

Danach kann SIGNALDuino für den Arduino Nano übersetzt werden:
<syntaxhighlight lang=bash>
cd RF_Receiver
make
# Auf den Arduino laden (flashen)
make upload
# Aufräumen mit
make clean
</syntaxhighlight>

== SIGNALDuino konfigurieren und testen ==
[[Datei:Fhemduino_schematic.png|mini|FHEMduino bzw. SIGNALDuino Schaltplan]]
In der Datei <code>RF_Receiver.ino</code> sind u.a. folgende Einstellungen:
* <code>BAUDRATE</code> Die Datenrate mit der SIGNALDuino mit dem PC kommuniziert (Voreinstellung 57600). Man kann also z.B. mit <code>minicom -D /dev/ttyUSB0 -8 -b 57600</code> die Kommunikation testen.
* <code>PIN_LED</code> Der Pin an dem die LED zur Signalisierung von Nachrichten angeschlossen ist (Voreinstellung D13 = LED <code>L</code> auf dem Nano).
* <code>PIN_RECEIVE</code> Der Pin zum Empfang von Daten (Voreinstellung D2).
* <code>PIN_SEND</code> Der Pin zum Senden von Daten (Voreinstellung D11).

Öffnet man ein Terminal (z.B. <code>minicom</code> siehe oben) so kann man die Kommandoschnittstelle des SIGNALDuino probieren:
* Eingabe "<code>?</code> Enter" listet die verfügbaren Kommandos: ''Use one of V i R t X F S P C G''
:* <code>V</code>: Zeigt die Version der Software
:* <code>i</code>: Präfix für ein Intertechno-Kommando.
:* <code>R</code>: Zeigt den freien Arbeitsspeicher (RAM) in Bytes
:* <code>t</code>: Zeigt die Dauer des Betriebs seit dem letzten Start in Sekunden (uptime).
:* <code>XQ</code>: Empfänger abschalten (RX Quit)
:* <code>XE</code>: Empfänger einschalten (RX Enable)
:* <code>F</code>: Filter wechseln (derzeit ohne Funktion)
:* <code>S</code>: Präfix für das Aussenden von Nachrichten.
:* <code>P</code>: Prüft die Kommunikation (Ping). Antwortet mit "OK".
:* <code>CG</code>: Abfrage der Konfiguration (Config Get) aus dem EEPROM.
:* <code>CES</code>: Aktiviere Nachrichten mit Sync Puls (Config Enable Sync).
:* <code>CEC</code>: Aktiviere Nachrichten mit Manchester Code (Config Enable Manchester Code).
:* <code>CEU</code>: Aktiviere nicht synchronisierte Nachrichten (Config Enable Unsync).
:* <code>CD[SCU]</code>: Deaktivieren den entsprechenden Nachrichtentyp (z.B. <code>CDU</code> deaktiviert asynchron).
:* <code>G</code>: Veraltete Abfrage der Konfiguration, sollte mit <code>CG</code> gemacht werden.

Als erstes sollte man mit dem Terminalprogramm ein großes "P" gefolgt von den Eingabetaste eingeben.
Bei korrekter Verbindung sollte der SIGNALDuino mit "OK" antworten.

== Foren Links ==
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.nemcon.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]

[[Kategorie:HOWTOS]]
[[Kategorie:Other Components]]
[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]

Quick-Start/en

2023-11-09T10:50:38Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Hinweis|zur deutschen Version geht es [[Quick-Start|hier]]}}
==Installation==

First step is to install FHEM on your server (dedicated hardware or virtual machine). We provide instructions for different operating systems [https://fhem.de/#Installation here].

Having started FHEM the first time, please have a look at the FHEM logfile<ref>In most cases you'll find the log in <code>/opt/fhem/log</code></ref><ref>Most installations use Linux as operating system for the server. So if not stated differently, the commands and examples provided here use the syntax for Linux</ref>. The log file will look something like the following example:

<syntaxhighlight lang="text">
2018.03.09 09:17:51 1: Including fhem.cfg
2018.03.09 09:17:51 3: telnetPort: port 7072 opened
2018.03.09 09:17:51 3: WEB: port 8083 opened
2018.03.09 09:17:51 3: WEBphone: port 8084 opened
2018.03.09 09:17:51 3: WEBtablet: port 8085 opened
2018.03.09 09:17:51 2: eventTypes: loaded 0 events from ./log/eventTypes.txt
2018.03.09 09:17:51 1: usb create starting
2018.03.09 09:17:51 3: [...]
2018.03.09 09:17:51 1: usb create end
2018.03.09 09:17:51 0: Featurelevel: 5.8
2018.03.09 09:17:51 0: Server started with 9 defined entities (fhem.pl:16349/2018-03-07 perl:5.024001 os:linux user:fhem pid:9341)
</syntaxhighlight>

==Talking to FHEM==
After installation, FHEM can be accessed by a {{Link2CmdRef|Anker=FHEMWEB|Lang=en|Label=FHEMWEB}}interface to be found at the following URL:
'''http://<fhem-server>:8083/fhem'''

{{Hinweis|You may add more FHEMWEB devices. This may be helpfull in case you want to use a different style than default ''f18'' on smaller display sizes or provide pages with limited options to controll FHEM for other users. In case you need a lower level communication channel to FHEM, e.g. for scripting or emergancy cases, have a look at [[Telnet|telnet]].}}

<gallery>
datei:ErsteSchritteInFhem01.png|Desktop version of the FHEM start screen just after installation
datei:erster_aufruf_smartphone.png|Smallscreen version of the start screen
Datei:Erster_aufruf_telnet.png|A new telnet connection after issuing a ''version'' command
</gallery>

;Elements of the web interface:
*The input box at the top is used to enter commands and here referred to as "command field". Finish your typing with {{Taste|Enter}} to pass the commands to FHEM for processing.
*Left of the command field there's a symbol (+). Clicking will prompt a popup field to enter [[Import von Code Snippets|RAW-Code]] - a very effective way to enter multiple command lines in one step.
*The menu on the left starts with the item ''Save config''. FHEM allows to change its configuration at runtime. To make changes permanent and keep them available after restart of FHEM or the server hardware also, they have to be written to a configuration file<ref>In most cases this is a text file, but you may also use a database. See {{Link2CmdRef|Anker=configDB|Lang=en|Label=configDB}} for how to use a database as configuration source</ref>. If you see a red ''?'' beneath this menu item, this indicates unsaved changes of your configuration.
*Below "Save config" is a section listing the "rooms" known by FHEM. At first start you will only find the rooms ''Unsorted'' and ''Everything''. New rooms will automatically appear if you assign the respective attribute<ref>Further informationen on the terminology used in a FHEM context is provided in our [[:Kategorie:Glossary|glossary (german)]]</ref> to the devices<ref>Please note: The term "'''device'''" is often used used in the FHEM context in a special way. This could - but must not necessarily be - a physical piece of equipment. "Device" just is a term for any physical or virtual "object" that can be introduced in a FHEM system by a ''define'' or ''defmod'' command.</ref> you add later on.
*The - preliminary - last section of the menu is built by some links you might find useful.

==Securing the FHEM server component==
As you have already seen, in a fresh installation you merely have to be in the same network segment to have full access to the FHEM server. There's no encryption nor authorization by user or password. This is why you get respective warnings at FHEM's starting page.
FHEM may be secured using one of the following options:

===allowed and SSL===
These two methods may be combined and can be used to secure one or both ways (telnet and web interface) to interact with and configure FHEM. Allowed restricts access by user authentication, SSL adds transport layer encryption (HTTPS/SSL).

{{Randnotiz|RNTyp=b|RNText=For instructions on how to use FHEM commands and additional info just type <code>help <command></code> in the command field and press {{Taste|Enter}}.}}
It is recommended to define one or more ''allowed'' devices. For instructions on how to do this, please have a look at our {{Link2CmdRef|Anker=allowed|Lang=en|Label=CommandRef}} or just pass <code>help allowed</code> to the command field.

As long as there's no allowed device defined, FHEM restricts all interfaces access' to the local network.
{{Randnotiz|RNTyp=b|RNText=The notation <code><command> <parameter></code> is not only used here, but is also very common in other documents and examples you'll find when using FHEM. In these cases you are asked to replace the placeholder in the brackets (including the "<>"-brackets) by your own meaningful content.}}

Additionally you may add for your FHEMWEB device, whose sole purpose is to serve you FHEM via browser, a {{Link2CmdRef|Anker=HTTPS|Lang=en|Label=HTTPS}} attribute to activate HTTPS for http connections. For telnet (being also to some extent also a TCP/IP port) please use the {{Link2CmdRef|Anker=SSL|Lang=en|Label=SSL}} attribute.

By default, none of these securing methods is activated. If you are securing your server and FHEM by other methods you may switch off the respective warning using the global attribute {{Link2CmdRef|Anker=motd|Lang=en|Label=motd}}.

===FHEM and the WWW===
If you intend to have access to FHEM not only from your local net it is highly recommended to take additional measures. Common options are to use a VPN (Virtual Private Network) and/or a reverse proxy server like [[Apache_Authentication_Proxy|Apache]] or [[HTTPS-Absicherung_%26_Authentifizierung_via_nginx_Webserver|nginx]].

===Additional remarks on security===
Please note: Running a server system requires regular updates to the operating system and other software components installed on it. Besides that, any other components you use for home automation will contribute to the level of (non-)security of the entire system you run in the end.

==Interfaces to the real world==
{{Randnotiz|RNTyp=b|RNText=If at this point you do not have any hardware to be included in your FHEM you may follow our [[First steps in FHEM|first steps in FHEM]] to get an impression how to configure devices in FHEM.}}To get information about what is happening in the real world, you have to somehow connect FHEM with it.

Many FHEM installations use one or more USB devices (e.g. CUL, FHZ1x00, TCM, ZWave, ...) directly attached to the FHEM server for this task. To use this type of connection<ref>This also applies when devices are attached using serial interfaces provided at GPIO pins of single-board computers like the ''Raspberry Pi''.</ref> you need additional pieces of software, especially the Perl module ''serial''<ref>The Perl-''serial''-module can either be installed by issuing the <code>sudo cpan Device::SerialPort</code> command at OS level or by installing precompiled Debian packages (''libdevice-serialport-perl''). Beginning with Mac OS X 10.5 (Leopard) the module is also provided as package. If the perl module is not available for your operating system you may use the ''@directio''-option (see commandref for further information).</ref>. Have a look at the respective part of the commandref for details about the configuration of your USB device(s). The Perl module is not required if the device is connected via Ethernet (e.g. HM-LAN or CUNO).

===Automatic Configuration===
By default FHEM will try to identify commonly used USB devices like FHZ, CUL<ref>In a Linux environment, FHEM will also try to flash an attached CUL in case it's not yet programmed with firmware. For details see the descriptions of the commands <code>usb</code> and <code>CUL flash</code> in commandref.</ref>, COC, ZWave or TCM. These just have to be attached when FHEM is starting to have FHEM write the respective parts to its configuration file. When attaching devices to a running FHEM you have to issue a <code>shutdown restart</code> in the command field to start the auto configuration.

Typically you'll have to do additional configuration work also for automatically detected devices by assigning the appropriate values to attributes. You can easily get an overview of the available attributes and to some extent also a set of values for them by just clicking the name of the device shown in the respective room. New devices in most cases can be found in the room ''Unsorted''.

Once you have basic definitions of all of your USB devices it's recommended to deactivate the automatic recognition of USB devices by entering <code>attr initialUsbCheck disable 1</code> to the command field.

===Manual Configuration===
{{Randnotiz|RNTyp=g|RNText=In commandref you'll find again a notation like <code>define <name> CUL <device> <FHTID></code>. Please replace the placeholders in the brackets with own content and also delete the brackets.}}
USB devices can easily also be configured manualy, especially in cases they are not automatically detected as described above. After plugging them in, just look where these are located in your file system - typically somewhere in the directory <code>/dev</code>. E.g. a CUL will be found as a file ''/dev/ttyACM*'' in a Linux environment. Mac OS X will label the same device as ''/dev/cu.usbmodem*''. Use this description (entire path and file name) to enter the define command directly in the command field.
Examples:
*A CUL stick can be defined like this: <code>define CUL1 CUL /dev/ttyACM0@9600 1234</code><ref>Please note: the number "1234" is just an example; replace this by your own parameter</ref>
*Z-Wave controller: <code>define ZWDongle ZWDongle /dev/serial/by-id/usb-0658_0200-if00@115200</code><ref>This type of representation of the USB device in the Linux file system can also be used. To get the information in that form, you just type <code>ls -l /dev/serial/by-id</code> at operating system level</ref>

Please consult the {{Link2CmdRef|Lang=en|Label=commandref}} for further information on configuration of a specific device.

==Adding and configuring sensors and actors==

===autocreate===
By default, FHEM is also configured to automatically add to your configuration all kinds of devices it detects when running. This especially happens when you use RF equipment. FHEM will use its ''autocreate'' function as soon as the respective device sends data over the air.

So if you want to include sensors like S300 or FHT, all you have to do is to attach an appropriate USB device for reception of messages sent by your devices and wait, look out for changes in the logfile and refresh the FHEM webpage in your browser. The naming of newly detected devices is oriented on their technical parameters.

===Rename===
{{Randnotiz|RNTyp=g|RNText=When renaming a device, also the respective logfiles and weblinks will be renamed automatically. Please note: It is possible to manually rename also the weblinks or logfiles, but in this case, the corresponding main device will not be renamed alongside.}}You may use the command <code>rename</code> to change this to your needs and likes. So for example for a FHT sensor you can type in the command field:

rename FHT_1234 fht.kitchen

===Manual Definition of Devices===
If you want to manually add a device or have to do so because autocreate won't work, you have to follow these steps:

Wait until the device sends some data. In the FHEM logfile (available via the menu at "Unsorted -> FileLog -> Logfile -> text") you may see e.g. the following line:

FS20 Unknown device <HOUSECODE>, Button <BTN> Code <CDE>, please define it

Add the new device by passing the following command to the command field:

define piri1 FS20 <HOUSECODE> <BTN>

Set the appropriate ''model'' attribute:

attr piri1 model fs20piri

Once you did that, the other attributes you may set are restricted to the ones that really apply to the chosen model.
Also for other RF types of hardware devices not automatically recognized there should appear a similar line in the logfile.

The exact procedure to include other types of RF equipment typically varies.
E.g. HomeMatic devices do not necessarily need to be under full control of FHEM (paired). To be included by autocreate, a HomeMatic device has to send a pairing request, and FHEM has to enter a special mode to accept this request. Enter <code>set CUL hmPairForSec 600</code> in the command field to make the latter happen and see the manual of the device how to do it on that end. ZWave devices require a similar procedure with slightly different commands.

===Including Devices by Sending Configuration Commands===

Some types of devices require special RF commands to configure them for usage with a central unit like FHEM or to link them directly with other devices (e.g. a PIR message used directly by a switch). To include that type of hardware, you have to first manually configure FHEM to prepare it to send out these so called learning messages.

E.g. a FS20 device can be defined like this:

define lamp1 FS20 1234 56

Prepare the device by pressing its physical registration button until the LED starts blinking. Then you click on the link in the device's FHEM web page to send out the learning command. The LED should stop blinking to indicate that it now is programmed to house code 1234 and device code 56. You may also use the 4-base ELV notation instead. Once this is sucessfully done, you may again set model specific attributes to limit the available options to ones relevant for this model, e.g.:

attr lamp1 model fs20st

{{Randnotiz|RNTyp=b|RNText=Whenever there's a (FHT/HomeMatic/EnOcean or other) device visible in FHEM after automatic or manual inclusion this not necessarily means it also is fully integrated or "paired". It is highly recommended to check out first if there are still commands pending or options to be set and sent to the device first!}}Other types of RF systems (EnOcean/HomeMatic/ZWave) also need specific and substantial procedures to be followed to get these devices under full control of FHEM. Please have a look at the corresponding section of the commandref and the manual of the device before starting these procedures.

==Basics about controlling your devices==
Once your sensors and actors are correctly defined in FHEM you will be able to control any of your actors using FHEM's telnet or web interface.
{{Randnotiz|RNTyp=b|RNText=If you start with FHEM and are able to read German, it's recommended to read the [http://fhem.de/Heimautomatisierung-mit-fhem.pdf Einführung in die Automatisierung mit FHEM]. This document is - beside some details - still up to date. Although new features like the f18 style, modules like {{Link2CmdRef|Anker=allowed|Label=allowed}} or {{Link2CmdRef|Anker=DOIF|Label=DOIF}} are not covered there, and the selection of available hardware systems has continued to increase since its last update. Nevertheless, this introduction still offers a quite comprehensive overview of the general procedures and possibilities with FHEM.

The module DOIF has only a short {{Link2CmdRef|Anker=DOIF|Label=English commandref}}. The complete commandref is provided by the module maintainer only in {{Link2CmdRef|Anker=DOIF|Lang=de|Label=German with several example codes}}. If you can't understand this or don't want to get used to DOIF for this reason: you can use the full functionality of FHEM without DOIF. Use for example {{Link2CmdRef|Anker=notify|Label=notify}}, {{Link2CmdRef|Anker=at|Label=at}} and the other modules instead.}}

===Timer===
The most basic way to implement timer functionality in FHEM is to define an "at".
Examples and basic instructions you'll find in the {{Link2CmdRef|Lang=en|Anker=at|Label=commandref}}.

===Reacting on events from the real world===
If you want FHEM to react to any message sent by one or more sensors or other devices (an "event" in FHEM terminology), you use an [[event handler]].
The basic event handler in FHEM is called {{Link2CmdRef|Lang=en|Anker=notify|Label=notify}}; another one is for example {{Link2CmdRef|Lang=en|Anker=DOIF|Label=DOIF}}.

Please open a new tab in your browser with the [[Event monitor]] or open a telnet connection by:

telnet <fhemhost> 7072

Once the connection is opened type:

inform timer

Now you will see all events in the telnet connection or the Event Monitor. E.g.:

2011-12-16 21:51:55 FS20 myPiri on-for-timer 120

If you mark the line you want to react on, you may ask the assistant in the Event Monitor to help you to define a reaction to such an event. This may be something like:

define lampNotify notify myPiri set myLamp on

or

define lampNotify notify myPiri:on.* set myLamp on

To test if this notify or DOIF acts as expected you may use the <code>trigger</code> command to simulate an event in the real world. E.g.:

trigger myPiri on-for-timer 120

[[at]], [[notify]] and other [[event handler]] like {{Link2CmdRef|Anker=DOIF_|Lang=de|Label=DOIF}}<ref>[[DOIF]] combines event control, time control, state machine and frontend in one modul</ref>, {{Link2CmdRef|Anker=sequence|Lang=de|Label=sequence}}<ref>[[sequence]] handles series of [[Event|events]]</ref>, {{Link2CmdRef|Anker=watchdog|Lang=de|Label=watchdog}}<ref>[[watchdog]] reacts on missing [[Event|events]]</ref> etc. use either predefined FHEM commands, shell scripts or Perl one liners as arguments. For details and tips for Perl one liners please read the ''Perl specials'' section at the commandref.
You may use so-called regular expressions ("regex") to build more complex conditions. These regex can be applied for analysis of events and as well in the execution part of the notify. A short introduction to regex is available e.g. here: https://regex101.com/.

=== Combined time and event control ===

Combined time and event control is possible with [[DOIF/Einsteigerleitfaden,_Grundfunktionen_und_Erläuterungen#Beispiel_C.29:_Kombinierte_Ereignis-_und_Zeitsteuerung|DOIF (time and event control)]], notify and other modules.

The example shows a timespan combined with a readings value. Between 6 am and 7 pm a lamp is switched on, if the measured brightness is lower than 40. If the condition gets false, the lamp is switched off.

DOIF-Solution:
define di_lamp DOIF ([06:00-19:00] and [sensor:brightness] < 40) (set lamp on) DOELSE (set lamp off)

==Record and present data==
[[Datei:SolarthermiePlot.png|350px|thumb|right|Example: plot of a solar heat system]]

===Record data: Logging===
To save data/events/messages to a logfile, you have to create one or several {{Link2CmdRef|Anker=FileLog|Lang=en|Label=FileLog}} devices. There's a helper function called <code>autocreate</code>. This also adds a logfile to devices automatically recognized and included by the autocreate mechanism. For manually added devices you can use the option {{Link2CmdRef|Anker=createlog|Lang=en|Label=createlog}} which may be used in case you want to add additional logfiles, too. To write just one logfile for several devices to be logged combined, use an appropriate regular expression.

For subsequent graphical presentation of the logged data, FHEMWEB offers the wizard described below.

The size of each logfile will be determined by its wildcard characters (year/month/week/day). Please take a look at the {{Link2CmdRef|Anker=FileLog|Lang=en|Label=FileLog}} definition. You can enable archiving with the ''nrarchive'' or ''archivecmd'' attributes.

Take a look at {{Link2CmdRef|Anker=dblog|Lang=en|Label=dblog}} to use a database instead of a regular file for logging.

===From logged data to diagrams: Plotting===

To build diagrams out of the logged data, just click on "Create SVG instance" in the detail view of each logfile. This will direct you to the ''gplot-Editor'', a wizard guiding you through a lot of options to fulfill this task.

[[Datei:Gplot-Editor1.png]]

Choose which of your sets of data should be part of your diagram. You may also mix data originating from different sources for your diagrams. Please note: Sometimes it's necessary to click on {{Taste|write .gplot file }}, especially to get the possibility to switch between different data sources.

There's also a (German) article [[Plots_erzeugen|Plots erzeugen]] that will direct you to some practical examples. For further information also look at the commandref's {{Link2CmdRef|Anker=SVG|Lang=en|Label=SVG}} section.

To include data in your diagrams not directly logged from within FHEM, add the ''readonly'' parameter to the FileLog definition. Make sure that there are no other devices named identically and enter something like the following to the command field (usually '''''<regexp>''''' needs to be identical to the device name, i.e. '''''messages''''' in this case):
:<code>define messages FileLog /var/log/messages <regexp> readonly </code>

== Frontends: Adopting the web interface to your needs ==
So far [[FHEMWEB]] - to be exact FHEMWEB's default style "f18" has been used as user interface between you and the FHEM server. "f18" is capable to adopt the web sites to different display sizes for all kind of gadgets like mobile phones, tablets or computers.
=== Styles ===
To change FHEMWEB's look and feel, you may choose other color shemes or styles. You are not limited to just one scheme, but may use different styles or color schemes for different FHEMWEB instanzes<ref>Just use a different port for each of them</ref>. So you may see at one glance, if you are using a more administrative instance or just a very limited instance with just a few devices to interact<ref>For more info see commandref: {{Link2CmdRef|Anker=FHEMWEB|Lang=en|Label=FHEMWEB}} bzw. {{Link2CmdRef|Anker=allowed|Lang=en|Label=allowed}}</ref>.

===Rooms and groups===
It makes sense to group your devices for structured access in FHEMWEB by setting the ''room'' and/or ''group<ref>To sort groups use the ''sortby'' attribute.</ref> ''attributes, attribute ''defaultRoom'' will mark a starting page. FHEMWEB puts devices without a ''room'' attribute into the "Unsorted" room, new room names will be added to the menu on the left<ref>For even more structuring options in rooms use the delimiter "->". This will generate sub-rooms, e.g. <code>attr <device> room MyLogics->Light</code>.</ref> . Devices in the room "hidden" will not be shown by default.

You can also define a stripped down FHEMWEB instance by defining the menu entries to be hidden in the ''hiddenroom'' FHEMWEB attribute.

Edit the colors / fonts by changing the style.css ("Edit files" -> style.css) or create you own style (see stylesheetPrefix), so it won't be overwritten by the next update command.

===More options on the frontend side===
FHEMWEB offers a new style, called '''[https://forum.fhem.de/index.php?topic=82351.0 f18]'''. This overcomes the need for several FHEMWEB instances for different screen sizes. Give it a try!
Using a completely different frontend is also possible. Browse the wiki or forum board ''FHEM » Frontends'' to find the solution that fits your needs best!

==Complex structures==
Put your devices into different rooms. You can use the <code>room=<roomname></code> filter to set different devices at once. This is just a simple example: See the {{Link2CmdRef|Anker=devspec|Lang=en|Label=devspec}} section for details.
For more complex scenarios consider the {{Link2CmdRef|Anker=structure|Lang=en|Label=structure}} module. You can define different structure levels like floors, buildings, etc. and set all elements of a given structure at once.

==Shortlist: commands to learn first==
*{{Link2CmdRef|Anker=list|Lang=en|Label=list}} - ([[list|Wiki]])
*{{Link2CmdRef|Anker=define|Lang=en|Label=define}}
*{{Link2CmdRef|Anker=defmod|Lang=en|Label=defmod}}
*{{Link2CmdRef|Anker=version|Lang=en|Label=version}} - ([[version|Wiki]])
*{{Link2CmdRef|Anker=update|Lang=en|Label=update}} - ([[update|Wiki]])
*{{Link2CmdRef|Anker=shutdown|Lang=en|Label=shutdown}}
*{{Link2CmdRef|Anker=DOIF|Lang=en|Label=DOIF}} - ([[DOIF|Wiki]])
*{{Link2CmdRef|Anker=notify|Lang=en|Label=notify}} - ([[notify|Wiki]])
*{{Link2CmdRef|Anker=at|Lang=en|Label=at}} - ([[at|Wiki]])
*{{Link2CmdRef|Anker=sleep|Lang=en|Label=sleep}}
*{{Link2CmdRef|Anker=cancel|Lang=en|Label=cancel}}
*{{Link2CmdRef|Anker=watchdog|Lang=en|Label=watchdog}} - ([[watchdog|Wiki]])

==FHEM (TM) is a GPL'd perl server...==
As FHEM is written in perl, most users will be reminded of it's perl nature at some point in time. Though it may not be mandatory for FHEM users to learn perl, it's highly recommended to also have a look at this programming language for getting deeper insights in what is going on in your home automation system. As often [[Regulärer Ausdruck|regular expressions (german)]] are used within the perl code, getting familiar with this toolset is also a good idea. To solve some problems you may encounter using perl and regex is the most efficient way to go.
For first insight see {{Link2CmdRef|Anker=command|Lang=en|Label=FHEM command types}}, {{Link2CmdRef|Anker=perl|Lang=en|Label=Perl specials}} and the article [[99 myUtils anlegen|99 myUtils anlegen (german)]]. Despite beeing marked as outdated, [[DevelopmentIntroduction|this article]] and others in this sections still privide usefull futher info in English to more experienced users and experts.

==References==
<references />

[[Kategorie:FHEM]]
[[Kategorie:FHEM-Verwendung]]

Quick-Start

2023-11-09T10:50:22Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Hinweis|An english version of this document is available [[Quick-Start/en|here]]}}
==Installation==
Zunächst installieren Sie FHEM auf der von Ihnen bevorzugten Hardware (oder virtuellen Maschine). Sie finden dazu Erklärungen für die unterschiedlichsten Betriebssysteme [https://fhem.de/#Installation hier].

{{Randnotiz|RNTyp=b|RNText=Bei einer Standard-Installation unter Linux befinden sich - mit Ausnahme des für den automatischen Start erforderlichen Scripts - alle Dateien, die FHEM für den Betrieb benötigt oder anlegt im Verzeichnis <code>/opt/fhem</code> sowie den darin befindlichen Unterverzeichnissen. Denken Sie daher rechtzeitig daran, Sicherheitskopien des Verzeichnisses anzufertigen.}}Nach dem ersten Start von FHEM sehen die Einträge im FHEM-Logfile des Log-Verzeichnisses<ref>Dieses befindet sich häufig unter /opt/fhem/log</ref><ref>Hier wie im Folgenden wird davon ausgegangen, dass Sie FHEM auf einem Server mit einem Linux-Betriebssystem betreiben, sofern nicht ausdrücklich etwas anderes angegeben ist</ref> zum Beispiel wie folgt aus:

<syntaxhighlight lang="text">
2018.03.09 09:17:51 1: Including fhem.cfg
2018.03.09 09:17:51 3: telnetPort: port 7072 opened
2018.03.09 09:17:51 3: WEB: port 8083 opened
2018.03.09 09:17:51 3: WEBphone: port 8084 opened
2018.03.09 09:17:51 3: WEBtablet: port 8085 opened
2018.03.09 09:17:51 2: eventTypes: loaded 0 events from ./log/eventTypes.txt
2018.03.09 09:17:51 1: usb create starting
2018.03.09 09:17:51 3: [...]
2018.03.09 09:17:51 1: usb create end
2018.03.09 09:17:51 0: Featurelevel: 5.8
2018.03.09 09:17:51 0: Server started with 9 defined entities (fhem.pl:16349/2018-03-07 perl:5.024001 os:linux user:fhem pid:9341)
</syntaxhighlight>

==Erster Aufruf von FHEM==
Beim ersten Start ist FHEM über ein Webinterface ({{Link2CmdRef|Anker=FHEMWEB|Lang=de|Label=FHEMWEB}}) erreichbar. Die URL hierfür lautet '''http://<fhem-server>:8083/fhem'''.
{{Hinweis|Für spezielle Zwecke oder Nutzergruppen können weitere FHEMWEB-Geräte definiert werden. Dies bietet sich an, wenn man einen anderen Style als den Standard-Style f18 zusammen mit kleineren Bildschirmgrößen verwendet oder Zugänge für bestimmte Nutzergruppen mit reduziertem Funktionsumfang bereitstellen will. Daneben kann man eine [[Telnet|telnet]]-Schnittstelle<ref>Da diese das System nur gering belastet, kann darüber FHEM auch noch in Situationen erreicht und gesteuert werden, in denen FHEMWEB nicht mehr funktioniert.</ref> definieren.}}

<gallery>
datei:ErsteSchritteInFhem01.png|Die Startseite direkt nach der Installation auf einem Desktop
datei:erster_aufruf_smartphone.png|Der erste Aufruf von FHEM auf einem Smartphone
</gallery>

;Das Web-Interface kurz erklärt:
*Am oberen Bildschirmrand befindet sich ein Kommandofeld. In diesem können Befehle eingegeben werden, die FHEM nach Eingabe der {{Taste|Enter}}-Taste ausführt
*Links daneben befindet sich ein Symbol (+), über das Sie ein Eingabefeld für den [[Import von Code Snippets|Import von RAW-Code]] erreichen können
*Mit dem ersten Menüpunkt links - ''Save config'' - können Änderungen gespeichert werden. Erst dann werden werden diese in die Konfigurationsdatei geschrieben und sind somit auch noch nach einem Neustart von FHEM vorhanden. Ungespeicherte Änderungen signalisiert FHEM durch ein ''?'' neben dem Menüpunkt
*Im nächsten Abschnitt links werden alle vorhandenen Räume aufgelistet. Zu Beginn sind das nur die Räume ''Unsorted'' und ''Everything''. Weitere Räume können natürlich später angelegt werden
*Im - vorläufig - letzten Abschnitt auf der linken Seite sind einige nützliche Links untergebracht

==Absicherung der FHEM-Serverkomponente==
In der Grundkonfiguration kann jeder, der sich in dem selben Netzwerk wie der FHEM-Server befindet, unverschlüsselt und ohne der Eingabe von Benutzerdaten auf FHEM zugreifen. FHEM weist mit einer Sicherheitswarnung auf diesen Umstand hin.
Um die Installation abzusichern, bieten sich mehrere empfohlene Optionen an.

===allowed und SSL===
Mit diesen Einstellungen können beide Konfigurations-Möglichkeiten in FHEM (telnet und Webinterface) mit einem Passwort und einer Transport-Verschlüsselung (HTTPS/SSL) abgesichert werden.

{{Randnotiz|RNTyp=b|RNText=Sie erhalten für alle FHEM-Befehle die jeweilige Syntax und weitere Informationen, wenn Sie <code>help <Befehl></code> in der Kommandozeile eingeben.}}
Dazu müssen zunächst ein oder mehrere ''allowed''-'''[[Gerät|Geräte]]'''<ref>Geräte werden in FHEM oft als "'''Device'''" bezeichnet. Allerdings wird der Begriff "[[Device]]" oder "[[Gerät]]" im FHEM-Kontext etwas weiter verstanden. Dies kann, muß aber nicht zwingend ein physisches Gerät sein. Als "Device" wird schlicht alles bezeichnet, für das eine "define ..."-Anweisung existiert bzw. eingegeben wurde/wird/werden kann.</ref> definiert werden. Die Anleitung dazu findet sich in der {{Link2CmdRef|Anker=allowed|Lang=de|Label=CommandRef}} oder indem in der FHEM-Kommandozeile der Web-Schnittstelle <code>help allowed</code> eingeben wird.

Ist keine allowed-Instanz definiert, sind Zugriffe auf FHEM nur innerhalb desselben Netzwerks möglich.
{{Randnotiz|RNTyp=b|RNText=Hier wie im Folgenden und in vielen Beispielen, die in der Dokumentation zu finden sind, findet sich die Schreibweise <code><Befehl> <Parameter></code>. Dies ist so zu verstehen, dass die Angaben in der Klammer jeweils einschließlich der <>-Zeichen durch eine sinnvolle eigene Angabe zu ersetzen sind.}}

Zusätzlich kann für [[FHEMWEB]] mithilfe des [[Attribut|Attributes]] {{Link2CmdRef|Anker=HTTPS|Lang=de|Label=HTTPS}} eine HTTPS-Verbindung aktiviert werden. Für telnet (welches mehr oder weniger ein TCP/IP Port ist) wird das [[Attribut]]<ref>Weitere Informationen zu den hier verwendeten FHEM-spezifischen Begriffen finden Sie im [[:Kategorie:Glossary|Glossar]]</ref> {{Link2CmdRef|Anker=SSL|Lang=de|Label=SSL}} verwendet.

Standardmäßig ist keine dieser Einstellungen gesetzt. Um die deshalb erscheinenden Sicherheitswarnungen zu deaktivieren, kann das globale Attribut {{Link2CmdRef|Anker=motd|Lang=de|Label=motd}} verwendet werden.

===FHEM und das Internet===
Sofern FHEM nicht nur aus dem lokalen Netz erreichbar sein soll, sollten zusätzliche Sicherheitsmaßnahmen ergriffen werden. Mögliche Optionen dafür sind die Verwendung eines VPNs (Virtual Private Network) und/oder eines Reverse-Proxy-Servers mit z.B. [[Apache_Authentication_Proxy|Apache]] oder [[HTTPS-Absicherung_%26_Authentifizierung_via_nginx_Webserver|nginx]].

===Weitere Sicherheitshinweise===
Beachten Sie, dass nicht nur die Software auf Ihrem Server stets aktuell gehalten werden muss, sondern auch die von Ihnen verwendeten Komponenten maßgeblich dazu beitragen, wie sicher Ihre Hausautomatisierung insgesamt ist.

==Schnittstellen zur realen Welt==
{{Randnotiz|RNTyp=b|RNText=Sofern Sie an dieser Stelle keine konkreten Geräte haben, die Sie in Ihr FHEM einbinden wollen, können Sie mit Hilfe der [[Erste Schritte in FHEM|ersten Schritte in FHEM]] einen Eindruck gewinnen, wie Geräte in FHEM eingerichtet werden.}}Um Informationen über Ereignisse oder Zustände in der realen Welt zu erhalten, muss FHEM mit der Außenwelt verbunden werden.

Dies geschieht in vielen FHEM-Installationen durch die Verwendung eines oder mehrerer USB-Geräte (z.B. [[CUL]], [[FHZ nn00|FHZ1x00]], TCM, ZWave, etc.) welche mit dem FHEM-Server verbunden sind. Dazu werden die Perl ''serial''-Module<ref>Wenn das ''serial''-Modul benötigt wird, kann es mit dem Kommando <code>sudo cpan Device::SerialPort </code> nachträglich installiert werden. Es gibt aber auch schon bereits vorkompilierte Debian-Pakete (''libdevice-serialport-perl''). In OSX 10.5 ist das Paket ebenfalls bereits enthalten. Kann das Paket nicht installiert werden, bietet sich die ''@directio''-Option in der commandref als mögliche Informationsquelle an.</ref> benötigt. Im commandref-Abschnitt zum jeweiligen USB-Gerät ist ersichtlich, welche Module genau benötigt werden. <ref>Das gilt entsprechend, wenn Geräte über die serielle Schnittstellen eingebunden werden sollen, die an den GPIO-Schnittstellen eines Raspberry Pi verfügbar sind.</ref> Sie benötigen dieses Modul nicht, wenn das Gerät über Ethernet angeschlossen wird (z.B. [[HMLAN|HM-LAN]] oder [[CUNO]]).

===Automatische Konfiguration===
In der Standard-Konfiguration sucht FHEM beim Start automatisch nach USB-Geräten wie z.B. FHZ, [[CUL]]<ref>Unter einem Linux-Betriebssystem wird FHEM gegebenenfalls versuchen, einen bereits angesteckten aber noch unprogrammierten [[CUL]] zu programmieren. Details dazu entnehmen Sie bitte den Beschreibungen der Befehle usb und CUL flash in der commandref.</ref>
, [[COC]], ZWave oder TCM und erstellt die entsprechenden Einträge in seiner Konfigurationsdatei. Wird ein Gerät im laufenden FHEM-Betrieb angeschlossen, muss FHEM durch die Eingabe von <code>shutdown restart</code> in der Befehlszeile neu gestartet werden, bevor das Gerät verwendet werden kann.

Für automatisch eingebundene Geräte müssen in der Regel noch weitere Einstellungen vorgenommen werden. Dies erfolgt durch das Setzen entsprechender Attribute. Die verfügbaren Attribute sowie teilweise auch konkret einstellbare Werte für die Attribute können aufgerufen werden, indem auf auf das entsprechende Gerät im jeweiligen Raum geklickt wird. Neu angelegte Geräte werden im Raum ''Unsorted'' angezeigt.

Sobald die automatische Konfiguration aller zu verwendenden USB-Geräte abgeschlossen ist, sollte die automatische Erkennung durch Eingabe von <code>attr initialUsbCheck disable 1</code> in der Befehlszeile deaktiviert werden.

===Manuelle Konfiguration===
{{Randnotiz|RNTyp=g|RNText=In der Commandref findet sich in der Regel eine Darstellung in der folgenden Form: <code>define <name> CUL <device> <FHTID></code>. Dabei sind alle Angaben mit Klammern dazu gedacht, durch eigene Werte (ohne Klammern) ersetzt zu werden.}}
Um Geräte mit USB-Anschluss manuell zu definieren (oder falls FHEM diese nicht automatisch erkennt), kann - nach Anschluss des Gerätes - im Verzeichnis /dev nach der dort entsprechend eingetragenen Gerätebezeichnung gesucht werden. Für einen [[CUL]] zum Beispiel wird unter einem Linux-Betriebssystem eine Datei mit der Bezeichnung ''/dev/ttyACM*'' angelegt. Auf OS X ''/dev/cu.usbmodem*''. Mit dieser Gerätebezeichnung (also des Dateinamens) kann das Gerät manuell in der Befehlszeile angelegt werden.

*Am Beispiel eines CUL-Sticks: <code>define CUL1 CUL /dev/ttyACM0@9600 1234</code><ref>Auch hier ist die Angabe "1234" lediglich beispielhaft und durch einen eigenen Parameter zu ersetzen</ref>
*Oder eines Z-Wave-Controllers: <code>define ZWDongle ZWDongle /dev/serial/by-id/usb-0658_0200-if00@115200</code><ref>Die für diese Art der Einbindung erforderlichen Informationen erhalten Sie, indem Sie auf Betriebssystemebene <code>ls -l /dev/serial/by-id</code> eingeben</ref>

Informationen, wie genau das jeweilige Gerät angelernt wird, finden sich im zugehörigen Abschnitt der {{Link2CmdRef|Lang=de|Label=commandref}}

==Einbinden und Konfiguration von Sensoren und Aktoren==

===autocreate===
Viele funkgesteuerte [[Gerät|Geräte]] werden in der default-Konfiguration wegen der voreingestellten {{Link2CmdRef|Anker=autocreate|Lang=de|Label=autocreate}}-Funktion automatisch erstellt, sobald diese Werte senden.

Diese Funktion erzeugt automatisch beim Empfang einer Nachricht von einem Geräten (z.B. eines Sensors wie dem S300 oder FHT) ein neues [[Device]] in FHEM. Bitte warten Sie eine gewisse Zeit, beobachten Sie die Logeinträge oder den [[Event monitor|Eventmonitor]] und aktualisieren Sie Ihren Browser um neu erstellte [[Gerät|Geräte]] angezeigt zu bekommen. Die automatisch vergebenen Namen orientieren sich dabei an technischen Parametern.

===Umbenennen===
{{Randnotiz|RNTyp=g|RNText=Wenn Sie das Gerät selbst umbenennen, werden auch die zugehörigen Logfiles und Weblinks automatisch mit umbenannt. Wenn Sie dagegen die Weblinks oder Logfiles umbenennen, werden die zugehörigen Geräte nicht mit umbenannt.}}Um automatisch erstellte Geräteeinträge umzubenennen, kann der Befehl {{Link2CmdRef|Anker=rename|Lang=de|Label=rename}} verwendet werden. Geben Sie den Befehl mit den entsprechenden Parametern in der Befehlszeile der Webseite ein. Z.B.:

rename FHT_1234 fht.kitchen

===Manuelles Anlegen===
Wenn Sie das [[Gerät]] manuell anlegen wollen oder müssen, weil autocreate diese nicht anlegen kann, dann gehen Sie folgendermaßen vor:

Warten Sie eine Weile bis Daten übertragen werden. Im Logfile (zu erreichen unter Webseite Menüpunkt Unsorted-> [[FileLog]] -> Logfile -> text) erscheint z.B. folgende Textzeile:
FS20 Unknown device <HOUSECODE>, Button <BTN> Code <CDE>, please define it

Definieren Sie dieses neue Gerät mittels folgendem Eintrag:
define piri1 FS20 <HOUSECODE> <BTN>

Setzen sie das model-Attribut des Gerätes:
attr piri1 model fs20piri

Anschließend erhalten Sie nur noch die für dieses Gerät verfügbaren Attribute angezeigt. Hier sehen Sie eine komplette Liste der [[FS20]] Modelle.
Bei einem anderen neuen Gerät sollte eine ähnliche Nachricht im Logfile erscheinen.

Um [[HomeMatic]]- oder zWave-Geräte anzulernen, muss FHEM zuerst mit dem Befehl <code>set CUL hmPairForSec 600</code> in Empfangsbereitschaft versetzt werden und anschließend der Anlernknopf auf dem Gerät gedrückt werden.

===Einbinden von Geräten, die Anlernbefehle benötigen===

Manche Geräte benötigen Anlernsignale, um eine Koppelung mit anderen Geräten bzw. einer Zentrale wie FHEM herzustellen. Für solche Geräte muss zunächst manuell eine Konfiguration in FHEM vorgenommen werden, um solche Anlernsignale generieren zu können.

Definieren Sie z.B. ein [[FS20]] Gerät mit z.B. folgendem Befehl in der Befehlszeile:

define lamp1 FS20 1234 56

Dann drücken Sie den Anmeldeknopf an dem Gerät solange, bis die LED blinkt. Anschließend klicken sie auf den ''on'' Link auf der FHEM Webseite um das Einschalt-Kommando zu senden. Die LED sollte aufhören zu blinken. Das Gerät ist nun auf den Hauscode 1234 Gerätecode 56 programmiert. Sie können alternativ die 4-base ELV-Notation benutzen. Anschließend können Sie wieder modellspezifische [[Attribut|Attribute]] für das [[Gerät]] setzen. Z.B.:

attr lamp1 model fs20st

Mit diesem Eintrag bekommen Sie nunmehr wieder nur die für dieses [[Gerät]] relevanten Kommandos angezeigt.

{{Randnotiz|RNTyp=b|RNText=Das automatische oder manuelle Eintragen von FHT/HomeMatic/EnOcean-Geräten in FHEM bedeutet nicht automatisch, dass das betreffende Gerät mit FHEM gepairt ist bzw. das pairing erfolgreich abgeschlossen wurde!}}Andere Systeme (EnOcean/HomeMatic/ZWave) brauchen eine umfangreichere Prozedur und das entsprechende Gerät muss zuerst in den pairing mode versetzt werden. Bitte sehen Sie sich den entsprechenden Eintrag auf der commandref.html-Seite für Ihr [[Gerät]] zur Information an.

==Grundlegendes zum Steuern Ihrer Geräte==
Sobald Sensoren und Aktoren in FHEM eingebunden sind, können diese bereits über telnet oder die WEB-Schnittstelle gesteuert werden.
{{Randnotiz|RNTyp=b|RNText=Für Einsteiger empfiehlt sich die Lektüre der [[http://fhem.de/Heimautomatisierung-mit-fhem.pdf! Einführung in die Automatisierung mit FHEM]]. Zwar sind dort Neuerungen wie der Style [[FHEMWEB|f18]], [[set magic]], Module wie [[allowed]] oder [[DOIF]] nicht behandelt und die Auswahl an verfügbaren Hardwaresystemen hat sich seit dessen letzter Aktualisierung weiter erhöht. Dennoch bietet diese Einführung nach wie vor einen recht umfassenden Überblick in die allgemeinen Vorgehensweisen und Möglichkeiten mit FHEM.}}
Für den Aufbau einer zeit- und ereignisorientierten Steuerung werden jedoch weitere Steuerungselemente - sogenannte "'''[[Modul|Module]]'''" - benötigt. Nachfolgend sollen kurz einige der wichtigsten Module vorgestellt werden.

Unter '''[[Automatisierung]]''' stehen weitere Informationen zur Verfügung.

===Zeitabhängige Kommandos===
Zur Zeitsteuerung benötigt man einen [[Timehandler]].

===Reaktion auf Ereignisse===
[[Gerät|Geräte]] teilen bestimmte Aktualisierungen ihres Zustandes über [[Event|Events]] mit, z.B. die Änderung eines Messwertes oder eines Schaltzustandes. Die Events werden von [[Eventhandler|Eventhandlern]] empfangen und verarbeitet. Als Ergebnis der Verarbeitung werden Befehle ausgeführt.

Die einfachste Form eines [[Eventhandler|Eventhandlers]] ist ein {{Link2CmdRef|Anker=notify|Lang=de|Label=notify}} oder {{Link2CmdRef|Anker=DOIF|Lang=de|Label=DOIF}}.

Die in FHEM auftretenden Ereignisse können mit dem [[Event monitor|Eventmonitor]] angezeigt werden oder in einem mit FHEM verbundenen [[Telnet]]-Client durch den Befehl <code>inform timer</code>.

Die angezeigten [[Event|Events]] sind die wichtigste Grundlage, um einen Ereignisfilter, Suchmuster oder Auslöser zu formulieren.

Das [[Event]] wird auf die nachstehende Weise dargestellt:

2011-12-16 21:51:55 FS20 myPiri on-for-timer 120

Gemäß dieser Eventzeile können Sie eine Aktion wie folgt definieren:

define lampNotify notify myPiri set myLamp on

oder

define lampNotify notify myPiri:on.* set myLamp on

Um dieses [[notify]] zu testen können Sie die Ereignisse unter Verwendung des Befehls [[trigger]]<ref>{{Link2CmdRef|Anker=trigger|Lang=de}}</ref> simulieren. Z.B.:

trigger myPiri on-for-timer 120

[[at]], [[notify]] und andere [[Eventhandler]], wie z.B. {{Link2CmdRef|Anker=DOIF|Lang=de|Label=DOIF}}<ref>[[DOIF]] vereint Ereignissteuerung, Zeitsteuerung, Zustandsautomaten und Frontend in einem Modul</ref>, {{Link2CmdRef|Anker=sequence|Lang=de|Label=sequence}}<ref>[[sequence]] verknüpft eine Folge von [[Ereignis|Ereignissen]]</ref>, {{Link2CmdRef|Anker=watchdog|Lang=de|Label=watchdog}}<ref>[[watchdog]] reagiert auf ausbleibende [[Ereignis|Ereignisse]]</ref> usw. verwenden entweder vordefinierte FHEM-Kommandos, SHELL-Scripte oder Perl-Ausdrücke als Argumente. Für Details und Tipps zu Perl-Ausdrücken lesen Sie bitte den Abschnitt zu {{Link2CmdRef|Anker=perl|Lang=de|Label=Perl Besonderheiten}} in der commandref.
Sowohl bei der Auswertung von [[Ereignis|Ereignissen]], als auch bei den FHEM-Kommandos können Sie [[Regulärer_Ausdruck|reguläre Ausdrücke]] verwenden, sogenannte regex. Eine kurze Einführung zu regex finden Sie z.B. hier: https://regex101.com/.

=== Kombinierte Zeit- und Ereignissteuerung ===

Auch eine kombinierte Zeit- und Ereignissteuerung ist mit [[Timehandler|Timehandlern]] und [[Eventhandler|Eventhandlern]] möglich.

==== [[DOIF]]: Kombination einer Zeitspanne mit der Abfrage eines Readings ====

Zwischen 6 Uhr und 19 Uhr soll eine Lampe eingeschaltet werden, wenn die Helligkeit unter 40 gemessen wird. Sonst, wenn die Bedingung nicht zutrifft, soll die Lampe ausgeschaltet werden.
Liegt die Helligkeit zum Beginn der Zeitspanne (6 Uhr) bereits unter 40, soll die Lampe zu diesem Zeitpunkt eingeschaltet werden.
Liegt die Helligkeit zum Ende der Zeitspanne (19 Uhr) noch unter 40, soll die Lampe zu diesem Zeitpunkt ausgeschaltet werden.

Im [[Event monitor]] erscheint folgendes [[Event]], der hervorgehobene Teil des [[Event|Events]] löst die Bedingungsprüfung in [[DOIF]] aus.
2018-08-07 15:46:33.887 CUL_HM '''sensor brightness''': 39.41
Im DOIF wird der [[DOIF/Einsteigerleitfaden,_Grundfunktionen_und_Erl%C3%A4uterungen#Ausl.C3.B6ser|Auslöser]] immer in eckigen Klammern angegeben, wie hier die Zeitspanne und das [[Ereignis]]; in der Definition fett hervorgehoben. Der [[DOIF/Einsteigerleitfaden,_Grundfunktionen_und_Erl%C3%A4uterungen#Ausl.C3.B6ser|Auslöser]] für das [[Ereignis]] kann über die Kombination von [[Gerätename]] (sensor) und [[Gerätevariable]] (brightness) angegeben werden, dabei wird der Wert des [[Readings]] zurückgegeben, vergleichbar mit [[set magic]]. Die Verknüpfung von Zeitspanne und Readingsvergleich erfolgt über einen logischen Operator, dem Perl-Operator <code>and</code>. Der Wert des Readings wird mit einem Vergleichswert (40) über einen vergleichenden Operator verglichen, dem Perl-Operator <code><</code> mit der Bedeutung ''kleiner als''.
define di_lamp DOIF ('''[06:00-19:00]''' and '''[sensor:brightness]''' < 40) (set lamp on) DOELSE (set lamp off)

Das [[DOIF]] kann mit dem FHEM-Befehl setreading<ref>{{Link2CmdRef|Anker=setreading|Lang=de}}</ref> getestet werden.
setreading sensor brightness 39
Lässt das [[DOIF]] innerhalb der Zeitspanne die Lampe einschalten.
setreading sensor brightness 40
Lässt das [[DOIF]] innerhalb der Zeitspanne die Lampe ausschalten.

==Daten aufzeichnen und darstellen==
[[Datei:SolarthermiePlot.png|350px|thumb|right|Beispiel für Solarthermie]]

===Daten aufzeichnen: Loggen===
Um Daten/Nachrichten/Ereignisse für eine spätere Analyse oder grafische Darstellung aufzuzeichnen, können Sie ein oder mehrere Device/s vom Typ {{Link2CmdRef|Anker=FileLog|Lang=de|Label=FileLog}} anlegen. Die Funktion <code>autocreate</code> erstellt für neu erkannte [[Gerät|Geräte]] automatisch jeweils eine Logdatei. Sie können jedoch die Funktion {{Link2CmdRef|Anker=createlog|Lang=de|Label=createlog}} nutzen, um später eine weitere Logdatei hinzuzufügen. Wenn Sie die Daten von mehreren Geräten in einem [[FileLog]] zusammenfassen wollen, passen Sie den regulären Ausdruck (regex) entsprechend an.

[[FHEMWEB]] hat eine vordefinierte Funktionen zur Erstellung von Grafiken aus den aufgezeichneten Daten, näheres dazu im folgenden Abschnitt.

Bei [[FileLog]] können Sie die Aufzeichnungsdauer sowie Archivierungsfunktionen selbst bestimmen. Setzen Sie dazu entsprechende Logkriterien (z.B. Jahr/Monat/Woche/Tag) bzw. die Attribute ''nrarchive'' und/oder ''archivecmd''.

Wenn Sie statt [[FileLog]] lieber eine Datenbank nutzen wollen, können Sie {{Link2CmdRef|Anker=dblog|Lang=de|Label=dblog}} verwenden.

===Grafische Aufarbeitung aufgezeichneter Daten: plotten===

Um die aufgezeichneten Daten grafisch darzustellen, kann man in die Detailansicht eines FileLogs wechseln und dort auf "Create SVG instance" klicken. Damit gelangen Sie zum gplot-Editor.

[[Datei:Gplot-Editor1.png]]

In diesem können Sie nun alle Daten wählen, die grafisch dargestellt werden sollen und dabei auch Daten aus unterschiedlichen Quellen gemeinsam darstellen. Beachten Sie, dass Sie dazu ggf. Zwischenstände durch Drücken der Taste {{Taste|write .gplot file }} speichern müssen, um Daten aus anderen als der zuletzt genutzten Quelle auswählen zu können.

Im Beitrag [[Plots_erzeugen|Plots erzeugen]] sowie im Abschnitt {{Link2CmdRef|Anker=SVG|Lang=de|Label=SVG}} der commandref erhalten Sie hierzu weitere Informationen.

Um fremde (nicht unter FHEM erfasste) Daten als Plot oder als normalen Text anzuzeigen, spezifizieren Sie bitte den ''readonly'' Parameter bei der Definition des FileLog zusätzlich zu dem korrekten Dateinamen; der <regexp> Parameter sollte identisch dem Devicenamen sein (im folgenden Beispiel also '''''messages'''''):
:<code>define messages FileLog /var/log/messages <regexp> readonly </code>

== Das Web-Interface anpassen==
In der Darstellung bis hier war [[FHEMWEB]] für das Erscheinungsbild von FHEM im Browser verantwortlich, wobei der voreingestellte Style "f18" für eine dynamische Darstellung für verschiedene Bildschirmgeräte und -größen sorgt.
=== Styles ===
Sie können das Erscheinungsbild von FHEMWEB ändern, indem Sie andere Farbschemata oder andere Styles festlegen. Dabei können Sie für verschiedene Instanzen<ref>Dabei ist jeweils nur die Verwendung eines anderen Ports erforderlich</ref> auch unterschiedliche Styes verwenden und so z.B. das Aussehen/und oder die Funktionalität von FHEM verändern, je nachdem, ob FHEM zu Administrationszwecken<ref>In FHEMWEB-Instanzen, in denen code eingegeben werden soll, kann zur Unterstützung [[codemirror]] aktiviert werden.</ref> oder in der regulären Anwendung aufgerufen wird<ref>Weitere Hinweise hierzu finden Sie in der commandref zu {{Link2CmdRef|Anker=FHEMWEB|Lang=de|Label=FHEMWEB}} bzw. {{Link2CmdRef|Anker=allowed|Lang=de|Label=allowed}}</ref>.

===Räume und Gruppen===
Um die Geräte zu ordnen, bietet FHEMWEB eine Reihe von Möglichkeiten an. Es ist in der Regel zu empfehlen, alle Geräte in Räumen<ref>Um gegliederte Räume zu erzeugen, nutzen Sie den Trenner "->". Beispiel: <code>attr <device> room Steuerung->Logik</code>.</ref> zu gruppieren und auch innerhalb der Räume sinnvoll anzuordnen, indem Sie das ''group''-Attribut setzen<ref>Für die Sortierung innerhalb einer Gruppe kann das Attribut ''sortby'' genutzt werden.</ref>, mit ''defaultRoom'' läßt sich eine Startseite festlegen. FHEMWEB zeigt Geräte ohne Raum-Attribut im Raum (Menüpunkt) ''Unsorted''. Fügen Sie Geräten das ''hidden''-Raumattribut hinzu, so werden diese Geräte nicht auf der Webseite angezeigt.

Sie können ein kürzeres Menü auf der Webseite erzeugen, indem Sie Menüpunkte (bzw. Räume), die nicht angezeigt werden sollen mit dem Attribut ''hiddenroom'' versehen<ref>Darüber lassen sich auch die Anzeige von links zum Zugriff auf die Detailansichten ausschalten</ref>

Farben und Schriften können Sie durch Anpassung der Datei style.css ändern (Edit files -> style.css) oder Sie erstellen Ihren eigenen Stil (siehe auch stylesheetPrefix) dann wird Ihr neuer Stil auch nicht beim nächsten Ausführen des update-Kommandos überschrieben.
===Andere Frontends===
Neben [[FHEMWEB]] können auch andere Frontends an FHEM angebunden werden, um darüber Ihre Geräte zu steuern und darzustellen. Weiterführende Hinweise finden Sie hier im Wiki und im Forum unter ''FHEM » Frontends''.

==Komplexe Strukturen==
Um gleichzeitig verschiedene Geräte auf einmal anzusprechen, kann mit Filtern und Abfragen gearbeitet werden. Details entnehmen sie bitten dem {{Link2CmdRef|Anker=devspec|Lang=de|Label=devspec}}-Abschnitt der commandref.
Z.B. können Sie die ''room=<roomname>'' Spezifikation verwenden, um gleichzeitig alle diesem Raum zugeordneten Geräte auf einmal anzusprechen.

Für noch komplexere Szenarien informieren sie sich bitte über das {{Link2CmdRef|Anker=structure|Lang=de|Label=structure}}-Modul. Sie können verschiedene Ebenen wie Flure, Gebäude usw. definieren und alle Geräte einer definierten Struktur auf einmal ansprechen.

==Wichtige Befehle und Module für die erste Zeit==
*{{Link2CmdRef|Anker=list|Lang=de|Label=list}} - ([[list|Wiki]])
*{{Link2CmdRef|Anker=define|Lang=de|Label=define}}
*{{Link2CmdRef|Anker=defmod|Lang=de|Label=defmod}}
*{{Link2CmdRef|Anker=version|Lang=de|Label=version}} - ([[version|Wiki]])
*{{Link2CmdRef|Anker=update|Lang=de|Label=update}} - ([[update|Wiki]])
*{{Link2CmdRef|Anker=shutdown|Lang=de|Label=shutdown}}
*{{Link2CmdRef|Anker=DOIF|Lang=de|Label=DOIF}} - ([[DOIF|Wiki]])
*{{Link2CmdRef|Anker=notify|Lang=de|Label=notify}} - ([[notify|Wiki]])
*{{Link2CmdRef|Anker=at|Lang=de|Label=at}} - ([[at|Wiki]])
*{{Link2CmdRef|Anker=sleep|Lang=de|Label=sleep}}
*{{Link2CmdRef|Anker=cancel|Lang=de|Label=cancel}}
*{{Link2CmdRef|Anker=watchdog|Lang=de|Label=watchdog}} - ([[watchdog|Wiki]])

==FHEM ist ein Perl Server...==

Die meisten FHEM-Nutzer werden früher oder später daran erinnert, dass FHEM in Perl programmiert ist. Auch wenn es in vielen Fällen nicht zwingend erforderlich ist, diese Programmiersprache zu erlernen, ist es für ein vertieftes Verständnis der Funktionsweise Ihrer Hausautomatisierung hilfreich, wenn Sie sich auch mit den Grundlagen zu Perl sowie der häufig vorkommenden [[Regulärer Ausdruck|regex-Ausdrücken]] vertraut machen. Manche Problemstellungen lassen sich nach wie vor am effektivsten unmittelbar mit diesen Werkzeugen lösen.
Einen ersten Einblick in diese Themen finden Sie in den {{Link2CmdRef|Anker=command|Lang=de|Label=FHEM Befehls-Typen}}, {{Link2CmdRef|Anker=perl|Lang=de|Label=PERL Besonderheiten}} und dem Artikel zu [[99 myUtils anlegen]]. [[DevelopmentModuleIntro|In dieser Artikelserie]] sind weitere Informationen für Fortgeschrittene und Experten zu finden.

==Hinweise==
<references />

[[Kategorie:FHEM]]
[[Kategorie:FHEM-Verwendung]]

HTTPMOD

2023-11-09T10:49:22Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}

HTTPMOD provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Introduction ==
With the help of HTTPMOD you can automatically access websites, retrieve information and send data. In the simplest case, an http call is started regularly and the content of a page, for example, is read and processed further. The URL and the time interval in which the call is to be made must then be specified when the call is made. In order to read information from the called web pages, readings are required. In this readings one specifies Regex, which reads the necessary information. Here is an example.

<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 20000
</syntaxhighlight>

This creates a device that accesses the http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html website with the TV program every 20000 seconds. If neither readings nor other attributes are defined, then only the call of the website takes place and FHEM receives no further data from the web access.

But now a television program is returned when you call the website, which you might want to read out. In order to save the contents in FHEM, which are related to the ARD, you need a reading. This reading must contain a name (so that FHEM knows under which name the information is stored) and a regex (so that you know where the information is stored on the website). Since usually not one, but many readings are defined, these readings are numbered consecutively. This is done by numbers that are given immediately after the word reading. In our example this would be for example
<syntaxhighlight lang="perl">
attr PM reading1Name ARD
attr PM reading1Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>\s*(.*?)\s*<\/a>
attr PM reading2Name ARD_time
attr PM reading2Regex <span class="stationName">ARD<\/span>[\w\W]*?<td class="time">\s*(.*?)\s*<
attr PM reading3Name ARD_details
attr PM reading3Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>[\w\W]*?<\/a>\s*<br\/>\s*(.*?)(<img|<\/div)
</syntaxhighlight>

Reading1 contains the programme, reading2 the time and reading3 further details. The Regex result from the structure of the website and may have to be designed in painstaking detail.

There are cases where this is not enough. For example, it could be the case that the information from the web access is not automated, but manually received. Then a 0 must first be entered at the top of the duration. But how does HTTPMOD then know when the data should be retrieved? This is done with get-commands. If a get-command is executed, HTTPMOD accesses the website, fetches the information and fills the corresponding readings.

Again, it is possible to create not one but several get-commands. Therefore, get is always followed by (at least) one number with which the get commands are numbered. Here is another example. The TV program should be called manually and not time-controlled. To do this we first change the definition to
<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 0
</syntaxhighlight>
and add the following to the attributes
<syntaxhighlight lang="perl">
attr PM get1Name ARDHolen
</syntaxhighlight>
With the command "get PM ARDHolen" the above readings are filled. In order for FHEM to know that the other reading2, reading3, etc. are to be read as well as reading1, the (user) attribute
<syntaxhighlight lang="perl">
attr PM get1CheckAllReadings 1
</syntaxhighlight>
needs to be defined.

If the URL is not sufficient when the web page is called, but a special header is to be sent with it, this can be done with the get1Header attribute. If the header is multiline, the individual lines can be entered with get1Header1, get1Header2, and so on.

If you want to evaluate or control different URLs, you can define several get commands (get1, get2, etc.) and provide them with your own URLs. get1 usually reads only the reading1, get2 reads only the reading2 and so on. With CheckAllReadings all readings are evaluated simultaneously.

If only data is to be sent on the web page, but not read, the set command is recommended. It has the same structure as the get-command.

It becomes a bit more complex if the website requires a login check. The sid attributes are used for this purpose.

== Availability, prerequisites and definition ==
This module is part of the regular FHEM distribution and uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.
Please also note that FHEM HttpUtils need the global attribute dnsServer to be set in order to work really non blocking even when dns requests can not be answered.

The device is defined as follows
<syntaxhighlight lang="perl">
define <name> HTTPMOD <URL> <Interval>
</syntaxhighlight>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</syntaxhighlight>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds
;upgradeAttributes
:convert outdated attributes for older HTTPMOD-Versions that are still defined for this device from the old syntax to the new one.
:attributes with the description "this attribute should not be used anymore" or similar will be translated to the new syntax, e.g. readingsName1 to reading01Name.
;storeKeyValue
:stores a key value pair in an obfuscated form in the file system. Such values can then be used in replacements where the mode is "key" e.g. to avoid storing passwords in the configuration in clear text

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;enableControlSet
:enables the built in set commands ''interval'', ''stop'', ''start'', ''reread'', ''upgradeAttributes'', ''storeKeyValue''

;enableCookies
:enables the cookie handling inside HTTPMOD. It is advisable to always set this attribute and allow HTTPMOD to track the state of cookies and set them for following HTTP-requests

;enforceGoodReadingNames
:makes sure that HTTPMOD only creates readings that are allowd for Fhem (especially if reading names are dynamically created from JSON object names with extractAllJSON. It is advisable to always set this attribute.

;handleRedirects
:enables the redirect handling inside HTTPMOD which should be used together with the cookie handling of HTTPMOD. HTTPMOD will then automatically follow redirects from a web server and keep track of cookies at the same time. It is advisable to always set this attribute.

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?OExpr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?OMap
:Output Map. Defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*OMap.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;do_not_notify

;readingFnAttributes

== Simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<syntaxhighlight lang="perl">
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</syntaxhighlight>

The resulting HTTP Response would look like this:

<syntaxhighlight lang="perl">
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</syntaxhighlight>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<syntaxhighlight lang="perl">
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</syntaxhighlight>

the definition could be:
<syntaxhighlight lang="perl">
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300

attr AmbientMonitor enableControlSet 1
attr AmbientMonitor enableCookies 1
attr AmbientMonitor enforceGoodReadingNames 1
attr AmbientMonitor handleRedirects 1

attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</syntaxhighlight>

== formatting and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* <code>(reading|get)[0-9]*(-[0-9]+)?OExpr</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?OMap</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Format</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Decode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Encode</code>

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups) or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<syntaxhighlight lang="perl">
reading01Format %.1f
</syntaxhighlight>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<syntaxhighlight lang="perl">
reading01-2Format %.1f
</syntaxhighlight>

Can be used in cases where a regular expression specified as reading01regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<syntaxhighlight lang="perl">
readingFormat %.1f
</syntaxhighlight>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingOExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

Example for an expression:
<syntaxhighlight lang="perl">
attr PM reading03OExpr $val * 10
</syntaxhighlight>
Just like in the above example of the readingFormat attributes, readingOExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingOMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

Example for a map:
<syntaxhighlight lang="perl">
attr PM reading02-3OMap 0:kalt, 1:warm, 2:sehr warm
</syntaxhighlight>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<syntaxhighlight lang="perl">
attr PM getDecode UTF-8
</syntaxhighlight>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
{{Randnotiz|RNTyp=y|RNText=Starting with version ''2018-02-10'' the internal that holds the HTTP response is no longer called '''''buf''''' but rather '''''httpbody''''', and it is only displayed when attribute '''''showBody''''' is set to "1".}}
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. Please note that buf might contain special characters like newlines but they are not shown in fhemweb. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.

If there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.
Be careful if the text you are getting from your device contains special characters like newline. You don't see such special characters in the fhem webinterface as contents of the internal buf but they might cause your regular expression to fail.

If you have trouble defining a regular expression that matches a certain name, then many complicated characters and then a number, it might be helpful to use a negation in matching like <code>temp[^\d]+([\d\.]).*</code>. In this examle <code>[^\d]+</code> means any character that is not a numerical digit, more than once.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<syntaxhighlight lang="perl">
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</syntaxhighlight>

could match two numbers. When you specify only one reading02Name like
<syntaxhighlight lang="perl">
reading02Name Temp
</syntaxhighlight>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<syntaxhighlight lang="perl">
reading02-1Name
reading02-2Name
...
</syntaxhighlight>
The same notation can be used for formatting attributes like readingXOMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<syntaxhighlight lang="perl">
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</syntaxhighlight>

The data in the HTTP response looks like this:

<syntaxhighlight lang="perl">
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<syntaxhighlight lang="perl">
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</syntaxhighlight>

with JSON you can write
<syntaxhighlight lang="perl">
attr test2 get01JSON data_34.4008.value
</syntaxhighlight>
which will create a reading with the Name "Chlor" (as shown above) and take the value 0.25 from the JSON string.

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<syntaxhighlight lang="perl">
attr test2 extractAllJSON
</syntaxhighlight>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<syntaxhighlight lang="perl">
attr test2 get01ExtractAllJSON
</syntaxhighlight>
which would only apply to all data read as response to the get command defined as get01.

It might seem very simple at first sight to use extractAllJSON but if you prefer readings with a meaningful name you should instead define these readings with readingXXName and readingXXJSON or getXXName and getXXJSON individually. Of Course it would be possible to create additional user readings outside HTTPMOD but doing calculations, naming and formatting inside HTTPMOD is more efficient.

=== JSON Lists ===

imagine the HTTP Response contains:

<syntaxhighlight lang="perl">
{ "power":"0",
"modes":["Off","SimpleColor","RainbowChase"],
"code1":3,
"code2":4
}
</syntaxhighlight>

then a configuration like

<syntaxhighlight lang="perl">
attr device reading01JSON modes
attr device reading01Name Mode
</syntaxhighlight>

will create a list of Subreadings just like a regex with multiple matches can create multiple subreadings:

{| class="wikitable"
| Mode-1 || Off
|-
| Mode-2 || SimpleColor
|-
| Mode-3 || RainbowChase
|}

if you don't want several subreadings but one reading that contains the list of modes, you can specify a recombine expression:

<syntaxhighlight lang="perl">
attr device reading01Name Modes
attr device reading01RecombineExpr join ",", @matchlist
</syntaxhighlight>

which will create one reading containing a list:

{| class="wikitable"
| Modes || Off,SimpleColor,RainbowChase
|}

JSON parsing specifications also don't Need to match exactly. If there is no exact match for a defined reading, the HTTPMOD will try to Interpret the specification as a regex and look for json object paths that match the specification as a regex. For example:

<syntaxhighlight lang="perl">
attr device reading01Name CodeElem
attr device reading01JSON code
</syntaxhighlight>

which will create a list of readings:

{| class="wikitable"
| CodeElem-1|| 3
|-
| CodeElem-2 || 4
|}

and of course they could also be recombined into one reading with a RecombineExpr Attribute.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<syntaxhighlight lang="xml">
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actor>
</root>
</syntaxhighlight>

with XPath you can write
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</syntaxhighlight>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</syntaxhighlight>

will create the readings

{| class="wikitable"
| Actor-1 || Peter X
|-
| Actor-2 || Charles Y
|-
| Actor-3 || John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code>, then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.
* If the <code>replacement[0-9]*Mode</code> is <code>key</code>, then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

Example:

<syntaxhighlight lang="perl" line="1">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024

attr mydevice get05Name profile
attr mydevice get05URL http://www.mydevice.local/getprofile?password=%%password%%
attr mydevice replacement02Mode key
attr mydevice replacement02Regex %%password%%
attr mydevice replacement02Value password
</syntaxhighlight>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.

A second get will look the same except a different name and replacement value.

With the command <code>set mydevice storeKeyValue password geheim</code> you can store the password geheim in an obfuscated form in the file system.
To use this password and send it in a request you can use the above replacement with mode key. The value password will then refer to the ofuscated string stored with the key password.

The mode <code>expression</code> allows you to define your own replacement syntax:
<syntaxhighlight lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</syntaxhighlight>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

HTTPMOD has two built in replacements: One for session Ids and another one for the input value in a set command.
The placeholder $sid is always replaced with the internal <code>$hash->{sid}</code> which contains the session id after it is extracted from a previous HTTP response.
If you don't like to use the placeholder $sid then you can define your own replacement for example like:

<syntaxhighlight lang="perl">
attr mydevice replacement01Mode internal
attr mydevice replacement01Regex %session%
attr mydevice replacement01Value sid
</syntaxhighlight>

Now the internal <code>$hash->{sid}</code> will be used as a replacement for the placeholder %session%.

In the same way a value that is passed to a set-command can be put into a request with a user defined replacement.
In this case the internal <code>$hash->{value}</code> will contain the value passed to the set command.
<code>$hash->{value}</code> might even be a string containing several values that could be put into several different positions in a request by using user defined replacements.

'''Other example : steering a pellet stove from Rika'''

The stove API of Rika on https://www.rika-firenet.com/web/ delivers a JSON string with all settings and values, and can be piloted with a data string containing all the "set" values at once.

Delivered JSON on get https://www.rika-firenet.com/api/client/xxxxxxxx/status : (xxxxxxxx must be replaced with the unique stove ID)
<syntaxhighlight lang="perl">
{
"name": "Vorzimmer",
"stoveID": "xxxxxxxxx",
"lastSeenMinutes": 1,
"lastConfirmedRevision": 1504385700,
"controls": {
"revision": 1504385700,
"onOff": true,
"operatingMode": 2,
"heatingPower": 65,
"targetTemperature": 24,
"heatingTimesActive": false,
"heatingTimesActiveForComfort": true,
"setBackTemperature": 18,
"convectionFan1Active": false,
"convectionFan1Level": 0,
"convectionFan1Area": 0,
"convectionFan2Active": false,
"convectionFan2Level": 0,
"convectionFan2Area": 0,
"frostProtectionActive": false,
"frostProtectionTemperature": 5
},
"sensors": {
"statusError": 0,
"statusWarning": 0,
"statusService": 0,
"statusMainState": 1,
"statusSubState": 3,
"statusFrostStarted": false,
"inputFlameTemperature": 21,
"inputRoomTemperature": 21,
"inputExternalRequest": true,
"outputDischargeMotor": 0,
"outputInsertionMotor": 0,
"outputIDFan": 0,
"outputAirFlaps": 0,
"outputIgnition": false,
"parameterStoveTypeNumber": 13,
"parameterVersionMainBoard": 223,
"parameterVersionTFT": 223,
"parameterRuntimePellets": 11,
"parameterRuntimeLogs": 0,
"parameterFeedRateTotal": 17,
"parameterFeedRateService": 683,
"parameterOnOffCycles": 2
},
"stoveType": "DOMO MultiAir",
"stoveFeatures": {
"multiAir1": true,
"multiAir2": true,
"insertionMotor": false,
"airFlaps": false,
"logRuntime": false
}
}
</syntaxhighlight>

Data string to send to https://www.rika-firenet.com/api/client/xxxxxxxx/controls in order to set values:
<syntaxhighlight lang="perl">
heatingTimesActiveForComfort=true&frostProtectionTemperature=3&setBackTemperature=18&targetTemperature=24&convectionFan2Level=0&convectionFan2Active=false&convectionFan1Level=0&onOff=true&convectionFan1Active=false&convectionFan2Area=0&revision=1505550101&heatingTimesActive=false&convectionFan1Area=0&frostProtectionActive=false&operatingMode=2&heatingPower=65
</syntaxhighlight>

Code in 99_myUtils.pm:
<syntaxhighlight lang="perl">
use JSON;
...
sub
replaceJSON ($$) {
my ($valToReplace, $value) = @_;

#$value in the parameters is a default value
#It has to be replaced through the real value nnn passed in the set command "set <device> valToset nnn"
$value = InternalVal("Ofen", "value", $value);
Log3 ("Ofen", 3, "replaceJSON Internalvalue: $value");

#Force an update to avoid outdated revision number
fhem ("get Ofen revision");

#Get all the controls as json
my $json = ReadingsVal("Ofen", "controlsJSON","");
Log3 ("Ofen", 3, "replaceJSON configsJSON: $json");

# When starting FHEM or rereading config, the reading controlsJSON is empty
return if ($json eq "");

my $decoded = decode_json($json);
my $result;
for my $key ( keys %$decoded ) {
$result .= "$key=";
if ($key eq $valToReplace) {
$result .= $value."&";
} else {
$result .= $decoded->{$key}."&";
}
}
chop($result); #remove last &
Log3("Ofen", 3, "replaceJSON Result: $result");
return $result;
}
</syntaxhighlight>

Define stove in fhem:
<syntaxhighlight lang="perl">
defmod Ofen HTTPMOD https://www.rika-firenet.com/api/client/xxxxxxxx/status 60

attr Ofen enableCookies 1
attr Ofen reAuthRegex id="login"|Unauthorized
attr Ofen sid01Data email=xx@xx&password=xx
attr Ofen sid01URL https://www.rika-firenet.com/web/login

attr Ofen reading01JSON sensors_inputRoomTemperature
attr Ofen reading01Name RaumTemp
attr Ofen reading02JSON controls_setBackTemperature
attr Ofen reading02Name Absenkung
attr Ofen reading03JSON controls_frostProtectionTemperature
attr Ofen reading03Name Frostschutz
attr Ofen reading10Name controlsJSON
attr Ofen reading10Regex (?s)controls.*?({.*?})

attr Ofen get09Name revision
attr Ofen get09URL https://www.rika-firenet.com/api/client/xxxxxxxx/status

attr Ofen setURL https://www.rika-firenet.com/api/client/xxxxxxxx/controls
attr Ofen setData {{data}}
attr Ofen replacement01Mode expression
attr Ofen replacement01Regex {{data}}

attr Ofen set11Name frostProtectionTemperature
attr Ofen set11Replacement01Value replaceJSON("frostProtectionTemperature", 2)

attr Ofen set12Name targetTemperature
attr Ofen set12Replacement01Value replaceJSON("targetTemperature", 24)
</syntaxhighlight>

A detailed explanation (in german) of the login process can be found here: [https://forum.fhem.de/index.php/topic,76220.msg682514.html#msg682514]
and the explanation of the other parameters here: [https://forum.fhem.de/index.php/topic,76220.msg685710.html#msg685710]

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAge</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement</code>

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the <code>MaxAge</code> attributes allow. If readings are outdated, the <code>MaxAgeReplacementMode</code> defines how the affected
reading values should be replaced. <code>MaxAgeReplacementMode</code> can be <code>text</code>, <code>reading</code>, <code>internal</code>, <code>expression</code> or <code>delete</code>.

<code>MaxAge</code> specifies the number of seconds that a reading should remain untouched before it is replaced.

<code>MaxAgeReplacement</code> contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<syntaxhighlight lang="perl">
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</syntaxhighlight>
The variable <code>$val</code> contains the value of the reading before it became outdated.

Or to show that a device was offline:
<syntaxhighlight lang="perl">
attr MyLight reading01Name color
attr MyLight reading01JSON result_02_color
attr MyLight reading01MaxAge 300
attr MyLight reading01MaxAgeReplacement "offline"
attr MyLight reading01MaxAgeReplacementMode text
</syntaxhighlight>

== Note on determining how to send requests to a special device ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses. This is a tedious task but probably the best way to achieve a successful result.

Let us consider an example. The Telekom Speedport W724V has a login-site that is famous for being cumbersome. Burp allows to monitor each step in the login procedure. In the case of a speedport the following steps occur:

First burp shows that a get command is issued
##################################################################################################
GET / HTTP/1.1
Host: speedport.ip
Cache-Control: max-age=0
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Language: de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4
Cookie: lang=de
Connection: close
In order to mimic the behavior of a real person calling the website HTTPMOD should copy all necessary steps. Host, Cookie and the GET-command are usually necessary. The same cannot be said of the User-Agent because the website can be called from any mobile or desktop computer.

Then, the speedport will answer with a command that consists of several lines. By going through every line for every step in the login procedure one will finally arrive at the information that is necessary to successfully enter the login of the speedport (in case of the W724V, for example, it is necessary to copy a token called _httoken and to include the referer).

== Advanced configuration to define a <code>set</code> command and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the (numerical) value given to the set command.

This can be as simple as:
<syntaxhighlight lang="perl">
# No cyclic requests and no main URL needed in this example
define MyDevice HTTPMOD none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</syntaxhighlight>

A user command
<syntaxhighlight lang="perl">
set MyDevice Licht 1
</syntaxhighlight>

will be translated into the http GET request
<syntaxhighlight lang="perl">
http://192.168.1.22/switch=1
</syntaxhighlight>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<syntaxhighlight lang="perl">
attr MyDevive set01IMap 0:off, 1:on
</syntaxhighlight>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<syntaxhighlight lang="perl">
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</syntaxhighlight>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<syntaxhighlight lang="html">
{"set" :{"34.3118.value" :"10" }}
</syntaxhighlight>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the FHEMweb GUI.

The HTTP response to such a request will be ignored unless you specify the attribute <code>setParseResponse</code>
for all set commands or <code>set01ParseResponse</code> for the set command with number 01.
If the HTTP response to a set command is parsed then this is done like the parsing of responses to get commands and you can use the attributes ending e.g. on Format, Encode, Decode, OMap and OExpr to manipulate / format the values read.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<syntaxhighlight lang="perl">
attr PM set01TextArg
</syntaxhighlight>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<syntaxhighlight lang="perl">
attr PM set03Name On
attr PM set03NoArg
</syntaxhighlight>

== Advanced configuration to create a valid session id that might be necessary ==
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<syntaxhighlight lang="perl">
http://User:Password@192.168.1.18/something
</syntaxhighlight>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

* <code>sid[0-9]*URL</code>
* <code>sid[0-9]*Data.*</code>
* <code>sid[0-9]*Header.*</code>
* <code>sid[0-9]*IgnoreRedirects</code>
* <code>idRegex</code>
* <code>idJSON</code>
* <code>idXPath</code>
* <code>idXPath-Strict</code>
* <code>(get|set|sid)[0-9]*IdRegex</code>
* <code>(get|set|sid)[0-9]*IdJSON</code>
* <code>(get|set|sid)[0-9]*IdXPath</code>
* <code>(get|set|sid)[0-9]*IdXPath-Strict</code>

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to send a request without
doing the login procedure. If the result contains an error that authentication is necessary, then a login is performed.
To detect such an error in the HTTP response, you can again use a regular expression, JSON or XPath, this time with the attributes

* <code>reAuthRegex</code>
* <code>reAuthJSON</code>
* <code>reAuthXPath</code>
* <code>reAuthXPath-Strict</code>
* <code>(get|set)[0-9]*ReAuthRegex</code>
* <code>(get|set)[0-9]*ReAuthJSON</code>
* <code>(get|set)[0-9]*ReAuthXPath</code>
* <code>(get|set)[0-9]*ReAuthXPath-Strict</code>

reAuthJSON or reAuthXPath typically only extract one piece of data from a response.
If the existence of the specified piece of data is sufficent to start a login procedure, then nothing more needs to be defined to detect this situation.
If however the indicator is a status code that contains different values depending on a successful request and a failed request if a new authentication is needed,
then you can combine things like reAuthJSON with reAuthRegex. In this case the regex is only matched to the data extracted by JSON (or XPath).
This way you can easily extract the status code using JSON parsing and then specify the code that means "authentication needed" as a regular expression.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribute (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===
<syntaxhighlight lang="perl">
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</syntaxhighlight>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

===Another Practical Example reading the SOC from a Renault Zoe===
<syntaxhighlight lang="perl">
define myZoe HTTPMOD https://www.services.renault-ze.com/api/vehicle/VINVINVIN/battery 7000
attr myZoe userattr reading01JSON reading01Name reading02JSON reading02Name reading03JSON reading03Nam\
e reading04JSON reading04Name reading05JSON reading05Name requestHeader02 sid1Data sid1Header01 sid1Id\
JSON sid1IgnoreRedirects:0,1 sid1URL
attr myZoe reAuthJSON message
attr myZoe reading01JSON charge_level
attr myZoe reading01Name SOC
attr myZoe reading02JSON charging
attr myZoe reading02Name charging
attr myZoe reading03JSON plugged
attr myZoe reading03Name plugged
attr myZoe reading04JSON remaining_range
attr myZoe reading04Name remaining_range
attr myZoe reading05JSON last_update
attr myZoe reading05Name last_update
attr myZoe requestHeader02 Authorization: Bearer $sid
attr myZoe sid1Data {"username":"ZEUSERNAME","password":"ZEPASSWORD"}
attr myZoe sid1Header01 Content-Type: application/json
attr myZoe sid1IdJSON token
attr myZoe sid1IgnoreRedirects 1
attr myZoe sid1URL https://www.services.renault-ze.com/api/user/login
attr myZoe timeout 10
#attr myZoe verbose 7
</syntaxhighlight>

The $sid is read by logging in with username and password from JSON {"token": ..} after detecting an error {"message": ..} from a failed request. This example offers no solution for the reading of the VIN from the login request, which in turn is part of the reading URL. It should be possible to read more than just the $sid from the login sequence.

In the special case where a session id is set as a HTTP-Cookie (with the header Set-cookie: in the HTTP response) HTTPMOD offers an even simpler way. With the attribute enableCookies a very basic cookie handling mechanism is activated that stores all cookies that the server sends to the HTTPMOD device and puts them back as cookie headers in the following requests.

For such cases no sidIdRegex and no $sid in a user defined header is necessary.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue FHEM <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

When a get option is defined by attributes, the module allows querying additional values from the device that require individual HTTP-Requests or special parameters to be sent

Extension to the above example:

<syntaxhighlight lang="perl">
attr PM get01Name MyGetValue
attr PM get01URL http://MyPoolManager/cgi-bin/directory/webgui.fcgi?special=1?sid=$sid
attr PM getHeader1 Content-Type: application/json
attr PM get01Data {"get" :{"30.1234.value"}}
</syntaxhighlight>

This example defines a get option with the name MyGetValue.
By issuing <code>get PM MyGetValue</code> in FHEM, the defined HTTP request is sent to the device.
The HTTP response is then parsed using the same readingXXName and readingXXRegex attributes as above so
additional pairs will probably be needed there for additional values.

if you prefer to define the parsing and formatting of readings individually per get command, you can use
attributes like get01Regex, get01XPath, get01Format, get01OMap and so on just like for reading01...

You can also include parameters / values that are passed to the get command in the request just like for set commands.
The placeholder $val will be replaced with the value given to the get command or you can specify your own replacement as described above.

If the new get parameter should also be queried regularly, you can define the following optional attributes:

<syntaxhighlight lang="perl">
attr PM get01Poll 1
attr PM get01PollDelay 300
</syntaxhighlight>

The first attribute includes this reading in the automatic update cycle and the second defines an alternative lower update frequency. When the interval defined initially in the define is over and the normal readings are read from the device, the update function will check for additional get parameters that should be included in the update cycle.

If a PollDelay is specified for a get parameter, the update function also checks if the time passed since it has last read this value is more than the given PollDelay. If not, this reading is skipped and it will be rechecked in the next cycle when interval is over again. So the effective PollDelay will always be a multiple of the interval specified in the initial define.

Please note that each defined get command that is included in the regular update cycle will create its own HTTP request. So if you want to extract several values from the same request, it is much more efficient to do this by defining readingXXName and readingXXRegex, XPath or JSON attributes and to specify an interval and a URL in the define of the HTTPMOD device.

Example for a Siemens webserver provided by Lanhydrock:
<syntaxhighlight lang="perl">
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8OMap Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</syntaxhighlight>

== All attributes ==
;reading[0-9]+Name
:the name of a reading to extract with the corresponding readingRegex, readingJSON, readingXPath or readingXPath-Strict
:Please note that the old syntax <b>readingsName.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|set)[0-9]+Name
:Name of a get or set command
:If the HTTP response that is received after the command is parsed with an individual parse option then this name is also used as a reading name. Please note that no individual parsing needs to be defined for a get or set. If no regex, XPath or JSON is specified for the command, then HTTPMOD will try to parse the response using all the defined readingRegex, reading XPath or readingJSON attributes.

;(get|set|reading)[0-9]+Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the (get|set|reading)[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading or get or set but without the numbers in the middle, e.g. as getRegex or readingRegex, then it applies to all the other readings / get / set commands where no specific Regex is defined.<br>
:The value to extract should be in a capture group / sub expression e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)
:Using this attribute for a set command (setXXRegex) only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
:Please note that the old syntax <code>readingsRegex.*</code> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
:If for get or set commands neither a generic Regex attribute without numbers nor a specific (get|set)[0-9]+Regex attribute is specified and also no XPath or JSON parsing specification is given for the get or set command, then HTTPMOD tries to use the parsing definitions for general readings defined in reading[0-9]+Name, reading[0-9]+Regex or XPath or JSON attributes and assigns the Readings that match here.

;(get|set|reading)[0-9]+RegOpt
:Lets the user specify regular expression modifiers. For example if the same regular expression should be matched as often as possible in the HTTP response, then you can specify RegOpt g which will case the matching to be done as /regex/g
:The results will be trated the same way as multiple capture groups so the reading name will be extended with -number.
:For other possible regular expression modifiers see http://perldoc.perl.org/perlre.html#Modifiers

;(get|set|reading)[0-9]+XPath
:defines an xpath to one or more values when parsing HTML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get|set|reading[0-9]+XPath-Strict
:defines an xpath to one or more values when parsing XML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]+AutoNumLen
:In cases where a regular expression or an XPath results in multiple results and these results are stored in a common reading name with extension -number, then you can modify the format of this number to have a fixed length with leading zeros. AutoNumLen 3 for example will lead to reading names ending with -001 -002 and so on.

;(get|set|reading)[0-9]+AlwaysNum
:if set to 1 this attributes forces reading names to end with a -1, -01 (depending on the above described AutoNumLen) even if just one value is parsed.

;get|set|reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names. See the above example.
:If you don't know the paths, then start by using extractAllJSON and the use the names of the readings as values for the JSON attribute.<br>
:Please don't forget to also specify a name for a reading, get or set.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted. The list of matches will be in the variable @matchlist.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed. <br>
:If this attribute is set to 1, then additionally to the matching of the corresponding get specific regex (get[0-9]*Regex), XPath or JSON attribute also all the reading names and parse definitions defined in Reading[0-9]+Name and Reading[0-9]+Regex, XPath or JSON attributes are checked and if they match, the coresponding Readings are assigned as well.
:Please note that this does not mean that get01CheckAllReadings will cause a get02Regex to be used. Only the corresponding get01Regex will be used but additionally all the readingXYRegex attributes.
:This is automatically done if a get or set command is defined without its own parse attributes.

;(get|reading)[0-9]*OExpr
:defines an optional expression that is used in an eval to compute / format a readings value after parsing an HTTP response
:The raw value from the parsing will be in the variable $val.
:If specified as readingOExpr then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Expr.
:Please note that the old syntax <b>readingsExpr.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|reading)[0-9]*Expr
:This is the old syntax for (get|reading)[0-9]*OExpr. It should be replaced by (get|reading)[0-9]*OExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|reading)[0-9]*OMap
:Map that defines a mapping from raw value parsed to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
:If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.<br>
:The individual options in a map are separated by a komma and an optional space. Spaces are allowed to appear in a visible value however kommas are not possible.

;(get|reading)[0-9]*Map
:This is the old syntax for (get|reading)[0-9]*OMap. It should be replaced by (get|reading)[0-9]*OMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|set|reading)[0-9]*Format
:Defines a format string that will be used in sprintf to format a reading value.
:If specified without the numbers in the middle e.g. as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.<br>

;(get|set|reading)[0-9]*Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set)[0-9]*URL
:URL to be requested for the set or get command. If this option is missing, the URL specified during define will be used.

;(get|set)[0-9]*Data
:Data to be sent to the device as POST data when the get or set command is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;(get|set)[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get or set commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;(get|set)[0-9]*Header.*
:HTTP Headers to be sent to the device when the set is executed

;requestHeader.*
:Define an optional additional HTTP Header to set in the HTTP request of the main loop

;requestData
:optional POST Data to be sent in the request of the main loop. If not defined, it will be an HTTP GET request as defined in HttpUtils which is used by this module

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;(get|set)[0-9]*TextArg
:For a get command this defines that the command accepts a text value after the option name. By default a get command doesn't accept optional values after the command name.
:If TextArg is specified and a value is passed after the get name then this value can then be used in a request URL, header or data as replacement for $val or in a user defined replacement that uses the internal "value" ($hash->{value}).
:If used for a set command then it defines that the value to be set doesn't require any validation / conversion.
:The raw value is passed on as text to the device. By default a set command expects a numerical value or a text value that is converted to a numeric value using a map.

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+IExpr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Expr
:This is the old syntax for (get|reading)[0-9]*IExpr. It should be replaced by (get|reading)[0-9]*IExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+IMap
:Map that defines a mapping from raw to input values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FHEMWEB so the user can choose one of the input values.

;set[0-9]+Map
:This is the old syntax for (get|reading)[0-9]*IMap. It should be replaced by (get|reading)[0-9]*IMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*NoArg
:Defines that this set option doesn't require arguments. It allows sets like "on" or "off" without further values.

;set[0-9]*ParseResponse
:defines that the HTTP response to the set will be parsed as if it was the response to a get command.

;(get|set)[0-9]*URLExpr
:Defines a Perl expression to specify the HTTP Headers for this request. This overwrites any other header specification and should be used carefully only if needed. The original Header is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*DatExpr
:Defines a Perl expression to specify the HTTP Post data for this request. This overwrites any other post data specification and should be used carefully only if needed. The original Data is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*HdrExpr
:Defines a Perl expression to specify the URL for this request. This overwrites any other URL specification and should be used carefully only if needed. The original URL is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the (get|set)[0-9]*ReAuthRegex attributes.

;(get|set)[0-9]*ReAuthRegex
:Regex that will detect when a session has expired during a set operation and a new login needs to be performed.
:It works like the global reAuthRegex but is used for set operations.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;clearSIdBeforeAuth
:will set the session id to "" before doing the authentication steps

;authRetries
:number of retries for authentication procedure - defaults to 1

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, internal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is <code>text</code>, then value is a static text that is used as the replacement.
:If replacementMode is <code>reading</code> then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
:If replacementMode is <code>internal</code> the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
:If replacementMode is <code>expression</code> the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.
:If replacementMode is <code>key</code> then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text, expression and delete.

;get|reading[0-9]*DeleteIfUnmatched
:If set to 1 this attribute causes certain readings to be deleted when the parsing of the website does not match the specified reading. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation does not parse this reading again. This is especially useful for parsing that creates several matches / readings and the number of matches can vary from request to request. For example if reading01Regex creates 4 readings in one update cycle and in the next cycle it only matches two times then the readings containing the remaining values from the last round will be deleted.
:Please note that this mechanism will not work in all cases after a restart. Especially when a get definition does not contain its own parsing definition but ExtractAllJSON or relies on HTTPMOD to use all defined reading.* attributes to parse the responsee to a get command, old readings might not be deleted after a restart of fhem.
;get|reading[0-9]*DeleteOnError
:If set to 1 this attribute causes certain readings to be deleted when the website can not be reached and the HTTP request returns an error. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation returns an error.
The same restrictions as for DeleteIfUnmatched apply regarding a fhem restart.

;httpVersion
:defines the HTTP-Version to be sent to the server. This defaults to 1.0.

;sslVersion
:defines the SSL Version for the negotiation with the server. The attribute is evaluated by HttpUtils. If it is not specified, HttpUtils assumes SSLv23:!SSLv3:!SSLv2

;sslArgs
:defines a list that is converted to a key / value hash and gets passed to HttpUtils. To avoid certificate validation for broken servers you can for example specify
:<code>attr myDevice sslArgs SSL_verify_mode,SSL_VERIFY_NONE</code>

;alignTime
:Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the FHEM at command)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;enableControlSet
:enables the built in set commands interval, stop, start, reread, upgradeAttributes, storeKeyValue.

;enableCookies
:enables the built in cookie handling if set to 1. With cookie handling each HTTPMOD device will remember cookies that the server sets and send them back to the server in the following requests.
:This simplifies session magamenet in cases where the server uses a session ID in a cookie. In such cases enabling cookies should be sufficient and no sidRegex and no manual definition of a cookie header should be necessary.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS that contains the names of all readings that could be matched in the last request as well as UNMATCHED_READINGS and LAST_REQUEST.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR that contains the error message of the last error returned from HttpUtils.

;removeBuf
:if set to 1 then HTTPMOD removes the internal named buf when a HTTP-response has been received.
:$hash->{buf} is used internally be Fhem httpUtils and in some use cases it is desireable to remove this internal after reception
:because it contains a very long response which looks ugly in Fhemweb.

;timeout
:time in seconds to wait for an answer. Default value is 2

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Example: [https://www.goingelectric.de/forum/viewtopic.php?f=57&t=21462|Abfrage Akkustand einer Zoe und mehr von Renault ZE Services]
* Example: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Extract weather information from WeatherUnderground]]
* Example: [[Pollenflug|Pollen count]]
* Example: [[HTTPMOD Beispielkonfiguration zur Anbindung einer Daikin Klimaanlage mit WLAN-Modul|Connect Daikin aircondition to FHEM]]
* Example: [[Go-eCharger|Extract information from go-eCharger]]
* Example: [[Sonnenspeicher|Integration of energy supplies from sonnen (https://sonnenbatterie.de/en/start)]]
* Example: [https://forum.fhem.de/index.php/topic,95989.msg915870.html#msg915870 Miele 3rd party API für Miele Smarthome Geräte]
* Example: [https://forum.fhem.de/index.php/topic,84215.msg918662.html#msg918662 Honeywell Evohome Totalconnect]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg889015.html#msg889015 Tigo Energy Integration]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg708518.html#msg708518 Ecowater]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in FHEM Forum that discusses the first version of this module
* {{Link2Forum|Topic=29471|LinkText=Thread}} in FHEM Forum that discusses the second major version of this module
* {{Link2Forum|Topic=45176|LinkText=Thread}} in FHEM Forum that discusses the third major version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

FTUI Widget Svgplot

2023-11-09T10:47:32Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Infobox Modul
|ModPurpose=SVG-Diagramme in FTUI anzeigen
|ModType=x
|ModFTopic=u/i
|ModForumArea=TabletUI
|ModTechName=svgplot
|ModOwner=u/i ({{Link2FU|7023|Forum}})
}}
Das [[{{PAGENAME}}|Widget svgplot]] ist ein Widget für [[FHEM Tablet UI]] zur Anzeige bereits selbst erstellter [[SVG]]-Diagramme. 2019-01 wurde es geprüft und war funktional.

==Funktionalität==
Innerhalb einer FTUI-Oberfläche wird ein bereits verfügbares, also selbst für FHEM erstelltes [[SVG]]-Diagramm angezeigt. Das Diagramm wird aktualisiert. Weitere Funktionen (Navigation nach vergangener Zeit usw.) sind nicht vorhanden.

==Attribute==
{|class="wikitable"
!Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-device'''||zu Grunde liegendes Device||||
|-
|'''data-gplotfile'''||Name des vorhandenen (!) gplot-Files|||
|-
|'''data-logdevice'''||Name des Logfiles||||
|-
|'''data-logfile'''||||CURRENT||
|-
|'''data-refresh'''||Aktualisierung in Sekunden||||300

|}

==Beispiel==
Ein svgplot soll in der 3. Zeile, 1. Spalte beginnen und 7 Kacheln breit sowie 3 Kacheln hoch sein:
<syntaxhighlight lang="html">
<li data-row="3" data-col="1" data-sizex="7" data-sizey="3">|
<div data-type="svgplot"
data-device="SVG_Movie"
data-gplotfile="SVG_Movie"
data-logdevice="FileLog_Movie"
data-logfile="CURRENT"
data-refresh="300">
</div>
</li>
</syntaxhighlight>

==Alternatives Widget==
[[FTUI Widget Chart]] visualisiert Verläufe durch Auswertung von FHEM-Logdateien. Die Navigation über den Zeitstrahl ist gegeben.

[[Kategorie:FHEM Tablet UI|Svgplot]]

DWD OpenData

2023-11-09T10:47:02Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

{{Hinweis|Versionsänderung: Die Vorhersagedaten wurden Mitte September 2018 von CSV auf KML umgestellt. Diese Umstellung ist inkompatibel: das DWD_OpenData-Modul muss aktualisiert werden, einige Reading-Namen haben sich geändert und der Weblink muss deinstalliert und neu installiert werden (siehe diesen {{Link2Forum|Topic=83097|Message=840270|Linktext=Beitrag im Forum}}).}}

{{Infobox Modul
|ModPurpose=Daten vom DWD OpenData Server abrufen
|ModType=d
|ModCmdRef=DWD_OpenData
|ModForumArea=Unterstützende Dienste/Wettermodule
|ModTechName=55_DWD_OpenData.pm
|ModOwner=JensB ({{Link2FU|14024|Forum}}/[[Benutzer Diskussion:JensB|Wiki]])
}}

Der Deutsche Wetterdienst (DWD) stellt Wetterdaten über den [https://www.dwd.de/DE/leistungen/opendata/opendata.html Open Data Server] zur Verfügung. Die Verwendung dieses Dienstes und der vom DWD zur Verfügung gestellten Daten unterliegt den auf der OpenData Webseite beschriebenen Bedingungen. Einen Überblick über die verfügbaren Daten findet man in der Tabelle [https://www.dwd.de/DE/leistungen/opendata/help/inhalt_allgemein/opendata_content_de_en_xls.xls OpenData_weather_content.xls] oder hier: https://opendata.dwd.de/weather/lib/MetElementDefinition.xml.

== Anwendung ==
Aufgrund der unterschiedlichen vom DWD bereitgestellten Datenformate benötigt das Modul zur Dekodierung je nach gewünschtem Funktionsumfang zusätzliche Perl-Module, die nicht standardmäßig vorinstalliert sind und je nach Systemkonfiguration nachinstalliert werden müssen. Außerdem unterstützt das Modul Zeitzonen, um z.B. die Wettervorhersage internationaler Stationen in Ortszeit darstellen zu können. Hierfür sind je nach Systemkonfiguration weitere Einstellungen erforderlich. Auch die Sprache der Wochentage für die Wettervorhersage ist frei wählbar. Je nach Systemkonfiguration ist aber die Standardsprache u.U. auf Englisch eingestellt, was weitere Anpassungen der Systemkonfiguration erforderlich macht.

=== Vorbereitung ===
Im folgenden wird z.T. von einem System mit Rasbian oder Debian mit System-V Startsystem ausgegangen. Auf anderen Betriebssystemen und auf Systemen mit System-D müssen die Installationsschritte ggf. angepasst werden.

1. Für die Wettervorhersage und die Wetterwarnungen:
Installation des Perl-Moduls ''XML::LibXML'' über die System-Kommandozeile mit
<syntaxhighlight lang="bash">
sudo apt-get install libxml-libxml-perl
</syntaxhighlight>
oder mit CPAN.

2. Weiterhin ist das Perl-Modul '' DateTime'' erforderlich. Dieses lässt sich mit <source lang="bash">sudo apt-get install libdatetime-perl</source> installieren.

3. Falls man einen eigenen Internet-Proxy nutzt:
Die Konfiguration des Proxies für FHEM erfolgt z.B. durch Eintrag von
<pre>
attr global proxy <myProxyHost>:<myProxyPort>
</pre>
in die [[Konfiguration]], wobei ''myProxyHost'' durch den Namen oder die IP-Adresse des Proxy-Servers ersetzt werden muss und für ''myProxyPort'' der Port des Proxy-Servers eingetragen werden muss (oft 3128).

3. FHEM Uhrzeit und Zeitzone:
Durch Eingabe von
<pre>
{localtime()}
</pre>
in die FHEM-Kommandozeile überprüfen, ob die FHEM-Uhrzeit plausibel ist. Ist dies nicht der Fall sollten die Uhrzeit auf Systemebene überprüft werden und ggf. die Systemeinstellungen angepasst werden.
Ermitteln der Bezeichnung der eigenen Zeitzone über die System-Kommandozeile mit
<pre>
tzselect
</pre>
und diese Bezeichnung in die Datei ''/etc/timezone'' eintragen und
<pre>
export TZ=`cat /etc/timezone`
</pre>
der Datei ''/etc/profile'' hinzufügen und dann das System neu starten. Nun muss die Zeitanzeige in FHEM korrekt sein.

4. FHEM Sprache:
Durch Eingabe von
<pre>
{$ENV{LANG}}
</pre> in die FHEM-Kommandozeile überprüfen, in welcher Sprache der Wochentag angezeigt wird. Stimmt die Sprache nicht, dann auf der System-Kommandozeile
<pre>
dpkg-reconfigure locales
</pre> eingeben und aus der Liste z.B. ''de_DE.UTF-8'' zusätzlich auswählen. Dieser Befehl gilt für Debian-basierte Betriebssysteme - für andere Betriebssysteme ist eine analoge Funktion zu verwenden. Mit Eingabe von
<pre>
locale -a
</pre> auf der System-Kommandozeile überprüfen, ob die ausgewählte Sprache nun zur Verfügung steht. Sollte FHEM nach einem Neustart noch immer nicht die gewünschte Sprache verwenden, kann man auf einem System V Linux durch Hinzufügen von z.B.
<pre>
export LANG=de_DE.UTF-8
</pre> in die Datei ''/etc/init.d/fhem'' (irgendwo zwischen ''start'' und ''perl'') und erneutem Neustart von FHEM die Sprache für FHEM erzwingen. Bei einem Systemd Linux kann man die Einstellungen mit ''systemctl edit --full fhem.service'' bearbeiten. Spätestes jetzt muss die Wochentagsanzeige in FHEM korrekt sein.

5. Nur für den Weblink erforderlich:
Installation des Perl-Moduls ''DateTime'' über die System-Kommandozeile mit
<pre>
sudo apt-get install libdatetime-perl
</pre>
oder mit CPAN.

=== Define ===
Siehe {{Link2CmdRef|Anker=DWD_OpenDatadefine|Label=Commandref}}.

=== Attributes ===
Siehe {{Link2CmdRef|Anker=DWD_OpenDataattr|Label=Commandref}}.

== Anwendungsbeispiele ==
=== Beispiel zur Modul-Einrichtung ===

* Wettervorhersage
Für die Wettervorhersage muss der Stationscode ermittelt werden. Dazu den [https://www.dwd.de/DE/leistungen/met_verfahren_mosmix/mosmix_stationskatalog.pdf MOSMIX Stationskatalog] herunterladen, öffnen und die gewünschte Station heraussuchen (Spalte ''id''). Einen Teil der deutschen Stationen kann man auch der [https://www.dwd.de/DE/derdwd/messnetz/bodenbeobachtung/messnetzkarte_boden.pdf Bodenmessnetzkarte] entnehmen. Den ermittelten Stationscode kann man dann entweder für eine Einzelabfrage als Parameter für das Kommando ''get forecast'' verwenden oder für die automatische Aktualisierung als Attribut ''forecastStation'' hinterlegen. Insgesamt werden vom DWD mehr als 70 Merkmale zur Verfügung gestellt. Eine Auflistung findet sich im Dokument [https://opendata.dwd.de/weather/lib/MetElementDefinition.xml MetElementDefinition]. Nur ein kleiner Teil der Merkmale wird in der Standardeinstellung des Moduls als Reading zur Verfügung gestellt. Wer andere Merkmale benötigt muss sie mit Komma getrennt dem Attribut ''forecastProperties'' zuweisen. Es empfiehlt sich zur Performance-Optimierung sowohl das Attribut ''forecastDays'' als auch das Attribut ''forecastProperties'' auf den tatsächlichen Bedarf einzustellen.

* Wetterwarnungen
Für die Wetterwarnungen muss die Warnzelle ermittelt werden. Dazu [https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_warncellids_csv.csv Warnzellen-ID Katalog] herunterladen, öffnen und die gewünschte Warnzelle heraussuchen. Unterstützt werden Gemeinden (beginnen mit 8), Landkreise (beginnen mit 1 oder 9) oder Küste (beginnen mit 5). Die Warnzellen-ID kann man dann entweder für eine Einzelabfrage als Parameter für das Kommando ''get alerts'' verwenden oder für die automatische Aktualisierung als Attribut ''alertArea'' hinterlegen. Die Warnzellen-ID ist ab der 2. Stelle identisch mit den ersten Ziffern des amtlichen Gemeindeschlüssels. Man kann z.B. den Namen von Gemeinde oder Landkreis bei den [https://www.statistik-bw.de/Statistik-Portal/gemeindeverz.asp Statistischen Ämtern des Bundes und der Länder] eingeben, den amtlichen Gemeindeschlüssel ermitteln und dann mit vorangestellter 1, 8 oder 9 im Warnzellen-ID Katalog des DWD nach einem Eintrag mit exakter oder weitgehender Übereinstimmung suchen. Wem das zu kompliziert vorkommt, der kann bei mehrdeutigen Gemeinde- bzw. Landkreisbezeichnungen auch versuchen auszuprobieren, welche die richtige Warnzellen-ID ist.

Um das Modul mit automatisch Aktualisierung von Vorhersage und Wetterwarnungen zu nutzen, kann z.B. folgendes in die [[Konfiguration]] eingetragen werden:

<pre>
define DWD DWD_OpenData
attr DWD alertArea 111000000
attr DWD forecastStation 99810
attr DWD forecastDays 3
attr DWD forecastWW2Text 1
</pre>

* Performance
Das DWD_OpenData-Modul ist ein Datenmodul mit relativ vielen Readings. In der Standardkonfiguration wird, wie bei jedem anderen FHEM Modul, bei jeder Änderung jedes Readings ein FHEM internes Ereignis erzeugt, damit andere FHEM Devices auf diese Änderungen reagieren können. Diese Ereignisse sorgen auch dafür, dass man Änderungen in der Weboberfläche sofort angezeigt bekommt, ohne die Webseite neu aufzurufen. Interessiert sich aber kein FHEM Device für die Änderungsbenachrichtigung bestimmter Readings, entsteht unnötiger Verarbeitungs-Overhead, der je nach FHEM Konfiguration und verfügbarer CPU-Leistung auch mehrere Sekunden benötigen kann und in dieser Zeit andere Abläufe blockiert. Um die Performance zu optimieren, empfiehlt es sich, mit [[event-on-update-reading]] für eine angepasste und dadurch effizientere Verarbeitung zu sorgen, indem man nur für jene Readings Ereignisse zulässt, welche man für die Weiterverarbeitung braucht. Der DWD_OpenData_Weblink braucht z.B. gar keine Ereignisse, um zu funktionieren. Hier eine minimalistische Beispielkonfiguration:

<pre>
attr DWD event-on-update-reading state,fc_state,a_state
</pre>

Weitere Details zur Installation und Konfiguration des Moduls finden sich in der
{{Link2CmdRef|Anker=DWD_OpenData|Label=Commandref}}.

=== Beispiel für die Einrichtung eines Meteogramms ===
Um den vorhergesagten Wetterverlauf als Meteogramm in Kurvenform mit [[SVG]] darzustellen, kann man wie folgt vorgehen:

1. 99_myUtils.pm

Für die Bestimmung der Werte für den SVG-Plot wird eine Perl-Funktion benötigt, die in die Datei 99_myUtils.pm vor dem Ende eingefügt wird. Wer diese FHEM-Datei noch nicht nutzt, legt sie einfach an (siehe [[99_myUtils_anlegen]]).
<syntaxhighlight lang="perl">
package main;

use strict;
use warnings;

...

#
# (c) mumpitzstuff 19.12.2018
#
# see https://forum.fhem.de/index.php/topic,83097.msg874150.html#msg874150
#
sub logProxy_dwd2Plot($$$$;$$$)
{
my ($device, $fcValue, $from, $to, $fcHour, $expMode, $shiftTime) = @_;
my $regex;
my @rl;

return undef if(!$device);

if ($fcValue =~ s/_$//)
{
$regex = "^fc[\\d]+_[\\d]+_".$fcValue."\$";
}
else
{
$regex = "^fc[\\d]+_".$fcValue."\$";
}

$fcHour = 12 if(!defined($fcHour));
$expMode = "point" if(!defined($expMode));
#Log3 undef,2, "Regex: ".$regex;

# ermitteln aller relevanten Readings
if ( defined($defs{$device}) )
{
if ( $defs{$device}{TYPE} eq "DWD_OpenData" )
{
@rl = sort
{
my ($an) = ($a =~ m/fc(\d+)_.*/);
my ($bn) = ($b =~ m/fc(\d+)_.*/);
my ($ao) = ($a =~ m/fc\d+_(\d+).*/);
my ($bo) = ($b =~ m/fc\d+_(\d+).*/);
$an <=> $bn or $ao <=> $bo or $a cmp $b;
} ( grep /${regex}/,keys %{$defs{$device}{READINGS}} );
return undef if ( !@rl );
}
else
{
Log3 undef, 2, "logProxy_dwd2Plot: $device is not a DWD_OpenData device";
return undef;
}
}

my $fromsec = SVG_time_to_sec($from);
my $tosec = SVG_time_to_sec($to);
my $sec = $fromsec;
my ($h, $hp, $fcDay, $mday, $mon, $year);
my $timestamp;

my $reading;
my $value;
my $prev_value;
my $min = 999999;
my $max = -999999;
my $ret = "";

# while not end of plot range reached
while (($sec < $tosec) && @rl)
{
#remember previous value for start of plot range
$prev_value = $value;

$reading = shift @rl;
($fcDay) = $reading =~ m/^fc(\d+).*/;
($hp) = $reading =~ m/^fc\d+_(\d+).*/;
#Log 1, "hp: ".$hp;

if ($hp)
{
$h = ReadingsVal($device, "fc".$fcDay."_".$hp."_time", $fcHour);
if ($h =~ m/^(\d+):\d+/)
{
$h = $1;
}
}
else
{
$h = $fcHour;
}

$value = ReadingsVal($device, $reading, undef);

# calculate minutes of sunshine per hour
if ($fcValue =~ /^SunD(\d+)/)
{
if (defined($1))
{
$value = $value / ($1 * 36);
}
else
{
$value = $value / (12 * 36);
}
}

# calculate amount of rain per hour
if ($fcValue =~ /^RR(\d+)c$/)
{
if (defined($1))
{
$value /= $1;
}
}

($year, $mon, $mday) = split('\-',ReadingsVal($device, "fc".$fcDay."_date",undef));
$timestamp = sprintf("%04d-%02d-%02d_%02d:%02d:%02d", $year, $mon, $mday, $h, 0, 0);
$sec = SVG_time_to_sec($timestamp);
if (defined($shiftTime))
{
$sec += $shiftTime;
$timestamp = logProxy_shiftTime($timestamp, $shiftTime);
}

# skip all values before start of plot range
next if ( $sec < $fromsec );

# add first value at start of plot range
if ( !$ret && $prev_value )
{
$min = $prev_value if ( $prev_value < $min );
$max = $prev_value if ( $prev_value > $max );
$ret .= "$from $prev_value\n";
}

# done if after end of plot range
last if ($sec > $tosec);

$min = $value if ( $value < $min );
$max = $value if ( $value > $max );

# add actual control point
$ret .= "$timestamp $value\n";
}

if (($sec < $tosec) && !@rl && ($expMode eq "day"))
{
$timestamp = sprintf("%04d-%02d-%02d_%02d:%02d:%02d", $year, $mon, $mday, 23, 59, 59);
$_ = SVG_time_to_sec($timestamp);
if (defined($shiftTime))
{
$_ += $shiftTime;
$timestamp = logProxy_shiftTime($timestamp, $shiftTime);
}

if ($_ < $tosec)
{
$ret .= "$timestamp $value\n";
}
else
{
$ret .= "$to $value\n";
}
}
elsif (($sec > $tosec) && ($expMode eq "day"))
{
$value = $prev_value + ($value - $prev_value) * (86400 + ($tosec - $sec)) / 86400;
$ret .= "$to $value\n";
}

return ($ret, $min, $max, $prev_value);
}

1;
</syntaxhighlight>

2. LogProxy

Wer bereits ein [[logProxy]]-Device hat, muss den Namen seines logProxy-Devices in die weiter unter aufgeführte GPlot-Konfiguration eintragen. Ansonsten wird es wie folgt neu erstellt:
<pre>
define LogProxy logProxy
</pre>

3. FileLog

Das Meteogramm kennt anders als andere FHEM-Plots keine Vergangenheit außer heute. Trotzdem wird aus formalen Gründen ein [[FileLog]]-Device benötigt. Dazu kann ein beliebiges vorhandenes FileLog-Device verwendet werden. Wer will, kann hierfür aber auch ein neues FileLog Device für das DWD_OpenData-Device anlegen (Achtung: wird schnell umfangreich):
<pre>
define FileLog_DWD FileLog ./log/DWD-%Y-%m.log DWD
</pre>

Im folgenden wird für das FileLog-Device der Platzhalter ''FileLog_Dummy'' verwendet, der mit dem Namen des gewählten FileLog-Devices zu ersetzen ist.

4. SVG Plot

Das eigentliche Meteogramm ist ein SVG-Device. Will man mehrere Tage darstellen bietet sich die folgende Definition an:
<pre>
define SVG_DWD SVG FileLog_Dummy:SVG_DWD:CURRENT
attr SVG_DWD fixedoffset 6
attr SVG_DWD fixedrange 7days
attr SVG_DWD nrAxis 1,2
</pre>

Dabei muss das SVG-Attribut ''fixedoffset'' entweder gleich oder kleiner als die Einstellung des DWD_OpenData-Attributs ''forecastDays'' (Standardwert: 6 Tage) gewählt werden und das SVG-Attribut ''fixedrange'' um eins größer als ''fixedoffset'' eingestellt werden.

Will man stattdessen nur die nächsten 24 Stunden anzeigen, nimmt man folgende Einstellungen:
<pre>
define SVG_DWD SVG FileLog_Dummy:SVG_DWD:CURRENT
attr SVG_DWD endPlotNow 1
attr SVG_DWD fixedoffset 1
attr SVG_FileLog_WETTER_DWD_3 label "Tmin: $data{max1} °C, Tmax: $data{min1} °C"
attr SVG_DWD nrAxis 1,2
</pre>

Um die DWD_OpenData-Readings mit dem Plot zu verknüpfen, muss man nun die GPlot-Konfigurationsdatei des SVG-Plots manuell bearbeiten. Dazu auf den Link klicken, der im SVG_DWD-Device am Internal ''GPLOTFILE'' steht. Die y-Wertebereiche für die Regenmenge und die Temperaturen sind im Beispiel auskommentiert (Autorange). Das kann man so lassen oder man stellt sie nach den eigenen Wetter-Gegebenheiten ein. Je nach Konfiguration des DWD_OpenData-Attributs ''forecastResolution'' sind aber noch einige weitere Einstellungen anzupassen. Das folgende Beispiel ist für die 3h-Auflösung:
<pre>
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title 'Wettervorhersage'
set ytics
set y2tics
set grid ytics
set ylabel "Regen [mm]"
#set yrange [0:4]
set y2label "Temperatur [°C]"
#set y2range [-5:35]
set y3label "Wolken/Regen/Sonne [%]"
set y3range [0:100]

#LogProxy Func:logProxy_dwd2Plot("DWD","TTT_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","Tx",$from,$to,18,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","Tn",$from,$to,6,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","SunD3_",$from,$to,0,"day",(-3*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","RR3c_",$from,$to,0,"day",(-3*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","FX1_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","R600_",$from,$to,0,"day",(-3*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","Neff_",$from,$to,0,"day")
#LogProxy ConstX:TimeNow(),0,100
#LogProxy ConstY:0

plot "<IN>" using 1:2 axes x1y2 title 'T' ls l0 lw 2 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y2 title 'Tmax' ls l0dot lw 2 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y2 title 'Tmin' ls l0dot lw 2 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Sonne' ls l4fill lw 1 with lines,\
"<IN>" using 1:2 axes x1y1 title 'Regenmenge' ls l2fill lw 1 with steps,\
"<IN>" using 1:2 axes x1y3 title 'Wind' ls l1 lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Regen' ls l5fill lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Wolken' ls l6fill lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 notitle ls l5 lw 4 with lines,\
"<IN>" using 1:2 axes x1y2 notitle ls l5 lw 1 with lines
</pre>

Verwendet man dagegen eine Auflösung von 1 Stunde, sind folgende LogProxy-Einträge erforderlich:
<pre>
#LogProxy Func:logProxy_dwd2Plot("DWD","TTT_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","Tx",$from,$to,18,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","Tn",$from,$to,6,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","SunD1_",$from,$to,0,"day",(-1*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","RR1c_",$from,$to,0,"day",(-1*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","FX1_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","R101_",$from,$to,0,"day",(-0.5*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","Neff_",$from,$to,0,"day")
#LogProxy ConstX:TimeNow(),0,100
#LogProxy ConstY:0
</pre>

Für die Darstellung der nächsten 24 Stunden mit einer Auflösung von 1 Stunde nimmt man folgende GPlot-Konfiguration:
<pre>
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'
set ytics
set y2tics
set y3tics
set grid xtics y2tics
set ylabel "Regen [mm]"
set y2label "Temperatur [°C]"
set y3label "Wolken/Regen/Sonne [%]"
set y3range [0:100]

#LogProxy Func:logProxy_dwd2Plot("DWD","TTT_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","SunD1_",$from,$to,0,"day",(-1*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","RR1c_",$from,$to,0,"day",(-1*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","FX1_",$from,$to,0,"day")
#LogProxy Func:logProxy_dwd2Plot("DWD","R101_",$from,$to,0,"day",(-0.5*3600))
#LogProxy Func:logProxy_dwd2Plot("DWD","Neff_",$from,$to,0,"day")
#LogProxy ConstY:0

plot "<IN>" using 1:2 axes x1y2 title 'T' ls l0 lw 2 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Sonne' ls l4fill lw 1 with lines,\
"<IN>" using 1:2 axes x1y1 title 'Regenmenge' ls l2fill lw 1 with steps,\
"<IN>" using 1:2 axes x1y3 title 'Wind' ls l1 lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Regen' ls l5fill lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y3 title 'Wolken' ls l6fill lw 1 with quadraticSmooth,\
"<IN>" using 1:2 axes x1y2 notitle ls l2 lw 2 with lines
</pre>

Je nachdem, welche Auflösung man verwendet, werden unterschiedliche Readings des DWD_OpenData-Devices benötigt. Diese sind in den LogProxy-Zeilen in der GPlot-Konfigurationsdatei zu finden und müssen auf jeden Fall dem Attribut ''forecastProperties'' des DWD_OpenData-Device hinzugefügt werden.

Viele Detaileinstellungen des Meteogramms lassen sich individualisieren. Man kann z.B. mehr oder weniger Daten anzeigen und zumindest für ''heute'' auch aktuelle Messwerte hinzufügen.

Hier ein Beispiel für ein Meteogramm über 4 Tage mit 3 Stunden Auflösung:

[[File:DWDODmeteogram4d3h.png|500px]]

=== Beispiel für die Einrichtung eines Weblinks ===
Zur graphischen Darstellung der Vorhersage und der Wetterwarnungen mit [[FHEMWEB]] steht das Modul [https://raw.githubusercontent.com/jnsbyr/fhem/master/FHEM/99_DWD_OpenData_Weblink.pm 99_DWD_OpenData_Weblink.pm] zur Verfügung.

Zunächst die Moduldatei herunterladen und in das Modulverzeichnis ''fhem/FHEM'' kopieren. Entweder die Datei direkt auf den FHEM-Server herunterladen (z.B. mit ''wget'') oder beim indirekten Herunterladen darauf achten, dass dabei das Encoding nicht verändert wird (also z.B. bei WinSCP den Binär-Modus und nicht den Text-Modus verwenden). Ansonsten werden später z.B. Sonderzeichen wie ''°C'' falsch angezeigt.

Anschließend kann in die [[Konfiguration]] z.B. folgendes eingetragen werden:

<pre>
define DWD_Weblink_Generator DWD_OpenData_Weblink
attr DWD_Weblink_Generator IODev DWD
attr DWD_Weblink_Generator forecastDays 4
# refreshRate nur dann setzten, wenn der Browser Java-Script beherrscht:
attr DWD_Weblink_Generator refreshRate 900

define DWD_Weblink weblink htmlCode { DWD_OpenData_Weblink::AsHtmlH("DWD_Weblink_Generator") }
</pre>

Damit legt man das Weblink-Generator-Device an und verknüpft es mit dem DWD_OpenData-Device. Außerdem wird der [[weblink ]] selbst angelegt, der seinerseits mit dem Weblink-Generator-Device verknüpft wird. Der Weblink benötigt für seine Funktion eine bestimmte Auswahl der Vorhersage-Merkmale. Wer das Attribut ''forecastProperties'' des DWD_OpenData-Moduls anpassen will, muss diese Merkmale auf jeden Fall mit berücksichtigen.

Wenn vom Weblink nichts im Browser zu sehen ist, kann das daran liegen, dass der Browser kein aktuelles JavaScript verwendet oder JavaScript deaktiviert ist. Dann sollte das Attribut ''refreshRate'' auf 0 Sekunden eingestellt oder gelöscht werden. Mit aktiviertem Refresh werden die Daten auch ohne Seitenneuaufbau regelmäßig und bei Tab-Wechsel aktualisiert.

Die Liste der erforderlichen Vorhersage-Merkmale finden sich zusammen mit allen weiteren Details zur Installation und Konfiguration in der Modulhilfe von ''99_DWD_OpenData_Weblink.pm'', die man z.B. nach dem Anlegen des Weblink-Generator-Devices über die Weboberfläche abrufen kann.

Hier ein Ausschnitt aus der Darstellung des Weblinks mit [[FHEMWEB]]:

[[File:DWDODweblink.png|500px]]

99 myUtils anlegen

2023-11-09T10:45:34Z

Drhirn: veraltete "source"-Angaben in "syntaxhighlight" geändert

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:

<syntaxhighlight lang="perl">
package main;
use strict;
use warnings;

sub
myUtils_Initialize($$)
{
my ($hash) = @_;
}
1;
</syntaxhighlight>

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:

<syntaxhighlight 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;</syntaxhighlight>
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:

<syntaxhighlight lang="perl">define test at *09:00 { wakeup($we, "Schlafzimmerlampe") }</syntaxhighlight>
Die Deklaration der Routine in Ihrer Programmdatei muss dann so beginnen:

<syntaxhighlight lang="perl">#Nur am Wochenende eingeschaltet
sub wakeup($$) {
my ($wochenende, $device) = @_;
if ($wochenende) {
fhem( "set $device on" );
}
else {
fhem( "set $device off" );
}
}</syntaxhighlight>
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:

<syntaxhighlight lang="perl">sub parameterlos() {
...
}</syntaxhighlight>
{ 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
<syntaxhighlight lang="perl">
=pod
=begin html

<a id="myUtils"></a>
<h3>myUtils</h3>
<ul>
<b>Name</b>
<br>
Text<br>
Examples:
<ul>
<code>Example Code </code><br>
</ul>
</ul>

=end html
=begin html_DE

<a id="myUtils"></a>
<h3>myUtils</h3>

=end html_DE
=cut
</syntaxhighlight>

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:
<syntaxhighlight lang="perl">{system("/usr/bin/perl ./contrib/commandref_join.pl")}</syntaxhighlight>
Für eine schnelle Überprüfung des Commandrefeintrages können Sie auch <syntaxhighlight lang="perl">help myUtils</syntaxhighlight> (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]]

PRESENCE

2023-11-09T10:36:56Z

Drhirn: Erklärung zu ble2mqtt und Link auf dessen Wiki-Seite ergänzt

{{Infobox Modul
|ModPurpose=Anwesenheitserkennung
|ModType=h
|ModForumArea=Unterstützende Dienste
|ModTechName=73_PRESENCE.pm
|ModOwner=Jörg/JoWiemann ({{Link2FU|94|Forum}} / [[Benutzer Diskussion:JoWiemann|Wiki]])
}}

Das [[PRESENCE]] Modul bietet für die Anwesenheitserkennung mehrere Varianten an:

* '''lan-ping''' - Das Überwachen via PING Checks, die durch den FHEM Server versandt werden.
* '''fritzbox''' - Das Überwachen von Geräten auf einer FritzBox via ctlmgr_ctl (Nur auf einer FritzBox möglich)
* ''' Bluetooth'''
:- '''local-bluetooth''' - Das Überwachen via Bluetooth Checks, die vom FHEM Server direkt durchgeführt werden (angeschlossener Bluetooth-Stick und die Software bluez voraussgesetzt)
:- '''lan-bluetooth''' - Das Überwachen von Bluetoothgeräten, über Netzwerk. Auf einer oder mehreren Maschinen im Netzwerk (z.B. [[:Kategorie:Raspberry Pi|Raspberry Pi]]) läuft ein Presence-Daemon, der nach Bluetooth-Geräten sucht. Um mehrere Presence-Daemon mit FHEM zu verbinden, gibt es den Collector-Daemon, der sich zu allen Presence-Damons im Netzwerk verbindet und das Ergebnis von allen zusammenfasst.
* '''function''' - Das Überwachen mithilfe einer selbst geschrieben Perl-Funktion, die den Anwesenheitsstatus zurückgibt (0 oder 1)
* '''shell-script''' - Das Überwachen mithilfe eines selbst geschriebenen Shell-Programms/Skript, das eine 0 oder 1 ausgibt, um den Anwesenheitsstatus mitzuteilen.

= Überwachen mittels Ping im WLAN/LAN =
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Um ein Gerät via Ping zu überwachen, muss folgende Definition durchgeführt werden:
:<code>define Handy PRESENCE lan-ping 192.168.0.30</code>

Dadurch wird die IP-Addresse 192.168.0.30 alle 30 Sekunden geprüft, ob sie erreichbar ist. Wenn sie erreichbar ist, ist der Status "present" (anwesend), ansonsten "absent" (abwesend).

Der Timeout kann verändert werden, indem ein Wert (in Sekunden) an das Define anhängt wird:
:<code>define Handy PRESENCE lan-ping 192.168.0.30 '''60'''</code>

Nun würde das Handy alle 60 Sekunden geprüft werden.

Nur wenn bei einem iPhone/iPad die Funktion "über WLAN synchronisieren" aktiviert ist, ist es auch im Standby zuverlässig pingbar. Standardmäßig deaktivieren Apple-Geräte ihr WLAN im Standby-Betrieb um die Akkulaufzeit zu verlängern.

Sollte die Fehlermeldung
:<code> PRESENCE (Handy) - ping command returned with output: ping: icmp open socket: Operation not permitted </code>
im Log auftauchen und lan-ping dadurch nicht funktionieren, liegt ein Berechtigungsproblem vor. Kein Grund den User fhem zu root zu machen!
Prüfe zu erst als User root ob die Capabilities gesetzt sind.
:<code>getcap /bin/ping</code>
Sollte folgendes Ergeben zu Tage fördern.
:<code>/bin/ping = cap_net_raw+ep</code>
Ist dem nicht so, setzen wir die benötigten Capabilities
:<code>setcap cap_net_raw+ep /bin/ping</code>
Mehr Informationen zum Thema Capabilities [https://manpages.debian.org/jessie/manpages-de/capabilities.7.de.html].

= FritzBox: direktes Abfragen der Aktivität via ctlmgr_ctl =
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Eine sehr häufige und auch zuverlässige Methode ist auf einer FritzBox die Abfrage mittels ctlmgr_ctl Befehl. Über diesen lassen sich alle Geräte abfragen ob sie aktiv sind. Ist ein Gerät aktiv, so gilt es als anwesend.

Dieser Modus kann allerdings nur in FHEM Installationen direkt auf einer FritzBox verwendet werden. Des weiteren muss FHEM unter dem User root laufen. Um ein Gerät zu überwachen, wird lediglich der Gerätename benötigt, so wie er unter dem Menüpunkt "Heimnetz" auftaucht.

Die erforderliche Definition:
:<code>define Handy PRESENCE fritzbox iPhone-4S</code>

= Überwachung mittels Perl-Code =
Es ist möglich zum Überwachen von Geräten eine eigene Perl-Funktion zu verwenden die dann vom PRESENCE Modul im Hintergrund aufgerufen wird.

define <name> PRESENCE function {...} [ <check-interval> [ <present-check-interval> ] ]

Sobald die Funktion den Rückgabewert 1 hat, ist das Gerät anwesend, bei 0 abwesend.

== Beispiel DHCP Überwachung auf Airport Basestation ==
Die hier vorgestellte Überwachung der DHCP Lease auf Airport Basestations per SNMP ist absolut robust gegenüber dem Ruhezustand von iOS und setzt keine weitere Konfiguration auf dem iPhone voraus. Das Abmelden beim Verlassen des Empfangsbereiches der Basestation geschieht mit etwa 5-10 Minuten Verzögerung und ist somit auch vor kurzzeitigen Empfangsproblemen sicher. Das nebenstehende Bild (???) verdeutlicht noch mal die Unterschiede zwischen einer IP-Basierten Ping-Überwachung und der Überwachung auf Ebene der Basestation oder FritzBox.

Bevor der folgende Code verwendet werden kann ist das Perl Modul Net:SNMP zu installieren (z. B. mit: <code>cpan install use Net::SNMP</code>).

Zuerst ist folgender Code in 99_myUtils.pm einzufügen, sollte diese noch nicht vorhanden sein muss diese aus dem Template welches unter Edit Files zu finden ist erzeugt werden.
'''Achtung, das ist nicht der komplette Inhalt der 99_myUtils!''' Das ist nur die einzelne Routine

<pre>
use Net::SNMP;
sub
snmpCheck($$)
{
my ($airport,$client)= @_;

my $community = "public";
my $host = $airport;
my $oid = ".1.3.6.1.2.1.3.1.1.2";
#my $oid = ".1.3.6.1.2.1.3.1.1.2.25.1.10.0.1";

my ( $session, $error ) = Net::SNMP->session(
-hostname => $host,
-community => $community,
-port => 161,
-version => 1
);

if( !defined($session) ) {
return 0;
return "Can't connect to host $host.";
}

my @snmpoids = ();

my $response = $session->get_next_request($oid);
my @nextid = keys %$response;
while ( @nextid && $nextid[0] && $nextid[0] =~ m/^$oid/ ) {
push( @snmpoids, $nextid[0] );

$response = $session->get_next_request( $nextid[0] );
@nextid = keys %$response;
}

if( !defined($response = $session->get_request( @snmpoids ) ) ) {
return 0;
}

foreach my $value (values %$response) {
return 1 if( $value eq $client )
}

return 0;
}
</pre>

Danach lässt sich das Mobilgerät so überwachen:
:<code>define iPhone PRESENCE function {snmpCheck("10.0.1.1","0x44d77429f35c")} 30 30</code>

wobei 10.0.1.1 durch die IP-Adresse der Basestation und 0x44d77429f35c durch die MAC Adresse des Geräts als HEX-Zahl ersetzt werden muss.

== Beispiel Anwesenheitserkennung mittels UniFi Controller ==

Die Anwesenheitserkennung bei Geräten in Verbindung mit UniFi-Produkten funktioniert selbst dann, wenn sich die Geräte im PowerSave-Modus befinden.

Beachte: Die Geräte werden erst ungefähr nach 5 Minuten, nachdem das Gerät das WLAN verlassen hat als disconnected angezeigt.

<code>define <NAME> PRESENCE function {ReadingsVal("<UniFi>","<NamedDevice>","") eq "connected" ? 1:0}</code>

= Überwachen mittels Events =
Der Vorteil gegenüber der Function-Variante ist, dass diese Variante ohne Blocking.pm-Overhead direkt ausgeführt werden kann und in "Echtzeit" abläuft (siehe {{Link2Forum|Topic=40287|Message=562823}}).

<code>define <NAME> PRESENCE event UniFi:NamedDevice:.disconnected UniFi:NamedDevice:.connected</code>

Dabei wird <UniFi> mit dem Namen des Unifi-Devices in FHEM ersetzt, <NamedDevice> mit dem Namen des zu überwachenden Devices im Unifi-Controller ersetzt.

= Überwachen mittels Bluetooth =
== Vorbereitung und Informationen ==
=== Getestete Hardware/Software ===
* '''Raspbian System''' - wheezy, Jessie (interner BT-Controller)
* '''BT-Dongle''' - CSL NET BT USB2.0 Stick, Bluetooth V4.0, Nano <br />'''Achtung''': Es muss ein BT V4.0 oder höher verwendet werden. Nur dieser unterstützt ''LowEnergy''
* '''BT-TAG''' - Gtag von Gigaset, TrackR, UDOO Neo, PebbleBee, iTag von Unitec, X4-LIFE Multifunkti BL-Anhänger, iTag Wireless Anti, Trackr bravo, GhostyuBeacon iBc41

=== BT-Dongle am RaspberryPI installieren ===
Um den BT-Dongle ''(hier: CSL NET BT USB2.0)'' am RaspberryPI verwenden zu können, müssen die notwendigen Pakete über die Paketverwaltung von debian nachinstalliert werden.
Wer bereits ein BT-Dongle installiert hat, kann diesen Schritt überspringen.
<pre>
apt-get install bluetooth
</pre>
Nach erfolgreicher Installation der Pakete sollte der RaspberryPI neu gestartet werden.
<pre>
sudo reboot
</pre>

Nach dem erfolgten Reboot bitte das Log des RaspberryPI auf folgende Einträge prüfen:
<pre>
Feb 12 19:52:55 fhem kernel: [ 4.773600] Bluetooth: Core ver 2.20
Feb 12 19:52:55 fhem kernel: [ 4.773748] NET: Registered protocol family 31
Feb 12 19:52:55 fhem kernel: [ 4.773765] Bluetooth: HCI device and connection manager initialized
Feb 12 19:52:55 fhem kernel: [ 4.773797] Bluetooth: HCI socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.773821] Bluetooth: L2CAP socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.773890] Bluetooth: SCO socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.797531] usbcore: registered new interface driver btusb
</pre>
Sobald der BT-Dongle erkannt wurde ''leuchtet'' (wenn vorhanden) auch die ''blaue/gelbe'' LED am Dongle auf.

=== BT-Tags aktivieren ===
Jetzt kann der BT-Tag aktiviert werden. Bei einigen BT-Tags muss dafür die '''Batteriesicherung''' gezogen werden.

Ein BT-Tag wird mit folgendem Befehl auf der Konsole gesucht:
<syntaxhighlight lang="bash">
sudo hcitool lescan

Ausgabe z.B.:
LE Scan ...
7C:2F:80:A1:XA:XD (unknown)
7C:2F:80:A1:XA:XD Gigaset G-tag
7C:2F:80:A1:X4:X1 (unknown)</syntaxhighlight>
Eine Übersicht über die möglichen Befehle von hcitool gibt es mit der Eingabe von:
<pre>
sudo hcitool

Ausgabe z.B.:
hcitool - HCI Tool ver 5.23
Usage:
hcitool [options] <command> [command parameters]
Options:
--help Display help
-i dev HCI device
Commands:
dev Display local devices
inq Inquire remote devices
scan Scan for remote devices
name Get name from remote device
info Get information from remote device
spinq Start periodic inquiry
epinq Exit periodic inquiry
cmd Submit arbitrary HCI commands
con Display active connections
cc Create connection to remote device
dc Disconnect from remote device
sr Switch master/slave role
cpt Change connection packet type
rssi Display connection RSSI
lq Display link quality
tpl Display transmit power level
afh Display AFH channel map
lp Set/display link policy settings
lst Set/display link supervision timeout
auth Request authentication
enc Set connection encryption
key Change connection link key
clkoff Read clock offset
clock Read local or remote clock
lescan Start LE scan
lewladd Add device to LE White List
lewlrm Remove device from LE White List
lewlsz Read size of LE White List
lewlclr Clear LE White list
lecc Create a LE Connection
ledc Disconnect a LE Connection
lecup LE Connection Update
</pre>

Falls beim SCAN kein BT-Tag gefunden wird, sollte das BT Interface neu gestartet werden. Dazu ist kein Reboot des RaspBerryPI notwendig.
<syntaxhighlight lang="bash">
sudo hciconfig hci0 down
sudo hciconfig hci0 up
sudo hcitool dev
</syntaxhighlight>

== Überwachung durch den FHEM Server direkt ==
[[Datei:Bluetooth-Adresse-iPhone.png|thumb|Bluetooth-Adresse eines iPhones]]
Jenach Aufstellungsort des FHEM Servers kann es sinnvoll sein, eine Bluetooth-Überwachung direkt durch den FHEM Server durchzuführen. Hierbei gilt allerdings zu beachten, dass Bluetooth nicht für große Reichweiten gedacht ist und in den meisten Fällen keine Wände überwinden kann. Das heisst, dass in den meisten Fällen damit nur ein Raum überwacht werden kann.

Je nach Einsatzzweck kann das auch so gewollt sein. Bluetooth USB Sticks, die bereits Bluetooth 4.0 unterstützen, können höhere Reichweiten über Zimmerwände hinaus erreichen. Vorausgesetzt, das Mobilgerät unterstützt Bluetooth 4.0.

Um eine Überwachung per Bluetooth durchführen zu können, benötigt man die Bluetooth-Adresse eines Gerätes. Diese ähnelt vom Aufbau einer MAC-Adresse. Generell wird die Adresse in den Telefon-Informationen bei Smartphones angezeigt.

Um eine Anwesenheitserkennung via Bluetooth durchzuführen, wird folgende Definition in der [[Konfiguration]] benötigt:
:<code>define Handy PRESENCE local-bluetooth XX:XX:XX:XX:XX:XX</code>

== Überwachung durch verteilte Agenten in der Wohnung (presenced/lepresenced/collectord/ble2mqtt) ==
[[Datei:Raspberry-Pi-mit-WLAN-und-Bluetooth-Stick.jpg|thumb|left|Raspberry Pi mit Bluetooth- und WLAN-USB-Stick]]
Um eine zuverlässige und flächendeckende Bluetooth-Anwesenheitserkennung durchzuführen, ist es unerlässlich, mehrere Bluetooth-Empfänger zu verwenden, die auf mehrere oder alle Räume verteilt sind.

Hierfür bietet sich zum Beispiel ein [[Raspberry Pi]] mit einem Mini-Bluetooth-USB-Stick und evtl. einem WLAN-USB-Stick an. Jeder Raum wird mit solch einem Raspberry ausgestattet und ist im WLAN Netz verfügbar.

Dieses Netz aus Raspberrys wird mit dem presenced / lepresenced Programm ausgestattet. Beide Programme sind Perl-Skripte, die als Daemon im Hintergrund laufen und auf Anfragen via Netzwerk warten. Es wird lediglich eine vollständige Perl-Grundinstallation mit Standardmodulen benötigt.

=== Unterschied presenced / lepresenced / collectord / ble2mqtt===
presenced, lepresenced und ble2mqtt sind Programme, welche in regelmäßigen Abständen nach Bluetooth-Geräten suchen. Sobald ein Gerät, welches vorab definiert wurde, gefunden wird, wechselt der Status des Geräts in FHEM auf Anwesend. Der Unterschied zwischen presenced, lepresenced und ble2mqtt ist, dass lepresenced und ble2mqtt insbesondere für [https://de.wikipedia.org/wiki/Bluetooth_Low_Energy Bluetooth-LE-Devices] sind und presenced für "normale" Bluetooth-Geräte.

collectord wiederum ist ein Programm, welches mehrere Pis verbindet und auf allen den aktuellen Status von presenced/lepresenced abfragt. Ist das gesuchte Bluetooth-Gerät auf einem der Pi anwesend, so wird es auch in der definierten Hauptinstanz auf anwesend gesetzt. Zusätzlich wird der Pi auf dem das Gerät gefunden wurde als Reading angegeben. Sofern alle Räume einen Empfangspegel (RSSI) ermitteln können, wird bei mehreren anwesenden Räumen der Raum mit dem besten Empfangspegel selektiert (siehe {{Link2Forum|Topic=54482}}).

=== Installation von (le)presenced ===
Diese Anleitung ist sowohl für presenced, als auch für lepresenced gültig. Einfachheitshalber wird nur lepresenced erwähnt, sämtliche Schritte gehen jedoch auch mit presenced, wobei einfach die genannten Daten durch presenced ersetzt werden müssen.

Die Software lepresenced kann aktuell über drei Varianten installiert werden. Dabei ist die bevorzugte Variante (Variante 1) die Installation über das bereitgestellte .deb-Paket.
Die Variante 2 setzt voraus, dass im FHEM contrib Verzeichnis (/opt/fhem/contrib) die aktuelle Version des .deb-Pakets liegt. Die Variante 3 ist dafür gedacht, wenn man keine .deb-Pakete installieren kann/will oder es aus anderen Gründen nicht funktioniert. Es wird davon abgeraten die Variante 3 zu verwenden. Vollständigkeitshalber wird sie aber aufgeführt.

===== Installation per .deb-Paket =====

Die bevorzugte Variante ist die Installation von lepresenced durch die passenden .deb Pakete.
{{Randnotiz|RNText=Bei einem Upgrade einer älteren Version reicht es, das neue .deb Paket mit
:<code>sudo dpkg -i lepresenced-X.XX-X.deb</code>
zu aktualisieren}}

'''1.Variante:'''
Herunterladen der aktuellen lepresenced-0.83-3.deb (Stand August 2017) Datei über den Webbrowser
[https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/ SVN-Repository]. Im SVN die passende Datei auswählen und in der folgende Webseite den Link unter:
<pre>
Download in other formats:
Original Format
</pre>
anklicken und die Datei herunterladen.
Die Datei kann jetzt auf den RPi kopiert und mit folgenden Befehlen ausgeführt werden (ggf. Berechtigungen anpassen).

Alternativ per wget Befehl direkt auf den RPi (aktuelle Versionsnummer beachten)
https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/lepresenced-0.83-3.deb

'''2.Variante:''' (zu Verwenden, wenn es Probleme bei Variante 1 gibt)
Herunterladen aus dem fhem contrib Verzeichnis:
Hierzu muss das contrib auf dem aktuellen Stand sein. Dazu wird die Installation von subversion (normal bereits vorhanden) benötigt.

sudo apt-get install subversion

Danach kann per
sudo svn checkout https://svn.fhem.de/fhem/trunk/fhem/contrib svnrepo

Das aktuelle Repository auf den Pi heruntergeladen werden. Danach sollte im gewählten Verzeichnis die eingecheckten Dateien verfügbar sein.
/opt/fhem/svnrepo/PRESENCE/deb

''' Installation der Variante 1 oder 2 '''

Egal welche Variante gewählt wurde, nun kann mit folgenden Befehlen das Paket installiert werden. Bitte Pfade ggf. anpassen.

'''Wichtig''': Das '''Paket''' hat eine ca. Größe von '''6,5Kb'''. Ab und an gibt es wohl Probleme mit der Installation, wodurch die Datei 11,5kb groß wird.
Diese Datei lässt sich nicht Installieren. In diesem Fall das Paket bitte mit der Variante 1 und dem Bereich "Download in other formats" herunterladen.

sudo dpkg -i lepresenced-0.83-3.deb

sudo apt-get -f install

Die Ausgabe der Installation sollte am Ende ein [ ok ] Starting lepresenced (via systemctl): lepresenced.service. ausgeben.

<pre>
Paketlisten werden gelesen... Fertig
Abhängigkeitsbaum wird aufgebaut.
Statusinformationen werden eingelesen.... Fertig
Abhängigkeiten werden korrigiert ... Fertig
Die folgenden zusätzlichen Pakete werden installiert:
bluez-hcidump
Die folgenden NEUEN Pakete werden installiert:
bluez-hcidump
0 aktualisiert, 1 neu installiert, 0 zu entfernen und 0 nicht aktualisiert.
1 nicht vollständig installiert oder entfernt.
Es müssen 157 kB an Archiven heruntergeladen werden.
Nach dieser Operation werden 490 kB Plattenplatz zusätzlich benutzt.
Möchten Sie fortfahren? [J/n]
Holen: 1 http://archive.raspberrypi.org/debian/ jessie/main bluez-hcidump armhf 5.23-2+rpi2 [157 kB]
Es wurden 157 kB in 0 s geholt (921 kB/s).
Vormals nicht ausgewähltes Paket bluez-hcidump wird gewählt.
(Lese Datenbank ... 42033 Dateien und Verzeichnisse sind derzeit installiert.)
Vorbereitung zum Entpacken von .../bluez-hcidump_5.23-2+rpi2_armhf.deb ...
Entpacken von bluez-hcidump (5.23-2+rpi2) ...
Trigger für man-db (2.7.0.2-5) werden verarbeitet ...
bluez-hcidump (5.23-2+rpi2) wird eingerichtet ...
lepresenced (0.82-1) wird eingerichtet ...
[ ok ] Starting lepresenced (via systemctl): lepresenced.service.
</pre>

'''3.Variante:'''

Bei dieser Variante wird das aktuellste lepresenced Skript aus github heruntergeladen. Das bedeutet, dass jegliche Konfiguration wie automatischer Start, Berechtigungen etc.
manuell konfiguriert werden muss. Diese Variante eignet sich nur für diejenigen, die keine .deb-Pakete installieren wollen/können oder die genau Wissen, was sie tun!
<pre>
https://github.com/mhop/fhem-mirror/blob/master/fhem/contrib/PRESENCE/lepresenced
</pre>

Zur "Installation" des Skripts folgendermaßen vorgehen:
Unter /fhem manuell den Ordner „script“ anlegen:
<pre>
mkdir script
</pre>
Datei lepresenced reinkopieren und ausführbar machen:
<pre>
sudo chmod +x /opt/fhem/script/lepresenced
sudo chgrp -cR dialout lepresenced
</pre>
Skript erstmalig starten:
<pre>
sudo ./lepresenced --loglevel LOG_EMERG -d
</pre>
Kommt beim Starten des Skript eine Fehlermeldung, müssen die Abhängigkeiten aufgelöst werden.
<pre>
Can't locate Net/Server/Daemonize.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.14.2 /usr/local/share/perl/5.14.2 /usr/lib/perl5 /usr/share/perl5 / usr/lib/perl/5.14 /usr/share/perl/5.14 /usr/local/lib/site_perl .) at /opt/fhem/lepresenced line 17.
BEGIN failed--compilation aborted at /opt/fhem/lepresenced line 17.
</pre>
Um die Abhängigkeiten aufzulösen muss folgendes nachinstalliert werden und anschließend ein Reboot durchgeführt werden.
<pre>
sudo apt-get install libnet-server-*
</pre>

===== Einrichtung eines Bluetooth-Geräts über FHEM =====

Nach dem letzten Schritt sind alle Bedingungen für eine abschließende Konfiguration eines BT-Geräts in FHEM abgeschlossen worden.
Jetzt kann der zum Beispiel ein G-Tag dem FHEM-Server bekannt gemacht werden:
<pre>
-- Name Modul Modus MAC vom Gtag IP vom PI Port Abfragezeit in Sekunden
define MeinGtAG PRESENCE lan-bluetooth xx:xx:xx:xx:xx:xx 127.0.0.1:5333 120
</pre>

'''Wichtig ist den angegeben Port zu unterscheiden. Für presenced muss der Port 5111 genommen werden, für lepresenced der Port 5333.'''
Den absent und present Mode kann man einfach testen, in dem man den Gtag mit Alufolie einwickelt.

Diese Variante sollte eingesetzt werden, wenn nur ein Pi nach Bluetooth-Geräten sucht. Möchte man mehr als ein Gerät nutzen um zum Beispiel eine größere Fläche abzudecken so muss mit collectored gearbeitet werden.

=== Alle Räume gemeinsam ansprechen mittels collectord ===
Um zwei presenced- oder lepresenced Installationen zu verbinden wird der collectord Daemon von Markus Bloch benötigt. Dieser kennt alle presenced-Installationen im Netzwerk und führt eine koordinierte Suche nach den gewünschten Geräten durch. Sobald ein Gerät in einem Raum erkannt wurde, meldet der collectord den Status einschließlich der Angabe des Raumes, in dem das Gerät erkannt wurde.

[[Datei:Presence_Collectord_Uebersicht.jpg|200px|thumb|left|Schematische Darstellung Presence und Collectord, Danke an dtavb]]
Auf Basis folgender Skizze wird die Einrichtung und der Betrieb der Anwesenheitserkennung und Überwachung <p></p>
mit dem PRESENCE-Modul sowie dem Skript (.deb-Paket) lepresenced beschrieben. Zusätzlich wird für die Verbindung <p></p>
mehrere lepresenced Instanzen der collectord verwendet.<p></p>
Diese Skizze dient als Basis für alle genannten Konfigurationen innerhalb dieses Artikels.
{{NeuerTextBlock}}

==== Aufbau ====
; RPi1 (Hauptinstanz):
: FHEM Installation
: presence/lepresenced Installation
: collectord installation
: Sämtliche Bluetooth-Geräte in FHEM definiert
; RPi2 (Zweitsystem):
: FHEM installation
: presence/lepresenced Installation
: Sämtliche Bluetooth-Geräte in FHEM definiert

==== Installation per .deb-Paket ====
collectord wird heruntergeladen und installiert:
https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/collectord-1.8.deb (Stand Januar 2018)
<pre>
sudo dpkg -i collectord-1.8.deb
</pre>

Nach der Installation befindet sich im Verzeichnis: /etc/collectord.conf die Konfigurationsdatei für das collectord. Weitere Einstellungen können unter /etc/default/collectord vorgenommen werden.

==== Konfiguration auf Shellebene ====
<pre>
sudo vi /etc/collectord.conf
</pre>

Diese Datei muss jetzt nach folgender Vorlage angepasst werden.
<pre>
# room definition
#[room-name] # name of the room
#address=192.168.0.10 # ip-address or hostname
#port=5111 # tcp port which should be used (5111 is default)
#presence_timeout=120 # timeout in seconds for each check when devices are present
#absence_timeout=20 # timeout in seconds for each check when devices are absent

[RPi1] # Name (wird als Reading room bei den BT-Tags angezeigt) der presence Instanze
address=127.0.0.1 # Lokale Adresse RPi1 , da hier das Collectord später laufen soll!
port=5333 # Port der Presence Installation
presence_timeout=60 # Selbstgewaehlte Pruefintervalle
absence_timeout=60 # Selbstgewaehlte Pruefintervalle

[RPi2] # Name (wird als Reading room bei den BT-Tags angezeigt) der presence Instanze
address=192.168.178.127 # IP-Adresse der Instanz, wo nur das Presence laueft, also RPi2
port=5333 # Port der Presence Installation
presence_timeout=60 # Selbstgewaehlte Pruefintervalle
absence_timeout=60 # Selbstgewaehlte Pruefintervalle
</pre>

Hinweis:
* Es dürfen keine [Namen] mit Leerzeichen verwendet werden
* Der angegebene Port richtet sich danach, ob auf dem Pi presenced (Port 5111) oder lepresenced (Port 5333) nach dem Bluetooth-Gerät sucht

==== Konfiguration in FHEM ====
;RPi1
define Gtag PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 127.0.0.1:5222 60 ''Hinweis: (Der Port ist der, des collectord!! Standard 5222)''
;RPi2
define Gtag PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 192.168.178.127:5222 60 ''Hinweis: (Der Port ist der, des collectord!! Standard 5222 - die IP-Adresse von die von RPi1)''

Nach der Konfiguration kann der Daemon gestartet werden.
Sobald das Bluetoothgerät irgendwo in der Wohnung erkannt wurde, meldet der Collectord dies sofort
an FHEM und teilt den Raum mit in dem es erkannt worden ist. Diese Information wird im Reading "rooms" des jeweiligen BT-Gerätes dargestellt.

Zum testen sollte collectord einmalig manuell gestartet werden. Dies hat den Vorteil, dass man nochmal den Port des collectord prüfen kann, dieser steht in der Zeile <pre>created socket on 0.0.0.0 with port 5222</pre> und man sehen kann, ob der collectord richtig startet, oder Fehler auswirft. Gestartet wird mit folgendem Kommando:
<pre>
sudo collectord -vv -c /etc/collectord.conf
</pre>
Die Ausgabe sieht wie folgt aus:
<pre>
2017-04-02 17:52:55 - =================================================
2017-04-02 17:52:55 - started with PID 15554
2017-04-02 17:52:55 - reading configuration file
2017-04-02 17:52:55 - no config errors found
2017-04-02 17:52:56 - created socket on 0.0.0.0 with port 5222
2017-04-02 17:53:20 - new connection from 127.0.0.1:48656
2017-04-02 17:53:20 - created thread 1 for processing device 7C:2F:80:E1:14:31 in room RPi2 for peer 127.0.0.1 (UUID: d0beb79dd4771532eb5e207c7bf31788)
2017-04-02 17:53:20 - created thread 2 for processing device 7C:2F:80:E1:14:31 in room RPi1 for peer 127.0.0.1 (UUID: d0beb79dd4771532eb5e207c7bf31788)
2017-04-02 17:53:20 - new connection from 127.0.0.1:48662
2017-04-02 17:53:20 - new connection from 127.0.0.1:48664
2017-04-02 17:53:20 - created thread 3 for processing device 7C:2F:80:ED:BC:F7 in room RPi2 for peer 127.0.0.1 (UUID: 7495a112063d5db45e6335d3fe305e36)
2017-04-02 17:53:20 - created thread 4 for processing device 7C:2F:80:ED:BC:F7 in room RPi1 for peer 127.0.0.1 (UUID: 7495a112063d5db45e6335d3fe305e36)
2017-04-02 17:53:20 - created thread 5 for processing device 7C:2F:80:E1:2A:4D in room RPi2 for peer 127.0.0.1 (UUID: c228f8d4d33b06787f995c7903c02760)
2017-04-02 17:53:20 - created thread 6 for processing device 7C:2F:80:E1:2A:4D in room RPi1 for peer 127.0.0.1 (UUID: c228f8d4d33b06787f995c7903c02760)
2017-04-02 17:53:22 - new connection from 192.168.xxx.xxx:51638
2017-04-02 17:53:22 - created thread 7 for processing device 7C:2F:80:E1:14:31 in room RPi2 for peer 192.168.xxx.xxx (UUID: 5db7012e709d6dc2fcd8159fc0344e40)
2017-04-02 17:53:22 - created thread 8 for processing device 7C:2F:80:E1:14:31 in room RPi1 for peer 192.168.xxx.xxx (UUID: 5db7012e709d6dc2fcd8159fc0344e40)
2017-04-02 17:53:22 - new connection from 192.168.xxx.xxx:51640
2017-04-02 17:53:22 - created thread 9 for processing device 7C:2F:80:ED:BC:F7 in room RPi2 for peer 192.168.xxx.xxx (UUID: c4b4d7c654132cf88e8c1fec3a956d3d)
2017-04-02 17:53:23 - created thread 10 for processing device 7C:2F:80:ED:BC:F7 in room RPi1 for peer 192.168.xxx.xxx (UUID: c4b4d7c654132cf88e8c1fec3a956d3d)
2017-04-02 17:53:29 - new connection from 192.168.xxx.xxx:51642
2017-04-02 17:53:29 - created thread 11 for processing device 7C:2F:80:E1:2A:4D in room RPi2 for peer 192.168.xxx.xxx (UUID: ecd7081e5ae3a0d8e735c8750cb116a1)
2017-04-02 17:53:29 - created thread 12 for processing device 7C:2F:80:E1:2A:4D in room RPi1 for peer 192.168.xxx.xxx (UUID: ecd7081e5ae3a0d8e735c8750cb116a1)
</pre>

Wenn das Log wie oben abgebildet aussieht wurde alles richtig gemacht und unter dem Device in FHEM erscheint ein neues Reading "rooms" mit dem Wert der erkannten PRESENCE-Installation.

'''Verhalten presence timeout im zusammenhang mit dem Attribut "absenceThreshold" der PRESENCE Konfiguration in FHEM'''
<br>
In der collectord.conf sind <code>presence_timeout</code> und <code>absence_timeout</code> für den jeweiligen Raum konfiguriert.
Das bedeutet, sobald irgendein Gerät in diesem jeweiligen Raum anwesend/abwesend ist, wird das jeweilige Timeout an den verbundenen presenced/lepresenced geschickt um damit das Check-Interval entsprechend zu ändern.

In der PRESENCE-Definition kann man ebenfalls ein <code>absence_timeout</code>/<code>presence_timeout</code> setzen. Sobald sich der Zustand ändert, wird auch das jeweilige Timeout an den collectord gesandt. Dies hat aber auf die Checks in den jeweiligen Räumen und damit der collectord.conf keinen Einfluss. Der collectord schickt ein Statusupdate an PRESENCE nur, wenn das vorgegebene Timeout (von PRESENCE) erreicht ist und keine Statusänderung stattfand. Sobald eine Änderung des Status erfolgt wird natürlich sofort der Status an PRESENCE geschickt.

Das Attribut absenceThreshold/presenceThreshold funktioniert nachwievor. Hier ist nur wichtig wie man die Timeouts sowohl in PRESENCE als auch collectord.conf setzt.

'''Das Reading "room" bei einer PRESENCE Definition und der Zusammenhang zu collectord'''
<br>
Wenn ein BT LE Empfänger in mehr als einem Raum detektiert wird, führt der collectord (ab Version 1.8) eine RSSI-Erkennung durch. Sofern alle Räume den Empfangspegel (RSSI) ermitteln können, wird der Raum mit dem besten Empfangspegel als Raum für das "room"-Reading ausgewählt. Der lepresenced in aktueller Version von PatrickR gibt immer den Empfangspegel aus.

==== Automatischer Start ====
Wenn der collectord per .deb Paket installiert wurde, startet er automatisch bei einem Reboot mit (via systemd/init-Skript).
<br>

Der Collectord wird standardmäßig mit dem Port 5222 gestartet. Um diese anzupassen sind zwei Schritte notwendig:<br>
'''1.)''' Anpassen der /usr/bin/collectord
Hier bitte den Parameter my $opt_p von 5222 auf 5XXX abändern.

Da der collectord mittlerweile per systemd beim reboot des RPi gestarte wird muss auch diese Konfiguration auf den neuen Port angepasst werden.<br>
'''2.)''' Anpassen der /etc/default/collectord
<pre>
# collectord startup defaults:
# The TCP port collectord will listen for incoming connections (default: 5222)
PORT=5111
# The location of the configuration file (default: /etc/collectord.conf
CFGFILE=/etc/collectord.conf
</pre>

Manuell starten als Daemon (Parameter <code>-d</code>) mit:
<pre>
sudo collectord -c /etc/collectord.conf -d -v -l /var/log/collectord.log
</pre>

=== ble2mqtt ===
presenced und lepresence verwenden zur Erkennung von BT-Geräte Tools, die leider nicht mehr aktiv gewartet werden bzw. deprecated sind. Deswegen wurde ble2mqtt entwickelt. Dieses Tool hat den Vorteil, dass die gesammelten Informationen an einen MQTT-Broker gesendet werden und dadurch in FHEM leicht und flexibel zu verarbeiten sind. Genaue Informationen zu ble2mqtt finden sich auf der Wiki-Seite [[ble2mqtt]].

== Batterieüberwachung ==

=== Batterieüberwachung mit dem Modul BleTagBattery ===
{{Infobox Modul
|ModPurpose=Anwesenheitserkennung
|ModType=h

|ModTechName=74_BleTagBattery
|ModOwner=mumpitzstuff
}}
Mit dem Modul BleTagBattery - kann der Batteriestatus aller BT-LE Devices gelesen werden.
Es werden die Readings batteryLevel und battery angelegt für diejenigen BT-LE Tags, die an einer PRESENCE-Installation registriert wurden.

Vorraussetzung und Installation:

Bluez und Gattool
sudo apt-get install bluez

Das Gattool ist in den Installationen von Bluez inbegriffen.

Hinzufügen des githup für das Modul
update add http://raw.githubusercontent.com/mumpitzstuff/fhem-BleTagBattery/master/controls_bletagbattery.txt
update all
restart fhem: shutdown restart
BT-LE tags muss an einer PRESENCE-Installation des type "lan-bluetooth" registriert sein.

Nach dem Neustart von FHEM kann das Modul definiert werden:
define a new device: define <name of device> BleTagBattery

Das Modul versucht in der Standardkonfiguration alle 6 Stunden die BT-LE Devices zu erreichen und das Reading batteryLevel und battery zu aktualisieren.
Das Update kann auch manuell mit dem folgenden Befehl erzwungen werden

set <name of device> statusRequest.

Weiter Informationen und Disskussionen können dem eigentlichen [https://forum.fhem.de/index.php?topic=68104.0 Forumsbeitrag] entnommen werden,

=== Batterieüberwachung (aktuell nur G-Tags) ===

Leider überträgt der G-Tag nach der Einrichtung als Device in FHEM kein Reading mit seinem aktuellen Batteriestatus.
Dem wurde mit Hilfe des Forum Abhilfe geschaffen.
Im Folgenden wird erläutert wie die Batterieüberwachung eingerichtet werden kann.

'''Voraussetzung:'''

bc - Basiscalculator [https://packages.debian.org/de/sid/bc Bc-Paket]
<pre> sudo apt-get install bc </pre>

Anlegen eines Shellskript auf dem Raspberry System.
Die Parameter <<MAC-Adresse>> und <<TagName>> müssen durch die Werte des auszulesenden G-Tags ersetzt werden.
<pre>
#!/bin/bash
stringZ=$(sudo gatttool -b 5C:2B:80:C1:14:41 --char-read --handle=0x001b)
stringZ=${stringZ:33:2}
stringZ=$(echo "$stringZ" | tr a-f A-F)
decimal=$(echo "ibase=16; $stringZ" | bc)
perl /opt/fhem/fhem.pl 7072 "setreading MeinGtag Batterie $decimal"
</pre>

Dem Device in FHEM (hier MeinGtag) ein userReading mit dem Namen '''Batterie''' hinzufügen.
Das Shellskript mit folgendem Befehl starten:
<pre>
./GtagBatterie.sh
</pre>
'''Wichtig ist hierbei,''' dass Skript mit "./" und nicht mit "sh" aufzurufen. Beim Aufruf mit "sh GtagBatterie.sh" produziert es einen Fehler
<pre>GtagBatterie.sh: 3: GtagBatterie.sh: Bad substitution </pre>

Das Reading wird auf den ausgelesenen Wert der Batterie gesetzt.

Hinweis: Es sollte für jeden G-Tag ein eigenes Skript abgelegt werden. Das Skript kann per crontab oder fhem Kommando (system) regelmäßig aufgerufen werden.

=== Batterieüberwachung (alle Devices vom Typ "MODE=lan-bluetooth") ===

Es gibt eine weitere Möglichkeit um den Batteriestatus von LE Devices abzurufen und in FHEM als Reading darzustellen.
Dabei wird der Batteriezustand für alle LE Devices, die bereits in FHEM konfiguriert sind und per lepresenced überwacht werden, automatisch in einem shell-Script ermittelt.
Näheres dazu im Forumartikel {{Link2Forum|Topic=56960|LinkText=Erweiterung: Anwesenheitserkennung/Batterieüberwachung}}.

Vorteile:
* Automatische Ermittlung aller in FHEM konfigurierten LE Devices
* Möglichkeit, diese Devices alternativ manuell im Script einzutragen
* Es werden nur Devices abgefragt, die im Status "present" sind, also mit ziemlicher Sicherheit auch verfügbar sind
* Ein eventuell auf dem FHEM telnet-Port gesetztes Passwort kann im Script hinterlegt werden

'''Voraussetzung:'''

'''Funktionierendes lepresenced''' - siehe [[Anwesenheitserkennung#Anleitung_f.C3.BCr_ein_LE_Device_.28z.B._Gtags.2CPebbles_etc..29|Anleitung für ein LE Device (z.B. Gtags,Pebbles etc.)]]

'''socat''' - TCP port forwarder
<pre>
sudo apt-get update && sudo apt-get install socat
</pre>

'''gawk''' - Zum extrahieren der Daten
<pre>
sudo apt-get update && sudo apt-get install gawk
</pre>

'''gatttool''' - Bestandteil von bluez

gatttool ist auf den meisten Distributionen im bluez-Paket, allerdings nicht bei Opensuse. Dort muss man das Sourcepaket von bluez installieren und selbst kompilieren.
gatttool sollte dann nach /usr/bin oder /usr/local/bin kopiert werden,

Zusätzlich zu den notwendigen Erweiterungen werden für die Ausführung von gatttool '''Root-Rechte benötigt'''!

Das Script selbst gibt es hier: [https://raw.githubusercontent.com/micky0867/lebattery/master/lebattery lebattery]

Am Besten unter /opt/fhem/script/lebattery speichern und ausführbar machen:
<syntaxhighlight lang="bash">
sudo su -
mkdir /opt/fhem/script
cd /opt/fhem/script
wget https://raw.githubusercontent.com/micky0867/lebattery/master/lebattery
chmod 755 lebattery
</syntaxhighlight>

Je nach Bedarf können im Script noch die folgenden 3 Parameter angepasst werden:
<syntaxhighlight lang="bash">
# If allowed_telnetPort is protected by a password, add the password here
TELNETPASSWORD=""
# Attribute for batterylevel in FHEM
ATTRIBUT="batterylevel"
# Use this, if you dont want the script to determine the tags on its own
LETAGS=""
</syntaxhighlight>

Das Skript wird dann unter root folgendermaßen gestartet:
<pre>
/opt/fhem/script/lebattery -v
</pre>

Ausgabe des Skripts, wenn es mit dem Verbose Parameter -v gestartet wird.

Beide Devices sind vom Typ NUT mini, das Device mit dem FHEM-Namen '''nut_Micky''' ist im Status '''absent'''. Das zweite Device ist im Status '''present'''.
<pre>
Determining address for nut_Micky ...
nut_Micky is in state absent, no further action required

Determining address for nut_Test ...
Fetching batterylevel for nut_Test (F3:44:04:81:54:89) ...
Setting batterylevel for nut_Test to 100%
</pre>

Mein crontab-Eintrag (User root) sieht so aus:
<pre>
3 3 * * * /opt/fhem/script/lebattery -v >/opt/fhem/script/lebattery.log 2>&1
</pre>
Damit wird jeden Morgen um 3 Minuten nach 3 Uhr der Zustand der Batterien aller Devices ermittelt und in FHEM abgespeichert.<br>
Bevor man das mit crontab macht, sollte man allerdings zunächst sicher stellen, dass es auch ohne crontab funktioniert....

Bei Problemen kann man auch erstmal schauen, ob das mit dem gattool überhaupt funktioniert:
<pre>
gatttool -t <Typ> -b <MAC-Adresse> --char-read --uuid 0x2a19

handle: 0x0017 value: 64
</pre>
In diesem Fall hat die Batterie noch 100% (hex 64).<br>
Der Typ ist abhängig vom Hersteller und kann public (G-Tags) bzw. random (Nut) sein. Im Zweifelsfall beides ausprobieren.

= Beispiele =
== Anwesenheitserkennung / Anwesenheitsbenachrichtigung mit G-Tags ==
Ein Skript zur Nutzung der Gigaset G-TAGs zur Alarmierung bei öffnen und schließen von Türen und zur Anwesenheitserkennung, um die Alarmierung zu aktivieren bzw. deaktivieren.
Es kann verwendet werden um die Anwesenheit von mehrern Personen im Haushalt zu erkennen. Dabei wird eingeschränkt, dass nur bestimmte Personen die Alarmierung aktivieren können ( Eltern/Kind -Beziehung ).
Des Weiteren werden im Beispiel die Eltern benachrichtigt wenn eins der Kinder das Haus verlässt und die Eltern nicht anwesend sind.

{{Randnotiz|RNText=Namen der G-Tags in den Skripten bitte anpassen!}}

Für die ''Notify'' und die ''RESIDENTS-Erweiterung'' wird ein Dummy benötigt.
<pre>
define Alarm dummy
attr Alarm devStateIcon aktiv:secur_locked@red inaktiv:secur_open@lightgreen
attr Alarm eventMap on:aktiv off:inaktiv
attr Alarm setList on off
attr Alarm webCmd aktiv:inaktiv
attr Alarm room Alarm
</pre>

=== Mit Notify ===
<pre>
gtag.*.presence:.* {Anwesenheit_check("$EVTPART1", "$NAME")}
</pre>

Code für die 99_myUtils.pm
<pre>
### GTAG ANWESENHEITS CHECK
sub Anwesenheit_check($$) {
my ($EVENT, $NAME) = @_;

# gtag_rot - Alias Marco
# gtag_schwarz - Alias Ulli
# gtag_gruen - Alias Frida
# gtag_orange - Alias Hannah

my $RESIDENT = "rr_"; # Alle GTAGs sind Standardmäßig Residents Roommate
# $RESIDENT = "rg_" if (($NAME eq "gtag_orange") xor ($NAME eq "gtag_weis")); # Hier nur Gäste (Roomguest) Auskommentiert, da ich es so nicht brauche
my $ROOMMATE = ("$RESIDENT" . "$NAME"); # Residentsname zusammenbauen
my $ALIASNAME = AttrVal($ROOMMATE,'alias',$ROOMMATE); # ALIAS des Roommates auslesen

my $GTAG1 = Value('gtag_rot'); # ELTERN
my $GTAG2 = Value('gtag_schwarz'); # ELTERN

my $STATUS = "wahrscheinlich gerade los";
$STATUS = "anwesend" if ($EVENT eq "present"); # Status: anwesend
$STATUS = "unterwegs" if ($EVENT eq "absent"); # Status: unterwegs

Log 1, "$ALIASNAME ist $STATUS."; # LOG Eintrag erzeugen

if (($EVENT eq "present" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_gruen" xor $NAME eq "gtag_orange")) {
fhem("set teleBot send ALARMIERUNG BLEIBT AKTIV: $ALIASNAME ist da..."); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG BLEIBT AKTIV' '$ALIASNAME ist da...'"); # Pushover
}
elsif (($EVENT eq "present" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_rot" xor $NAME eq "gtag_schwarz")) {
fhem("set teleBot send ALARMIERUNG INAKTIV: $ALIASNAME ist da...; set Alarm inaktiv"); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG INAKTIV' '$ALIASNAME ist da...'; set Alarm inaktiv"); # Pushover
}
elsif (($EVENT eq "absent" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_gruen" xor $NAME eq "gtag_orange")) {
fhem("set teleBot send ALARMIERUNG BLEIBT AKTIV: $ALIASNAME hat das Haus verlassen."); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG BLEIBT AKTIV' '$ALIASNAME hat das Haus verlassen.'"); # Pushover
}
elsif (($EVENT eq "absent" && Value("Alarm") eq "inaktiv") && ($GTAG1 eq "absent" && $GTAG2 eq "absent")) {
fhem("set Alarm aktiv; set teleBot send ALARMIERUNG AKTIV: $ALIASNAME hat das Haus verlassen."); # Telegram
# fhem("set Alarm aktiv; set Infopush msg 'ALARMIERUNG AKTIV' '$ALIASNAME hat das Haus verlassen.' '' 0 ''"); # Pushover
}
}
</pre>

<br>

=== Mit Notify und Integration des RESIDENTS-MODUL ===

Der hier beschriebene Code erweitert die Funktionen unter dem Punkt 5.93.
Das Notify muss daher mit der folgenden Zeile erweitert werden.

<pre>
define Alarm_AnwesenheitCheck notify gtag.*.presence:.* { Anwesenheit_check("$EVTPART1", "$NAME"), Anwesenheit_check_resi("$NAME") }
</pre>

Zusätzlicher Code für die 99_myUtils.pm um die RESIDENTS Funktion nutzen zu können:
<pre>
### RESIDENTS
sub Anwesenheit_check_resi($) {
my ($NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME); # ALIASNAME des GTAGs auslesen

my $RESIDENT = "rr_"; # Als Standard sind alle GTAGs Roommates
$RESIDENT = "rg_" if (($NAME eq "gtag_orange") xor ($NAME eq "gtag_weis")); # Hier nur GTAG Namen der Gäste (Roomguest)
my $ROOMMATE = ("$RESIDENT" . "$ALIASNAME"); # Residentsname zusammenbauen

if (ReadingsVal($NAME,'presence',$NAME) eq "absent") {
fhem("set $ROOMMATE absent"); # Resisents Status von Roommates setzen
}
elsif(ReadingsVal($NAME,'presence',$NAME) eq "present") {
fhem("set $ROOMMATE home"); # Resisents Status von Roommates setzen
}
}
</pre>
<br>

=== Mit Notify und Fenster/Tür. -Kontakt Überwachung ===

Erweiterung für die Überwachung von Fenster/Tür. -Kontakten. Dazu sind zwei weitere Notifys notwendig die auf die Trigger der Kontakte regagieren
und so eine weitere Funktion in der 99_myUtils.pm ansprechen. Die Notifys triggern auf Kontakte die mit dem Namen Kontakt* beginnen.
Sollten die eigenen Fenster/Tür. -Kontakt anderen Namen besitzen, müssen die Skripte dementsprechend angepasst werden.
<pre>
define Alarm_Kontaktmeldung notify Kontakt.*:contact:.* {Kontakt_Meldung("$EVTPART1", "$NAME")}
</pre>
<pre>
define Alarm_Sabotagealarm notify Kontakt.*.sabotageError:.on {Kontakt_Sabotage("$EVTPART1", "$NAME")}
</pre>

Zusätzlicher Code für die 99_myUtils.pm um die TÜRKONTAKTE-Meldung nutzen zu können:
<pre>
### TÜRKONTAKTE-Meldung/Zustand
sub Kontakt_Meldung($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME);
Log 1, "$ALIASNAME wurde $EVENT";
if (ReadingsVal("Alarm", "state", "on") eq "on") {
fhem("set teleBot send $ALIASNAME wurde $EVENT"); # Nachricht über Telegram
# fhem("set Infopush msg '$ALIASNAME' '$ALIASNAME wurde $EVENT'"); # Nachricht über Pushover
}
}

### TÜRKONTAKTE-Sabotagealarm

sub Kontakt_Sabotage($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME);
Log 1, "$ALIASNAME meldet Sabotagealarm";
fhem("set teleBot send Alarm: $ALIASNAME meldet Sabotagealarm"); # Nachricht über Telegram
# fhem("set Infopush msg 'Alarmanlage' '$ALIASNAME meldet Sabotagealarm' '' 2 ' ' 60 600 "); # Nachricht über Pushover
}
</pre>
<br>

=== Hinweis zur Benutzung / Fehlerhandling ===

Der Alarm dummy hat den Zustand on:off. Die Bezeichnungen und Namen müssen 1:1 übernommen werden damit das Script funktioniert.
Andernfalls müssen die Bezeichnungen für z.B. absent:unterwegs und present:anwesend - angepasst werden.
Die Benachrichtigung kann aktuell per ''[[TelegramBot|Telegram]]'' sowie ''Pushover'' ('''Achtung mit zweiterem sind Abokosten verbunden!''') realisiert werden.
Diskussion zum Thema im Forum unter: {{Link2Forum|Topic=64080}}
<br>

= Problemlösungen =

'''Absent - Grundlos / Zufällig''' 2022

Zufällige oder Grundlose absent-Meldungen einzelner G-Tags können mit einem FIX behoben werden. Dazu ist es notwendig die BT-Firmware downzugraden.

Auf GIT das .deb Paket herunterladen und auf das jeweiligen System kopieren

wget <nowiki>https://github.com/winterheart/broadcom-bt-firmware/releases/download/v12.0.1.1105_p3/broadcom-bt-firmware-10.1.0.1115.deb</nowiki>

Anschliessend installieren und das System neu starten.

sudo dpkg -i broadcom-bt-firmware-10.1.0.1115.deb
{{Randnotiz|RNText= Dieser FIX scheint nicht bei jedem zu funktionieren! Es gibt auch System die Problemlos ohne FIX arbeiten. Bei einem Update/Upgrade des RPI muss der FIX - wenn notwendig - wieder erneut installiert werden.}}

Danach sollten die Tags wieder Problemlos erkannt werden und nicht nach wenigen Tagen wieder auf "absent" stehen.

Falls es '''Probleme beim Starten des Skripts''' gibt bzw. man das Skript ohne Reboot des Systems neustarten möchte, kann man dies per kill Befehl erledigen.

Das Thema wurde u.a in [https://forum.fhem.de/index.php?topic=75559.new;topicseen#new diesem] Beitrag beschrieben.
<syntaxhighlight lang="bash">
ps -ef | grep lepresenced
sudo kill <pid>
</syntaxhighlight>

Debuglevel lepresenced setzen:
{{Randnotiz|RNText=Um Debug-Meldungen zu bekommen (Vorsicht bei SD-Karten-Systemen wie dem RPi) - Hierbei werden die Schreibzyklen auf die SD-Karte erhöht.}}

Der Log Level muss im lepresenced-Skript selbst verändert werden. Um den Log-Level auf INFO/WARNING/DEBUG zu setzen, das Skript lepresenced mit einem Editor öffnen und die Stellen, wo LOG_WARNING zu finden ist, durch den nötigen LOG-Eintrag ersetzen.

<pre>
lepresenced --loglevel LOG_DEBUG
</pre>
Nur das wichtigste Loggen:
<pre>
lepresenced --loglevel LOG_WARNING
</pre>
Keinerlei LOG-Einträge
<pre>
lepresenced --loglevel LOG_EMERG
</pre>

Bei '''Problemen mit der Batterieüberwachung''' der Tags kann die Pi Firmware mit folgenden Befehl auf eine ältere Version zurückgesetzt werden.
Fehlermeldung beim Aufruf des lebattery oder anderen Batterietestskripten:
<pre>connect: Connection refused (111)</pre>

Lösung (vorübergehend)
<pre>
sudo rpi-update 8521fd34c8f66b6d109acce943f6e25ec93ec005
</pre>

Mehr dazu unter: {{Link2Forum|Topic=56960|Message=589165}}

'''Das BT-Device ist ständig "absent"'''<br>
Eine Mögliche Lösung kann sein, das Paket bluez-hcidump zu installieren. Das Werkzeug hcidump erlaubt die Beobachtung von Bluetooth-Aktivitäten.
Dies ist nicht notwendig, wenn bereits bluez installiert ist, da dies Teil des bluez Paketes ist
<pre>
sudo apt-get install bluez-hcidump
</pre>

'''Fehler in Logdateien /var/log/syslog und /var/log/kernel'''
Jul 29 15:08:11 raspberrypi kernel: [ 4905.634211] bt_err_ratelimited: 1 callbacks suppressed
Jul 29 15:08:11 raspberrypi kernel: [ 4905.634231] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:12 raspberrypi kernel: [ 4906.647350] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:13 raspberrypi kernel: [ 4907.532081] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:13 raspberrypi kernel: [ 4907.655564] Bluetooth: hci0 advertising data length corrected

Die Ursache des Problems ist noch nicht ergründet, allerdings betrifft dies aktuell nur den RPi3. Die Fehlermeldungen werden in verschiedene Logs geschrieben. Darunter maßgeblich "syslog" und "kern.log".

Lösung (vorübergehend):
Unterbinden der Einträge durch Anlage eines blocklist Eintrag:

1. Unter "/etc/rsyslog.d" eine Datei erzeugen mit dem Namen "01-blocklist.conf"
2. Inhalt: (Die Ausdrücke in den "" sind diejenigen, die aus dem log verschwinden sollen. - bei mir waren es die untenstehenden")
:msg,contains,"Bluetooth: hci0 advertising data length corrected" stop
:msg,contains,"bt_err_ratelimited:" stop
3. Dienst neu starten "sudo service rsyslog restart"

Weiter Infos werden im offiziellen Thema {{Link2Forum|Topic=28753|Message=499184|LinkText=hier}} diskutiert.

Seit Version 0.82 kann es beim Start zu folgenden Meldungen im Log kommen.
Sep 06 16:13:45 raspberrypi systemd[1]: Started lepresenced.
Sep 06 16:13:45 raspberrypi lepresenced[16010]: [tid:1] main::bluetooth_scan_thread: Received 'Set scan parameters failed: Input/output error', ...tting...
Sep 06 16:13:46 raspberrypi lepresenced[16010]: [tid:1] main::bluetooth_scan_thread: hcitool exited, retrying...

Diese Meldungen können ignoriert werden. Abhilfe schafft sich lepresenced selbst, indem es sich resettet.

'''Moderne iPhones und Android Geräte wechseln in den Schlaf-Modus''', um Energie zu sparen. Somit sind die Geräte zur Anwesenheitserkennung nicht per Ping zu erreichen.
Durch das Programm hping3, lassen sich zyklisch Pakete an die Geräte senden, um sie wieder "aufzuwecken".

Mehr im Forum [https://forum.fhem.de/index.php/topic,76342.0.html]

= Versionsänderungen lepresenced =
<pre>
--Version 0.81 (BasisVersion)
--Version 0.82 (stable 08/2017)
-Neue Kommandozeilenoption "--debug": Startet lepresenced im Vordergrund und gibt ausführliche Debug-Informationen auf STDOUT aus.
-Sanity Check: lepresenced prüft beim Starten die Verfügbarkeit von hciconfig, hcitool und hcidump.
-Model: lepresenced übermittelt das Reading model nun als lan-lepresenced. Das erlaubt die Erkennung von lepresenced in der FHEM-Statistik (sofern aktiviert).
--Version 0.83 (stable 09/2017)
- Behebung von Systemstart Fehlern
- Weitere Debug-Möglichkeiten. U. a. wird nun mitgezählt, ob hcitool lescan ("legacy") und hcidump eine identische Zahl an Beacons empfangen
</pre>

= Ansprechpartner =
# {{Link2FU|117|markusbloch }} (Markus) für das PRESENCE-Modul und collectord
# {{Link2FU|5068|PatrikR}} (Patrick) für lepresenced
# [[Benutzer Diskussion:Devender|Devender]] ({{Link2FU|20043|Dirk}}) für Wiki und Doku

[[Kategorie:Anwesenheitserkennung]]

PRESENCE

2023-11-09T10:29:36Z

Drhirn: ble2mqtt hinzugefügt

{{Infobox Modul
|ModPurpose=Anwesenheitserkennung
|ModType=h
|ModForumArea=Unterstützende Dienste
|ModTechName=73_PRESENCE.pm
|ModOwner=Jörg/JoWiemann ({{Link2FU|94|Forum}} / [[Benutzer Diskussion:JoWiemann|Wiki]])
}}

Das [[PRESENCE]] Modul bietet für die Anwesenheitserkennung mehrere Varianten an:

* '''lan-ping''' - Das Überwachen via PING Checks, die durch den FHEM Server versandt werden.
* '''fritzbox''' - Das Überwachen von Geräten auf einer FritzBox via ctlmgr_ctl (Nur auf einer FritzBox möglich)
* ''' Bluetooth'''
:- '''local-bluetooth''' - Das Überwachen via Bluetooth Checks, die vom FHEM Server direkt durchgeführt werden (angeschlossener Bluetooth-Stick und die Software bluez voraussgesetzt)
:- '''lan-bluetooth''' - Das Überwachen von Bluetoothgeräten, über Netzwerk. Auf einer oder mehreren Maschinen im Netzwerk (z.B. [[:Kategorie:Raspberry Pi|Raspberry Pi]]) läuft ein Presence-Daemon, der nach Bluetooth-Geräten sucht. Um mehrere Presence-Daemon mit FHEM zu verbinden, gibt es den Collector-Daemon, der sich zu allen Presence-Damons im Netzwerk verbindet und das Ergebnis von allen zusammenfasst.
* '''function''' - Das Überwachen mithilfe einer selbst geschrieben Perl-Funktion, die den Anwesenheitsstatus zurückgibt (0 oder 1)
* '''shell-script''' - Das Überwachen mithilfe eines selbst geschriebenen Shell-Programms/Skript, das eine 0 oder 1 ausgibt, um den Anwesenheitsstatus mitzuteilen.

= Überwachen mittels Ping im WLAN/LAN =
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Um ein Gerät via Ping zu überwachen, muss folgende Definition durchgeführt werden:
:<code>define Handy PRESENCE lan-ping 192.168.0.30</code>

Dadurch wird die IP-Addresse 192.168.0.30 alle 30 Sekunden geprüft, ob sie erreichbar ist. Wenn sie erreichbar ist, ist der Status "present" (anwesend), ansonsten "absent" (abwesend).

Der Timeout kann verändert werden, indem ein Wert (in Sekunden) an das Define anhängt wird:
:<code>define Handy PRESENCE lan-ping 192.168.0.30 '''60'''</code>

Nun würde das Handy alle 60 Sekunden geprüft werden.

Nur wenn bei einem iPhone/iPad die Funktion "über WLAN synchronisieren" aktiviert ist, ist es auch im Standby zuverlässig pingbar. Standardmäßig deaktivieren Apple-Geräte ihr WLAN im Standby-Betrieb um die Akkulaufzeit zu verlängern.

Sollte die Fehlermeldung
:<code> PRESENCE (Handy) - ping command returned with output: ping: icmp open socket: Operation not permitted </code>
im Log auftauchen und lan-ping dadurch nicht funktionieren, liegt ein Berechtigungsproblem vor. Kein Grund den User fhem zu root zu machen!
Prüfe zu erst als User root ob die Capabilities gesetzt sind.
:<code>getcap /bin/ping</code>
Sollte folgendes Ergeben zu Tage fördern.
:<code>/bin/ping = cap_net_raw+ep</code>
Ist dem nicht so, setzen wir die benötigten Capabilities
:<code>setcap cap_net_raw+ep /bin/ping</code>
Mehr Informationen zum Thema Capabilities [https://manpages.debian.org/jessie/manpages-de/capabilities.7.de.html].

= FritzBox: direktes Abfragen der Aktivität via ctlmgr_ctl =
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Eine sehr häufige und auch zuverlässige Methode ist auf einer FritzBox die Abfrage mittels ctlmgr_ctl Befehl. Über diesen lassen sich alle Geräte abfragen ob sie aktiv sind. Ist ein Gerät aktiv, so gilt es als anwesend.

Dieser Modus kann allerdings nur in FHEM Installationen direkt auf einer FritzBox verwendet werden. Des weiteren muss FHEM unter dem User root laufen. Um ein Gerät zu überwachen, wird lediglich der Gerätename benötigt, so wie er unter dem Menüpunkt "Heimnetz" auftaucht.

Die erforderliche Definition:
:<code>define Handy PRESENCE fritzbox iPhone-4S</code>

= Überwachung mittels Perl-Code =
Es ist möglich zum Überwachen von Geräten eine eigene Perl-Funktion zu verwenden die dann vom PRESENCE Modul im Hintergrund aufgerufen wird.

define <name> PRESENCE function {...} [ <check-interval> [ <present-check-interval> ] ]

Sobald die Funktion den Rückgabewert 1 hat, ist das Gerät anwesend, bei 0 abwesend.

== Beispiel DHCP Überwachung auf Airport Basestation ==
Die hier vorgestellte Überwachung der DHCP Lease auf Airport Basestations per SNMP ist absolut robust gegenüber dem Ruhezustand von iOS und setzt keine weitere Konfiguration auf dem iPhone voraus. Das Abmelden beim Verlassen des Empfangsbereiches der Basestation geschieht mit etwa 5-10 Minuten Verzögerung und ist somit auch vor kurzzeitigen Empfangsproblemen sicher. Das nebenstehende Bild (???) verdeutlicht noch mal die Unterschiede zwischen einer IP-Basierten Ping-Überwachung und der Überwachung auf Ebene der Basestation oder FritzBox.

Bevor der folgende Code verwendet werden kann ist das Perl Modul Net:SNMP zu installieren (z. B. mit: <code>cpan install use Net::SNMP</code>).

Zuerst ist folgender Code in 99_myUtils.pm einzufügen, sollte diese noch nicht vorhanden sein muss diese aus dem Template welches unter Edit Files zu finden ist erzeugt werden.
'''Achtung, das ist nicht der komplette Inhalt der 99_myUtils!''' Das ist nur die einzelne Routine

<pre>
use Net::SNMP;
sub
snmpCheck($$)
{
my ($airport,$client)= @_;

my $community = "public";
my $host = $airport;
my $oid = ".1.3.6.1.2.1.3.1.1.2";
#my $oid = ".1.3.6.1.2.1.3.1.1.2.25.1.10.0.1";

my ( $session, $error ) = Net::SNMP->session(
-hostname => $host,
-community => $community,
-port => 161,
-version => 1
);

if( !defined($session) ) {
return 0;
return "Can't connect to host $host.";
}

my @snmpoids = ();

my $response = $session->get_next_request($oid);
my @nextid = keys %$response;
while ( @nextid && $nextid[0] && $nextid[0] =~ m/^$oid/ ) {
push( @snmpoids, $nextid[0] );

$response = $session->get_next_request( $nextid[0] );
@nextid = keys %$response;
}

if( !defined($response = $session->get_request( @snmpoids ) ) ) {
return 0;
}

foreach my $value (values %$response) {
return 1 if( $value eq $client )
}

return 0;
}
</pre>

Danach lässt sich das Mobilgerät so überwachen:
:<code>define iPhone PRESENCE function {snmpCheck("10.0.1.1","0x44d77429f35c")} 30 30</code>

wobei 10.0.1.1 durch die IP-Adresse der Basestation und 0x44d77429f35c durch die MAC Adresse des Geräts als HEX-Zahl ersetzt werden muss.

== Beispiel Anwesenheitserkennung mittels UniFi Controller ==

Die Anwesenheitserkennung bei Geräten in Verbindung mit UniFi-Produkten funktioniert selbst dann, wenn sich die Geräte im PowerSave-Modus befinden.

Beachte: Die Geräte werden erst ungefähr nach 5 Minuten, nachdem das Gerät das WLAN verlassen hat als disconnected angezeigt.

<code>define <NAME> PRESENCE function {ReadingsVal("<UniFi>","<NamedDevice>","") eq "connected" ? 1:0}</code>

= Überwachen mittels Events =
Der Vorteil gegenüber der Function-Variante ist, dass diese Variante ohne Blocking.pm-Overhead direkt ausgeführt werden kann und in "Echtzeit" abläuft (siehe {{Link2Forum|Topic=40287|Message=562823}}).

<code>define <NAME> PRESENCE event UniFi:NamedDevice:.disconnected UniFi:NamedDevice:.connected</code>

Dabei wird <UniFi> mit dem Namen des Unifi-Devices in FHEM ersetzt, <NamedDevice> mit dem Namen des zu überwachenden Devices im Unifi-Controller ersetzt.

= Überwachen mittels Bluetooth =
== Vorbereitung und Informationen ==
=== Getestete Hardware/Software ===
* '''Raspbian System''' - wheezy, Jessie (interner BT-Controller)
* '''BT-Dongle''' - CSL NET BT USB2.0 Stick, Bluetooth V4.0, Nano <br />'''Achtung''': Es muss ein BT V4.0 oder höher verwendet werden. Nur dieser unterstützt ''LowEnergy''
* '''BT-TAG''' - Gtag von Gigaset, TrackR, UDOO Neo, PebbleBee, iTag von Unitec, X4-LIFE Multifunkti BL-Anhänger, iTag Wireless Anti, Trackr bravo, GhostyuBeacon iBc41

=== BT-Dongle am RaspberryPI installieren ===
Um den BT-Dongle ''(hier: CSL NET BT USB2.0)'' am RaspberryPI verwenden zu können, müssen die notwendigen Pakete über die Paketverwaltung von debian nachinstalliert werden.
Wer bereits ein BT-Dongle installiert hat, kann diesen Schritt überspringen.
<pre>
apt-get install bluetooth
</pre>
Nach erfolgreicher Installation der Pakete sollte der RaspberryPI neu gestartet werden.
<pre>
sudo reboot
</pre>

Nach dem erfolgten Reboot bitte das Log des RaspberryPI auf folgende Einträge prüfen:
<pre>
Feb 12 19:52:55 fhem kernel: [ 4.773600] Bluetooth: Core ver 2.20
Feb 12 19:52:55 fhem kernel: [ 4.773748] NET: Registered protocol family 31
Feb 12 19:52:55 fhem kernel: [ 4.773765] Bluetooth: HCI device and connection manager initialized
Feb 12 19:52:55 fhem kernel: [ 4.773797] Bluetooth: HCI socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.773821] Bluetooth: L2CAP socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.773890] Bluetooth: SCO socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.797531] usbcore: registered new interface driver btusb
</pre>
Sobald der BT-Dongle erkannt wurde ''leuchtet'' (wenn vorhanden) auch die ''blaue/gelbe'' LED am Dongle auf.

=== BT-Tags aktivieren ===
Jetzt kann der BT-Tag aktiviert werden. Bei einigen BT-Tags muss dafür die '''Batteriesicherung''' gezogen werden.

Ein BT-Tag wird mit folgendem Befehl auf der Konsole gesucht:
<syntaxhighlight lang="bash">
sudo hcitool lescan

Ausgabe z.B.:
LE Scan ...
7C:2F:80:A1:XA:XD (unknown)
7C:2F:80:A1:XA:XD Gigaset G-tag
7C:2F:80:A1:X4:X1 (unknown)</syntaxhighlight>
Eine Übersicht über die möglichen Befehle von hcitool gibt es mit der Eingabe von:
<pre>
sudo hcitool

Ausgabe z.B.:
hcitool - HCI Tool ver 5.23
Usage:
hcitool [options] <command> [command parameters]
Options:
--help Display help
-i dev HCI device
Commands:
dev Display local devices
inq Inquire remote devices
scan Scan for remote devices
name Get name from remote device
info Get information from remote device
spinq Start periodic inquiry
epinq Exit periodic inquiry
cmd Submit arbitrary HCI commands
con Display active connections
cc Create connection to remote device
dc Disconnect from remote device
sr Switch master/slave role
cpt Change connection packet type
rssi Display connection RSSI
lq Display link quality
tpl Display transmit power level
afh Display AFH channel map
lp Set/display link policy settings
lst Set/display link supervision timeout
auth Request authentication
enc Set connection encryption
key Change connection link key
clkoff Read clock offset
clock Read local or remote clock
lescan Start LE scan
lewladd Add device to LE White List
lewlrm Remove device from LE White List
lewlsz Read size of LE White List
lewlclr Clear LE White list
lecc Create a LE Connection
ledc Disconnect a LE Connection
lecup LE Connection Update
</pre>

Falls beim SCAN kein BT-Tag gefunden wird, sollte das BT Interface neu gestartet werden. Dazu ist kein Reboot des RaspBerryPI notwendig.
<syntaxhighlight lang="bash">
sudo hciconfig hci0 down
sudo hciconfig hci0 up
sudo hcitool dev
</syntaxhighlight>

== Überwachung durch den FHEM Server direkt ==
[[Datei:Bluetooth-Adresse-iPhone.png|thumb|Bluetooth-Adresse eines iPhones]]
Jenach Aufstellungsort des FHEM Servers kann es sinnvoll sein, eine Bluetooth-Überwachung direkt durch den FHEM Server durchzuführen. Hierbei gilt allerdings zu beachten, dass Bluetooth nicht für große Reichweiten gedacht ist und in den meisten Fällen keine Wände überwinden kann. Das heisst, dass in den meisten Fällen damit nur ein Raum überwacht werden kann.

Je nach Einsatzzweck kann das auch so gewollt sein. Bluetooth USB Sticks, die bereits Bluetooth 4.0 unterstützen, können höhere Reichweiten über Zimmerwände hinaus erreichen. Vorausgesetzt, das Mobilgerät unterstützt Bluetooth 4.0.

Um eine Überwachung per Bluetooth durchführen zu können, benötigt man die Bluetooth-Adresse eines Gerätes. Diese ähnelt vom Aufbau einer MAC-Adresse. Generell wird die Adresse in den Telefon-Informationen bei Smartphones angezeigt.

Um eine Anwesenheitserkennung via Bluetooth durchzuführen, wird folgende Definition in der [[Konfiguration]] benötigt:
:<code>define Handy PRESENCE local-bluetooth XX:XX:XX:XX:XX:XX</code>

== Überwachung durch verteilte Agenten in der Wohnung (presenced/lepresenced/collectord/ble2mqtt) ==
[[Datei:Raspberry-Pi-mit-WLAN-und-Bluetooth-Stick.jpg|thumb|left|Raspberry Pi mit Bluetooth- und WLAN-USB-Stick]]
Um eine zuverlässige und flächendeckende Bluetooth-Anwesenheitserkennung durchzuführen, ist es unerlässlich, mehrere Bluetooth-Empfänger zu verwenden, die auf mehrere oder alle Räume verteilt sind.

Hierfür bietet sich zum Beispiel ein [[Raspberry Pi]] mit einem Mini-Bluetooth-USB-Stick und evtl. einem WLAN-USB-Stick an. Jeder Raum wird mit solch einem Raspberry ausgestattet und ist im WLAN Netz verfügbar.

Dieses Netz aus Raspberrys wird mit dem presenced / lepresenced Programm ausgestattet. Beide Programme sind Perl-Skripte, die als Daemon im Hintergrund laufen und auf Anfragen via Netzwerk warten. Es wird lediglich eine vollständige Perl-Grundinstallation mit Standardmodulen benötigt.

=== Unterschied presenced / lepresenced / collectord / ble2mqtt===
presenced, lepresenced und ble2mqtt sind Programme, welche in regelmäßigen Abständen nach Bluetooth-Geräten suchen. Sobald ein Gerät, welches vorab definiert wurde, gefunden wird, wechselt der Status des Geräts in FHEM auf Anwesend. Der Unterschied zwischen presenced, lepresenced und ble2mqtt ist, dass lepresenced und ble2mqtt insbesondere für [https://de.wikipedia.org/wiki/Bluetooth_Low_Energy Bluetooth-LE-Devices] sind und presenced für "normale" Bluetooth-Geräte.

collectord wiederum ist ein Programm, welches mehrere Pis verbindet und auf allen den aktuellen Status von presenced/lepresenced abfragt. Ist das gesuchte Bluetooth-Gerät auf einem der Pi anwesend, so wird es auch in der definierten Hauptinstanz auf anwesend gesetzt. Zusätzlich wird der Pi auf dem das Gerät gefunden wurde als Reading angegeben. Sofern alle Räume einen Empfangspegel (RSSI) ermitteln können, wird bei mehreren anwesenden Räumen der Raum mit dem besten Empfangspegel selektiert (siehe {{Link2Forum|Topic=54482}}).

=== Installation von (le)presenced ===
Diese Anleitung ist sowohl für presenced, als auch für lepresenced gültig. Einfachheitshalber wird nur lepresenced erwähnt, sämtliche Schritte gehen jedoch auch mit presenced, wobei einfach die genannten Daten durch presenced ersetzt werden müssen.

Die Software lepresenced kann aktuell über drei Varianten installiert werden. Dabei ist die bevorzugte Variante (Variante 1) die Installation über das bereitgestellte .deb-Paket.
Die Variante 2 setzt voraus, dass im FHEM contrib Verzeichnis (/opt/fhem/contrib) die aktuelle Version des .deb-Pakets liegt. Die Variante 3 ist dafür gedacht, wenn man keine .deb-Pakete installieren kann/will oder es aus anderen Gründen nicht funktioniert. Es wird davon abgeraten die Variante 3 zu verwenden. Vollständigkeitshalber wird sie aber aufgeführt.

===== Installation per .deb-Paket =====

Die bevorzugte Variante ist die Installation von lepresenced durch die passenden .deb Pakete.
{{Randnotiz|RNText=Bei einem Upgrade einer älteren Version reicht es, das neue .deb Paket mit
:<code>sudo dpkg -i lepresenced-X.XX-X.deb</code>
zu aktualisieren}}

'''1.Variante:'''
Herunterladen der aktuellen lepresenced-0.83-3.deb (Stand August 2017) Datei über den Webbrowser
[https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/ SVN-Repository]. Im SVN die passende Datei auswählen und in der folgende Webseite den Link unter:
<pre>
Download in other formats:
Original Format
</pre>
anklicken und die Datei herunterladen.
Die Datei kann jetzt auf den RPi kopiert und mit folgenden Befehlen ausgeführt werden (ggf. Berechtigungen anpassen).

Alternativ per wget Befehl direkt auf den RPi (aktuelle Versionsnummer beachten)
https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/lepresenced-0.83-3.deb

'''2.Variante:''' (zu Verwenden, wenn es Probleme bei Variante 1 gibt)
Herunterladen aus dem fhem contrib Verzeichnis:
Hierzu muss das contrib auf dem aktuellen Stand sein. Dazu wird die Installation von subversion (normal bereits vorhanden) benötigt.

sudo apt-get install subversion

Danach kann per
sudo svn checkout https://svn.fhem.de/fhem/trunk/fhem/contrib svnrepo

Das aktuelle Repository auf den Pi heruntergeladen werden. Danach sollte im gewählten Verzeichnis die eingecheckten Dateien verfügbar sein.
/opt/fhem/svnrepo/PRESENCE/deb

''' Installation der Variante 1 oder 2 '''

Egal welche Variante gewählt wurde, nun kann mit folgenden Befehlen das Paket installiert werden. Bitte Pfade ggf. anpassen.

'''Wichtig''': Das '''Paket''' hat eine ca. Größe von '''6,5Kb'''. Ab und an gibt es wohl Probleme mit der Installation, wodurch die Datei 11,5kb groß wird.
Diese Datei lässt sich nicht Installieren. In diesem Fall das Paket bitte mit der Variante 1 und dem Bereich "Download in other formats" herunterladen.

sudo dpkg -i lepresenced-0.83-3.deb

sudo apt-get -f install

Die Ausgabe der Installation sollte am Ende ein [ ok ] Starting lepresenced (via systemctl): lepresenced.service. ausgeben.

<pre>
Paketlisten werden gelesen... Fertig
Abhängigkeitsbaum wird aufgebaut.
Statusinformationen werden eingelesen.... Fertig
Abhängigkeiten werden korrigiert ... Fertig
Die folgenden zusätzlichen Pakete werden installiert:
bluez-hcidump
Die folgenden NEUEN Pakete werden installiert:
bluez-hcidump
0 aktualisiert, 1 neu installiert, 0 zu entfernen und 0 nicht aktualisiert.
1 nicht vollständig installiert oder entfernt.
Es müssen 157 kB an Archiven heruntergeladen werden.
Nach dieser Operation werden 490 kB Plattenplatz zusätzlich benutzt.
Möchten Sie fortfahren? [J/n]
Holen: 1 http://archive.raspberrypi.org/debian/ jessie/main bluez-hcidump armhf 5.23-2+rpi2 [157 kB]
Es wurden 157 kB in 0 s geholt (921 kB/s).
Vormals nicht ausgewähltes Paket bluez-hcidump wird gewählt.
(Lese Datenbank ... 42033 Dateien und Verzeichnisse sind derzeit installiert.)
Vorbereitung zum Entpacken von .../bluez-hcidump_5.23-2+rpi2_armhf.deb ...
Entpacken von bluez-hcidump (5.23-2+rpi2) ...
Trigger für man-db (2.7.0.2-5) werden verarbeitet ...
bluez-hcidump (5.23-2+rpi2) wird eingerichtet ...
lepresenced (0.82-1) wird eingerichtet ...
[ ok ] Starting lepresenced (via systemctl): lepresenced.service.
</pre>

'''3.Variante:'''

Bei dieser Variante wird das aktuellste lepresenced Skript aus github heruntergeladen. Das bedeutet, dass jegliche Konfiguration wie automatischer Start, Berechtigungen etc.
manuell konfiguriert werden muss. Diese Variante eignet sich nur für diejenigen, die keine .deb-Pakete installieren wollen/können oder die genau Wissen, was sie tun!
<pre>
https://github.com/mhop/fhem-mirror/blob/master/fhem/contrib/PRESENCE/lepresenced
</pre>

Zur "Installation" des Skripts folgendermaßen vorgehen:
Unter /fhem manuell den Ordner „script“ anlegen:
<pre>
mkdir script
</pre>
Datei lepresenced reinkopieren und ausführbar machen:
<pre>
sudo chmod +x /opt/fhem/script/lepresenced
sudo chgrp -cR dialout lepresenced
</pre>
Skript erstmalig starten:
<pre>
sudo ./lepresenced --loglevel LOG_EMERG -d
</pre>
Kommt beim Starten des Skript eine Fehlermeldung, müssen die Abhängigkeiten aufgelöst werden.
<pre>
Can't locate Net/Server/Daemonize.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.14.2 /usr/local/share/perl/5.14.2 /usr/lib/perl5 /usr/share/perl5 / usr/lib/perl/5.14 /usr/share/perl/5.14 /usr/local/lib/site_perl .) at /opt/fhem/lepresenced line 17.
BEGIN failed--compilation aborted at /opt/fhem/lepresenced line 17.
</pre>
Um die Abhängigkeiten aufzulösen muss folgendes nachinstalliert werden und anschließend ein Reboot durchgeführt werden.
<pre>
sudo apt-get install libnet-server-*
</pre>

===== Einrichtung eines Bluetooth-Geräts über FHEM =====

Nach dem letzten Schritt sind alle Bedingungen für eine abschließende Konfiguration eines BT-Geräts in FHEM abgeschlossen worden.
Jetzt kann der zum Beispiel ein G-Tag dem FHEM-Server bekannt gemacht werden:
<pre>
-- Name Modul Modus MAC vom Gtag IP vom PI Port Abfragezeit in Sekunden
define MeinGtAG PRESENCE lan-bluetooth xx:xx:xx:xx:xx:xx 127.0.0.1:5333 120
</pre>

'''Wichtig ist den angegeben Port zu unterscheiden. Für presenced muss der Port 5111 genommen werden, für lepresenced der Port 5333.'''
Den absent und present Mode kann man einfach testen, in dem man den Gtag mit Alufolie einwickelt.

Diese Variante sollte eingesetzt werden, wenn nur ein Pi nach Bluetooth-Geräten sucht. Möchte man mehr als ein Gerät nutzen um zum Beispiel eine größere Fläche abzudecken so muss mit collectored gearbeitet werden.

=== Alle Räume gemeinsam ansprechen mittels collectord ===
Um zwei presenced- oder lepresenced Installationen zu verbinden wird der collectord Daemon von Markus Bloch benötigt. Dieser kennt alle presenced-Installationen im Netzwerk und führt eine koordinierte Suche nach den gewünschten Geräten durch. Sobald ein Gerät in einem Raum erkannt wurde, meldet der collectord den Status einschließlich der Angabe des Raumes, in dem das Gerät erkannt wurde.

[[Datei:Presence_Collectord_Uebersicht.jpg|200px|thumb|left|Schematische Darstellung Presence und Collectord, Danke an dtavb]]
Auf Basis folgender Skizze wird die Einrichtung und der Betrieb der Anwesenheitserkennung und Überwachung <p></p>
mit dem PRESENCE-Modul sowie dem Skript (.deb-Paket) lepresenced beschrieben. Zusätzlich wird für die Verbindung <p></p>
mehrere lepresenced Instanzen der collectord verwendet.<p></p>
Diese Skizze dient als Basis für alle genannten Konfigurationen innerhalb dieses Artikels.
{{NeuerTextBlock}}

==== Aufbau ====
; RPi1 (Hauptinstanz):
: FHEM Installation
: presence/lepresenced Installation
: collectord installation
: Sämtliche Bluetooth-Geräte in FHEM definiert
; RPi2 (Zweitsystem):
: FHEM installation
: presence/lepresenced Installation
: Sämtliche Bluetooth-Geräte in FHEM definiert

==== Installation per .deb-Paket ====
collectord wird heruntergeladen und installiert:
https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/collectord-1.8.deb (Stand Januar 2018)
<pre>
sudo dpkg -i collectord-1.8.deb
</pre>

Nach der Installation befindet sich im Verzeichnis: /etc/collectord.conf die Konfigurationsdatei für das collectord. Weitere Einstellungen können unter /etc/default/collectord vorgenommen werden.

==== Konfiguration auf Shellebene ====
<pre>
sudo vi /etc/collectord.conf
</pre>

Diese Datei muss jetzt nach folgender Vorlage angepasst werden.
<pre>
# room definition
#[room-name] # name of the room
#address=192.168.0.10 # ip-address or hostname
#port=5111 # tcp port which should be used (5111 is default)
#presence_timeout=120 # timeout in seconds for each check when devices are present
#absence_timeout=20 # timeout in seconds for each check when devices are absent

[RPi1] # Name (wird als Reading room bei den BT-Tags angezeigt) der presence Instanze
address=127.0.0.1 # Lokale Adresse RPi1 , da hier das Collectord später laufen soll!
port=5333 # Port der Presence Installation
presence_timeout=60 # Selbstgewaehlte Pruefintervalle
absence_timeout=60 # Selbstgewaehlte Pruefintervalle

[RPi2] # Name (wird als Reading room bei den BT-Tags angezeigt) der presence Instanze
address=192.168.178.127 # IP-Adresse der Instanz, wo nur das Presence laueft, also RPi2
port=5333 # Port der Presence Installation
presence_timeout=60 # Selbstgewaehlte Pruefintervalle
absence_timeout=60 # Selbstgewaehlte Pruefintervalle
</pre>

Hinweis:
* Es dürfen keine [Namen] mit Leerzeichen verwendet werden
* Der angegebene Port richtet sich danach, ob auf dem Pi presenced (Port 5111) oder lepresenced (Port 5333) nach dem Bluetooth-Gerät sucht

==== Konfiguration in FHEM ====
;RPi1
define Gtag PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 127.0.0.1:5222 60 ''Hinweis: (Der Port ist der, des collectord!! Standard 5222)''
;RPi2
define Gtag PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 192.168.178.127:5222 60 ''Hinweis: (Der Port ist der, des collectord!! Standard 5222 - die IP-Adresse von die von RPi1)''

Nach der Konfiguration kann der Daemon gestartet werden.
Sobald das Bluetoothgerät irgendwo in der Wohnung erkannt wurde, meldet der Collectord dies sofort
an FHEM und teilt den Raum mit in dem es erkannt worden ist. Diese Information wird im Reading "rooms" des jeweiligen BT-Gerätes dargestellt.

Zum testen sollte collectord einmalig manuell gestartet werden. Dies hat den Vorteil, dass man nochmal den Port des collectord prüfen kann, dieser steht in der Zeile <pre>created socket on 0.0.0.0 with port 5222</pre> und man sehen kann, ob der collectord richtig startet, oder Fehler auswirft. Gestartet wird mit folgendem Kommando:
<pre>
sudo collectord -vv -c /etc/collectord.conf
</pre>
Die Ausgabe sieht wie folgt aus:
<pre>
2017-04-02 17:52:55 - =================================================
2017-04-02 17:52:55 - started with PID 15554
2017-04-02 17:52:55 - reading configuration file
2017-04-02 17:52:55 - no config errors found
2017-04-02 17:52:56 - created socket on 0.0.0.0 with port 5222
2017-04-02 17:53:20 - new connection from 127.0.0.1:48656
2017-04-02 17:53:20 - created thread 1 for processing device 7C:2F:80:E1:14:31 in room RPi2 for peer 127.0.0.1 (UUID: d0beb79dd4771532eb5e207c7bf31788)
2017-04-02 17:53:20 - created thread 2 for processing device 7C:2F:80:E1:14:31 in room RPi1 for peer 127.0.0.1 (UUID: d0beb79dd4771532eb5e207c7bf31788)
2017-04-02 17:53:20 - new connection from 127.0.0.1:48662
2017-04-02 17:53:20 - new connection from 127.0.0.1:48664
2017-04-02 17:53:20 - created thread 3 for processing device 7C:2F:80:ED:BC:F7 in room RPi2 for peer 127.0.0.1 (UUID: 7495a112063d5db45e6335d3fe305e36)
2017-04-02 17:53:20 - created thread 4 for processing device 7C:2F:80:ED:BC:F7 in room RPi1 for peer 127.0.0.1 (UUID: 7495a112063d5db45e6335d3fe305e36)
2017-04-02 17:53:20 - created thread 5 for processing device 7C:2F:80:E1:2A:4D in room RPi2 for peer 127.0.0.1 (UUID: c228f8d4d33b06787f995c7903c02760)
2017-04-02 17:53:20 - created thread 6 for processing device 7C:2F:80:E1:2A:4D in room RPi1 for peer 127.0.0.1 (UUID: c228f8d4d33b06787f995c7903c02760)
2017-04-02 17:53:22 - new connection from 192.168.xxx.xxx:51638
2017-04-02 17:53:22 - created thread 7 for processing device 7C:2F:80:E1:14:31 in room RPi2 for peer 192.168.xxx.xxx (UUID: 5db7012e709d6dc2fcd8159fc0344e40)
2017-04-02 17:53:22 - created thread 8 for processing device 7C:2F:80:E1:14:31 in room RPi1 for peer 192.168.xxx.xxx (UUID: 5db7012e709d6dc2fcd8159fc0344e40)
2017-04-02 17:53:22 - new connection from 192.168.xxx.xxx:51640
2017-04-02 17:53:22 - created thread 9 for processing device 7C:2F:80:ED:BC:F7 in room RPi2 for peer 192.168.xxx.xxx (UUID: c4b4d7c654132cf88e8c1fec3a956d3d)
2017-04-02 17:53:23 - created thread 10 for processing device 7C:2F:80:ED:BC:F7 in room RPi1 for peer 192.168.xxx.xxx (UUID: c4b4d7c654132cf88e8c1fec3a956d3d)
2017-04-02 17:53:29 - new connection from 192.168.xxx.xxx:51642
2017-04-02 17:53:29 - created thread 11 for processing device 7C:2F:80:E1:2A:4D in room RPi2 for peer 192.168.xxx.xxx (UUID: ecd7081e5ae3a0d8e735c8750cb116a1)
2017-04-02 17:53:29 - created thread 12 for processing device 7C:2F:80:E1:2A:4D in room RPi1 for peer 192.168.xxx.xxx (UUID: ecd7081e5ae3a0d8e735c8750cb116a1)
</pre>

Wenn das Log wie oben abgebildet aussieht wurde alles richtig gemacht und unter dem Device in FHEM erscheint ein neues Reading "rooms" mit dem Wert der erkannten PRESENCE-Installation.

'''Verhalten presence timeout im zusammenhang mit dem Attribut "absenceThreshold" der PRESENCE Konfiguration in FHEM'''
<br>
In der collectord.conf sind <code>presence_timeout</code> und <code>absence_timeout</code> für den jeweiligen Raum konfiguriert.
Das bedeutet, sobald irgendein Gerät in diesem jeweiligen Raum anwesend/abwesend ist, wird das jeweilige Timeout an den verbundenen presenced/lepresenced geschickt um damit das Check-Interval entsprechend zu ändern.

In der PRESENCE-Definition kann man ebenfalls ein <code>absence_timeout</code>/<code>presence_timeout</code> setzen. Sobald sich der Zustand ändert, wird auch das jeweilige Timeout an den collectord gesandt. Dies hat aber auf die Checks in den jeweiligen Räumen und damit der collectord.conf keinen Einfluss. Der collectord schickt ein Statusupdate an PRESENCE nur, wenn das vorgegebene Timeout (von PRESENCE) erreicht ist und keine Statusänderung stattfand. Sobald eine Änderung des Status erfolgt wird natürlich sofort der Status an PRESENCE geschickt.

Das Attribut absenceThreshold/presenceThreshold funktioniert nachwievor. Hier ist nur wichtig wie man die Timeouts sowohl in PRESENCE als auch collectord.conf setzt.

'''Das Reading "room" bei einer PRESENCE Definition und der Zusammenhang zu collectord'''
<br>
Wenn ein BT LE Empfänger in mehr als einem Raum detektiert wird, führt der collectord (ab Version 1.8) eine RSSI-Erkennung durch. Sofern alle Räume den Empfangspegel (RSSI) ermitteln können, wird der Raum mit dem besten Empfangspegel als Raum für das "room"-Reading ausgewählt. Der lepresenced in aktueller Version von PatrickR gibt immer den Empfangspegel aus.

==== Automatischer Start ====
Wenn der collectord per .deb Paket installiert wurde, startet er automatisch bei einem Reboot mit (via systemd/init-Skript).
<br>

Der Collectord wird standardmäßig mit dem Port 5222 gestartet. Um diese anzupassen sind zwei Schritte notwendig:<br>
'''1.)''' Anpassen der /usr/bin/collectord
Hier bitte den Parameter my $opt_p von 5222 auf 5XXX abändern.

Da der collectord mittlerweile per systemd beim reboot des RPi gestarte wird muss auch diese Konfiguration auf den neuen Port angepasst werden.<br>
'''2.)''' Anpassen der /etc/default/collectord
<pre>
# collectord startup defaults:
# The TCP port collectord will listen for incoming connections (default: 5222)
PORT=5111
# The location of the configuration file (default: /etc/collectord.conf
CFGFILE=/etc/collectord.conf
</pre>

Manuell starten als Daemon (Parameter <code>-d</code>) mit:
<pre>
sudo collectord -c /etc/collectord.conf -d -v -l /var/log/collectord.log
</pre>

== Batterieüberwachung ==

=== Batterieüberwachung mit dem Modul BleTagBattery ===
{{Infobox Modul
|ModPurpose=Anwesenheitserkennung
|ModType=h

|ModTechName=74_BleTagBattery
|ModOwner=mumpitzstuff
}}
Mit dem Modul BleTagBattery - kann der Batteriestatus aller BT-LE Devices gelesen werden.
Es werden die Readings batteryLevel und battery angelegt für diejenigen BT-LE Tags, die an einer PRESENCE-Installation registriert wurden.

Vorraussetzung und Installation:

Bluez und Gattool
sudo apt-get install bluez

Das Gattool ist in den Installationen von Bluez inbegriffen.

Hinzufügen des githup für das Modul
update add http://raw.githubusercontent.com/mumpitzstuff/fhem-BleTagBattery/master/controls_bletagbattery.txt
update all
restart fhem: shutdown restart
BT-LE tags muss an einer PRESENCE-Installation des type "lan-bluetooth" registriert sein.

Nach dem Neustart von FHEM kann das Modul definiert werden:
define a new device: define <name of device> BleTagBattery

Das Modul versucht in der Standardkonfiguration alle 6 Stunden die BT-LE Devices zu erreichen und das Reading batteryLevel und battery zu aktualisieren.
Das Update kann auch manuell mit dem folgenden Befehl erzwungen werden

set <name of device> statusRequest.

Weiter Informationen und Disskussionen können dem eigentlichen [https://forum.fhem.de/index.php?topic=68104.0 Forumsbeitrag] entnommen werden,

=== Batterieüberwachung (aktuell nur G-Tags) ===

Leider überträgt der G-Tag nach der Einrichtung als Device in FHEM kein Reading mit seinem aktuellen Batteriestatus.
Dem wurde mit Hilfe des Forum Abhilfe geschaffen.
Im Folgenden wird erläutert wie die Batterieüberwachung eingerichtet werden kann.

'''Voraussetzung:'''

bc - Basiscalculator [https://packages.debian.org/de/sid/bc Bc-Paket]
<pre> sudo apt-get install bc </pre>

Anlegen eines Shellskript auf dem Raspberry System.
Die Parameter <<MAC-Adresse>> und <<TagName>> müssen durch die Werte des auszulesenden G-Tags ersetzt werden.
<pre>
#!/bin/bash
stringZ=$(sudo gatttool -b 5C:2B:80:C1:14:41 --char-read --handle=0x001b)
stringZ=${stringZ:33:2}
stringZ=$(echo "$stringZ" | tr a-f A-F)
decimal=$(echo "ibase=16; $stringZ" | bc)
perl /opt/fhem/fhem.pl 7072 "setreading MeinGtag Batterie $decimal"
</pre>

Dem Device in FHEM (hier MeinGtag) ein userReading mit dem Namen '''Batterie''' hinzufügen.
Das Shellskript mit folgendem Befehl starten:
<pre>
./GtagBatterie.sh
</pre>
'''Wichtig ist hierbei,''' dass Skript mit "./" und nicht mit "sh" aufzurufen. Beim Aufruf mit "sh GtagBatterie.sh" produziert es einen Fehler
<pre>GtagBatterie.sh: 3: GtagBatterie.sh: Bad substitution </pre>

Das Reading wird auf den ausgelesenen Wert der Batterie gesetzt.

Hinweis: Es sollte für jeden G-Tag ein eigenes Skript abgelegt werden. Das Skript kann per crontab oder fhem Kommando (system) regelmäßig aufgerufen werden.

=== Batterieüberwachung (alle Devices vom Typ "MODE=lan-bluetooth") ===

Es gibt eine weitere Möglichkeit um den Batteriestatus von LE Devices abzurufen und in FHEM als Reading darzustellen.
Dabei wird der Batteriezustand für alle LE Devices, die bereits in FHEM konfiguriert sind und per lepresenced überwacht werden, automatisch in einem shell-Script ermittelt.
Näheres dazu im Forumartikel {{Link2Forum|Topic=56960|LinkText=Erweiterung: Anwesenheitserkennung/Batterieüberwachung}}.

Vorteile:
* Automatische Ermittlung aller in FHEM konfigurierten LE Devices
* Möglichkeit, diese Devices alternativ manuell im Script einzutragen
* Es werden nur Devices abgefragt, die im Status "present" sind, also mit ziemlicher Sicherheit auch verfügbar sind
* Ein eventuell auf dem FHEM telnet-Port gesetztes Passwort kann im Script hinterlegt werden

'''Voraussetzung:'''

'''Funktionierendes lepresenced''' - siehe [[Anwesenheitserkennung#Anleitung_f.C3.BCr_ein_LE_Device_.28z.B._Gtags.2CPebbles_etc..29|Anleitung für ein LE Device (z.B. Gtags,Pebbles etc.)]]

'''socat''' - TCP port forwarder
<pre>
sudo apt-get update && sudo apt-get install socat
</pre>

'''gawk''' - Zum extrahieren der Daten
<pre>
sudo apt-get update && sudo apt-get install gawk
</pre>

'''gatttool''' - Bestandteil von bluez

gatttool ist auf den meisten Distributionen im bluez-Paket, allerdings nicht bei Opensuse. Dort muss man das Sourcepaket von bluez installieren und selbst kompilieren.
gatttool sollte dann nach /usr/bin oder /usr/local/bin kopiert werden,

Zusätzlich zu den notwendigen Erweiterungen werden für die Ausführung von gatttool '''Root-Rechte benötigt'''!

Das Script selbst gibt es hier: [https://raw.githubusercontent.com/micky0867/lebattery/master/lebattery lebattery]

Am Besten unter /opt/fhem/script/lebattery speichern und ausführbar machen:
<syntaxhighlight lang="bash">
sudo su -
mkdir /opt/fhem/script
cd /opt/fhem/script
wget https://raw.githubusercontent.com/micky0867/lebattery/master/lebattery
chmod 755 lebattery
</syntaxhighlight>

Je nach Bedarf können im Script noch die folgenden 3 Parameter angepasst werden:
<syntaxhighlight lang="bash">
# If allowed_telnetPort is protected by a password, add the password here
TELNETPASSWORD=""
# Attribute for batterylevel in FHEM
ATTRIBUT="batterylevel"
# Use this, if you dont want the script to determine the tags on its own
LETAGS=""
</syntaxhighlight>

Das Skript wird dann unter root folgendermaßen gestartet:
<pre>
/opt/fhem/script/lebattery -v
</pre>

Ausgabe des Skripts, wenn es mit dem Verbose Parameter -v gestartet wird.

Beide Devices sind vom Typ NUT mini, das Device mit dem FHEM-Namen '''nut_Micky''' ist im Status '''absent'''. Das zweite Device ist im Status '''present'''.
<pre>
Determining address for nut_Micky ...
nut_Micky is in state absent, no further action required

Determining address for nut_Test ...
Fetching batterylevel for nut_Test (F3:44:04:81:54:89) ...
Setting batterylevel for nut_Test to 100%
</pre>

Mein crontab-Eintrag (User root) sieht so aus:
<pre>
3 3 * * * /opt/fhem/script/lebattery -v >/opt/fhem/script/lebattery.log 2>&1
</pre>
Damit wird jeden Morgen um 3 Minuten nach 3 Uhr der Zustand der Batterien aller Devices ermittelt und in FHEM abgespeichert.<br>
Bevor man das mit crontab macht, sollte man allerdings zunächst sicher stellen, dass es auch ohne crontab funktioniert....

Bei Problemen kann man auch erstmal schauen, ob das mit dem gattool überhaupt funktioniert:
<pre>
gatttool -t <Typ> -b <MAC-Adresse> --char-read --uuid 0x2a19

handle: 0x0017 value: 64
</pre>
In diesem Fall hat die Batterie noch 100% (hex 64).<br>
Der Typ ist abhängig vom Hersteller und kann public (G-Tags) bzw. random (Nut) sein. Im Zweifelsfall beides ausprobieren.

= Beispiele =
== Anwesenheitserkennung / Anwesenheitsbenachrichtigung mit G-Tags ==
Ein Skript zur Nutzung der Gigaset G-TAGs zur Alarmierung bei öffnen und schließen von Türen und zur Anwesenheitserkennung, um die Alarmierung zu aktivieren bzw. deaktivieren.
Es kann verwendet werden um die Anwesenheit von mehrern Personen im Haushalt zu erkennen. Dabei wird eingeschränkt, dass nur bestimmte Personen die Alarmierung aktivieren können ( Eltern/Kind -Beziehung ).
Des Weiteren werden im Beispiel die Eltern benachrichtigt wenn eins der Kinder das Haus verlässt und die Eltern nicht anwesend sind.

{{Randnotiz|RNText=Namen der G-Tags in den Skripten bitte anpassen!}}

Für die ''Notify'' und die ''RESIDENTS-Erweiterung'' wird ein Dummy benötigt.
<pre>
define Alarm dummy
attr Alarm devStateIcon aktiv:secur_locked@red inaktiv:secur_open@lightgreen
attr Alarm eventMap on:aktiv off:inaktiv
attr Alarm setList on off
attr Alarm webCmd aktiv:inaktiv
attr Alarm room Alarm
</pre>

=== Mit Notify ===
<pre>
gtag.*.presence:.* {Anwesenheit_check("$EVTPART1", "$NAME")}
</pre>

Code für die 99_myUtils.pm
<pre>
### GTAG ANWESENHEITS CHECK
sub Anwesenheit_check($$) {
my ($EVENT, $NAME) = @_;

# gtag_rot - Alias Marco
# gtag_schwarz - Alias Ulli
# gtag_gruen - Alias Frida
# gtag_orange - Alias Hannah

my $RESIDENT = "rr_"; # Alle GTAGs sind Standardmäßig Residents Roommate
# $RESIDENT = "rg_" if (($NAME eq "gtag_orange") xor ($NAME eq "gtag_weis")); # Hier nur Gäste (Roomguest) Auskommentiert, da ich es so nicht brauche
my $ROOMMATE = ("$RESIDENT" . "$NAME"); # Residentsname zusammenbauen
my $ALIASNAME = AttrVal($ROOMMATE,'alias',$ROOMMATE); # ALIAS des Roommates auslesen

my $GTAG1 = Value('gtag_rot'); # ELTERN
my $GTAG2 = Value('gtag_schwarz'); # ELTERN

my $STATUS = "wahrscheinlich gerade los";
$STATUS = "anwesend" if ($EVENT eq "present"); # Status: anwesend
$STATUS = "unterwegs" if ($EVENT eq "absent"); # Status: unterwegs

Log 1, "$ALIASNAME ist $STATUS."; # LOG Eintrag erzeugen

if (($EVENT eq "present" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_gruen" xor $NAME eq "gtag_orange")) {
fhem("set teleBot send ALARMIERUNG BLEIBT AKTIV: $ALIASNAME ist da..."); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG BLEIBT AKTIV' '$ALIASNAME ist da...'"); # Pushover
}
elsif (($EVENT eq "present" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_rot" xor $NAME eq "gtag_schwarz")) {
fhem("set teleBot send ALARMIERUNG INAKTIV: $ALIASNAME ist da...; set Alarm inaktiv"); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG INAKTIV' '$ALIASNAME ist da...'; set Alarm inaktiv"); # Pushover
}
elsif (($EVENT eq "absent" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_gruen" xor $NAME eq "gtag_orange")) {
fhem("set teleBot send ALARMIERUNG BLEIBT AKTIV: $ALIASNAME hat das Haus verlassen."); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG BLEIBT AKTIV' '$ALIASNAME hat das Haus verlassen.'"); # Pushover
}
elsif (($EVENT eq "absent" && Value("Alarm") eq "inaktiv") && ($GTAG1 eq "absent" && $GTAG2 eq "absent")) {
fhem("set Alarm aktiv; set teleBot send ALARMIERUNG AKTIV: $ALIASNAME hat das Haus verlassen."); # Telegram
# fhem("set Alarm aktiv; set Infopush msg 'ALARMIERUNG AKTIV' '$ALIASNAME hat das Haus verlassen.' '' 0 ''"); # Pushover
}
}
</pre>

<br>

=== Mit Notify und Integration des RESIDENTS-MODUL ===

Der hier beschriebene Code erweitert die Funktionen unter dem Punkt 5.93.
Das Notify muss daher mit der folgenden Zeile erweitert werden.

<pre>
define Alarm_AnwesenheitCheck notify gtag.*.presence:.* { Anwesenheit_check("$EVTPART1", "$NAME"), Anwesenheit_check_resi("$NAME") }
</pre>

Zusätzlicher Code für die 99_myUtils.pm um die RESIDENTS Funktion nutzen zu können:
<pre>
### RESIDENTS
sub Anwesenheit_check_resi($) {
my ($NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME); # ALIASNAME des GTAGs auslesen

my $RESIDENT = "rr_"; # Als Standard sind alle GTAGs Roommates
$RESIDENT = "rg_" if (($NAME eq "gtag_orange") xor ($NAME eq "gtag_weis")); # Hier nur GTAG Namen der Gäste (Roomguest)
my $ROOMMATE = ("$RESIDENT" . "$ALIASNAME"); # Residentsname zusammenbauen

if (ReadingsVal($NAME,'presence',$NAME) eq "absent") {
fhem("set $ROOMMATE absent"); # Resisents Status von Roommates setzen
}
elsif(ReadingsVal($NAME,'presence',$NAME) eq "present") {
fhem("set $ROOMMATE home"); # Resisents Status von Roommates setzen
}
}
</pre>
<br>

=== Mit Notify und Fenster/Tür. -Kontakt Überwachung ===

Erweiterung für die Überwachung von Fenster/Tür. -Kontakten. Dazu sind zwei weitere Notifys notwendig die auf die Trigger der Kontakte regagieren
und so eine weitere Funktion in der 99_myUtils.pm ansprechen. Die Notifys triggern auf Kontakte die mit dem Namen Kontakt* beginnen.
Sollten die eigenen Fenster/Tür. -Kontakt anderen Namen besitzen, müssen die Skripte dementsprechend angepasst werden.
<pre>
define Alarm_Kontaktmeldung notify Kontakt.*:contact:.* {Kontakt_Meldung("$EVTPART1", "$NAME")}
</pre>
<pre>
define Alarm_Sabotagealarm notify Kontakt.*.sabotageError:.on {Kontakt_Sabotage("$EVTPART1", "$NAME")}
</pre>

Zusätzlicher Code für die 99_myUtils.pm um die TÜRKONTAKTE-Meldung nutzen zu können:
<pre>
### TÜRKONTAKTE-Meldung/Zustand
sub Kontakt_Meldung($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME);
Log 1, "$ALIASNAME wurde $EVENT";
if (ReadingsVal("Alarm", "state", "on") eq "on") {
fhem("set teleBot send $ALIASNAME wurde $EVENT"); # Nachricht über Telegram
# fhem("set Infopush msg '$ALIASNAME' '$ALIASNAME wurde $EVENT'"); # Nachricht über Pushover
}
}

### TÜRKONTAKTE-Sabotagealarm

sub Kontakt_Sabotage($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME);
Log 1, "$ALIASNAME meldet Sabotagealarm";
fhem("set teleBot send Alarm: $ALIASNAME meldet Sabotagealarm"); # Nachricht über Telegram
# fhem("set Infopush msg 'Alarmanlage' '$ALIASNAME meldet Sabotagealarm' '' 2 ' ' 60 600 "); # Nachricht über Pushover
}
</pre>
<br>

=== Hinweis zur Benutzung / Fehlerhandling ===

Der Alarm dummy hat den Zustand on:off. Die Bezeichnungen und Namen müssen 1:1 übernommen werden damit das Script funktioniert.
Andernfalls müssen die Bezeichnungen für z.B. absent:unterwegs und present:anwesend - angepasst werden.
Die Benachrichtigung kann aktuell per ''[[TelegramBot|Telegram]]'' sowie ''Pushover'' ('''Achtung mit zweiterem sind Abokosten verbunden!''') realisiert werden.
Diskussion zum Thema im Forum unter: {{Link2Forum|Topic=64080}}
<br>

= Problemlösungen =

'''Absent - Grundlos / Zufällig''' 2022

Zufällige oder Grundlose absent-Meldungen einzelner G-Tags können mit einem FIX behoben werden. Dazu ist es notwendig die BT-Firmware downzugraden.

Auf GIT das .deb Paket herunterladen und auf das jeweiligen System kopieren

wget <nowiki>https://github.com/winterheart/broadcom-bt-firmware/releases/download/v12.0.1.1105_p3/broadcom-bt-firmware-10.1.0.1115.deb</nowiki>

Anschliessend installieren und das System neu starten.

sudo dpkg -i broadcom-bt-firmware-10.1.0.1115.deb
{{Randnotiz|RNText= Dieser FIX scheint nicht bei jedem zu funktionieren! Es gibt auch System die Problemlos ohne FIX arbeiten. Bei einem Update/Upgrade des RPI muss der FIX - wenn notwendig - wieder erneut installiert werden.}}

Danach sollten die Tags wieder Problemlos erkannt werden und nicht nach wenigen Tagen wieder auf "absent" stehen.

Falls es '''Probleme beim Starten des Skripts''' gibt bzw. man das Skript ohne Reboot des Systems neustarten möchte, kann man dies per kill Befehl erledigen.

Das Thema wurde u.a in [https://forum.fhem.de/index.php?topic=75559.new;topicseen#new diesem] Beitrag beschrieben.
<syntaxhighlight lang="bash">
ps -ef | grep lepresenced
sudo kill <pid>
</syntaxhighlight>

Debuglevel lepresenced setzen:
{{Randnotiz|RNText=Um Debug-Meldungen zu bekommen (Vorsicht bei SD-Karten-Systemen wie dem RPi) - Hierbei werden die Schreibzyklen auf die SD-Karte erhöht.}}

Der Log Level muss im lepresenced-Skript selbst verändert werden. Um den Log-Level auf INFO/WARNING/DEBUG zu setzen, das Skript lepresenced mit einem Editor öffnen und die Stellen, wo LOG_WARNING zu finden ist, durch den nötigen LOG-Eintrag ersetzen.

<pre>
lepresenced --loglevel LOG_DEBUG
</pre>
Nur das wichtigste Loggen:
<pre>
lepresenced --loglevel LOG_WARNING
</pre>
Keinerlei LOG-Einträge
<pre>
lepresenced --loglevel LOG_EMERG
</pre>

Bei '''Problemen mit der Batterieüberwachung''' der Tags kann die Pi Firmware mit folgenden Befehl auf eine ältere Version zurückgesetzt werden.
Fehlermeldung beim Aufruf des lebattery oder anderen Batterietestskripten:
<pre>connect: Connection refused (111)</pre>

Lösung (vorübergehend)
<pre>
sudo rpi-update 8521fd34c8f66b6d109acce943f6e25ec93ec005
</pre>

Mehr dazu unter: {{Link2Forum|Topic=56960|Message=589165}}

'''Das BT-Device ist ständig "absent"'''<br>
Eine Mögliche Lösung kann sein, das Paket bluez-hcidump zu installieren. Das Werkzeug hcidump erlaubt die Beobachtung von Bluetooth-Aktivitäten.
Dies ist nicht notwendig, wenn bereits bluez installiert ist, da dies Teil des bluez Paketes ist
<pre>
sudo apt-get install bluez-hcidump
</pre>

'''Fehler in Logdateien /var/log/syslog und /var/log/kernel'''
Jul 29 15:08:11 raspberrypi kernel: [ 4905.634211] bt_err_ratelimited: 1 callbacks suppressed
Jul 29 15:08:11 raspberrypi kernel: [ 4905.634231] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:12 raspberrypi kernel: [ 4906.647350] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:13 raspberrypi kernel: [ 4907.532081] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:13 raspberrypi kernel: [ 4907.655564] Bluetooth: hci0 advertising data length corrected

Die Ursache des Problems ist noch nicht ergründet, allerdings betrifft dies aktuell nur den RPi3. Die Fehlermeldungen werden in verschiedene Logs geschrieben. Darunter maßgeblich "syslog" und "kern.log".

Lösung (vorübergehend):
Unterbinden der Einträge durch Anlage eines blocklist Eintrag:

1. Unter "/etc/rsyslog.d" eine Datei erzeugen mit dem Namen "01-blocklist.conf"
2. Inhalt: (Die Ausdrücke in den "" sind diejenigen, die aus dem log verschwinden sollen. - bei mir waren es die untenstehenden")
:msg,contains,"Bluetooth: hci0 advertising data length corrected" stop
:msg,contains,"bt_err_ratelimited:" stop
3. Dienst neu starten "sudo service rsyslog restart"

Weiter Infos werden im offiziellen Thema {{Link2Forum|Topic=28753|Message=499184|LinkText=hier}} diskutiert.

Seit Version 0.82 kann es beim Start zu folgenden Meldungen im Log kommen.
Sep 06 16:13:45 raspberrypi systemd[1]: Started lepresenced.
Sep 06 16:13:45 raspberrypi lepresenced[16010]: [tid:1] main::bluetooth_scan_thread: Received 'Set scan parameters failed: Input/output error', ...tting...
Sep 06 16:13:46 raspberrypi lepresenced[16010]: [tid:1] main::bluetooth_scan_thread: hcitool exited, retrying...

Diese Meldungen können ignoriert werden. Abhilfe schafft sich lepresenced selbst, indem es sich resettet.

'''Moderne iPhones und Android Geräte wechseln in den Schlaf-Modus''', um Energie zu sparen. Somit sind die Geräte zur Anwesenheitserkennung nicht per Ping zu erreichen.
Durch das Programm hping3, lassen sich zyklisch Pakete an die Geräte senden, um sie wieder "aufzuwecken".

Mehr im Forum [https://forum.fhem.de/index.php/topic,76342.0.html]

= Versionsänderungen lepresenced =
<pre>
--Version 0.81 (BasisVersion)
--Version 0.82 (stable 08/2017)
-Neue Kommandozeilenoption "--debug": Startet lepresenced im Vordergrund und gibt ausführliche Debug-Informationen auf STDOUT aus.
-Sanity Check: lepresenced prüft beim Starten die Verfügbarkeit von hciconfig, hcitool und hcidump.
-Model: lepresenced übermittelt das Reading model nun als lan-lepresenced. Das erlaubt die Erkennung von lepresenced in der FHEM-Statistik (sofern aktiviert).
--Version 0.83 (stable 09/2017)
- Behebung von Systemstart Fehlern
- Weitere Debug-Möglichkeiten. U. a. wird nun mitgezählt, ob hcitool lescan ("legacy") und hcidump eine identische Zahl an Beacons empfangen
</pre>

= Ansprechpartner =
# {{Link2FU|117|markusbloch }} (Markus) für das PRESENCE-Modul und collectord
# {{Link2FU|5068|PatrikR}} (Patrick) für lepresenced
# [[Benutzer Diskussion:Devender|Devender]] ({{Link2FU|20043|Dirk}}) für Wiki und Doku

[[Kategorie:Anwesenheitserkennung]]

Ble2mqtt

2023-11-09T10:24:59Z

Drhirn: Baustelle entfernt

{{Infobox Modul
|ModPurpose=Anwesenheitserkennung von Bluetooth-Geräten
|ModType=u
|ModFTopic=127173
|ModForumArea=Unterstützende Dienste
|ModTechName=ble2mqtt
|ModOwner=PatrickR
}}
'''ble2mqtt''' ist ein Script, dass den Anwesenheitsstatus eines oder mehrerer Bluetooth Low Energy Geräte überprüfen und das Ergebnis an einen MQTT Broker schicken kann.

Es verwendet dazu die Linux Tools ''bluetoothctl'' und ''gatttool''.

ble2mqtt ist in Perl geschrieben und wurde von {{Link2FU|5068|PatrickR}} erstellt. Weitere Informationen finden sich in diesem {{Link2Forum|Topic=127173|LinkText=Forums-Topic }}. Fragen dazu bitte in den Bereich [https://forum.fhem.de/index.php?board=44.0 Unterstützende Dienste]


==Voraussetzungen==
* Debian od. Raspberry Pi OS
* Bluetooth Empfänger

==Parameter==
Beim Start von ble2mqtt können folgende Parameter angegeben werden:

{| class="wikitable"
!Parameter!!Beschreibung!!Standardwert!!Beispiel!!Optional
|-
| --mqttserver
|Die Adresse des MQTT Brokers inklusive Port
|
| --mqttserver mqtt.example.org:1883
|nein
|-
| --mqttfingerprint
|Der Fingerprint des für die TLS-verschlüsselte Kommunikation mit dem MQTT Broker verwendeten Zertifikates
|
| --mqttfingerprint bfe5d244a821194230f1479fe2f8f7bbcd2a8cb8
|ja
|-
| --mqtttopic
| An welches MQTT-Topic das Tool die Informationen schicken soll.
|ble2mqtt
| --mqtttopic ble2mqtt/Wohnzimmer
|ja
|-
| --mqttuser
|Der Benutzernamen, unter dem die Verbindung zum Broker hergestellt werden soll
|
| --mqttuser ble2mqtt
|ja bzw. abhängig vom Broker
|-
| --mqttpass
|Das zum Benutzernamen gehörende Passwort
|
| --mqttpass verysecret3
|ja bzw. abhängig vom Broker
|-
| --retain
|Versendet die Nachrichten present und lastseen als retained.
|0
| --retain
|ja
|-
| --daemonize
|Wenn ble2mqtt im Hintergrund (als Daemon) ausgeführt werden soll
|0
| --daemonize
|ja
|-
| --loglevel
|Wie und was genau protokolliert werden soll. Mögliche Loglevel sind LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
|LOG_INFO
| --loglevel LOG_ERR
|ja
|-
| --logtarget
|Wohin gelogged werden soll. Mögliche Optionen sind ''syslog'' und ''stdout''.
|syslog
| --logtarget stdout
|ja
|-
| --absentinterval
|Anzahl an Sekunden, nach denen das Gerät als abwesend bezeichnet werden soll. Mindestwert ist 30.
|60
| --absentinterval 120
|ja
|-
| --rssithreshold
|Ab welcher Abweichung des RSSI Wertes ein Update getriggert werden soll. Mindestwert ist 5.
|10
| --rssithreshold 8
|ja
|-
| --watchdogthreshold
|Ab welchem Zeitraum in Sekunden nach Empfangen des letzten BT-Signals ble2mqtt neu gestartet werden soll. Mindestwert ist 30. Der Wert 0 bedeutet deaktiviert, also nie.
|0
| --watchdogthreshold 30
|ja
|-
| --debug
|Kann nur gemeinsam mit --daemonize verwendet werden, um Logeinträge auf stdout auszugeben. Je höher die Nummer, desto mehr Output.
|0
| --daemonize --debug 4
|ja
|-
| --mac
|Filtert mittels Regex nach MAC-Adressen der von ble2mqtt zu beachtenden BLE-Geräte. Alle anderen Geräte werden ignoriert.
|
| --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'
|ja
|-
| --batterymaxage
|Zeit in Stunden, nach denen ein Batterie-Wert als veraltet angesehen und aktualisiert wird. Der Wert 0 deaktiviert den Batterie-Check.
|48
| --batterymaxage 6
|ja
|-
| --forcebattery
|Nur in Kombination mit --mac. Erzwingt einen Batterie-Check, auch wenn das battery-service am Gerät nicht erkannt wird.
|0
| --forcebattery
|ja
|}
===Beispiele===
* Broker verlangt Username/Passwort; es sollen keine Batterie-Werte ausgelesen werden
ble2mqtt --mqttserver mqtt.example.org:1883 --mqttuser ble2mqtt --mqttpass verysecret3 --batterymaxage 0

* Broker verlangt keine Authentifizierung; es soll nach zwei G-Tags gesucht werden; definiertes MQTT-Topic; Batteriewerte benötigt
ble2mqtt --mqttserver mqtt.example.org:1883 --mqtttopic ble2mqtt/Wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'

* Broker verlangt keine Authentifizierung; Geräte sollen nach 45s ohne Kontakt als abwesend angezeigt werden; MQTT Nachrichten sollen gespeichert bleiben
ble2mqtt --mqttserver mqtt.example.org:1883 --absentinterval 45 --retain

==Installation==
Zur Installation muss das ble2mqtt-Script auf den Server kopiert werden und es müssen diverse Linux- und Perl-Pakete installiert werden.

Zuerst das Script nach /usr/local/bin kopieren, um beim Aufruf in der Bash nicht immer den ganzen Pfad voranstellen zu müssen.
sudo cp -a ble2mqttd /usr/local/bin/
Danach das Script noch als ausführbar markieren
sudo chmod +x /usr/local/bin/ble2mqttd

===Benötigte Linux Pakete===
Die benötigten Pakete können ganz einfach mit ''apt'' installiert werden. Dabei werden auch mögliche Abhängigkeiten automatisch installiert.

sudo apt install -y libssl-dev libio-socket-ssl-perl libreadonly-perl libtest-expect-perl libnet-ssleay-perl libnet-server-perl

===Benötigte Perl-Module===
Es wird das Modul ''Net::MQTT::Simple'' (''libnet-mqtt-simple-perl'') benötigt. Das ist - Stand 08.11.2023 - noch nicht in den Stable-Repositories von Debian verfügbar und muss daher mittels ''cpan'' installiert werden. Voraussetzung dafür ist das Modul ''CPAN::DistnameInfo'', welches zuerst installiert werden muss.

sudo cpan CPAN::DistnameInfo
sudo cpan Net::MQTT::Simple

Sobald ''libnet-mqtt-simple-perl'' verfügbar ist, kann dieses statt der Perl-Module wie ein normales Linux-Paket installiert werden.

===Erster Test===
Mit einem einfachen Aufruf von '''ble2mqtt''' kann getestet werden, ob alle benötigten Module und Pakete vorhanden sind.

sudo /usr/local/bin/ble2mqttd

===Erstellen einens Systemd-Daemons===
Damit '''ble2mqtt''' bei jedem Systemstart automatisch gestartet wird, muss ein Systemd-Daemon erstellt werden. Das wird gemacht, in dem eine neue Textdatei mit folgendem Inhalt angelegt und der Daemon dann aktiviert wird.

{{Hinweis|'''Wichtig:''' Das Kommando, mit welchen Parametern ble2mqtt gestartet wird, muss natürlich individuell angepasst werden!}}

sudo nano /etc/systemd/system/ble2mqttd.service

<syntaxhighlight lang="ini">
[Unit]
Description=ble2mqttd
After=bluetooth.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/ble2mqttd --mqttserver mqtt.example.com:1883 --mqtttopic ble2mqtt/wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)' --absentinterval 30 --mqttuser <username> --mqttpass <password>

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

sudo systemctl daemon-reload
sudo systemctl enable ble2mqttd.service
sudo systemctl start ble2mqttd.service

==Einbindung in FHEM==
Da ble2mqtt alle Informationen an einen [[MQTT]]-Broker sendet, können diese Informationen ganz einfach als [[MQTT2_DEVICE]] in FHEM eingebunden werden. Wie dabei vorgegangen werden kann, unterscheidet sich je nach Anwendungsbereich und den eigenen Vorlieben.

Als Beispiel sie hier die Anwesenheitserkennung mittels BT-Tags angeführt.

===Anwesenheitserkennung mittels BT-Tags===
[[File:ble2mqtt.png|thumb|Readings eines Devices, dass mit diesem Code erstellt wurde]]
Der folgende Code geht davon aus, dass es mehrere ble2mqtt-Instanzen gibt und ein BT-Tag mit der MAC-Adresse AA:BB:CC:DD:EE:FF erkannt werden soll.

Die verschiedenen ble2mqtt-Instanzen schicken ihre Nachrichten in unterschiedliche Topics.
Für jede Instanz ein eigenes Topic:
*ble2mqtt/wohnzimmer
*ble2mqtt/schlafzimmer
*ble2mqtt/kueche
Im Attribut ''devicetopic'' werden diese Topics dann gemeinsam ausgewertet. Das funktioniert, in dem der Name des Subtopics einfach durch den Regex-Ausdruck ''.*'' ersetzt wird.

Bedeutet aber auch, dass die Informationen - wenn gewünscht - wieder in unterschiedliche Readings zerlegt werden müssen. Um z.B. schnell zu erkennen, in welchem Raum der BT-Tag gerade liegt. Das passiert hier z.B. bei den Nachrichten für ''rssi'' und ''presence''. Daraus resultieren dann eigene Readings für jedes MQTT-Subtopic.

Das "raumübergreifende" Reading ''presence'' wird anhand der des Alters in Sekunden der letzten lastseen-Nachricht gesteuert. Die lastseen-Nachricht wird immer gesendet, wenn der Scanvorgang von ble2mqtt das gewünschte Gerät findet.

<syntaxhighlight lang="perl">
define ble2mqttGTag MQTT2_DEVICE FHEM
attr ble2mqttGTag devicetopic ble2mqtt/.*/AA_BB_CC_DD_EE_FF
attr ble2mqttGTag event-on-change-reading .*
attr ble2mqttGTag readingList ble2mqtt/.*/heartbeat:.* heartbeat
$DEVICETOPIC/rssi:.* {my $room=(split m{[/]}x,$TOPIC)[1]; my $roomMax=$room; my $rssiMax=$EVENT; my @readings = grep { $_ =~ m{\Arssi_(?!$room).*}x } keys %{$defs{"$NAME"}->{READINGS}}; for (@readings) {my $rssiTmp=ReadingsVal($NAME,$_,'-100'); my $roomTmp=(split m{[_]}x,$_)[1]; if(($rssiMax gt $rssiTmp)&&(ReadingsVal($NAME,"presence_".$roomTmp,'absent') eq 'present')) {$rssiMax=$rssiTmp; $roomMax=$roomTmp}}; {rssi=>$rssiMax,room=>$roomMax,"rssi_$room"=>$EVENT}}
$DEVICETOPIC/lastseen:.* {lastseen=>strftime "%Y-%m-%d %H:%M:%S", localtime($EVENT)}
$DEVICETOPIC/present:.* {my $roomAct=(split m{[/]}x,$TOPIC)[1]; my $rssi=ReadingsVal($NAME,"rssi_".$roomAct,'-100'); my $presenceAct=$EVENT?'present':'absent'; my $room=$EVENT ? $roomAct:''; my @readings = grep { $_ =~ m{\Apresence_(?!$roomAct).*}x } keys %{$defs{$NAME}->{READINGS}}; for (@readings) {if(ReadingsVal($NAME,$_,'absent') eq 'present') {my $roomTmp=(split m{[_]}x,$_)[1]; my $rssiTmp=ReadingsVal($NAME,"rssi_".$roomTmp,'-100'); if($rssi gt $rssiTmp){$room=$roomTmp; $rssi=$rssiTmp}}}; {"presence_$roomAct"=>$presenceAct, room=>$room}}
ble2mqtt/.*/state:.* state
$DEVICETOPIC/battery:.* batteryLevel
attr ble2mqttGTag userReadings presence {if (ReadingsAge($NAME,"lastseen",0)>60) {return "absent";}else{return "present";}}
</syntaxhighlight>

Das Ergebnis ist unter anderem ein Reading ''presence'' mit den Zuständen ''absent'' und ''present''. Es kann somit ganz einfach als "presenceDevice" in einem [[ROOMMATE]]-Device verwendet werden:
attr rr_Franz rr_presenceDevices ble2mqttGTag

[[Category:MQTT]][[Category:Anwesenheitserkennung]][[Category:FHEM Utilities]]

Benutzer:Drhirn

2023-11-09T10:24:30Z

Drhirn: Die Seite wurde geleert.

FHEMWEB

2023-11-09T10:22:34Z

Drhirn: Hinweis auf zwei Beiträge im Wiki, die sich mit HTTPS beschäftigen, ergänzt

{{Infobox Modul
|ModPurpose=Standard Fhem-Webfrontend
|ModType=h
|ModForumArea=Frontends
|ModTechName=01_FHEMWEB.pm
|ModOwner=Rudolf König/rudolfkoenig ({{Link2FU|8|Forum}}/[[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}
{{Randnotiz|RNText=Eine FHEM-Installation kann mehrere FHEMWEB-Definitionen (mit je einem anderen Port) enthalten. Dies kann genutzt werden, um
* für andere Styles als f18 unterschiedliche Darstellungen für verschiedene Bildschirmgrößen zu erreichen, oder
* verschiedenen Darstellungen für mehrere Benutzer oder Anwendungsbereiche zu ermöglichen.}}
[[FHEMWEB]] ist das Standard Webfrontend von Fhem. Es implementiert auch einen einfachen Webserver (optional mit Basic-Auth und HTTPS). Aus historischen Gründen wird es auch als [[PGM2]] bezeichnet. FHEMWEB läuft voraussetzungslos.

== Anpassungen ==
=== ''Themes'' ===
FHEMWEB kennt keine Themes im strengen Sinne. Man kann allerdings mit drei Dateien das Aussehen des Frontends anpassen.

Zuerst ist ein Prefix zu vergeben, der das Theme beschreiben soll. Hier möge ''tufte'' als Beispiel dienen (siehe diesen {{Link2Forum|Topic=81637|Message=737465}}). Mit dem Attribut
:<code>attr <FHEMWEB-name> stylesheetPrefix tufte</code>
würde man das entsprechende Theme auswählen. Dieses Theme wiederum setzt voraus, dass sich im Verzeichnis /opt/fhem/www/pgm2 drei Daten mit folgenden Namen befinden:
* tuftestyle.css: Diese Datei steuert das Layout des Frontends.
* tuftesvg_style.css: Diese Datei steuert das Layout bei der Einbindung der SVG-Grafiken.
* tuftesvg_defs.svg: Diese Datei steuert das Layout des SVG-Grafikinhaltes.

=== Attribute ===
FHEMWEB besitzt mehrere Attribute, die das Aussehen des Frontends verändern können und im Folgenden näher beschrieben werden.

=== devStateIcon ===
Das Attribut devStateIcon dient dazu, das anzuzeigende Icon eines Devices in Abhängigkeit vom Device-Status (STATE) in der Raumübersicht (room) festzulegen. Zudem kann man einstellen, was bei einem Klick auf das Icon geschieht. Details siehe [[devStateIcon]]

=== sortby ===
Mit sortby können Elemente im Frontend sortiert werden. Es gibt zwei Beiträge zur Sortierung mit sortby im Forum: {{Link2Forum|Topic=11940|Message=70664}} und {{Link2Forum|Topic=26733|Message=197127}}

=== title ===
Mit diesem Attribut kann der Titel der Seite gesetzt werden. Dadurch wird das globale Attribut "title" überschrieben, das ansonsten für alle FHEMWEB Instanzen gilt.
Im Forum gibt es ein Beispiel für einen dynamischen Seitentitel: {{Link2Forum|Topic=48668|Message=403260}}

=== menuEntries ===
Mit menuEntries können weitere Einträge im Menü aufgenommen werden. Beispielsweise kann man so den Backup-Befehl einbinden. Unter dem Link [[Backup#Backup_manuell_ausf.C3.BChren_.28Weboberfl.C3.A4che.29|Backup-Befehl in FHEM-Menü einbinden]] ist dies näher erläutert.

=== webCmd ===
Durch Doppelpunkte getrennte Auflistung von Befehlen, die für FHEMWEB gelten sollen (funktioniert nicht mit smallscreen).

=== widgetOverride ===
Mit diesem Attribut kann man Bedienelemente, die vom Modulautor eigentlich vorgesehen waren, verändern. Dies gilt insbesondere für set-Befehle, mit denen Parameter verändert werden.

widgetOverride kennt mindestens zwei Parameter: Zuerst kommt der set-Befehl oder das webcmd, das überschrieben werden soll; dann ein Doppelpunkt und dann kommt das neu vorgesehene Bedienelement.

Beispiele:
* [[WifiLight#Color-Picker_aktivieren|Color-Picker]]
* [[EnOcean-FUD61NPN-Funk-Universal-Dimmaktor#Anzeige_eines_alternativen_Bedienelementes|knob]]
* usuzu (= universelle Zeitschaltuhr): {{Link2Forum|Topic=32660}}
* weitere [[FHEMWEB/Widgets]]

== Sicherheitsrelevante Anpassungen ==
=== csrfToken ===
FHEM hat mit der Version 5.8 eine Sicherheitsmaßnahme scharfgeschaltet, den csrfToken. Dieser Token wird bei jedem Neustart von FHEM neu gebildet.
Weitere Details finden sich im Wiki-Eintrag [[csrfToken-HowTo]]

=== apiWeb Instanz ===
Die apiWeb Instanz dient dazu, externe Zugriffe auf das FHEM System kontrolliert zu steuern.
Im Grunde wird nichts anderes gemacht, als eine zweite FHEM Webinstanz einzurichten, welche dann gesondert abgesichert wird.

Man legt sich hierfür eine FHEMWEB Instanz an:

<pre>
define apiWEB FHEMWEB 8088 global
attr apiWEB column Alarms: Apartment: Living: Bedroom: Kitchen: Sonos: Residents: Weather: Bathroom: Logs: Statistics: DashboardRoom: System: hidden: all:
attr apiWEB hiddenroom input,detail,save,Unsorted,Everything,CUL_HM,FS20,Commandref,style,Edit files,Select style,Logfile,Floorplans,Remote doc,FileLogs,Apartment,Bathroom,Bedroom,Kitchen,Living,Residents,System,Weather,Event monitor,NEW
attr apiWEB room hidden
attr apiWEB webname webhook
</pre>

Diese wird dann weiter mit Hilfe eines [[allowed]]-Devices abgesichert, in dem nur die tatsächlich benötigten Kommandos erlaubt werden und damit alle anderen nicht erlaubten (attr,define,get,set,...) automatisch nicht mehr zur Verfügung stehen:
<pre>
define allowedApiWEB allowed
attr allowedApiWEB allowedCommands set
attr allowedApiWEB allowedDevices Lampe1
attr allowedApiWEB validFor apiWEB
attr allowedApiWEB allowedIfAuthenticatedByMe 0
</pre>

Desweiteren ist dringend anzuraten, den Zugriff über TLS/SSL und HTTP Basic-Authentication weiter abzusichern. Nähere Informationen findet man hierzu in der {{Link2CmdRef|Anker=FHEMWEB}} unter dem Punkt HTTPS und in den Wiki-Beiträgen [[FHEM_mit_HTTPS_SSL-Zertifikat_und_eine_eigene_Zertifizierungsstelle]] und [[FHEMWEB_mit_Let's_Encrypt_Zertifikaten]].

Letztlich fehlt noch das entsprechende Attribut:
:<code>attr WEBhook HTTPS</code>

Als nächstes aktivieren wir Benutzername+Passwort für den Zugriff. Die {{Link2CmdRef|Anker=allowed}} für allowed gibt auch hier unter dem Punkt basicAuth entsprechende Hinweise.

== Links ==
* Begriffserklärung zur Unterscheidung von [[eventMap]], [[devStateIcon]], [[webCmd]] und [[setList]] mit Beispielen in diesem {{Link2Forum|Topic=12080|LinkText=Forenthread}}
* [[Icons]]
* [[FHEMWEB/Widgets|FHEMWEB Widgets]]

[[Kategorie:FHEM Frontends]]

FHEM mit HTTPS SSL-Zertifikat und eine eigene Zertifizierungsstelle

2023-11-09T10:18:52Z

Drhirn: Liste aus den Möglichkeiten gemacht

== Vorwort ==
=== Dein Anliegen ===
Du möchtest FHEM mit HTTPS betreiben, hasst es aber, ständig von Deinem Browser darauf aufmerksam gemacht zu werden, dass dies "keine sichere Verbindung" ist.
Oder Du möchtest einen weiteren Serverdienst aufsetzen, welcher verschlüsselte SSL oder TLS-Verbindungen anbietet (z.B. HTTPS, POP3S, IMAPS, LDAPS, SMTP mit TLS).

=== Die Schwierigkeit dabei ===
Um eine mit SSL/TLS abgesicherte Verbindung anzubieten, benötigst Du ein Serverzertifikat. Dieses muss von einer Zertifizierungsstelle (Certification Authority oder kurz CA) signiert sein.
Ein offizielles Serverzertifikat, welches von einer offiziellen Stelle signiert ist, ist leider nicht kostenlos. Meist werden jährliche Gebühren in Höhe von mehreren hundert Euro fällig. Ausnahme ist die CA [https://letsencrypt.org/ Let's Encrypt], die seit 2015 kostenlose Zertifikate anbietet.

=== Mögliche Lösungen ===
*Unter Linux kann man mit Bordmitteln eine eigene CA aufsetzen und selbst ein Zertifikate erstellen und signieren. Das ist ein Vorgang von wenigen Minuten. Alle Einzelheiten beschreibt dieser Artikel. Der einzige Unterschied zu einem von einer anerkannten Stelle signierten Zertifikat ist, dass der Client (Emailprogramm, Browser, etc.) einmalig das root CA importieren muß.

*Eine weitere Lösung ist die Verwendung der Let's Encrypt CA und des Tools Certbot. Damit werden Zertifikate erstellt, die von allen gängigen Browsern als gültig anerkannt werden. Eine Anleitung zur Einrichtung ist in diesem Wiki-Beitrag: [[FHEMWEB_mit_Let's_Encrypt_Zertifikaten]].

== Genaues Vorgehen ==
=== OpenSSL installieren ===
Für die Verwaltung der Zertifikate und im übrigen auch für die Verschlüsselung der Verbindungen mit SSL und TLS kommt unter Linux fast immer OpenSSL zum Einsatz. Wahrscheinlich ist das auf Deinem Sytem deshalb bereits installiert, wenn nicht, musst Du das Paket openssl nachinstallieren. Du benötigst aus diesem Paket den Kommandozeilenbefehl openssl.

=== Erstellen der CA ===
Lege zunächst ein Verzeichnis an, in dem Du das Zertifikat ablegen willst. Wir nehmen in unserem Beispiel /root/ca:
<syntaxhighlight lang="bash">
root@linux# mkdir /root/ca
root@linux# cd /root/ca</syntaxhighlight>
Die Gültigkeit setzen wir mit 10 Jahren bewusst sehr hoch an. Läuft die CA aus, so werden nämlich auch alle damit signierten Serverzertifikate ungültig. Die CA enthält einen geheimen Schlüssel, welcher automatisch erzeugt und in der Datei cakey.pem abgelegt wird. Das CA-Zertifikat wird nach cacert.pem geschrieben. Der folgende Befehl erzeugt das einen Schlüssel für das Zertifikat mit einer Länge von 2048 Bit:
<syntaxhighlight lang="bash">
root@linux# openssl req -new -x509 -newkey rsa:2048 -keyout cakey.pem -out cacert.pem -days 3650
Generating a 2048 bit RSA private key
..............................................................
..............................................................
.........................................+++
......................................+++
writing new private key to 'cakey.pem'</syntaxhighlight>

Wer den geheimen Schlüssel der CA kennt, kann damit beliebige Serverzertifikate signieren. Deshalb wird diese Schlüsseldatei nicht im Klartext auf der Festplatte abgelegt, sondern mit einer Passphrase verschlüsselt. Diese Passphrase benötigst Du immer dann, wenn Du mit der CA neue Zertifikate ausstellen willst:
<nowiki>
Enter PEM pass phrase: sehrlangesgeheimespasswort
Verifying - Enter PEM pass phrase: sehrlangesgeheimespasswort</nowiki>
Nun werden wir gebeten, Daten einzugeben, welche die CA identifizieren. Diese werden dem Client angezeigt, wenn er aufgefordert wird, das Zertifikat zu akzeptieren oder abzulehnen. Der Code für Deutschland ist DE. Wenn Du ein Feld leer lassen möchtest, so gib einen Punkt ein. Ansonsten wird der in eckigen Klammern stehende Defaultwert eingetragen:
<nowiki>
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: DE
State or Province Name (full name) [Some-State]:Brandenburg
Locality Name (eg, city) []:Potsdam
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Familie AG
Organizational Unit Name (eg, section) []:EDV</nowiki>
Das Feld Common Name (CN) ist hier der offizielle Name der Zertifizierungsstelle. Für Dein eigenes CA kannst Du einfach Deinen eigenen Namen eintragen:
<nowiki>
Common Name (eg, YOUR name) []: Cool Tux
Email Address []: cooltux@gmail.tada</nowiki>
Fertig. Folgende zwei Dateien sind entstanden:
<nowiki>
root@linux# ll
insgesamt 9
drwxr-xr-x 2 root root 112 2006-04-30 12:08 .
drwx------ 12 root root 600 2006-04-30 11:54 ..
-rw-r--r-- 1 root root 1212 2006-04-30 12:08 cacert.pem
-rw-r--r-- 1 root root 963 2006-04-30 12:08 cakey.pem</nowiki>
Vorsichtshalber solltest Du die Rechte so setzen, dass die Schlüsseldatei nur für root lesbar ist:
<nowiki>
root@linux# chmod 600 cakey.pem</nowiki>
Du kannst nun ausprobieren, ob Du den Schlüssel mit der Passphrase wieder öffnen kannst:
<nowiki>
root@linux# openssl rsa -in cakey.pem -noout -text
Enter pass phrase for cakey.pem: wrzlprmpft
Private-Key: (1024 bit)
modulus:
00:d5:a5:37:51:e9:d9:fa:e3:97:e7:46:b2:88:1a:
b5:46:80:47:76:14:ae:2b:8b:3e:35:5c:ab:15:84:
53:d9:63:2e:7f:08:4b:ec:77:db:02:45:f8:c7:46:
58:cd:2d:f9:29:4d:96:3d:d8:6c:5d:9f:79:8a:04:
cf:b7:3a:89:da:a9:63:9f:44:b3:83:cf:0d:70:7d:</nowiki>
usw...

=== Schlüssel für das Serverzertifikat erzeugen ===
Nachdem wir nun eine eigene CA haben, kann diese nun endlich für unseren Server ein Zertifikat herausgeben. Dazu erzeugen wir zunächst einen 2048 Bit langen RSA Schlüssel, der mit AES 128 verschlüsselt auf der Platte abgelegt wird (ja wirklich, auch hier wieder ein verschlüsselter Schlüssel). Die Passphrase muss diesmal nicht sonderlich geheim sein, da wir sie ohnehin im Anschluss wieder entfernen werden. OpenSSL lässt allerdings keine leere Phrase zu:
<syntaxhighlight lang="bash">
root@linux# openssl genrsa -out server-key.pem -aes128 2048
Generating RSA private key, 2048 bit long modulus
....+++
.......................................+++
e is 65537 (0x10001)
Enter pass phrase for server-key.pem: test
Verifying - Enter pass phrase for server-key.pem: test</syntaxhighlight>
So. Nun entfernen wir die Passphrase wieder. Warum? Der Serverdienst (Apache, Cyrus, etc.) muss schließlich in der Lage sein, den Schlüssel ohne Dein Zutun zu lesen. Oder möchtest Du bei jedem Booten des Servers ein Passwort eingeben müssen?
<syntaxhighlight lang="bash">
root@linux# openssl rsa -in server-key.pem -out server-key.pem
Enter pass phrase for server-key.pem: jaja
writing RSA key</syntaxhighlight>

=== Certificate Signing Request erzeugen ===
Der nächste Schritt zum eigenen Zertifikat ist ein CSR. Dies muss dann nur noch von der CA signiert werden. Hier sind wieder Angaben analog zum Erstellen der CA nötig, was oft Verwirrung stiftet. Die allgemeinen Daten kann man ggfl. gleich wie oben eingeben:
<syntaxhighlight lang="bash">
root@linux# openssl req -new -key server-key.pem -out req.pem -nodes
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: DE
State or Province Name (full name) [Some-State]:Brandenburg
Locality Name (eg, city) []:Potsdam
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Familie AG
Organizational Unit Name (eg, section) []:EDV</syntaxhighlight>
ACHTUNG, jetzt kommt das Wichtige: Beim Serverzertifikat ist der Common Name von entscheidender Bedeutung. Hier muss der DNS-Name stehen, unter dem der Client den Server anspricht! Wird das Zertifikat für eine HTTPS-Verbindung zu fhem.local verwendet, so muss der Common Name eben genau fhem.local heißen. Anderfalls wird der Browser das Zertifikat nicht akzeptieren, da er davon ausgehen muss, auf dem falschen Server gelandet zu sein.
<nowiki>
Common Name (eg, YOUR name) []: fhem.local
Email Address []: admin.fhem.local</nowiki>
Weitere Optionen kann man einfach leer lassen:
<nowiki>
A challenge password []:
An optional company name []:</nowiki>
Mittlerweile tummeln sich schon vier Dateien in unserem Verzeichnis:
<syntaxhighlight lang="bash">
root@linux# ll
insgesamt 17
drwxr-xr-x 2 root root 168 2006-04-30 12:29 .
drwx------ 12 root root 600 2006-04-30 11:54 ..
-rw-r--r-- 1 root root 1212 2006-04-30 12:08 cacert.pem
-rw------- 1 root root 963 2006-04-30 12:08 cakey.pem
-rw-r--r-- 1 root root 1017 2006-04-30 12:29 req.pem
-rw-r--r-- 1 root root 1679 2006-04-30 12:21 server-key.pem</syntaxhighlight>

=== OpenSSL-Konfiguration anpassen ===
Leider kann man bei OpenSSL nicht alle Daten als Kommandozeilenargumente übergeben. Einige Einstellungen muss man lästigerweise in der Datei /etc/ssl/openssl.cnf ändern, bevor man signieren kann. Öffne diese Datei und passe folgende Zeilen in der Sektion [ CA_default ] an:
<syntaxhighlight lang="bash">
/etc/ssl/openssl.cnf:
dir = . # Where everything is kept
new_certs_dir = $dir # default place for new certs
private_key = $dir/cakey.pem # The private key
RANDFILE = $dir/.rand # private random number file
default_days = 3650 # how long to certify for</syntaxhighlight>
Das Feld default_days ist auf 365 Tage voreingestellt und gibt die Gültigkeit des Zertifikates an. Abgelaufene Zertifikate sind im Übrigen ein sehr häufiges Problem. Wenn es soweit ist, kennt sich damit nämlich schon lange keiner mehr aus. Deswegen kannst Du wie im Beispiel angegeben die Lebensdauer z.B. auf 10 Jahre heraufsetzen.

Nun muss man noch einige Dateien anlegen:
<syntaxhighlight lang="bash">
root@linux# echo 01 > serial
root@linux# touch index.txt</syntaxhighlight>

=== Serverzertifikat signieren ===
Kommen wir zum feierlichen Abschluss: Unsere CA signiert nun das Zertifikat:

''(Hinweis: Vor Ausführung das Kapitel "Bekannte Probleme" beachten)''
<syntaxhighlight lang="bash">
root@linux# openssl ca -in req.pem -notext -out server-cert.pem
Enter pass phrase for ./cakey.pem: langesgeheimespasswort

...

Certificate is to be certified until Apr 27 10:45:36 2016 GMT (3650 days)
Sign the certificate? [y/n]: y

1 out of 1 certificate requests certified, commit? [y/n] y
Write out database with 1 new entries
Data Base Updated</syntaxhighlight>

=== Zertifikate installieren ===
Wie Du das Zertifikat in FHEM installierst, findest Du [[Raspberry_Pi_%26_HTTPS|hier]] und wenn Du ein Server Zertifikat für NGINX installieren möchtest, findest Du Infos dazu [[HTTPS-Absicherung_%26_Authentifizierung_via_nginx_Webserver|hier]]

=== Schlüsselcontainer erstellen ===
Für externe Applikationen wie "owntracks" müssen die erstellten Zertifikate und Keys in einen .p12 - Schlüsselcontainer verpackt werden
<syntaxhighlight lang="bash">
root@linux# openssl pkcs12 -export -out server.p12 -in server-cert.pem -inkey server-key.pem

Enter Export Password:
Verifying - Enter Export Password:
</syntaxhighlight>
Das dort vergebene Passwort unbedingt sichern!

Die Dateien server.p12 sowie die cacert.pem zusammen mit dem vergebenen Passwort für die .p12 Datei , können nun auf der externen Applikation verwendet werden um von extern auf den Server per SSL zugreifen zu können.

Bitte hierbei unbedingt auch den Punkt unter "Bekannte Probleme" beachten!

== Nachwort ==
=== Einbinden der root CA in die Zertifizierungsstelle des Browsers ===
Beim Firefox importieren wir unsere cacert.pem unter Einstellungen -> Erweitert -> Zertifikate -> Zertifikate anzeigen -> Zertifizierungsstellen ein.
Unter Chrome/Chromium finden wir die Zertifikatsverwaltung unter Einstellungen -> Erweitert -> Zertifikate verwalten HTTPS/SSL-Zertifikate und -Einstellungen verwalten -> Zertifizierungsstellen

=== Bekannte Probleme ===
Für den Chrome/Chromium und externen Applikationen wie "owntracks" müssen wir zusätzlich "Subject Alternative Names (SAN)" in unser Zertifikat eintragen. Dies geschieht beim Serverzertifikat signieren. Dazu müssen wir uns eine weitere Datei anlegen:
<syntaxhighlight lang="bash">
root@linux# vim oats.extensions.cnf

basicConstraints=CA:FALSE
subjectAltName=@my_subject_alt_names
subjectKeyIdentifier = hash

[ my_subject_alt_names ]
DNS.1 = localhost
DNS.2 = localhost.local
DNS.3 = localhost.fritz.box

DNS.4 = HomeServer
DNS.5 = HomeServer.local
DNS.6 = HomeServer.fritz.box

# [Optional] Address of your dynamic DNS subdomain
DNS.7 = homeserver.domain.de

# IPv4 local host
IP.1 = 127.0.0.1

# your local IPv4 address of your fhem Server
IP.2 = 192.168.178.200

# [Optional] IPv6 Link local address of your fhem Server if available
IP.3 = fe80::dea1:dea2:dea3:dead

# [Optional] local IPv6 address of your fhem Server without network prefix if available
# The difference to the above address is the missing "fe80" reference
IP.4 = ::dea1:dea2:dea3:dead</syntaxhighlight>

Dabei die DNS.x Namen durch die DNS Namen (bzw. IP Addressen) ersetzen, womit man Fhem aufruft.

Die Signierung unseres Serverzertifikates erfolgt dann mit folgendem Befehl:
<syntaxhighlight lang="bash">
openssl ca -in req.pem -notext -extfile oats.extensions.cnf -out server-cert.pem</syntaxhighlight>

=== Prüfen von Zertifikaten ===
Zertifikate kann man im übrigen auf dieser [https://tools.keycdn.com/ssl| Seite] prüfen lassen.
Dazu kopiert man den Inhalt der server-cert.pem in das Eingabefeld der Seite und klickt dann auf Check.

[[Kategorie:HOWTOS]]

FHEM mit HTTPS SSL-Zertifikat und eine eigene Zertifizierungsstelle

2023-11-09T10:18:15Z

Drhirn: Möglicher Weg mit Let's Encrypt ergänzt

== Vorwort ==
=== Dein Anliegen ===
Du möchtest FHEM mit HTTPS betreiben, hasst es aber, ständig von Deinem Browser darauf aufmerksam gemacht zu werden, dass dies "keine sichere Verbindung" ist.
Oder Du möchtest einen weiteren Serverdienst aufsetzen, welcher verschlüsselte SSL oder TLS-Verbindungen anbietet (z.B. HTTPS, POP3S, IMAPS, LDAPS, SMTP mit TLS).

=== Die Schwierigkeit dabei ===
Um eine mit SSL/TLS abgesicherte Verbindung anzubieten, benötigst Du ein Serverzertifikat. Dieses muss von einer Zertifizierungsstelle (Certification Authority oder kurz CA) signiert sein.
Ein offizielles Serverzertifikat, welches von einer offiziellen Stelle signiert ist, ist leider nicht kostenlos. Meist werden jährliche Gebühren in Höhe von mehreren hundert Euro fällig. Ausnahme ist die CA [https://letsencrypt.org/ Let's Encrypt], die seit 2015 kostenlose Zertifikate anbietet.

=== Mögliche Lösungen ===
Unter Linux kann man mit Bordmitteln eine eigene CA aufsetzen und selbst ein Zertifikate erstellen und signieren. Das ist ein Vorgang von wenigen Minuten. Alle Einzelheiten beschreibt dieser Artikel.
Der einzige Unterschied zu einem von einer anerkannten Stelle signierten Zertifikat ist, dass der Client (Emailprogramm, Browser, etc.) einmalig das root CA importieren muß.

Eine weitere Lösung ist die Verwendung der Let's Encrypt CA und des Tools Certbot. Damit werden Zertifikate erstellt, die von allen gängigen Browsern als gültig anerkannt werden. Eine Anleitung zur Einrichtung ist in diesem Wiki-Beitrag: [[FHEMWEB_mit_Let's_Encrypt_Zertifikaten]].

== Genaues Vorgehen ==
=== OpenSSL installieren ===
Für die Verwaltung der Zertifikate und im übrigen auch für die Verschlüsselung der Verbindungen mit SSL und TLS kommt unter Linux fast immer OpenSSL zum Einsatz. Wahrscheinlich ist das auf Deinem Sytem deshalb bereits installiert, wenn nicht, musst Du das Paket openssl nachinstallieren. Du benötigst aus diesem Paket den Kommandozeilenbefehl openssl.

=== Erstellen der CA ===
Lege zunächst ein Verzeichnis an, in dem Du das Zertifikat ablegen willst. Wir nehmen in unserem Beispiel /root/ca:
<syntaxhighlight lang="bash">
root@linux# mkdir /root/ca
root@linux# cd /root/ca</syntaxhighlight>
Die Gültigkeit setzen wir mit 10 Jahren bewusst sehr hoch an. Läuft die CA aus, so werden nämlich auch alle damit signierten Serverzertifikate ungültig. Die CA enthält einen geheimen Schlüssel, welcher automatisch erzeugt und in der Datei cakey.pem abgelegt wird. Das CA-Zertifikat wird nach cacert.pem geschrieben. Der folgende Befehl erzeugt das einen Schlüssel für das Zertifikat mit einer Länge von 2048 Bit:
<syntaxhighlight lang="bash">
root@linux# openssl req -new -x509 -newkey rsa:2048 -keyout cakey.pem -out cacert.pem -days 3650
Generating a 2048 bit RSA private key
..............................................................
..............................................................
.........................................+++
......................................+++
writing new private key to 'cakey.pem'</syntaxhighlight>

Wer den geheimen Schlüssel der CA kennt, kann damit beliebige Serverzertifikate signieren. Deshalb wird diese Schlüsseldatei nicht im Klartext auf der Festplatte abgelegt, sondern mit einer Passphrase verschlüsselt. Diese Passphrase benötigst Du immer dann, wenn Du mit der CA neue Zertifikate ausstellen willst:
<nowiki>
Enter PEM pass phrase: sehrlangesgeheimespasswort
Verifying - Enter PEM pass phrase: sehrlangesgeheimespasswort</nowiki>
Nun werden wir gebeten, Daten einzugeben, welche die CA identifizieren. Diese werden dem Client angezeigt, wenn er aufgefordert wird, das Zertifikat zu akzeptieren oder abzulehnen. Der Code für Deutschland ist DE. Wenn Du ein Feld leer lassen möchtest, so gib einen Punkt ein. Ansonsten wird der in eckigen Klammern stehende Defaultwert eingetragen:
<nowiki>
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: DE
State or Province Name (full name) [Some-State]:Brandenburg
Locality Name (eg, city) []:Potsdam
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Familie AG
Organizational Unit Name (eg, section) []:EDV</nowiki>
Das Feld Common Name (CN) ist hier der offizielle Name der Zertifizierungsstelle. Für Dein eigenes CA kannst Du einfach Deinen eigenen Namen eintragen:
<nowiki>
Common Name (eg, YOUR name) []: Cool Tux
Email Address []: cooltux@gmail.tada</nowiki>
Fertig. Folgende zwei Dateien sind entstanden:
<nowiki>
root@linux# ll
insgesamt 9
drwxr-xr-x 2 root root 112 2006-04-30 12:08 .
drwx------ 12 root root 600 2006-04-30 11:54 ..
-rw-r--r-- 1 root root 1212 2006-04-30 12:08 cacert.pem
-rw-r--r-- 1 root root 963 2006-04-30 12:08 cakey.pem</nowiki>
Vorsichtshalber solltest Du die Rechte so setzen, dass die Schlüsseldatei nur für root lesbar ist:
<nowiki>
root@linux# chmod 600 cakey.pem</nowiki>
Du kannst nun ausprobieren, ob Du den Schlüssel mit der Passphrase wieder öffnen kannst:
<nowiki>
root@linux# openssl rsa -in cakey.pem -noout -text
Enter pass phrase for cakey.pem: wrzlprmpft
Private-Key: (1024 bit)
modulus:
00:d5:a5:37:51:e9:d9:fa:e3:97:e7:46:b2:88:1a:
b5:46:80:47:76:14:ae:2b:8b:3e:35:5c:ab:15:84:
53:d9:63:2e:7f:08:4b:ec:77:db:02:45:f8:c7:46:
58:cd:2d:f9:29:4d:96:3d:d8:6c:5d:9f:79:8a:04:
cf:b7:3a:89:da:a9:63:9f:44:b3:83:cf:0d:70:7d:</nowiki>
usw...

=== Schlüssel für das Serverzertifikat erzeugen ===
Nachdem wir nun eine eigene CA haben, kann diese nun endlich für unseren Server ein Zertifikat herausgeben. Dazu erzeugen wir zunächst einen 2048 Bit langen RSA Schlüssel, der mit AES 128 verschlüsselt auf der Platte abgelegt wird (ja wirklich, auch hier wieder ein verschlüsselter Schlüssel). Die Passphrase muss diesmal nicht sonderlich geheim sein, da wir sie ohnehin im Anschluss wieder entfernen werden. OpenSSL lässt allerdings keine leere Phrase zu:
<syntaxhighlight lang="bash">
root@linux# openssl genrsa -out server-key.pem -aes128 2048
Generating RSA private key, 2048 bit long modulus
....+++
.......................................+++
e is 65537 (0x10001)
Enter pass phrase for server-key.pem: test
Verifying - Enter pass phrase for server-key.pem: test</syntaxhighlight>
So. Nun entfernen wir die Passphrase wieder. Warum? Der Serverdienst (Apache, Cyrus, etc.) muss schließlich in der Lage sein, den Schlüssel ohne Dein Zutun zu lesen. Oder möchtest Du bei jedem Booten des Servers ein Passwort eingeben müssen?
<syntaxhighlight lang="bash">
root@linux# openssl rsa -in server-key.pem -out server-key.pem
Enter pass phrase for server-key.pem: jaja
writing RSA key</syntaxhighlight>

=== Certificate Signing Request erzeugen ===
Der nächste Schritt zum eigenen Zertifikat ist ein CSR. Dies muss dann nur noch von der CA signiert werden. Hier sind wieder Angaben analog zum Erstellen der CA nötig, was oft Verwirrung stiftet. Die allgemeinen Daten kann man ggfl. gleich wie oben eingeben:
<syntaxhighlight lang="bash">
root@linux# openssl req -new -key server-key.pem -out req.pem -nodes
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: DE
State or Province Name (full name) [Some-State]:Brandenburg
Locality Name (eg, city) []:Potsdam
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Familie AG
Organizational Unit Name (eg, section) []:EDV</syntaxhighlight>
ACHTUNG, jetzt kommt das Wichtige: Beim Serverzertifikat ist der Common Name von entscheidender Bedeutung. Hier muss der DNS-Name stehen, unter dem der Client den Server anspricht! Wird das Zertifikat für eine HTTPS-Verbindung zu fhem.local verwendet, so muss der Common Name eben genau fhem.local heißen. Anderfalls wird der Browser das Zertifikat nicht akzeptieren, da er davon ausgehen muss, auf dem falschen Server gelandet zu sein.
<nowiki>
Common Name (eg, YOUR name) []: fhem.local
Email Address []: admin.fhem.local</nowiki>
Weitere Optionen kann man einfach leer lassen:
<nowiki>
A challenge password []:
An optional company name []:</nowiki>
Mittlerweile tummeln sich schon vier Dateien in unserem Verzeichnis:
<syntaxhighlight lang="bash">
root@linux# ll
insgesamt 17
drwxr-xr-x 2 root root 168 2006-04-30 12:29 .
drwx------ 12 root root 600 2006-04-30 11:54 ..
-rw-r--r-- 1 root root 1212 2006-04-30 12:08 cacert.pem
-rw------- 1 root root 963 2006-04-30 12:08 cakey.pem
-rw-r--r-- 1 root root 1017 2006-04-30 12:29 req.pem
-rw-r--r-- 1 root root 1679 2006-04-30 12:21 server-key.pem</syntaxhighlight>

=== OpenSSL-Konfiguration anpassen ===
Leider kann man bei OpenSSL nicht alle Daten als Kommandozeilenargumente übergeben. Einige Einstellungen muss man lästigerweise in der Datei /etc/ssl/openssl.cnf ändern, bevor man signieren kann. Öffne diese Datei und passe folgende Zeilen in der Sektion [ CA_default ] an:
<syntaxhighlight lang="bash">
/etc/ssl/openssl.cnf:
dir = . # Where everything is kept
new_certs_dir = $dir # default place for new certs
private_key = $dir/cakey.pem # The private key
RANDFILE = $dir/.rand # private random number file
default_days = 3650 # how long to certify for</syntaxhighlight>
Das Feld default_days ist auf 365 Tage voreingestellt und gibt die Gültigkeit des Zertifikates an. Abgelaufene Zertifikate sind im Übrigen ein sehr häufiges Problem. Wenn es soweit ist, kennt sich damit nämlich schon lange keiner mehr aus. Deswegen kannst Du wie im Beispiel angegeben die Lebensdauer z.B. auf 10 Jahre heraufsetzen.

Nun muss man noch einige Dateien anlegen:
<syntaxhighlight lang="bash">
root@linux# echo 01 > serial
root@linux# touch index.txt</syntaxhighlight>

=== Serverzertifikat signieren ===
Kommen wir zum feierlichen Abschluss: Unsere CA signiert nun das Zertifikat:

''(Hinweis: Vor Ausführung das Kapitel "Bekannte Probleme" beachten)''
<syntaxhighlight lang="bash">
root@linux# openssl ca -in req.pem -notext -out server-cert.pem
Enter pass phrase for ./cakey.pem: langesgeheimespasswort

...

Certificate is to be certified until Apr 27 10:45:36 2016 GMT (3650 days)
Sign the certificate? [y/n]: y

1 out of 1 certificate requests certified, commit? [y/n] y
Write out database with 1 new entries
Data Base Updated</syntaxhighlight>

=== Zertifikate installieren ===
Wie Du das Zertifikat in FHEM installierst, findest Du [[Raspberry_Pi_%26_HTTPS|hier]] und wenn Du ein Server Zertifikat für NGINX installieren möchtest, findest Du Infos dazu [[HTTPS-Absicherung_%26_Authentifizierung_via_nginx_Webserver|hier]]

=== Schlüsselcontainer erstellen ===
Für externe Applikationen wie "owntracks" müssen die erstellten Zertifikate und Keys in einen .p12 - Schlüsselcontainer verpackt werden
<syntaxhighlight lang="bash">
root@linux# openssl pkcs12 -export -out server.p12 -in server-cert.pem -inkey server-key.pem

Enter Export Password:
Verifying - Enter Export Password:
</syntaxhighlight>
Das dort vergebene Passwort unbedingt sichern!

Die Dateien server.p12 sowie die cacert.pem zusammen mit dem vergebenen Passwort für die .p12 Datei , können nun auf der externen Applikation verwendet werden um von extern auf den Server per SSL zugreifen zu können.

Bitte hierbei unbedingt auch den Punkt unter "Bekannte Probleme" beachten!

== Nachwort ==
=== Einbinden der root CA in die Zertifizierungsstelle des Browsers ===
Beim Firefox importieren wir unsere cacert.pem unter Einstellungen -> Erweitert -> Zertifikate -> Zertifikate anzeigen -> Zertifizierungsstellen ein.
Unter Chrome/Chromium finden wir die Zertifikatsverwaltung unter Einstellungen -> Erweitert -> Zertifikate verwalten HTTPS/SSL-Zertifikate und -Einstellungen verwalten -> Zertifizierungsstellen

=== Bekannte Probleme ===
Für den Chrome/Chromium und externen Applikationen wie "owntracks" müssen wir zusätzlich "Subject Alternative Names (SAN)" in unser Zertifikat eintragen. Dies geschieht beim Serverzertifikat signieren. Dazu müssen wir uns eine weitere Datei anlegen:
<syntaxhighlight lang="bash">
root@linux# vim oats.extensions.cnf

basicConstraints=CA:FALSE
subjectAltName=@my_subject_alt_names
subjectKeyIdentifier = hash

[ my_subject_alt_names ]
DNS.1 = localhost
DNS.2 = localhost.local
DNS.3 = localhost.fritz.box

DNS.4 = HomeServer
DNS.5 = HomeServer.local
DNS.6 = HomeServer.fritz.box

# [Optional] Address of your dynamic DNS subdomain
DNS.7 = homeserver.domain.de

# IPv4 local host
IP.1 = 127.0.0.1

# your local IPv4 address of your fhem Server
IP.2 = 192.168.178.200

# [Optional] IPv6 Link local address of your fhem Server if available
IP.3 = fe80::dea1:dea2:dea3:dead

# [Optional] local IPv6 address of your fhem Server without network prefix if available
# The difference to the above address is the missing "fe80" reference
IP.4 = ::dea1:dea2:dea3:dead</syntaxhighlight>

Dabei die DNS.x Namen durch die DNS Namen (bzw. IP Addressen) ersetzen, womit man Fhem aufruft.

Die Signierung unseres Serverzertifikates erfolgt dann mit folgendem Befehl:
<syntaxhighlight lang="bash">
openssl ca -in req.pem -notext -extfile oats.extensions.cnf -out server-cert.pem</syntaxhighlight>

=== Prüfen von Zertifikaten ===
Zertifikate kann man im übrigen auf dieser [https://tools.keycdn.com/ssl| Seite] prüfen lassen.
Dazu kopiert man den Inhalt der server-cert.pem in das Eingabefeld der Seite und klickt dann auf Check.

[[Kategorie:HOWTOS]]

FHEMWEB mit Let's Encrypt Zertifikaten

2023-11-09T10:15:27Z

Drhirn: Die Seite wurde neu angelegt: „[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der [https://www.eff.org/ Electronic Frontier Foundation (EFF)] mit dem automatisiert Zertifikate der [https://letsencrypt.org/ Let's Encrypt CA] erstellt werden können. Diese Zertifikate können auch in FHEM verwendet werden, um mittels HTTPS auf FHEMWEB zuzugreifen. In dieser Anleitung wird beschrieben wie Certbot installiert, #Zertifikate erstellen|Zert…“

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der [https://www.eff.org/ Electronic Frontier Foundation (EFF)] mit dem automatisiert Zertifikate der [https://letsencrypt.org/ Let's Encrypt CA] erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um mittels HTTPS auf [[FHEMWEB]] zuzugreifen.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com -d example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/www.example.com/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/www.example.com/privkey1.pem

Sind alle Berechtigungen vergeben (die sich beim Erneuern der Zertifikate nicht ändern), müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

[[Kategorie:HOWTOS]][[Kategorie:Sicherheit]][[Kategorie:Systemadministration]][[Kategorie:FHEM Frontends]]

Benutzer:Drhirn

2023-11-09T10:09:43Z

Drhirn:

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der [https://www.eff.org/ Electronic Frontier Foundation (EFF)] mit dem automatisiert Zertifikate der [https://letsencrypt.org/ Let's Encrypt CA] erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um mittels HTTPS auf [[FHEMWEB]] zuzugreifen.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com -d example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/www.example.com/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/www.example.com/privkey1.pem

Sind alle Berechtigungen vergeben (die sich beim Erneuern der Zertifikate nicht ändern), müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

FHEM mit HTTPS SSL-Zertifikat und eine eigene Zertifizierungsstelle

2023-11-09T10:04:59Z

Drhirn: Hinweis auf kostenlose Zertifikate bei Let's Encrypt ergänzt

== Vorwort ==
=== Dein Anliegen ===
Du möchtest FHEM mit HTTPS betreiben, hasst es aber, ständig von Deinem Browser darauf aufmerksam gemacht zu werden, dass dies "keine sichere Verbindung" ist.
Oder Du möchtest einen weiteren Serverdienst aufsetzen, welcher verschlüsselte SSL oder TLS-Verbindungen anbietet (z.B. HTTPS, POP3S, IMAPS, LDAPS, SMTP mit TLS).

=== Die Schwierigkeit dabei ===
Um eine mit SSL/TLS abgesicherte Verbindung anzubieten, benötigst Du ein Serverzertifikat. Dieses muss von einer Zertifizierungsstelle (Certification Authority oder kurz CA) signiert sein.
Ein offizielles Serverzertifikat, welches von einer offiziellen Stelle signiert ist, ist leider nicht kostenlos. Meist werden jährliche Gebühren in Höhe von mehreren hundert Euro fällig. Ausnahme ist die CA [https://letsencrypt.org/ Let's Encrypt], die seit 2015 kostenlose Zertifikate anbietet.

=== Eine mögliche Lösung ===
Unter Linux kann man mit Bordmitteln eine eigene CA aufsetzen und selbst ein Zertifikate erstellen und signieren. Das ist ein Vorgang von wenigen Minuten. Alle Einzelheiten beschreibt dieser Artikel.
Der einzige Unterschied zu einem von einer anerkannten Stelle signierten Zertifikat ist, dass der Client (Emailprogramm, Browser, etc.) einmalig das root CA importieren muß.

== Genaues Vorgehen ==
=== OpenSSL installieren ===
Für die Verwaltung der Zertifikate und im übrigen auch für die Verschlüsselung der Verbindungen mit SSL und TLS kommt unter Linux fast immer OpenSSL zum Einsatz. Wahrscheinlich ist das auf Deinem Sytem deshalb bereits installiert, wenn nicht, musst Du das Paket openssl nachinstallieren. Du benötigst aus diesem Paket den Kommandozeilenbefehl openssl.

=== Erstellen der CA ===
Lege zunächst ein Verzeichnis an, in dem Du das Zertifikat ablegen willst. Wir nehmen in unserem Beispiel /root/ca:
<syntaxhighlight lang="bash">
root@linux# mkdir /root/ca
root@linux# cd /root/ca</syntaxhighlight>
Die Gültigkeit setzen wir mit 10 Jahren bewusst sehr hoch an. Läuft die CA aus, so werden nämlich auch alle damit signierten Serverzertifikate ungültig. Die CA enthält einen geheimen Schlüssel, welcher automatisch erzeugt und in der Datei cakey.pem abgelegt wird. Das CA-Zertifikat wird nach cacert.pem geschrieben. Der folgende Befehl erzeugt das einen Schlüssel für das Zertifikat mit einer Länge von 2048 Bit:
<syntaxhighlight lang="bash">
root@linux# openssl req -new -x509 -newkey rsa:2048 -keyout cakey.pem -out cacert.pem -days 3650
Generating a 2048 bit RSA private key
..............................................................
..............................................................
.........................................+++
......................................+++
writing new private key to 'cakey.pem'</syntaxhighlight>

Wer den geheimen Schlüssel der CA kennt, kann damit beliebige Serverzertifikate signieren. Deshalb wird diese Schlüsseldatei nicht im Klartext auf der Festplatte abgelegt, sondern mit einer Passphrase verschlüsselt. Diese Passphrase benötigst Du immer dann, wenn Du mit der CA neue Zertifikate ausstellen willst:
<nowiki>
Enter PEM pass phrase: sehrlangesgeheimespasswort
Verifying - Enter PEM pass phrase: sehrlangesgeheimespasswort</nowiki>
Nun werden wir gebeten, Daten einzugeben, welche die CA identifizieren. Diese werden dem Client angezeigt, wenn er aufgefordert wird, das Zertifikat zu akzeptieren oder abzulehnen. Der Code für Deutschland ist DE. Wenn Du ein Feld leer lassen möchtest, so gib einen Punkt ein. Ansonsten wird der in eckigen Klammern stehende Defaultwert eingetragen:
<nowiki>
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: DE
State or Province Name (full name) [Some-State]:Brandenburg
Locality Name (eg, city) []:Potsdam
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Familie AG
Organizational Unit Name (eg, section) []:EDV</nowiki>
Das Feld Common Name (CN) ist hier der offizielle Name der Zertifizierungsstelle. Für Dein eigenes CA kannst Du einfach Deinen eigenen Namen eintragen:
<nowiki>
Common Name (eg, YOUR name) []: Cool Tux
Email Address []: cooltux@gmail.tada</nowiki>
Fertig. Folgende zwei Dateien sind entstanden:
<nowiki>
root@linux# ll
insgesamt 9
drwxr-xr-x 2 root root 112 2006-04-30 12:08 .
drwx------ 12 root root 600 2006-04-30 11:54 ..
-rw-r--r-- 1 root root 1212 2006-04-30 12:08 cacert.pem
-rw-r--r-- 1 root root 963 2006-04-30 12:08 cakey.pem</nowiki>
Vorsichtshalber solltest Du die Rechte so setzen, dass die Schlüsseldatei nur für root lesbar ist:
<nowiki>
root@linux# chmod 600 cakey.pem</nowiki>
Du kannst nun ausprobieren, ob Du den Schlüssel mit der Passphrase wieder öffnen kannst:
<nowiki>
root@linux# openssl rsa -in cakey.pem -noout -text
Enter pass phrase for cakey.pem: wrzlprmpft
Private-Key: (1024 bit)
modulus:
00:d5:a5:37:51:e9:d9:fa:e3:97:e7:46:b2:88:1a:
b5:46:80:47:76:14:ae:2b:8b:3e:35:5c:ab:15:84:
53:d9:63:2e:7f:08:4b:ec:77:db:02:45:f8:c7:46:
58:cd:2d:f9:29:4d:96:3d:d8:6c:5d:9f:79:8a:04:
cf:b7:3a:89:da:a9:63:9f:44:b3:83:cf:0d:70:7d:</nowiki>
usw...

=== Schlüssel für das Serverzertifikat erzeugen ===
Nachdem wir nun eine eigene CA haben, kann diese nun endlich für unseren Server ein Zertifikat herausgeben. Dazu erzeugen wir zunächst einen 2048 Bit langen RSA Schlüssel, der mit AES 128 verschlüsselt auf der Platte abgelegt wird (ja wirklich, auch hier wieder ein verschlüsselter Schlüssel). Die Passphrase muss diesmal nicht sonderlich geheim sein, da wir sie ohnehin im Anschluss wieder entfernen werden. OpenSSL lässt allerdings keine leere Phrase zu:
<syntaxhighlight lang="bash">
root@linux# openssl genrsa -out server-key.pem -aes128 2048
Generating RSA private key, 2048 bit long modulus
....+++
.......................................+++
e is 65537 (0x10001)
Enter pass phrase for server-key.pem: test
Verifying - Enter pass phrase for server-key.pem: test</syntaxhighlight>
So. Nun entfernen wir die Passphrase wieder. Warum? Der Serverdienst (Apache, Cyrus, etc.) muss schließlich in der Lage sein, den Schlüssel ohne Dein Zutun zu lesen. Oder möchtest Du bei jedem Booten des Servers ein Passwort eingeben müssen?
<syntaxhighlight lang="bash">
root@linux# openssl rsa -in server-key.pem -out server-key.pem
Enter pass phrase for server-key.pem: jaja
writing RSA key</syntaxhighlight>

=== Certificate Signing Request erzeugen ===
Der nächste Schritt zum eigenen Zertifikat ist ein CSR. Dies muss dann nur noch von der CA signiert werden. Hier sind wieder Angaben analog zum Erstellen der CA nötig, was oft Verwirrung stiftet. Die allgemeinen Daten kann man ggfl. gleich wie oben eingeben:
<syntaxhighlight lang="bash">
root@linux# openssl req -new -key server-key.pem -out req.pem -nodes
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: DE
State or Province Name (full name) [Some-State]:Brandenburg
Locality Name (eg, city) []:Potsdam
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Familie AG
Organizational Unit Name (eg, section) []:EDV</syntaxhighlight>
ACHTUNG, jetzt kommt das Wichtige: Beim Serverzertifikat ist der Common Name von entscheidender Bedeutung. Hier muss der DNS-Name stehen, unter dem der Client den Server anspricht! Wird das Zertifikat für eine HTTPS-Verbindung zu fhem.local verwendet, so muss der Common Name eben genau fhem.local heißen. Anderfalls wird der Browser das Zertifikat nicht akzeptieren, da er davon ausgehen muss, auf dem falschen Server gelandet zu sein.
<nowiki>
Common Name (eg, YOUR name) []: fhem.local
Email Address []: admin.fhem.local</nowiki>
Weitere Optionen kann man einfach leer lassen:
<nowiki>
A challenge password []:
An optional company name []:</nowiki>
Mittlerweile tummeln sich schon vier Dateien in unserem Verzeichnis:
<syntaxhighlight lang="bash">
root@linux# ll
insgesamt 17
drwxr-xr-x 2 root root 168 2006-04-30 12:29 .
drwx------ 12 root root 600 2006-04-30 11:54 ..
-rw-r--r-- 1 root root 1212 2006-04-30 12:08 cacert.pem
-rw------- 1 root root 963 2006-04-30 12:08 cakey.pem
-rw-r--r-- 1 root root 1017 2006-04-30 12:29 req.pem
-rw-r--r-- 1 root root 1679 2006-04-30 12:21 server-key.pem</syntaxhighlight>

=== OpenSSL-Konfiguration anpassen ===
Leider kann man bei OpenSSL nicht alle Daten als Kommandozeilenargumente übergeben. Einige Einstellungen muss man lästigerweise in der Datei /etc/ssl/openssl.cnf ändern, bevor man signieren kann. Öffne diese Datei und passe folgende Zeilen in der Sektion [ CA_default ] an:
<syntaxhighlight lang="bash">
/etc/ssl/openssl.cnf:
dir = . # Where everything is kept
new_certs_dir = $dir # default place for new certs
private_key = $dir/cakey.pem # The private key
RANDFILE = $dir/.rand # private random number file
default_days = 3650 # how long to certify for</syntaxhighlight>
Das Feld default_days ist auf 365 Tage voreingestellt und gibt die Gültigkeit des Zertifikates an. Abgelaufene Zertifikate sind im Übrigen ein sehr häufiges Problem. Wenn es soweit ist, kennt sich damit nämlich schon lange keiner mehr aus. Deswegen kannst Du wie im Beispiel angegeben die Lebensdauer z.B. auf 10 Jahre heraufsetzen.

Nun muss man noch einige Dateien anlegen:
<syntaxhighlight lang="bash">
root@linux# echo 01 > serial
root@linux# touch index.txt</syntaxhighlight>

=== Serverzertifikat signieren ===
Kommen wir zum feierlichen Abschluss: Unsere CA signiert nun das Zertifikat:

''(Hinweis: Vor Ausführung das Kapitel "Bekannte Probleme" beachten)''
<syntaxhighlight lang="bash">
root@linux# openssl ca -in req.pem -notext -out server-cert.pem
Enter pass phrase for ./cakey.pem: langesgeheimespasswort

...

Certificate is to be certified until Apr 27 10:45:36 2016 GMT (3650 days)
Sign the certificate? [y/n]: y

1 out of 1 certificate requests certified, commit? [y/n] y
Write out database with 1 new entries
Data Base Updated</syntaxhighlight>

=== Zertifikate installieren ===
Wie Du das Zertifikat in FHEM installierst, findest Du [[Raspberry_Pi_%26_HTTPS|hier]] und wenn Du ein Server Zertifikat für NGINX installieren möchtest, findest Du Infos dazu [[HTTPS-Absicherung_%26_Authentifizierung_via_nginx_Webserver|hier]]

=== Schlüsselcontainer erstellen ===
Für externe Applikationen wie "owntracks" müssen die erstellten Zertifikate und Keys in einen .p12 - Schlüsselcontainer verpackt werden
<syntaxhighlight lang="bash">
root@linux# openssl pkcs12 -export -out server.p12 -in server-cert.pem -inkey server-key.pem

Enter Export Password:
Verifying - Enter Export Password:
</syntaxhighlight>
Das dort vergebene Passwort unbedingt sichern!

Die Dateien server.p12 sowie die cacert.pem zusammen mit dem vergebenen Passwort für die .p12 Datei , können nun auf der externen Applikation verwendet werden um von extern auf den Server per SSL zugreifen zu können.

Bitte hierbei unbedingt auch den Punkt unter "Bekannte Probleme" beachten!

== Nachwort ==
=== Einbinden der root CA in die Zertifizierungsstelle des Browsers ===
Beim Firefox importieren wir unsere cacert.pem unter Einstellungen -> Erweitert -> Zertifikate -> Zertifikate anzeigen -> Zertifizierungsstellen ein.
Unter Chrome/Chromium finden wir die Zertifikatsverwaltung unter Einstellungen -> Erweitert -> Zertifikate verwalten HTTPS/SSL-Zertifikate und -Einstellungen verwalten -> Zertifizierungsstellen

=== Bekannte Probleme ===
Für den Chrome/Chromium und externen Applikationen wie "owntracks" müssen wir zusätzlich "Subject Alternative Names (SAN)" in unser Zertifikat eintragen. Dies geschieht beim Serverzertifikat signieren. Dazu müssen wir uns eine weitere Datei anlegen:
<syntaxhighlight lang="bash">
root@linux# vim oats.extensions.cnf

basicConstraints=CA:FALSE
subjectAltName=@my_subject_alt_names
subjectKeyIdentifier = hash

[ my_subject_alt_names ]
DNS.1 = localhost
DNS.2 = localhost.local
DNS.3 = localhost.fritz.box

DNS.4 = HomeServer
DNS.5 = HomeServer.local
DNS.6 = HomeServer.fritz.box

# [Optional] Address of your dynamic DNS subdomain
DNS.7 = homeserver.domain.de

# IPv4 local host
IP.1 = 127.0.0.1

# your local IPv4 address of your fhem Server
IP.2 = 192.168.178.200

# [Optional] IPv6 Link local address of your fhem Server if available
IP.3 = fe80::dea1:dea2:dea3:dead

# [Optional] local IPv6 address of your fhem Server without network prefix if available
# The difference to the above address is the missing "fe80" reference
IP.4 = ::dea1:dea2:dea3:dead</syntaxhighlight>

Dabei die DNS.x Namen durch die DNS Namen (bzw. IP Addressen) ersetzen, womit man Fhem aufruft.

Die Signierung unseres Serverzertifikates erfolgt dann mit folgendem Befehl:
<syntaxhighlight lang="bash">
openssl ca -in req.pem -notext -extfile oats.extensions.cnf -out server-cert.pem</syntaxhighlight>

=== Prüfen von Zertifikaten ===
Zertifikate kann man im übrigen auf dieser [https://tools.keycdn.com/ssl| Seite] prüfen lassen.
Dazu kopiert man den Inhalt der server-cert.pem in das Eingabefeld der Seite und klickt dann auf Check.

[[Kategorie:HOWTOS]]

Benutzer:Drhirn

2023-11-09T09:47:41Z

Drhirn: /* Standalone-Plugin */

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der Electronic Frontier Foundation (EFF) mit dem automatisiert Let's Encrypt Zertifikate erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um mittels HTTPS auf [[FHEMWEB]] zuzugreifen.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com -d example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/www.example.com/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/www.example.com/privkey1.pem

Sind alle Berechtigungen vergeben (die sich beim Erneuern der Zertifikate nicht ändern), müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

Benutzer:Drhirn

2023-11-09T08:49:18Z

Drhirn:

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der Electronic Frontier Foundation (EFF) mit dem automatisiert Let's Encrypt Zertifikate erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um mittels HTTPS auf [[FHEMWEB]] zuzugreifen.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/www.example.com/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/www.example.com/privkey1.pem

Sind alle Berechtigungen vergeben (die sich beim Erneuern der Zertifikate nicht ändern), müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

Benutzer:Drhirn

2023-11-09T08:46:15Z

Drhirn: /* Einbindung in FHEM */

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der Electronic Frontier Foundation (EFF) mit dem automatisiert Let's Encrypt Zertifikate erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um den Netzwerkverkehr zu verschlüsseln.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/www.example.com/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/www.example.com/privkey1.pem

Sind alle Berechtigungen vergeben (die sich beim Erneuern der Zertifikate nicht ändern), müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

Benutzer:Drhirn

2023-11-09T08:44:51Z

Drhirn: /* Einbindung in FHEM */

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der Electronic Frontier Foundation (EFF) mit dem automatisiert Let's Encrypt Zertifikate erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um den Netzwerkverkehr zu verschlüsseln.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/server/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/server/privkey1.pem

Sind alle Berechtigungen vergeben (die sich beim Erneuern der Zertifikate nicht ändern), müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/www.example.com/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

Ble2mqtt

2023-11-08T14:55:27Z

Drhirn: /* Erstellen einens Systemd-Daemons */

{{Baustelle}}
{{Infobox Modul
|ModPurpose=Anwesenheitserkennung von Bluetooth-Geräten
|ModType=u
|ModFTopic=127173
|ModForumArea=Unterstützende Dienste
|ModTechName=ble2mqtt
|ModOwner=PatrickR
}}
'''ble2mqtt''' ist ein Script, dass den Anwesenheitsstatus eines oder mehrerer Bluetooth Low Energy Geräte überprüfen und das Ergebnis an einen MQTT Broker schicken kann.

Es verwendet dazu die Linux Tools ''bluetoothctl'' und ''gatttool''.

ble2mqtt ist in Perl geschrieben und wurde von {{Link2FU|5068|PatrickR}} erstellt. Weitere Informationen finden sich in diesem {{Link2Forum|Topic=127173|LinkText=Forums-Topic }}. Fragen dazu bitte in den Bereich [https://forum.fhem.de/index.php?board=44.0 Unterstützende Dienste]


==Voraussetzungen==
* Debian od. Raspberry Pi OS
* Bluetooth Empfänger

==Parameter==
Beim Start von ble2mqtt können folgende Parameter angegeben werden:

{| class="wikitable"
!Parameter!!Beschreibung!!Standardwert!!Beispiel!!Optional
|-
| --mqttserver
|Die Adresse des MQTT Brokers inklusive Port
|
| --mqttserver mqtt.example.org:1883
|nein
|-
| --mqttfingerprint
|Der Fingerprint des für die TLS-verschlüsselte Kommunikation mit dem MQTT Broker verwendeten Zertifikates
|
| --mqttfingerprint bfe5d244a821194230f1479fe2f8f7bbcd2a8cb8
|ja
|-
| --mqtttopic
| An welches MQTT-Topic das Tool die Informationen schicken soll.
|ble2mqtt
| --mqtttopic ble2mqtt/Wohnzimmer
|ja
|-
| --mqttuser
|Der Benutzernamen, unter dem die Verbindung zum Broker hergestellt werden soll
|
| --mqttuser ble2mqtt
|ja bzw. abhängig vom Broker
|-
| --mqttpass
|Das zum Benutzernamen gehörende Passwort
|
| --mqttpass verysecret3
|ja bzw. abhängig vom Broker
|-
| --retain
|Versendet die Nachrichten present und lastseen als retained.
|0
| --retain
|ja
|-
| --daemonize
|Wenn ble2mqtt im Hintergrund (als Daemon) ausgeführt werden soll
|0
| --daemonize
|ja
|-
| --loglevel
|Wie und was genau protokolliert werden soll. Mögliche Loglevel sind LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
|LOG_INFO
| --loglevel LOG_ERR
|ja
|-
| --logtarget
|Wohin gelogged werden soll. Mögliche Optionen sind ''syslog'' und ''stdout''.
|syslog
| --logtarget stdout
|ja
|-
| --absentinterval
|Anzahl an Sekunden, nach denen das Gerät als abwesend bezeichnet werden soll. Mindestwert ist 30.
|60
| --absentinterval 120
|ja
|-
| --rssithreshold
|Ab welcher Abweichung des RSSI Wertes ein Update getriggert werden soll. Mindestwert ist 5.
|10
| --rssithreshold 8
|ja
|-
| --watchdogthreshold
|Ab welchem Zeitraum in Sekunden nach Empfangen des letzten BT-Signals ble2mqtt neu gestartet werden soll. Mindestwert ist 30. Der Wert 0 bedeutet deaktiviert, also nie.
|0
| --watchdogthreshold 30
|ja
|-
| --debug
|Kann nur gemeinsam mit --daemonize verwendet werden, um Logeinträge auf stdout auszugeben. Je höher die Nummer, desto mehr Output.
|0
| --daemonize --debug 4
|ja
|-
| --mac
|Filtert mittels Regex nach MAC-Adressen der von ble2mqtt zu beachtenden BLE-Geräte. Alle anderen Geräte werden ignoriert.
|
| --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'
|ja
|-
| --batterymaxage
|Zeit in Stunden, nach denen ein Batterie-Wert als veraltet angesehen und aktualisiert wird. Der Wert 0 deaktiviert den Batterie-Check.
|48
| --batterymaxage 6
|ja
|-
| --forcebattery
|Nur in Kombination mit --mac. Erzwingt einen Batterie-Check, auch wenn das battery-service am Gerät nicht erkannt wird.
|0
| --forcebattery
|ja
|}
===Beispiele===
* Broker verlangt Username/Passwort; es sollen keine Batterie-Werte ausgelesen werden
ble2mqtt --mqttserver mqtt.example.org:1883 --mqttuser ble2mqtt --mqttpass verysecret3 --batterymaxage 0

* Broker verlangt keine Authentifizierung; es soll nach zwei G-Tags gesucht werden; definiertes MQTT-Topic; Batteriewerte benötigt
ble2mqtt --mqttserver mqtt.example.org:1883 --mqtttopic ble2mqtt/Wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'

* Broker verlangt keine Authentifizierung; Geräte sollen nach 45s ohne Kontakt als abwesend angezeigt werden; MQTT Nachrichten sollen gespeichert bleiben
ble2mqtt --mqttserver mqtt.example.org:1883 --absentinterval 45 --retain

==Installation==
Zur Installation muss das ble2mqtt-Script auf den Server kopiert werden und es müssen diverse Linux- und Perl-Pakete installiert werden.

Zuerst das Script nach /usr/local/bin kopieren, um beim Aufruf in der Bash nicht immer den ganzen Pfad voranstellen zu müssen.
sudo cp -a ble2mqttd /usr/local/bin/
Danach das Script noch als ausführbar markieren
sudo chmod +x /usr/local/bin/ble2mqttd

===Benötigte Linux Pakete===
Die benötigten Pakete können ganz einfach mit ''apt'' installiert werden. Dabei werden auch mögliche Abhängigkeiten automatisch installiert.

sudo apt install -y libssl-dev libio-socket-ssl-perl libreadonly-perl libtest-expect-perl libnet-ssleay-perl libnet-server-perl

===Benötigte Perl-Module===
Es wird das Modul ''Net::MQTT::Simple'' (''libnet-mqtt-simple-perl'') benötigt. Das ist - Stand 08.11.2023 - noch nicht in den Stable-Repositories von Debian verfügbar und muss daher mittels ''cpan'' installiert werden. Voraussetzung dafür ist das Modul ''CPAN::DistnameInfo'', welches zuerst installiert werden muss.

sudo cpan CPAN::DistnameInfo
sudo cpan Net::MQTT::Simple

Sobald ''libnet-mqtt-simple-perl'' verfügbar ist, kann dieses statt der Perl-Module wie ein normales Linux-Paket installiert werden.

===Erster Test===
Mit einem einfachen Aufruf von '''ble2mqtt''' kann getestet werden, ob alle benötigten Module und Pakete vorhanden sind.

sudo /usr/local/bin/ble2mqttd

===Erstellen einens Systemd-Daemons===
Damit '''ble2mqtt''' bei jedem Systemstart automatisch gestartet wird, muss ein Systemd-Daemon erstellt werden. Das wird gemacht, in dem eine neue Textdatei mit folgendem Inhalt angelegt und der Daemon dann aktiviert wird.

{{Hinweis|'''Wichtig:''' Das Kommando, mit welchen Parametern ble2mqtt gestartet wird, muss natürlich individuell angepasst werden!}}

sudo nano /etc/systemd/system/ble2mqttd.service

<syntaxhighlight lang="ini">
[Unit]
Description=ble2mqttd
After=bluetooth.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/ble2mqttd --mqttserver mqtt.example.com:1883 --mqtttopic ble2mqtt/wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)' --absentinterval 30 --mqttuser <username> --mqttpass <password>

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

sudo systemctl daemon-reload
sudo systemctl enable ble2mqttd.service
sudo systemctl start ble2mqttd.service

==Einbindung in FHEM==
Da ble2mqtt alle Informationen an einen [[MQTT]]-Broker sendet, können diese Informationen ganz einfach als [[MQTT2_DEVICE]] in FHEM eingebunden werden. Wie dabei vorgegangen werden kann, unterscheidet sich je nach Anwendungsbereich und den eigenen Vorlieben.

Als Beispiel sie hier die Anwesenheitserkennung mittels BT-Tags angeführt.

===Anwesenheitserkennung mittels BT-Tags===
[[File:ble2mqtt.png|thumb|Readings eines Devices, dass mit diesem Code erstellt wurde]]
Der folgende Code geht davon aus, dass es mehrere ble2mqtt-Instanzen gibt und ein BT-Tag mit der MAC-Adresse AA:BB:CC:DD:EE:FF erkannt werden soll.

Die verschiedenen ble2mqtt-Instanzen schicken ihre Nachrichten in unterschiedliche Topics.
Für jede Instanz ein eigenes Topic:
*ble2mqtt/wohnzimmer
*ble2mqtt/schlafzimmer
*ble2mqtt/kueche
Im Attribut ''devicetopic'' werden diese Topics dann gemeinsam ausgewertet. Das funktioniert, in dem der Name des Subtopics einfach durch den Regex-Ausdruck ''.*'' ersetzt wird.

Bedeutet aber auch, dass die Informationen - wenn gewünscht - wieder in unterschiedliche Readings zerlegt werden müssen. Um z.B. schnell zu erkennen, in welchem Raum der BT-Tag gerade liegt. Das passiert hier z.B. bei den Nachrichten für ''rssi'' und ''presence''. Daraus resultieren dann eigene Readings für jedes MQTT-Subtopic.

Das "raumübergreifende" Reading ''presence'' wird anhand der des Alters in Sekunden der letzten lastseen-Nachricht gesteuert. Die lastseen-Nachricht wird immer gesendet, wenn der Scanvorgang von ble2mqtt das gewünschte Gerät findet.

<syntaxhighlight lang="perl">
define ble2mqttGTag MQTT2_DEVICE FHEM
attr ble2mqttGTag devicetopic ble2mqtt/.*/AA_BB_CC_DD_EE_FF
attr ble2mqttGTag event-on-change-reading .*
attr ble2mqttGTag readingList ble2mqtt/.*/heartbeat:.* heartbeat
$DEVICETOPIC/rssi:.* {my $room=(split m{[/]}x,$TOPIC)[1]; my $roomMax=$room; my $rssiMax=$EVENT; my @readings = grep { $_ =~ m{\Arssi_(?!$room).*}x } keys %{$defs{"$NAME"}->{READINGS}}; for (@readings) {my $rssiTmp=ReadingsVal($NAME,$_,'-100'); my $roomTmp=(split m{[_]}x,$_)[1]; if(($rssiMax gt $rssiTmp)&&(ReadingsVal($NAME,"presence_".$roomTmp,'absent') eq 'present')) {$rssiMax=$rssiTmp; $roomMax=$roomTmp}}; {rssi=>$rssiMax,room=>$roomMax,"rssi_$room"=>$EVENT}}
$DEVICETOPIC/lastseen:.* {lastseen=>strftime "%Y-%m-%d %H:%M:%S", localtime($EVENT)}
$DEVICETOPIC/present:.* {my $roomAct=(split m{[/]}x,$TOPIC)[1]; my $rssi=ReadingsVal($NAME,"rssi_".$roomAct,'-100'); my $presenceAct=$EVENT?'present':'absent'; my $room=$EVENT ? $roomAct:''; my @readings = grep { $_ =~ m{\Apresence_(?!$roomAct).*}x } keys %{$defs{$NAME}->{READINGS}}; for (@readings) {if(ReadingsVal($NAME,$_,'absent') eq 'present') {my $roomTmp=(split m{[_]}x,$_)[1]; my $rssiTmp=ReadingsVal($NAME,"rssi_".$roomTmp,'-100'); if($rssi gt $rssiTmp){$room=$roomTmp; $rssi=$rssiTmp}}}; {"presence_$roomAct"=>$presenceAct, room=>$room}}
ble2mqtt/.*/state:.* state
$DEVICETOPIC/battery:.* batteryLevel
attr ble2mqttGTag userReadings presence {if (ReadingsAge($NAME,"lastseen",0)>60) {return "absent";}else{return "present";}}
</syntaxhighlight>

Das Ergebnis ist unter anderem ein Reading ''presence'' mit den Zuständen ''absent'' und ''present''. Es kann somit ganz einfach als "presenceDevice" in einem [[ROOMMATE]]-Device verwendet werden:
attr rr_Franz rr_presenceDevices ble2mqttGTag

[[Category:MQTT]][[Category:Anwesenheitserkennung]][[Category:FHEM Utilities]]

Ble2mqtt

2023-11-08T14:51:49Z

Drhirn: /* Einbindung in FHEM */

{{Baustelle}}
{{Infobox Modul
|ModPurpose=Anwesenheitserkennung von Bluetooth-Geräten
|ModType=u
|ModFTopic=127173
|ModForumArea=Unterstützende Dienste
|ModTechName=ble2mqtt
|ModOwner=PatrickR
}}
'''ble2mqtt''' ist ein Script, dass den Anwesenheitsstatus eines oder mehrerer Bluetooth Low Energy Geräte überprüfen und das Ergebnis an einen MQTT Broker schicken kann.

Es verwendet dazu die Linux Tools ''bluetoothctl'' und ''gatttool''.

ble2mqtt ist in Perl geschrieben und wurde von {{Link2FU|5068|PatrickR}} erstellt. Weitere Informationen finden sich in diesem {{Link2Forum|Topic=127173|LinkText=Forums-Topic }}. Fragen dazu bitte in den Bereich [https://forum.fhem.de/index.php?board=44.0 Unterstützende Dienste]


==Voraussetzungen==
* Debian od. Raspberry Pi OS
* Bluetooth Empfänger

==Parameter==
Beim Start von ble2mqtt können folgende Parameter angegeben werden:

{| class="wikitable"
!Parameter!!Beschreibung!!Standardwert!!Beispiel!!Optional
|-
| --mqttserver
|Die Adresse des MQTT Brokers inklusive Port
|
| --mqttserver mqtt.example.org:1883
|nein
|-
| --mqttfingerprint
|Der Fingerprint des für die TLS-verschlüsselte Kommunikation mit dem MQTT Broker verwendeten Zertifikates
|
| --mqttfingerprint bfe5d244a821194230f1479fe2f8f7bbcd2a8cb8
|ja
|-
| --mqtttopic
| An welches MQTT-Topic das Tool die Informationen schicken soll.
|ble2mqtt
| --mqtttopic ble2mqtt/Wohnzimmer
|ja
|-
| --mqttuser
|Der Benutzernamen, unter dem die Verbindung zum Broker hergestellt werden soll
|
| --mqttuser ble2mqtt
|ja bzw. abhängig vom Broker
|-
| --mqttpass
|Das zum Benutzernamen gehörende Passwort
|
| --mqttpass verysecret3
|ja bzw. abhängig vom Broker
|-
| --retain
|Versendet die Nachrichten present und lastseen als retained.
|0
| --retain
|ja
|-
| --daemonize
|Wenn ble2mqtt im Hintergrund (als Daemon) ausgeführt werden soll
|0
| --daemonize
|ja
|-
| --loglevel
|Wie und was genau protokolliert werden soll. Mögliche Loglevel sind LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
|LOG_INFO
| --loglevel LOG_ERR
|ja
|-
| --logtarget
|Wohin gelogged werden soll. Mögliche Optionen sind ''syslog'' und ''stdout''.
|syslog
| --logtarget stdout
|ja
|-
| --absentinterval
|Anzahl an Sekunden, nach denen das Gerät als abwesend bezeichnet werden soll. Mindestwert ist 30.
|60
| --absentinterval 120
|ja
|-
| --rssithreshold
|Ab welcher Abweichung des RSSI Wertes ein Update getriggert werden soll. Mindestwert ist 5.
|10
| --rssithreshold 8
|ja
|-
| --watchdogthreshold
|Ab welchem Zeitraum in Sekunden nach Empfangen des letzten BT-Signals ble2mqtt neu gestartet werden soll. Mindestwert ist 30. Der Wert 0 bedeutet deaktiviert, also nie.
|0
| --watchdogthreshold 30
|ja
|-
| --debug
|Kann nur gemeinsam mit --daemonize verwendet werden, um Logeinträge auf stdout auszugeben. Je höher die Nummer, desto mehr Output.
|0
| --daemonize --debug 4
|ja
|-
| --mac
|Filtert mittels Regex nach MAC-Adressen der von ble2mqtt zu beachtenden BLE-Geräte. Alle anderen Geräte werden ignoriert.
|
| --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'
|ja
|-
| --batterymaxage
|Zeit in Stunden, nach denen ein Batterie-Wert als veraltet angesehen und aktualisiert wird. Der Wert 0 deaktiviert den Batterie-Check.
|48
| --batterymaxage 6
|ja
|-
| --forcebattery
|Nur in Kombination mit --mac. Erzwingt einen Batterie-Check, auch wenn das battery-service am Gerät nicht erkannt wird.
|0
| --forcebattery
|ja
|}
===Beispiele===
* Broker verlangt Username/Passwort; es sollen keine Batterie-Werte ausgelesen werden
ble2mqtt --mqttserver mqtt.example.org:1883 --mqttuser ble2mqtt --mqttpass verysecret3 --batterymaxage 0

* Broker verlangt keine Authentifizierung; es soll nach zwei G-Tags gesucht werden; definiertes MQTT-Topic; Batteriewerte benötigt
ble2mqtt --mqttserver mqtt.example.org:1883 --mqtttopic ble2mqtt/Wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'

* Broker verlangt keine Authentifizierung; Geräte sollen nach 45s ohne Kontakt als abwesend angezeigt werden; MQTT Nachrichten sollen gespeichert bleiben
ble2mqtt --mqttserver mqtt.example.org:1883 --absentinterval 45 --retain

==Installation==
Zur Installation muss das ble2mqtt-Script auf den Server kopiert werden und es müssen diverse Linux- und Perl-Pakete installiert werden.

Zuerst das Script nach /usr/local/bin kopieren, um beim Aufruf in der Bash nicht immer den ganzen Pfad voranstellen zu müssen.
sudo cp -a ble2mqttd /usr/local/bin/
Danach das Script noch als ausführbar markieren
sudo chmod +x /usr/local/bin/ble2mqttd

===Benötigte Linux Pakete===
Die benötigten Pakete können ganz einfach mit ''apt'' installiert werden. Dabei werden auch mögliche Abhängigkeiten automatisch installiert.

sudo apt install -y libssl-dev libio-socket-ssl-perl libreadonly-perl libtest-expect-perl libnet-ssleay-perl libnet-server-perl

===Benötigte Perl-Module===
Es wird das Modul ''Net::MQTT::Simple'' (''libnet-mqtt-simple-perl'') benötigt. Das ist - Stand 08.11.2023 - noch nicht in den Stable-Repositories von Debian verfügbar und muss daher mittels ''cpan'' installiert werden. Voraussetzung dafür ist das Modul ''CPAN::DistnameInfo'', welches zuerst installiert werden muss.

sudo cpan CPAN::DistnameInfo
sudo cpan Net::MQTT::Simple

Sobald ''libnet-mqtt-simple-perl'' verfügbar ist, kann dieses statt der Perl-Module wie ein normales Linux-Paket installiert werden.

===Erster Test===
Mit einem einfachen Aufruf von '''ble2mqtt''' kann getestet werden, ob alle benötigten Module und Pakete vorhanden sind.

sudo /usr/local/bin/ble2mqttd

===Erstellen einens Systemd-Daemons===
Damit '''ble2mqtt''' bei jedem Systemstart automatisch gestartet wird, muss ein Systemd-Daemon erstellt werden. Das wird gemacht, in dem eine neue Textdatei mit folgendem Inhalt angelegt und der Daemon dann aktiviert wird.

{{Hinweis|Text='''Wichtig:''' Das Kommando, mit welchen Parametern ble2mqtt gestartet wird, muss natürlich individuell angepasst werden!}}

sudo nano /etc/systemd/system/ble2mqttd.service

<syntaxhighlight lang="ini">
[Unit]
Description=ble2mqttd
After=bluetooth.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/ble2mqttd --mqttserver mqtt.example.com:1883 --mqtttopic ble2mqtt/wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)' --absentinterval 30 --mqttuser <username> --mqttpass <password>

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

sudo systemctl daemon-reload
sudo systemctl enable ble2mqttd.service
sudo systemctl start ble2mqttd.service

==Einbindung in FHEM==
Da ble2mqtt alle Informationen an einen [[MQTT]]-Broker sendet, können diese Informationen ganz einfach als [[MQTT2_DEVICE]] in FHEM eingebunden werden. Wie dabei vorgegangen werden kann, unterscheidet sich je nach Anwendungsbereich und den eigenen Vorlieben.

Als Beispiel sie hier die Anwesenheitserkennung mittels BT-Tags angeführt.

===Anwesenheitserkennung mittels BT-Tags===
[[File:ble2mqtt.png|thumb|Readings eines Devices, dass mit diesem Code erstellt wurde]]
Der folgende Code geht davon aus, dass es mehrere ble2mqtt-Instanzen gibt und ein BT-Tag mit der MAC-Adresse AA:BB:CC:DD:EE:FF erkannt werden soll.

Die verschiedenen ble2mqtt-Instanzen schicken ihre Nachrichten in unterschiedliche Topics.
Für jede Instanz ein eigenes Topic:
*ble2mqtt/wohnzimmer
*ble2mqtt/schlafzimmer
*ble2mqtt/kueche
Im Attribut ''devicetopic'' werden diese Topics dann gemeinsam ausgewertet. Das funktioniert, in dem der Name des Subtopics einfach durch den Regex-Ausdruck ''.*'' ersetzt wird.

Bedeutet aber auch, dass die Informationen - wenn gewünscht - wieder in unterschiedliche Readings zerlegt werden müssen. Um z.B. schnell zu erkennen, in welchem Raum der BT-Tag gerade liegt. Das passiert hier z.B. bei den Nachrichten für ''rssi'' und ''presence''. Daraus resultieren dann eigene Readings für jedes MQTT-Subtopic.

Das "raumübergreifende" Reading ''presence'' wird anhand der des Alters in Sekunden der letzten lastseen-Nachricht gesteuert. Die lastseen-Nachricht wird immer gesendet, wenn der Scanvorgang von ble2mqtt das gewünschte Gerät findet.

<syntaxhighlight lang="perl">
define ble2mqttGTag MQTT2_DEVICE FHEM
attr ble2mqttGTag devicetopic ble2mqtt/.*/AA_BB_CC_DD_EE_FF
attr ble2mqttGTag event-on-change-reading .*
attr ble2mqttGTag readingList ble2mqtt/.*/heartbeat:.* heartbeat
$DEVICETOPIC/rssi:.* {my $room=(split m{[/]}x,$TOPIC)[1]; my $roomMax=$room; my $rssiMax=$EVENT; my @readings = grep { $_ =~ m{\Arssi_(?!$room).*}x } keys %{$defs{"$NAME"}->{READINGS}}; for (@readings) {my $rssiTmp=ReadingsVal($NAME,$_,'-100'); my $roomTmp=(split m{[_]}x,$_)[1]; if(($rssiMax gt $rssiTmp)&&(ReadingsVal($NAME,"presence_".$roomTmp,'absent') eq 'present')) {$rssiMax=$rssiTmp; $roomMax=$roomTmp}}; {rssi=>$rssiMax,room=>$roomMax,"rssi_$room"=>$EVENT}}
$DEVICETOPIC/lastseen:.* {lastseen=>strftime "%Y-%m-%d %H:%M:%S", localtime($EVENT)}
$DEVICETOPIC/present:.* {my $roomAct=(split m{[/]}x,$TOPIC)[1]; my $rssi=ReadingsVal($NAME,"rssi_".$roomAct,'-100'); my $presenceAct=$EVENT?'present':'absent'; my $room=$EVENT ? $roomAct:''; my @readings = grep { $_ =~ m{\Apresence_(?!$roomAct).*}x } keys %{$defs{$NAME}->{READINGS}}; for (@readings) {if(ReadingsVal($NAME,$_,'absent') eq 'present') {my $roomTmp=(split m{[_]}x,$_)[1]; my $rssiTmp=ReadingsVal($NAME,"rssi_".$roomTmp,'-100'); if($rssi gt $rssiTmp){$room=$roomTmp; $rssi=$rssiTmp}}}; {"presence_$roomAct"=>$presenceAct, room=>$room}}
ble2mqtt/.*/state:.* state
$DEVICETOPIC/battery:.* batteryLevel
attr ble2mqttGTag userReadings presence {if (ReadingsAge($NAME,"lastseen",0)>60) {return "absent";}else{return "present";}}
</syntaxhighlight>

Das Ergebnis ist unter anderem ein Reading ''presence'' mit den Zuständen ''absent'' und ''present''. Es kann somit ganz einfach als "presenceDevice" in einem [[ROOMMATE]]-Device verwendet werden:
attr rr_Franz rr_presenceDevices ble2mqttGTag

[[Category:MQTT]][[Category:Anwesenheitserkennung]][[Category:FHEM Utilities]]

Datei:Ble2mqtt.png

2023-11-08T14:51:31Z

Drhirn: Readings eines MQTT2_DEVICE, dass mit diesem Code aus ble2mqtt erstellt wurde

== Beschreibung ==
Readings eines MQTT2_DEVICE, dass mit diesem Code aus [[ble2mqtt]] erstellt wurde

Ble2mqtt

2023-11-08T14:49:05Z

Drhirn:

{{Baustelle}}
{{Infobox Modul
|ModPurpose=Anwesenheitserkennung von Bluetooth-Geräten
|ModType=u
|ModFTopic=127173
|ModForumArea=Unterstützende Dienste
|ModTechName=ble2mqtt
|ModOwner=PatrickR
}}
'''ble2mqtt''' ist ein Script, dass den Anwesenheitsstatus eines oder mehrerer Bluetooth Low Energy Geräte überprüfen und das Ergebnis an einen MQTT Broker schicken kann.

Es verwendet dazu die Linux Tools ''bluetoothctl'' und ''gatttool''.

ble2mqtt ist in Perl geschrieben und wurde von {{Link2FU|5068|PatrickR}} erstellt. Weitere Informationen finden sich in diesem {{Link2Forum|Topic=127173|LinkText=Forums-Topic }}. Fragen dazu bitte in den Bereich [https://forum.fhem.de/index.php?board=44.0 Unterstützende Dienste]


==Voraussetzungen==
* Debian od. Raspberry Pi OS
* Bluetooth Empfänger

==Parameter==
Beim Start von ble2mqtt können folgende Parameter angegeben werden:

{| class="wikitable"
!Parameter!!Beschreibung!!Standardwert!!Beispiel!!Optional
|-
| --mqttserver
|Die Adresse des MQTT Brokers inklusive Port
|
| --mqttserver mqtt.example.org:1883
|nein
|-
| --mqttfingerprint
|Der Fingerprint des für die TLS-verschlüsselte Kommunikation mit dem MQTT Broker verwendeten Zertifikates
|
| --mqttfingerprint bfe5d244a821194230f1479fe2f8f7bbcd2a8cb8
|ja
|-
| --mqtttopic
| An welches MQTT-Topic das Tool die Informationen schicken soll.
|ble2mqtt
| --mqtttopic ble2mqtt/Wohnzimmer
|ja
|-
| --mqttuser
|Der Benutzernamen, unter dem die Verbindung zum Broker hergestellt werden soll
|
| --mqttuser ble2mqtt
|ja bzw. abhängig vom Broker
|-
| --mqttpass
|Das zum Benutzernamen gehörende Passwort
|
| --mqttpass verysecret3
|ja bzw. abhängig vom Broker
|-
| --retain
|Versendet die Nachrichten present und lastseen als retained.
|0
| --retain
|ja
|-
| --daemonize
|Wenn ble2mqtt im Hintergrund (als Daemon) ausgeführt werden soll
|0
| --daemonize
|ja
|-
| --loglevel
|Wie und was genau protokolliert werden soll. Mögliche Loglevel sind LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
|LOG_INFO
| --loglevel LOG_ERR
|ja
|-
| --logtarget
|Wohin gelogged werden soll. Mögliche Optionen sind ''syslog'' und ''stdout''.
|syslog
| --logtarget stdout
|ja
|-
| --absentinterval
|Anzahl an Sekunden, nach denen das Gerät als abwesend bezeichnet werden soll. Mindestwert ist 30.
|60
| --absentinterval 120
|ja
|-
| --rssithreshold
|Ab welcher Abweichung des RSSI Wertes ein Update getriggert werden soll. Mindestwert ist 5.
|10
| --rssithreshold 8
|ja
|-
| --watchdogthreshold
|Ab welchem Zeitraum in Sekunden nach Empfangen des letzten BT-Signals ble2mqtt neu gestartet werden soll. Mindestwert ist 30. Der Wert 0 bedeutet deaktiviert, also nie.
|0
| --watchdogthreshold 30
|ja
|-
| --debug
|Kann nur gemeinsam mit --daemonize verwendet werden, um Logeinträge auf stdout auszugeben. Je höher die Nummer, desto mehr Output.
|0
| --daemonize --debug 4
|ja
|-
| --mac
|Filtert mittels Regex nach MAC-Adressen der von ble2mqtt zu beachtenden BLE-Geräte. Alle anderen Geräte werden ignoriert.
|
| --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'
|ja
|-
| --batterymaxage
|Zeit in Stunden, nach denen ein Batterie-Wert als veraltet angesehen und aktualisiert wird. Der Wert 0 deaktiviert den Batterie-Check.
|48
| --batterymaxage 6
|ja
|-
| --forcebattery
|Nur in Kombination mit --mac. Erzwingt einen Batterie-Check, auch wenn das battery-service am Gerät nicht erkannt wird.
|0
| --forcebattery
|ja
|}
===Beispiele===
* Broker verlangt Username/Passwort; es sollen keine Batterie-Werte ausgelesen werden
ble2mqtt --mqttserver mqtt.example.org:1883 --mqttuser ble2mqtt --mqttpass verysecret3 --batterymaxage 0

* Broker verlangt keine Authentifizierung; es soll nach zwei G-Tags gesucht werden; definiertes MQTT-Topic; Batteriewerte benötigt
ble2mqtt --mqttserver mqtt.example.org:1883 --mqtttopic ble2mqtt/Wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'

* Broker verlangt keine Authentifizierung; Geräte sollen nach 45s ohne Kontakt als abwesend angezeigt werden; MQTT Nachrichten sollen gespeichert bleiben
ble2mqtt --mqttserver mqtt.example.org:1883 --absentinterval 45 --retain

==Installation==
Zur Installation muss das ble2mqtt-Script auf den Server kopiert werden und es müssen diverse Linux- und Perl-Pakete installiert werden.

Zuerst das Script nach /usr/local/bin kopieren, um beim Aufruf in der Bash nicht immer den ganzen Pfad voranstellen zu müssen.
sudo cp -a ble2mqttd /usr/local/bin/
Danach das Script noch als ausführbar markieren
sudo chmod +x /usr/local/bin/ble2mqttd

===Benötigte Linux Pakete===
Die benötigten Pakete können ganz einfach mit ''apt'' installiert werden. Dabei werden auch mögliche Abhängigkeiten automatisch installiert.

sudo apt install -y libssl-dev libio-socket-ssl-perl libreadonly-perl libtest-expect-perl libnet-ssleay-perl libnet-server-perl

===Benötigte Perl-Module===
Es wird das Modul ''Net::MQTT::Simple'' (''libnet-mqtt-simple-perl'') benötigt. Das ist - Stand 08.11.2023 - noch nicht in den Stable-Repositories von Debian verfügbar und muss daher mittels ''cpan'' installiert werden. Voraussetzung dafür ist das Modul ''CPAN::DistnameInfo'', welches zuerst installiert werden muss.

sudo cpan CPAN::DistnameInfo
sudo cpan Net::MQTT::Simple

Sobald ''libnet-mqtt-simple-perl'' verfügbar ist, kann dieses statt der Perl-Module wie ein normales Linux-Paket installiert werden.

===Erster Test===
Mit einem einfachen Aufruf von '''ble2mqtt''' kann getestet werden, ob alle benötigten Module und Pakete vorhanden sind.

sudo /usr/local/bin/ble2mqttd

===Erstellen einens Systemd-Daemons===
Damit '''ble2mqtt''' bei jedem Systemstart automatisch gestartet wird, muss ein Systemd-Daemon erstellt werden. Das wird gemacht, in dem eine neue Textdatei mit folgendem Inhalt angelegt und der Daemon dann aktiviert wird.

{{Hinweis|Text='''Wichtig:''' Das Kommando, mit welchen Parametern ble2mqtt gestartet wird, muss natürlich individuell angepasst werden!}}

sudo nano /etc/systemd/system/ble2mqttd.service

<syntaxhighlight lang="ini">
[Unit]
Description=ble2mqttd
After=bluetooth.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/ble2mqttd --mqttserver mqtt.example.com:1883 --mqtttopic ble2mqtt/wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)' --absentinterval 30 --mqttuser <username> --mqttpass <password>

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

sudo systemctl daemon-reload
sudo systemctl enable ble2mqttd.service
sudo systemctl start ble2mqttd.service

==Einbindung in FHEM==
Da ble2mqtt alle Informationen an einen [[MQTT]]-Broker sendet, können diese Informationen ganz einfach als [[MQTT2_DEVICE]] in FHEM eingebunden werden. Wie dabei vorgegangen werden kann, unterscheidet sich je nach Anwendungsbereich und den eigenen Vorlieben.

Als Beispiel sie hier die Anwesenheitserkennung mittels BT-Tags angeführt.

===Anwesenheitserkennung mittels BT-Tags===
[[File:ble2mqtt.png|thumb|Readings eines Devices, dass mit diesem Codes erstellt wurde]]
Der folgende Code geht davon aus, dass es mehrere ble2mqtt-Instanzen gibt und ein BT-Tag mit der MAC-Adresse AA:BB:CC:DD:EE:FF erkannt werden soll.

Die verschiedenen ble2mqtt-Instanzen schicken ihre Nachrichten in unterschiedliche Topics.
Für jede Instanz ein eigenes Topic:
*ble2mqtt/wohnzimmer
*ble2mqtt/schlafzimmer
*ble2mqtt/kueche
Im Attribut ''devicetopic'' werden diese Topics dann gemeinsam ausgewertet. Das funktioniert, in dem der Name des Subtopics einfach durch den Regex-Ausdruck ''.*'' ersetzt wird.

Bedeutet aber auch, dass die Informationen - wenn gewünscht - wieder in unterschiedliche Readings zerlegt werden müssen. Um z.B. schnell zu erkennen, in welchem Raum der BT-Tag gerade liegt. Das passiert hier z.B. bei den Nachrichten für ''rssi'' und ''presence''. Daraus resultieren dann eigene Readings für jedes MQTT-Subtopic.

Das "raumübergreifende" Reading ''presence'' wird anhand der des Alters in Sekunden der letzten lastseen-Nachricht gesteuert. Die lastseen-Nachricht wird immer gesendet, wenn der Scanvorgang von ble2mqtt das gewünschte Gerät findet.

<syntaxhighlight lang="perl">
define ble2mqttGTag MQTT2_DEVICE FHEM
attr ble2mqttGTag devicetopic ble2mqtt/.*/AA_BB_CC_DD_EE_FF
attr ble2mqttGTag event-on-change-reading .*
attr ble2mqttGTag readingList ble2mqtt/.*/heartbeat:.* heartbeat
$DEVICETOPIC/rssi:.* {my $room=(split m{[/]}x,$TOPIC)[1]; my $roomMax=$room; my $rssiMax=$EVENT; my @readings = grep { $_ =~ m{\Arssi_(?!$room).*}x } keys %{$defs{"$NAME"}->{READINGS}}; for (@readings) {my $rssiTmp=ReadingsVal($NAME,$_,'-100'); my $roomTmp=(split m{[_]}x,$_)[1]; if(($rssiMax gt $rssiTmp)&&(ReadingsVal($NAME,"presence_".$roomTmp,'absent') eq 'present')) {$rssiMax=$rssiTmp; $roomMax=$roomTmp}}; {rssi=>$rssiMax,room=>$roomMax,"rssi_$room"=>$EVENT}}
$DEVICETOPIC/lastseen:.* {lastseen=>strftime "%Y-%m-%d %H:%M:%S", localtime($EVENT)}
$DEVICETOPIC/present:.* {my $roomAct=(split m{[/]}x,$TOPIC)[1]; my $rssi=ReadingsVal($NAME,"rssi_".$roomAct,'-100'); my $presenceAct=$EVENT?'present':'absent'; my $room=$EVENT ? $roomAct:''; my @readings = grep { $_ =~ m{\Apresence_(?!$roomAct).*}x } keys %{$defs{$NAME}->{READINGS}}; for (@readings) {if(ReadingsVal($NAME,$_,'absent') eq 'present') {my $roomTmp=(split m{[_]}x,$_)[1]; my $rssiTmp=ReadingsVal($NAME,"rssi_".$roomTmp,'-100'); if($rssi gt $rssiTmp){$room=$roomTmp; $rssi=$rssiTmp}}}; {"presence_$roomAct"=>$presenceAct, room=>$room}}
ble2mqtt/.*/state:.* state
$DEVICETOPIC/battery:.* batteryLevel
attr ble2mqttGTag userReadings presence {if (ReadingsAge($NAME,"lastseen",0)>60) {return "absent";}else{return "present";}}
</syntaxhighlight>

Das Ergebnis ist unter anderem ein Reading ''presence'' mit den Zuständen ''absent'' und ''present''. Es kann somit ganz einfach als "presenceDevice" in einem [[ROOMMATE]]-Device verwendet werden:
attr rr_Franz rr_presenceDevices ble2mqttGTag

[[Category:MQTT]][[Category:Anwesenheitserkennung]][[Category:FHEM Utilities]]

Ble2mqtt

2023-11-08T14:44:23Z

Drhirn: Die Seite wurde neu angelegt: „{{Baustelle}} '''ble2mqtt''' ist ein Script, dass den Anwesenheitsstatus eines oder mehrerer Bluetooth Low Energy Geräte überprüfen und das Ergebnis an einen MQTT Broker schicken kann. Es verwendet dazu die Linux Tools ''bluetoothctl'' und ''gatttool''. ble2mqtt ist in Perl geschrieben und wurde von {{Link2FU|5068|PatrickR}} erstellt. Weitere Informationen finden sich in diesem {{Link2Forum|Topic=127173|LinkText=Forums-Topic }}. Fragen dazu bitte in…“

{{Baustelle}}
'''ble2mqtt''' ist ein Script, dass den Anwesenheitsstatus eines oder mehrerer Bluetooth Low Energy Geräte überprüfen und das Ergebnis an einen MQTT Broker schicken kann.

Es verwendet dazu die Linux Tools ''bluetoothctl'' und ''gatttool''.

ble2mqtt ist in Perl geschrieben und wurde von {{Link2FU|5068|PatrickR}} erstellt. Weitere Informationen finden sich in diesem {{Link2Forum|Topic=127173|LinkText=Forums-Topic }}. Fragen dazu bitte in den Bereich [https://forum.fhem.de/index.php?board=44.0 Unterstützende Dienste]


==Voraussetzungen==
* Debian od. Raspberry Pi OS
* Bluetooth Empfänger

==Parameter==
Beim Start von ble2mqtt können folgende Parameter angegeben werden:

{| class="wikitable"
!Parameter!!Beschreibung!!Standardwert!!Beispiel!!Optional
|-
| --mqttserver
|Die Adresse des MQTT Brokers inklusive Port
|
| --mqttserver mqtt.example.org:1883
|nein
|-
| --mqttfingerprint
|Der Fingerprint des für die TLS-verschlüsselte Kommunikation mit dem MQTT Broker verwendeten Zertifikates
|
| --mqttfingerprint bfe5d244a821194230f1479fe2f8f7bbcd2a8cb8
|ja
|-
| --mqtttopic
| An welches MQTT-Topic das Tool die Informationen schicken soll.
|ble2mqtt
| --mqtttopic ble2mqtt/Wohnzimmer
|ja
|-
| --mqttuser
|Der Benutzernamen, unter dem die Verbindung zum Broker hergestellt werden soll
|
| --mqttuser ble2mqtt
|ja bzw. abhängig vom Broker
|-
| --mqttpass
|Das zum Benutzernamen gehörende Passwort
|
| --mqttpass verysecret3
|ja bzw. abhängig vom Broker
|-
| --retain
|Versendet die Nachrichten present und lastseen als retained.
|0
| --retain
|ja
|-
| --daemonize
|Wenn ble2mqtt im Hintergrund (als Daemon) ausgeführt werden soll
|0
| --daemonize
|ja
|-
| --loglevel
|Wie und was genau protokolliert werden soll. Mögliche Loglevel sind LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
|LOG_INFO
| --loglevel LOG_ERR
|ja
|-
| --logtarget
|Wohin gelogged werden soll. Mögliche Optionen sind ''syslog'' und ''stdout''.
|syslog
| --logtarget stdout
|ja
|-
| --absentinterval
|Anzahl an Sekunden, nach denen das Gerät als abwesend bezeichnet werden soll. Mindestwert ist 30.
|60
| --absentinterval 120
|ja
|-
| --rssithreshold
|Ab welcher Abweichung des RSSI Wertes ein Update getriggert werden soll. Mindestwert ist 5.
|10
| --rssithreshold 8
|ja
|-
| --watchdogthreshold
|Ab welchem Zeitraum in Sekunden nach Empfangen des letzten BT-Signals ble2mqtt neu gestartet werden soll. Mindestwert ist 30. Der Wert 0 bedeutet deaktiviert, also nie.
|0
| --watchdogthreshold 30
|ja
|-
| --debug
|Kann nur gemeinsam mit --daemonize verwendet werden, um Logeinträge auf stdout auszugeben. Je höher die Nummer, desto mehr Output.
|0
| --daemonize --debug 4
|ja
|-
| --mac
|Filtert mittels Regex nach MAC-Adressen der von ble2mqtt zu beachtenden BLE-Geräte. Alle anderen Geräte werden ignoriert.
|
| --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'
|ja
|-
| --batterymaxage
|Zeit in Stunden, nach denen ein Batterie-Wert als veraltet angesehen und aktualisiert wird. Der Wert 0 deaktiviert den Batterie-Check.
|48
| --batterymaxage 6
|ja
|-
| --forcebattery
|Nur in Kombination mit --mac. Erzwingt einen Batterie-Check, auch wenn das battery-service am Gerät nicht erkannt wird.
|0
| --forcebattery
|ja
|}
===Beispiele===
* Broker verlangt Username/Passwort; es sollen keine Batterie-Werte ausgelesen werden
ble2mqtt --mqttserver mqtt.example.org:1883 --mqttuser ble2mqtt --mqttpass verysecret3 --batterymaxage 0

* Broker verlangt keine Authentifizierung; es soll nach zwei G-Tags gesucht werden; definiertes MQTT-Topic; Batteriewerte benötigt
ble2mqtt --mqttserver mqtt.example.org:1883 --mqtttopic ble2mqtt/Wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)'

* Broker verlangt keine Authentifizierung; Geräte sollen nach 45s ohne Kontakt als abwesend angezeigt werden; MQTT Nachrichten sollen gespeichert bleiben
ble2mqtt --mqttserver mqtt.example.org:1883 --absentinterval 45 --retain

==Installation==
Zur Installation muss das ble2mqtt-Script auf den Server kopiert werden und es müssen diverse Linux- und Perl-Pakete installiert werden.

Zuerst das Script nach /usr/local/bin kopieren, um beim Aufruf in der Bash nicht immer den ganzen Pfad voranstellen zu müssen.
sudo cp -a ble2mqttd /usr/local/bin/
Danach das Script noch als ausführbar markieren
sudo chmod +x /usr/local/bin/ble2mqttd

===Benötigte Linux Pakete===
Die benötigten Pakete können ganz einfach mit ''apt'' installiert werden. Dabei werden auch mögliche Abhängigkeiten automatisch installiert.

sudo apt install -y libssl-dev libio-socket-ssl-perl libreadonly-perl libtest-expect-perl libnet-ssleay-perl libnet-server-perl

===Benötigte Perl-Module===
Es wird das Modul ''Net::MQTT::Simple'' (''libnet-mqtt-simple-perl'') benötigt. Das ist - Stand 08.11.2023 - noch nicht in den Stable-Repositories von Debian verfügbar und muss daher mittels ''cpan'' installiert werden. Voraussetzung dafür ist das Modul ''CPAN::DistnameInfo'', welches zuerst installiert werden muss.

sudo cpan CPAN::DistnameInfo
sudo cpan Net::MQTT::Simple

Sobald ''libnet-mqtt-simple-perl'' verfügbar ist, kann dieses statt der Perl-Module wie ein normales Linux-Paket installiert werden.

===Erster Test===
Mit einem einfachen Aufruf von '''ble2mqtt''' kann getestet werden, ob alle benötigten Module und Pakete vorhanden sind.

sudo /usr/local/bin/ble2mqttd

===Erstellen einens Systemd-Daemons===
Damit '''ble2mqtt''' bei jedem Systemstart automatisch gestartet wird, muss ein Systemd-Daemon erstellt werden. Das wird gemacht, in dem eine neue Textdatei mit folgendem Inhalt angelegt und der Daemon dann aktiviert wird.

{{Hinweis|Text='''Wichtig:''' Das Kommando, mit welchen Parametern ble2mqtt gestartet wird, muss natürlich individuell angepasst werden!}}

sudo nano /etc/systemd/system/ble2mqttd.service

<syntaxhighlight lang="ini">
[Unit]
Description=ble2mqttd
After=bluetooth.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/ble2mqttd --mqttserver mqtt.example.com:1883 --mqtttopic ble2mqtt/wohnzimmer --mac '(11:22:33:44:55:66|77:88:99:00:AA:BB)' --absentinterval 30 --mqttuser <username> --mqttpass <password>

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

sudo systemctl daemon-reload
sudo systemctl enable ble2mqttd.service
sudo systemctl start ble2mqttd.service

==Einbindung in FHEM==
Da ble2mqtt alle Informationen an einen [[MQTT]]-Broker sendet, können diese Informationen ganz einfach als [[MQTT2_DEVICE]] in FHEM eingebunden werden. Wie dabei vorgegangen werden kann, unterscheidet sich je nach Anwendungsbereich und den eigenen Vorlieben.

Als Beispiel sie hier die Anwesenheitserkennung mittels BT-Tags angeführt.

===Anwesenheitserkennung mittels BT-Tags===
[[File:ble2mqtt.png|thumb|Readings eines Devices, dass mit diesem Codes erstellt wurde]]
Der folgende Code geht davon aus, dass es mehrere ble2mqtt-Instanzen gibt und ein BT-Tag mit der MAC-Adresse AA:BB:CC:DD:EE:FF erkannt werden soll.

Die verschiedenen ble2mqtt-Instanzen schicken ihre Nachrichten in unterschiedliche Topics.
Für jede Instanz ein eigenes Topic:
*ble2mqtt/wohnzimmer
*ble2mqtt/schlafzimmer
*ble2mqtt/kueche
Im Attribut ''devicetopic'' werden diese Topics dann gemeinsam ausgewertet. Das funktioniert, in dem der Name des Subtopics einfach durch den Regex-Ausdruck ''.*'' ersetzt wird.

Bedeutet aber auch, dass die Informationen - wenn gewünscht - wieder in unterschiedliche Readings zerlegt werden müssen. Um z.B. schnell zu erkennen, in welchem Raum der BT-Tag gerade liegt. Das passiert hier z.B. bei den Nachrichten für ''rssi'' und ''presence''. Daraus resultieren dann eigene Readings für jedes MQTT-Subtopic.

Das "raumübergreifende" Reading ''presence'' wird anhand der des Alters in Sekunden der letzten lastseen-Nachricht gesteuert. Die lastseen-Nachricht wird immer gesendet, wenn der Scanvorgang von ble2mqtt das gewünschte Gerät findet.

<syntaxhighlight lang="perl">
define ble2mqttGTag MQTT2_DEVICE FHEM
attr ble2mqttGTag devicetopic ble2mqtt/.*/AA_BB_CC_DD_EE_FF
attr ble2mqttGTag event-on-change-reading .*
attr ble2mqttGTag readingList ble2mqtt/.*/heartbeat:.* heartbeat
$DEVICETOPIC/rssi:.* {my $room=(split m{[/]}x,$TOPIC)[1]; my $roomMax=$room; my $rssiMax=$EVENT; my @readings = grep { $_ =~ m{\Arssi_(?!$room).*}x } keys %{$defs{"$NAME"}->{READINGS}}; for (@readings) {my $rssiTmp=ReadingsVal($NAME,$_,'-100'); my $roomTmp=(split m{[_]}x,$_)[1]; if(($rssiMax gt $rssiTmp)&&(ReadingsVal($NAME,"presence_".$roomTmp,'absent') eq 'present')) {$rssiMax=$rssiTmp; $roomMax=$roomTmp}}; {rssi=>$rssiMax,room=>$roomMax,"rssi_$room"=>$EVENT}}
$DEVICETOPIC/lastseen:.* {lastseen=>strftime "%Y-%m-%d %H:%M:%S", localtime($EVENT)}
$DEVICETOPIC/present:.* {my $roomAct=(split m{[/]}x,$TOPIC)[1]; my $rssi=ReadingsVal($NAME,"rssi_".$roomAct,'-100'); my $presenceAct=$EVENT?'present':'absent'; my $room=$EVENT ? $roomAct:''; my @readings = grep { $_ =~ m{\Apresence_(?!$roomAct).*}x } keys %{$defs{$NAME}->{READINGS}}; for (@readings) {if(ReadingsVal($NAME,$_,'absent') eq 'present') {my $roomTmp=(split m{[_]}x,$_)[1]; my $rssiTmp=ReadingsVal($NAME,"rssi_".$roomTmp,'-100'); if($rssi gt $rssiTmp){$room=$roomTmp; $rssi=$rssiTmp}}}; {"presence_$roomAct"=>$presenceAct, room=>$room}}
ble2mqtt/.*/state:.* state
$DEVICETOPIC/battery:.* batteryLevel
attr ble2mqttGTag userReadings presence {if (ReadingsAge($NAME,"lastseen",0)>60) {return "absent";}else{return "present";}}
</syntaxhighlight>

Das Ergebnis ist unter anderem ein Reading ''presence'' mit den Zuständen ''absent'' und ''present''. Es kann somit ganz einfach als "presenceDevice" in einem [[ROOMMATE]]-Device verwendet werden:
attr rr_Franz rr_presenceDevices ble2mqttGTag

[[Category:MQTT]][[Category:Anwesenheitserkennung]][[Category:FHEM Utilities]]

Benutzer:Drhirn

2023-10-12T13:57:33Z

Drhirn: /* Einbindung in FHEM */

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der Electronic Frontier Foundation (EFF) mit dem automatisiert Let's Encrypt Zertifikate erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um den Netzwerkverkehr zu verschlüsseln.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/server/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/server/privkey1.pem

Sind alle Berechtigungen vergeben (die sich beim Erneuern der Zertifikate nicht ändern), müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/test.jft.at/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/test.jft.at/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

Benutzer:Drhirn

2023-10-12T13:51:53Z

Drhirn:

[https://certbot.eff.org Certbot] ist ein freies Open-Source-Tool der Electronic Frontier Foundation (EFF) mit dem automatisiert Let's Encrypt Zertifikate erstellt werden können.

Diese Zertifikate können auch in FHEM verwendet werden, um den Netzwerkverkehr zu verschlüsseln.

In dieser Anleitung wird beschrieben wie [[#Certbot installieren|Certbot]] installiert, [[#Zertifikate erstellen|Zertifikate damit erstellt]] und diese dann [[#Einbindung in FHEM|FHEM zur Verfügung gestellt]] werden.

Let's Encrypt Zertifikate sind in der Regel 90 Tage gültig. Beim Beantragen eines Zertifikates wird von Certbot automatisch ein systemd Timer erstellt, der kurz vor Ablauf des Zertifikat einen Prozess zur Erneuerung desselben startet. Dabei müssen die selben Voraussetzungen gegeben sein, die auch bei der Erst-Erstellung des Zertifikates nötig sind.

==Certbot installieren==
;Voraussetzungen:
* Debian/Ubuntu/Raspberry Pi OS auf dem FHEM-Server
* SSH-Zugang zum FHEM-Server

Die empfohlene Installationsweise ist über die [https://snapcraft.io Snap Paketverwaltung]. Diese Anleitung geht von dieser Empfehlung aus. Wer Snap nicht verwenden möchte, findet [https://eff-certbot.readthedocs.io/en/latest/install.html hier] weitere Informationen.

Es werden zuerst die Paket-Quellen aktualisiert. Danach erfolgt die Installation der Snap Paketverwaltung und einer Laufzeitumgebung dafür:
sudo apt update
sudo apt install -y snapd
sudo snap install core

Im nächsten Schritt kann dann der Cerbot installiert werden:
sudo snap install --classic certbot

Damit Certbot ohne Angabe seines Pfades ausgeführt werden kann, wird noch ein symbolischer Link erstellt:
sudo ln -s /snap/bin/certbot /usr/bin/certbot

==Zertifikate erstellen==
Certbot bietet mehrere Möglichkeiten, Let's Encrypt Zertifikate zu erstellen. Diese hängen von den jeweiligen technischen Voraussetzungen ab.

Damit ein Zertifikat ausgestellt werden kann, muss der Server bzw. der Serveradministrator bestimmte Aufgaben erfüllen um zu beweisen, dass er auch Besitzer der Domain ist, für die ein Zertifikat erstellt werden soll. Beispiele für solche Aufgaben sind z.B. einen bestimmten Record im DNS-Eintrag der Domain zu erstellen oder eine definierte Datei auf einem Webserver abzulegen. Für jede dieser Aufgaben gibt es ein Certbot Plug-In. Genauere Details finden sich auf der Webseite von [https://letsencrypt.org/de/how-it-works/ Let's Encrpyt].

Welche der Möglichkeiten bzw. welches Plug-In genutzt wird, entscheidet der Serveradministrator.

Im Folgenden sind zwei verschiedene Plug-Ins erklärt. Weitere Informationen oder alternative Möglichkeiten bietet die [https://eff-certbot.readthedocs.io/en/latest/using.html#getting-certificates-and-choosing-plugins Certbot-Dokumentation].

===Standalone-Plugin===
Die "standalone" Variante bietet sich an, wenn auf dem System kein Web-Server installiert ist oder mit diesem nicht interagiert werden soll/kann.

Um die Let's Encrypt Aufgabe erfüllen zu können, wird automatisch ein in Certbot eingebauter Webserver gestartet. Dieser liefert eine Datei aus, die von Let's Encrypt dann überprüft wird.

;Voraussetzungen:
* Einen DNS Eintrag vom Typ A (IPv4) oder AAAA (IPv6) für eure Domain mit eurer externen IP Adresse
* Port 80 ist auf der Firewall geöffnet und wird zum FHEM-Server weitergeleitet
* Port 80 wird auf dem FHEM-Server von keinem anderen Service (Web-Server z.B.) verwendet

Sind alle Voraussetzungen erfüllt, kann ein Zertifikat mit folgendem Befehl beantragt werden:
sudo certbot certonly --standalone -d www.example.com

*'''''--standalone''''' bestimmt hier das zu verwendende Plug-In "standalone"
*'''''-d''''' die Domain, für die das Zertifikat ausgestellt werden soll. Es können - kommagetrennt - mehrere Domains angegeben werden. Oder der Parameter -d wird einfach öfter verwendet.

Weiteres Beispiel für das Beantragen eines Zertifikates mit mehreren Domains:
sudo certbot certonly --standalone -d www.example.com -d example.com

Wer den ganzen Ablauf zuerst testen möchte, kann einen "dry-run" durchführen. Dabei wird die Ausstellung durch einen Test-Server von Let's Encrypt durchgeführt, es werden aber keine Zertifikate am FHEM-Server gespeichert:
sudo certbot certonly --standalone --dry-run -d www.example.com

Eine weitere Möglichkeit, einen ausführlicheren Testlauf durchzuführen ist, den Let's Encrypt Staging-Server (Test-Server) zu verwenden. Dabei werden Zertifikate im System abgelegt, die zwar ungültig sind, aber zu Testzwecken verwendet werden können:
sudo certbot certonly --standalone --staging -d www.example.com



===DNS Plugins===
Eine ganz einfache Möglichkeit zur Erstellen von Zertifikaten bieten die DNS Plug-Ins.

Dabei muss kein lokaler Server aus dem Internet erreichbar sein, sondern es wird ein bestimmter DNS-Eintrag der Domain automatisch geändert und überprüft um zu beweisen, dass der Antragsteller Inhaber der Domain ist.

;Voraussetzungen
*Verwendung eines [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins unterstützten DNS-Providers] zur Verwaltung der eigenen Domain
*API-Key mit dem Recht, DNS-Einträge zu ändern

Für alle DNS Plug-Ins gilt, dass sie unter dem root-User laufen. Um das zu erlauben, ist folgender Befehl nötig:
sudo snap set certbot trust-plugin-with-root=ok

Anschließend muss das korrekte Plug-In installiert werden.

In dieser Anleitung wird die Verwendung des [https://certbot-dns-cloudflare.readthedocs.io/en/stable/ Cloudflare Plug-Ins] erklärt. Die Funktionsweise ist bei anderen ähnlich und auf der jeweiligen [https://eff-certbot.readthedocs.io/en/latest/using.html#dns-plugins Dokumentationsseite] des Plug-Ins ersichtlich.

Zuerst wird das Plug-In installiert:
sudo snap install certbot-dns-cloudflare

Danach wird eine Datei erstellt, die den API-Key mit der Berechtigung zum Ändern von DNS-Einträgen bei Cloudflare beinhaltet:
sudo mkdir /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

;/root/.secrets/cloudflare.ini
<syntaxhighlight lang="ini">
# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567
</syntaxhighlight>

Diese Datei muss dann noch vor unbefugtem Zugriff geschützt werden:
sudo chmod 0700 /root/.secrets/
sudo chmod 0400 /root/.secrets/cloudflare.ini

Sind diese Schritte erledigt, kann ein Zertifikat beantragt werden:
<syntaxhighlight lang="bash">
sudo certbot certonly \
--dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
--dns-cloudflare-propagation-seconds 20 \
-d www.example.com -d example.com
</syntaxhighlight>

==Einbindung in FHEM==
Um die Zertifikate nun in FHEM nutzen zu können, müssen zuerst die Berechtigungen auf diese geändert und dann symbolische Links zu Pfaden erstellt werden, wie sie FHEM erwartet.

Das Ändern der Berechtigungen ist wichtig, weil der User ''fhem'' sonst keinen Lesezugriff auf diese hätte. Das Erstellen der symbolischen Link, weil FHEM die Zertifikate im Ordner ''/opt/fhem/certs'' erwartet.

Grundsätzlich legt Certbot alle Zertifikate unter ''/etc/letsencrypt/archive'' ab. Und zwar unterschiedliche Versionen der Zertifikate. Damit Anwendungen die jeweils aktuellen Zertifikate ohne Änderung verwenden können, werden aber gleichzeitig auch symbolische Links nach ''/etc/letsencrypt/live'' gesetzt.

Kurz gesagt, für Anwendungen sind nur die jeweiligen Dateien unter ''/etc/letsencrypt/live'' relevant. Dabei vor allem:
* '''/etc/letsencrypt/live/www.example.com/privkey.pem''' (Der private Key)
* '''/etc/letsencrypt/live/www.example.com/fullchain.pem''' (Das erstellte Zertifikat mit der ganzen Signaturkette)

Nichts desto trotz müssen aber auf beiden Verzeichnisse (''archive'' und ''live'') die Zugriffsrechte geändert werden, damit der User ''fhem'' in späterer Folge daraus lesen kann. Für die Sicherheit der Zertifikate hat das keinen Einfluss, die sind durch eigene Dateisystemrechte geschützt.
sudo chmod 0755 /etc/letsencrypt/{live,archive}

Damit FHEM den Private Key lesen kann, ändern wir den Gruppenbesitz der Datei auf die Gruppe ''dialout'':
sudo chgrp dialout /etc/letsencrypt/archive/server/privkey1.pem

Und vergeben anschließend noch eine Leseberechtigung für diese Gruppe:
sudo chmod 0640 /etc/letsencrypt/archive/server/privkey1.pem

Sind alle Berechtigungen vergeben, müssen noch symbolische Links in das Verzeichnis ''/opt/fhem/certs'' erstellt werden, da FHEM die Zertifikats-Dateien genau dort erwartet. Alle folgenden Befehle werden unter dem Benutzerkontext des Users ''fhem'' ausgeführt, damit danach keine Berechtigungen mehr verändert werden müssen.

Zuerst wird das Verzeichnis selbst erstellt:
sudo -u fhem mkdir /opt/fhem/certs

Anschließend ein symbolischer Link für den PrivateKey eingerichtet:
sudo -u fhem ln -s /etc/letsencrypt/live/test.jft.at/privkey.pem /opt/fhem/certs/server-key.pem

Und danach einer für das Zertifikat:
sudo -u fhem ln -s /etc/letsencrypt/live/test.jft.at/fullchain.pem /opt/fhem/certs/server-cert.pem

Die Änderung in FHEM selbst beschränken sich auf eine einzige Änderung am FHEMWEB-Device (''WEB''):
attr WEB HTTPS 1

Danach die Konfiguration speichern und FHEM ist ab sofort unter https://www.example.com:8083/ zu erreichen.

Zigbee2mqtt

2022-10-14T07:42:23Z

Drhirn: "report" ist deprecated, das noch da stehen zu lassen ist verwirrend. Wird auch nicht mehr benötigt.

{{Baustelle}}
[[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.

== Installation von zigbee2mqtt ==
Die Installation des zigbee2mqtt-Diensts ist auf der [https://www.zigbee2mqtt.io/ Homepage des Projekts] beschrieben. Ergänzend muss in der ''configuration.yaml'' eine ''client_id'' unter ''mqtt'' (z.B. zigbee_pi) vergeben werden<ref>Die Anführungszeichen sowie genau zwei Leerzeichen sind hier erforderlich!</ref>.
mqtt:
client_id: 'zigbee_pi'

''tbd: weitere sinnvolle Einstellungen, availability, ...''


Da der Dienst auch später in den Anlernmodus versetzt werden kann, kann man auch gleich <code>permit_join: false</code> setzen, um das versehentliche Einbinden neuer oder fremder Geräte zu unterbinden.

Zur Verbesserung der Bedienerfreundlichkeit empfiehlt es sich, das [https://www.zigbee2mqtt.io/information/frontend.html frontend] von zigbee2mqtt zu aktivieren:

Hier kann man einige Einstellungen bequem vornehmen (beispielsweise den "friendly name") und auch die gepairten Geräte direkt schalten.
<pre>
frontend:
# Optional, default 8080
port: 8080
# Optional, default 0.0.0.0
host: 0.0.0.0
# Optional, enables authentication, disabled by default
auth_token: your-secret-token
</pre>

{{Hinweis|Wird ein CC2531 auf demselben Linux-Computer verwendet, auf dem auch FHEM installiert ist, kann es vorkommen, dass FHEM diesen mit einem [[CUL]] verwechselt und durch ''initialUsbCheck'' in FHEM einbindet, wodurch er für den zigbee2mqtt-Dienst nicht mehr verfügbar ist. Dann sollte ''initialUsbCheck'' deaktiviert und das automatisch angelegte CUL-Device wieder gelöscht werden. Weiter sollte der CC2531 auch in FHEM '''und''' zigbee2mqtt ''[[Mehrere USB-Geräte einbinden|by-id]]'' eingebunden werden, um Probleme beim gleichzeitigen Einsatz anderer Geräte, die ''/dev/ttyACMx'' belegen können, zu vermeiden (betrifft z.B. CUL/MapleCUL ).}}
{{Hinweis|Zwischenzeitlich stehen neben den CC2531 bzw. CC2530 einige weitere, wesentlich leistungsfähigere Coordinator-Chipsets zur Verfügung. Ein Blick auf die betreffenden Info-Seiten bei zigbee2mqtt sei daher ausdrücklich empfohlen!}}

== Define eines MQTT2-Devices als "Bridge" ==
Dann kann eine Art "Grund-Device" angelegt werden, das für die Ansteuerung des eigentlichen Server-Dienstes genutzt wird, der bereits unmittelbar nach der erfolgreichen Konfiguration von zigbee2mqtt zur Verfügung steht. In der Regel sollte dieses automatisch erstellt werden, wenn der zigbee2mqtt-Dienst (oder der betreffende Rechner) neu gestartet wird (oder FHEM oder dort ein Sensor einen Messwert sendet). Beispiel<ref>Hier waren bereits zwei Zigbee-Geräte angelernt</ref>:

defmod MQTT2_zigbee_pi MQTT2_DEVICE zigbee_pi
attr MQTT2_zigbee_pi IODev MQTT2_FHEM_Server
attr MQTT2_zigbee_pi readingList zigbee_pi:zigbee2mqtt/bridge/state:.* state\
zigbee_pi:zigbee2mqtt/0x90fd9ffffe65db16:.* { json2nameValue($EVENT, '') }\''
zigbee_pi:zigbee2mqtt/0x90fd9ffffe0bcd51:.* { json2nameValue($EVENT, '') }\''
zigbee_pi:zigbee2mqtt/bridge/log:.* { json2nameValue($EVENT, 'log_') }
attr MQTT2_zigbee_pi room MQTT2_DEVICE

Für die Funktion einer zigbee2mqtt-Bridge steht ein {{Link2CmdRef|Anker=set|Lang=en|Label=template}} bereit, das direkt die passenden Attribute vergibt, um dem zigbee2mqtt-Dienst passende Anweisungen geben zu können und weitere Geräte für die eigentlichen Aktoren und Sensoren anzulegen:
:<code>set MQTT2_zigbee_pi attrTemplate zigbee2mqtt_bridge</code>

Ist dieses angelegt, kann zigbee2mqtt mit
:<code>set MQTT2_zigbee_pi permit_join true</code>
in den Anlernmodus versetzt werden, anzulernende Geräte müssen anschließend jeweils nach Bedienungsanleitung in den Anlernmodus gebracht werden.

== Vereinzeln der eigentlichen Geräte ==
Über das mit dem template vergebene bridgeRegexp-Attribut
:<code>attr MQTT2_zigbee_pi bridgeRegexp zigbee2mqtt/([A-Za-z0-9]*)[/]?.*:.* "zigbee_$1" </code>
werden anschließend neue MQTT2_DEVICE-Geräte automatisch angelegt, sobald ein bisher unbekanntes Zigbee-Gerät einen neuen Status (z.B. einen Messwert) meldet. Um zu erfragen, welche Geräte dem zigbee-Deinst bekannt sind, kann via <code>get MQTT2_zigbee_pi devicelist true</code> eine Liste abgefragt werden, die weitere Informationen zu den bereits angelernten Geräten enthält.
Geräte, die nicht automatisch etwas senden, kann man mit Hilfe des MQTT2_SERVER-Geräts einmalig schalten, damit diese ihren Status bzw. das erfolgreiche Schalten zurückmelden, Beispiel<ref>Die mit 0x... beginnende Angabe entspricht dabei dem ''friendly_name''.</ref>:
:<code><nowiki>set MQTT2_FHEM_Server publish zigbee2mqtt/0x90fd9ffffe0bcd51/set {"state":"ON","brightness":60}</nowiki></code>
(Alternativ kann man das Gerät auch über das Frontend von zigbee2mqtt schalten, um das Device in FHEM automatisch anzulegen.)

Für Gerätetypen, für die bereits templates vorhanden sind, ist es am einfachsten, diese einmalig auf die Geräte anzuwenden. Das Vorgehen entspricht dabei dem oben für die Bridge beschriebenen. Dafür wird immer vorausgesetzt, dass ein neues Device mit autocreate (ggf. über die bridgeRegexp) angelegt wurde<ref>Dieses befindet sich dann im Raum MQTT2_DEVICE. Um diesen sichtbar zu machen, muss ggf. die Browser-Seite neu geladen werden.</ref>

Beispiele:
=== IKEA-Tradfri-Birne ===
{{Randnotiz|RNTyp=g|RNText=Wie wähle ich nun das richtige Template für mein Leuchtmittel aus?
-> Es wird nicht zwischen einer Birne/Bulb/Lampe und einem LED-Controller unterschieden sondern anhand der möglichen Lichtdarstellung des Gerätes:

light_dimmer:
Das anzusteuernde Geräte besitzt ausschließlich eine feste Lichtfarbe welche gedimmt werden kann.

light_cct:
Das anzusteuernde Gerät besitzt eine warmweiße sowie kaltweiße Lichtfarbe welche verändert sowie gedimmt werden kann.

light_rgb_xxx:
Das anzusteuernde Gerät besitzt die Möglichlichkeit einer farbigen Lichtdarstellung (Rot, Grün, Blau) und kann gedimmt werden.

light_rgbw_xxx:
Das anzusteuernde Gerät besitzt die Möglichlichkeit einer farbigen Lichtdarstellung (Rot, Grün, Blau) und besitzt eine warmweiße ODER kaltweiße Lichtfarbe welche eingestellt sowie gedimmt werden kann.

light_rgbcct_xxx:
Das anzusteuernde Gerät besitzt die Möglichlichkeit einer farbigen Lichtdarstellung (Rot, Grün, Blau) und besitzt eine warmweiße UND kaltweiße Lichtfarbe welche verändert sowie gedimmt werden kann.

xxx:
hex: Farbänderung mit hex
rgb: Farbänderung mit r g b
xy: Farbänderung mit x sowie y
hue: Farbänderung mit hue und saturation

Warum diese Einteilung in "hex", "rgb", "xy" sowie "hue"?
-> Zigbee2MQTT unterstützt das Übermitteln aller dieser Werte, allerdings unterscheiden sich hier die Geräte. Manche "verstehen" nur z.B. Hex-Farbänderungen, andere halt nur eine Farbänderung mit rgb-Werten.
-> Aus diesem Grund muss an dieser Stelle probiert werden mit welchem der 4 Templates sich die Farbveränderung des Gerätes steuern lässt!

HINWEIS: Templates für Farbänderungen mithilfe von XY- sowie HUE-Werten wurden bis heute nicht angelegt!
}}
Beispiel eines dimmbaren Tradfri-Leuchtmittels
defmod IKEA_Bulb2 MQTT2_DEVICE
attr IKEA_Bulb2 IODev MQTT2_FHEM_Server
attr IKEA_Bulb2 icon light_control
attr IKEA_Bulb2 devStateIcon {zigbee2mqtt_devStateIcon255($name)}
attr IKEA_Bulb2 readingList zigbee_pi:zigbee2mqtt/0x90fd9ffffe0bcd51:.* { json2nameValue($EVENT) }
attr IKEA_Bulb2 setList on:noArg zigbee2mqtt/0x90fd9ffffe0bcd51/set {"state":"ON"}\
off:noArg zigbee2mqtt/0x90fd9ffffe0bcd51/set {"state":"OFF"}\
brightness:colorpicker,BRI,0,15,255 zigbee2mqtt/0x90fd9ffffe0bcd51/set {"state":"on","$EVTPART0":"$EVTPART1"}
attr IKEA_Bulb2 webCmd toggle:on:off:brightness
attr IKEA_Bulb2 model L_02a_zigbee2mqtt_bulb

Kann man auch die Farbtemperatur einstellen, wird die setList wie folgt erweitert oder das entsprechende template<ref>Durch die ''model''-Angabe kann nachvollzogen werden, welches template angewendet wurde.</ref> angewendet:
...
color_temp:colorpicker,CT,250,1,454 zigbee2mqtt/0x90fd9ffffe0bcd51/set {"$EVTPART0":"$EVTPART1"}

Die templates sind dabei in der Regel so gestaltet, dass eventuell mehr Optionen in FHEMWEB erscheinen, als tatsächlich vorhanden oder erwünscht sind.
Da sich obige einfarbige dimmbare Lampe durch Klicken auf das devStateIcon schalten lässt, ist für die vollständige Ansteuerung bereits dieses webCmd hinreichend:
:<code>attr IKEA_Bulb2 webCmd brightness</code>

=== Temp/Hum. Sensor ===
tbd

=== Motion Sensor ===
Als MQTT-Server wird hier ''mosquitto'' verwendet, als IO-Device wird daher ein {{Link2CmdRef|Anker=MQTT2_CLIENT|Lang=en|Label=MQTT2_CLIENT}}-Gerät definiert:

defmod mqtt2_client MQTT2_CLIENT 192.168.2.4:1883
attr mqtt2_client autocreate 1
attr mqtt2_client rawEvents zigbee2mqtt/GB_Bewegungsmelder:.*
attr mqtt2_client room test
attr mqtt2_client subscriptions #

Das eigentliche Device sieht dann so aus:
defmod GB_Bewegungsmelder_MQTT2 MQTT2_DEVICE zigbee_158d0001f9d030
attr GB_Bewegungsmelder_MQTT2 IODev mqtt2_client
attr GB_Bewegungsmelder_MQTT2 devStateIcon motion:motion_detector@red off:motion_detector@green no_motion:motion_detector@green
attr GB_Bewegungsmelder_MQTT2 icon motion_detector@blue
attr GB_Bewegungsmelder_MQTT2 readingList mqtt2client:zigbee2mqtt/GB_Bewegungsmelder:.* { json2nameValue($EVENT) }
attr GB_Bewegungsmelder_MQTT2 room MQTT2_DEVICE
attr GB_Bewegungsmelder_MQTT2 stateFormat {\
if(ReadingsVal("$name","occupancy",0) eq "true") {\
sprintf("motion");;\
} else {\
sprintf("no_motion");; \
}\
}

=== Anlegen von Zigbee2MQTT-Gruppen in FHEM ===
{{Hinweis|Die nachfolgende Darstellung ist vorläufig!}}
{{Hinweis|Bevor man eine Gruppe mithilfe von Zigbee2MQTT anlegen kann, sollte man sicherstellen, dass man über die aktuelleste Version von Zigbee2MQTT verfügt (min. vom 15. Februar 2019). Außerdem sollte auch der Koordinator (zumeist CC2531) die aktuellste Firmware besitzen (min. vom 15. Februar 2019). Falls ein flashen des Koordinators mit der neusten Firmware erfolgen soll, ist darauf zu achten, dass nach einem flashen alle Geräte neu angelernt werden müssen! (Hinweise zum flashen ohne erneutem anlernen sind hier zu finden: https://www.zigbee2mqtt.io/information/flashing_without_re-pairing.html)}}

====Erstellen einer Zigbee2MQTT-Gruppe====
Bevor das Ganze in FHEM funktioniert, muss eine Gruppe in der "configuration.yaml" angelegt werden, dieser Vorgang ist auf folgender Seite beschrieben: https://www.zigbee2mqtt.io/information/groups.html
Wenn die Geräte anschließend über den FHEM MQTT2-Server der Gruppe hinzugefügen werden sollen, kann dies mit folgendem Befehl erfolgen:
set <MQTT2-Server> publish zigbee2mqtt/bridge/group/<Zigbee2MQTT Friendly-Gruppenname>/add <Zigbee2MQTT Friendly-Gerätename>

Beispiel:
:<code>set MQTT2_FHEM_Server publish zigbee2mqtt/bridge/group/Wohnzimmer/add Stehlampe</code>

Dieser Befehl kann so oft verwendet werden, wie man Geräte zu einer Gruppe hinzufügen möchte.

Zum Entfernen eines Gerätes aus einer Gruppe kann folgender Befehl verwendet werden:
:<code><nowiki>set <MQTT2-Server> publish zigbee2mqtt/bridge/group/<Zigbee2MQTT Friendly-Gruppenname>/remove <Zigbee2MQTT Friendly-Gerätename></nowiki></code>
Beispiel:
:<code>set MQTT2_FHEM_Server publish zigbee2mqtt/bridge/group/Wohnzimmer/remove Kuechenlampe</code>

====Anlegen der Gruppe in FHEM====
Da Gruppen in Zigbee2MQTT aktuell keine Rückmeldung über ihren Status geben, wird auch beim einmaligen Schalten kein Gerät automatisch in FHEM angelegt. Aus diesem Grund muss dies mit folgendem Befehl noch manuell erfolgen:
:<code><nowiki>defmod <FHEM NAME> MQTT2_DEVICE</nowiki></code>
Beispiel
:<code><nowiki>defmod lichtWohnzimmer MQTT2_DEVICE</nowiki></code>
Anschließend wird auch für dieses Gerät wieder ein passendes template ausgewählt, als wäre es ein normales Zigbee2MQTT-Gerät.
Im anschließenden Dialogfenster, welches sich nach dem Setzen des templates öffnet, müssen die folgenden Werte durch passende ersetzt werden:
BASE_TOPIC -> zigbee2mqtt
DEV_ID -> <Zigbee2MQTT Friendly-Gruppenname>

Danach sollte sich die Gruppe wie ein normales Zigbee2MQTT Gerät steuern lassen.

== Hinweise ==
<references />

[[Kategorie:HOWTOS]]
[[Kategorie:MQTT]]
[[Kategorie:ZigBee]]
[[Kategorie:IP Components|IP Komponenten]]
[[Kategorie:Interfaces]]

RHASSPY

2022-09-07T10:05:56Z

Drhirn: Link zu Rhasspy auf GitHub entfernt

{{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.

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 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]]

RHASSPY

2022-09-07T10:05:25Z

Drhirn: Hinweis auf GitHub entfernt

{{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.

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 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://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-09-07T10:04:30Z

Drhirn: Hinweis auf Installation/Update via GitHub entfernt

{{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.

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-17T15:47:27Z

Drhirn: /* Custom Converter für reelle Zahlen */

{{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</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 [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.

;<code id="attr-iodev">IODev</code>
:Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
:'''Beispiel:'''
:<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

;<code id="attr-forcenext">forceNext</code>
: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>

;<code id="attr-languagefile">languageFile</code>
: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>

;<code id="attr-response">response</code>
:'''Hinweis:''': Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.


;<code id="attr-rhasspyhotwords">rhasspyHotwords</code>
: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.

;<code id="attr-rhasspyintents">rhasspyIntents</code>
: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 ARRAYs 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]].

;<code id="attr-rhasspyshortcuts">rhasspyShortcuts</code>
: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.

;<code id="attr-rhasspytweaks">rhasspyTweaks</code>
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

:*<code id="attr-rhasspytweaks-timerlimits">timerLimits</code>
::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.

:*<code id="attr-rhasspytweaks-timersounds">timerSounds</code>
::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.

:*<code id="attr-rhasspytweaks-updateslots">updateSlots</code>
::Ä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>

:*<code id="attr-rhasspytweaks-confirmintents">confirmIntents</code>
::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 muss 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>

:*<code id="attr-rhasspytweaks-confirmintentresponses">confirmIntentResponses</code>
::Ü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.

:*<code id="attr-rhasspytweaks-intentfilter">intentFilter</code>
::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, 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.

:*<code id="attr-rhasspytweaks-ignorekeywords">ignoreKeywords</code>
::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>
:* <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> 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>

==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 dasselbe Attribut <code>group</code> oder <code>rhasspyGroup</code> haben.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte alle lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (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)] (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>

Example-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 drei folgenden Intents ''CancelAction'', ''ChoiceRoom'' und ''ChoiceDevice'' auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Rückgabe ist zwingend <code>{Mode}</code> mit dem Wert ''OK'', alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden.

=== 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.

=== ChoiceRoom ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl eines Raums.

=== ChoiceDevice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl eines Gerätes.

=== 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===
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-03-29T15:42:51Z

Drhirn: /* GetNumeric */ - airHumidity auf humidity geändert

{{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]])
}}
== 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</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 [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.

;<code id="attr-iodev">IODev</code>
:Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
:'''Beispiel:'''
:<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

;<code id="attr-forcenext">forceNext</code>
: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>

;<code id="attr-languagefile">languageFile</code>
: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>

;<code id="attr-response">response</code>
:'''Hinweis:''': Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.


;<code id="attr-rhasspyhotwords">rhasspyHotwords</code>
: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.

;<code id="attr-rhasspyintents">rhasspyIntents</code>
: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 ARRAYs 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]].

;<code id="attr-rhasspyshortcuts">rhasspyShortcuts</code>
: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.

;<code id="attr-rhasspytweaks">rhasspyTweaks</code>
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

:*<code id="attr-rhasspytweaks-timerlimits">timerLimits</code>
::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.

:*<code id="attr-rhasspytweaks-timersounds">timerSounds</code>
::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.

:*<code id="attr-rhasspytweaks-updateslots">updateSlots</code>
::Ä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>

:*<code id="attr-rhasspytweaks-confirmintents">confirmIntents</code>
::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 muss 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>

:*<code id="attr-rhasspytweaks-confirmintentresponses">confirmIntentResponses</code>
::Ü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.

:*<code id="attr-rhasspytweaks-intentfilter">intentFilter</code>
::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, 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.

:*<code id="attr-rhasspytweaks-ignorekeywords">ignoreKeywords</code>
::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>
:* <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> 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>

==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 dasselbe Attribut <code>group</code> oder <code>rhasspyGroup</code> haben.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte alle lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (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)] (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>

Example-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 drei folgenden Intents ''CancelAction'', ''ChoiceRoom'' und ''ChoiceDevice'' auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Rückgabe ist zwingend <code>{Mode}</code> mit dem Wert ''OK'', alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden.

=== 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.

=== ChoiceRoom ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl eines Raums.

=== ChoiceDevice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl eines Gerätes.

=== 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=Fehl|RNText=Derzeit funktioniert der Konverter aufgrund eines Fehlers in Rhasspy nicht}}
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-01-04T16:24:43Z

Drhirn: /* Custom Converter für reelle Zahlen */

{{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]])
}}
== 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</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 [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.

;<code id="attr-iodev">IODev</code>
:Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
:'''Beispiel:'''
:<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

;<code id="attr-forcenext">forceNext</code>
: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>

;<code id="attr-languagefile">languageFile</code>
: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>

;<code id="attr-response">response</code>
:'''Hinweis:''': Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.


;<code id="attr-rhasspyhotwords">rhasspyHotwords</code>
: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.

;<code id="attr-rhasspyintents">rhasspyIntents</code>
: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 ARRAYs 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]].

;<code id="attr-rhasspyshortcuts">rhasspyShortcuts</code>
: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.

;<code id="attr-rhasspytweaks">rhasspyTweaks</code>
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

:*<code id="attr-rhasspytweaks-timerlimits">timerLimits</code>
::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.

:*<code id="attr-rhasspytweaks-timersounds">timerSounds</code>
::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.

:*<code id="attr-rhasspytweaks-updateslots">updateSlots</code>
::Ä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>

:*<code id="attr-rhasspytweaks-confirmintents">confirmIntents</code>
::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 muss 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>

:*<code id="attr-rhasspytweaks-confirmintentresponses">confirmIntentResponses</code>
::Ü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.

:*<code id="attr-rhasspytweaks-intentfilter">intentFilter</code>
::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, 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.

:*<code id="attr-rhasspytweaks-ignorekeywords">ignoreKeywords</code>
::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>
:* <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> 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>

==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 dasselbe Attribut <code>group</code> oder <code>rhasspyGroup</code> haben.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte alle lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (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)] (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=airHumidity
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>airHumidity</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>

Example-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 drei folgenden Intents ''CancelAction'', ''ChoiceRoom'' und ''ChoiceDevice'' auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Rückgabe ist zwingend <code>{Mode}</code> mit dem Wert ''OK'', alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden.

=== 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.

=== ChoiceRoom ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl eines Raums.

=== ChoiceDevice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl eines Gerätes.

=== 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=Fehl|RNText=Derzeit funktioniert der Konverter aufgrund eines Fehlers in Rhasspy nicht}}
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-01-04T13:08:48Z

Drhirn: /* Custom Converter für reelle Zahlen */

{{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]])
}}
== 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</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 [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.

;<code id="attr-iodev">IODev</code>
:Das MQTT2_CLIENT Device, welches die MQTT-Nachrichten für RHASSPY liefert.
:'''Beispiel:'''
:<code>attr <rhasspyDevice> IODev rhasspyMQTT2</code>

;<code id="attr-forcenext">forceNext</code>
: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>

;<code id="attr-languagefile">languageFile</code>
: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>

;<code id="attr-response">response</code>
:'''Hinweis:''': Die Verwendung dieses Attributs ist nicht mehr empfohlen. Bessere Alternative ist die Sprach-Datei.


;<code id="attr-rhasspyhotwords">rhasspyHotwords</code>
: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.

;<code id="attr-rhasspyintents">rhasspyIntents</code>
: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 ARRAYs 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]].

;<code id="attr-rhasspyshortcuts">rhasspyShortcuts</code>
: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.

;<code id="attr-rhasspytweaks">rhasspyTweaks</code>
Mit diesen Einstellungen können benutzerdefinierte Optimierungen an RHASSPY vorgenommen werden.

:*<code id="attr-rhasspytweaks-timerlimits">timerLimits</code>
::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.

:*<code id="attr-rhasspytweaks-timersounds">timerSounds</code>
::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.

:*<code id="attr-rhasspytweaks-updateslots">updateSlots</code>
::Ä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>

:*<code id="attr-rhasspytweaks-confirmintents">confirmIntents</code>
::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 muss 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>

:*<code id="attr-rhasspytweaks-confirmintentresponses">confirmIntentResponses</code>
::Ü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.

:*<code id="attr-rhasspytweaks-intentfilter">intentFilter</code>
::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, 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.

:*<code id="attr-rhasspytweaks-ignorekeywords">ignoreKeywords</code>
::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>
:* <code id="attr-rhasspytweaks-ignorekeywords">gdt2groups</code> 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>

==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 dasselbe Attribut <code>group</code> oder <code>rhasspyGroup</code> haben.

Beispiel-Sätze:
<syntaxhighlight lang="perl">
schalte alle lampen in der küche aus
schließe alle rollläden im schlafzimmer
schalte alle lampen aus
</syntaxhighlight>

Beispiel Rhasspy-Sentences:
<syntaxhighlight lang="ini">
[de.fhem:SetOnOffGroup]
\[(schalt|mach)] (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)] (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=airHumidity
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>airHumidity</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>

Example-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 drei folgenden Intents ''CancelAction'', ''ChoiceRoom'' und ''ChoiceDevice'' auch - ein Intent, der im Rahmen von Dialogen benötigt wird. Siehe dazu auch [[RHASSPY/Vertiefung#Dialoge|Vertiefung - Dialoge]].
Rückgabe ist zwingend <code>{Mode}</code> mit dem Wert ''OK'', alles andere wird so behandelt, als wäre der Intent ''CancelAction'' ausgewählt worden.

=== 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.

=== ChoiceRoom ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl eines Raums.

=== ChoiceDevice ===
Siehe ''ConfirmAction''. Dient im Rahmen von Dialogen der Auswahl eines Gerätes.

=== 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===
Rhasspy is (currently) not able to recognize spoken Real numbers (e.g. ten point five) as numbers. Instead it interprets them as two numbers and "point".

To use Real numbers correctly, you have to create a [https://rhasspy.readthedocs.io/en/latest/training/#converters custom converter] and use this in your sentences.

To do this, create a file under <code><profile>/converters</code>, name it as you wish and make it executable.
E.g.
<syntaxhighlight lang="bash">
touch .config/rhasspy/profile/en/converters/customFloat
chmod +x .config/rhasspy/profile/en/converters/customFloat
</syntaxhighlight>

Then fill it with the following example-code:
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import sys
import json

# [22, ".", 5]
args = json.load(sys.stdin)

# 22.5
num = "".join(str(s).strip() for s in args)

print(num)
</syntaxhighlight>

Restart Rhasspy and afterwards you can use your custom-converter in your sentences.

<syntaxhighlight lang="ini">
[SetHeating]
set heating [to] (0..30 [point:. 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/Schnellstart

2021-12-04T19:18:07Z

Drhirn: Rhasspys Mosquitto standardmäßig läuft auf Port 12183

[[File:Rhasspy Webinterface.png|thumb|right|Das Rhasspy-Webinterface nach erfolgreicher Installation und Aufruf des ersten Intents (GetTime)]]
Die folgende Kurzanleitung soll den Einstieg erleichtern. Es ist dabei wichtig, jeden der Schritte vollständig abgeschlossen zu haben, bevor mit dem nächsten begonnen wird!

Voraussetzung für diese Anleitung ist, dass Rhasspy bereits funktionsfähig ist. Dazu bitte der Anleitung in der [https://rhasspy.readthedocs.io/en/latest/#getting-started offiziellen Dokumentation] folgen. 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.

Die Vorbereitung ist 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 FHEM Modul==
[[File:Rhasspy03.png|thumb|right|Installation/Update des RHASSPY Moduls via Kommando-Feld]]
Das RHASSPY-Modul kann ganz einfach mit einem einzelnen Befehl, der in die FHEM-Kommandozeile eingetragen werden muss, installiert werden:

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

Danach muss FHEM neu gestartet 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, 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 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.
<br clear="all">

== 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. Da aber vom Modul schon passende Slots erstellt wurden, können wir diese in den Sätzen verwenden, anstatt einen eigenen Satz für jedes Gerät schreiben zu müssen. Zusätzlich müssen wir aber ''Tags'' verwenden, 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 RHASSPY auf die eigenen Bedürfnisse anzupassen und weitere Geräte damit zu steuern. Alle Informationen dazu finden sich auf der Hauptseite von [[RHASSPY]].

==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]]